Sibuna 之书 1.0.0-beta.3 文档
语言: 简体中文
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
本页内容

第 XI 部分:速查卡

放在终端旁边:构建、运行、配置、路由、观测和诊断。完整的表格见第 X 部分;这张卡只列出运维人员要输入的内容。

构建

cargo build --release -p sibuna                          # 守护进程 + SQLite + 控制台
cargo build --release -p sibuna --no-default-features    # 纯内存,不依赖外部 crate
cargo build --release -p sibuna --features postgres-tls  # 共享 PostgreSQL 的集群
rustup target add wasm32-unknown-unknown   # 或设置 SIBUNA_POW_WASM / SIBUNA_CONSOLE_WASM
cargo test            # 单元、实时守护进程、存储和控制台测试
cargo clippy --all-targets && cargo fmt --check
cargo xtask check     # 70 行 / 1,408 行 / 99 列检查
cargo xtask browser   # 无头 Chromium 检查
cargo xtask bench product   # 在 wrk 下测完整产品 -> benchmarks/results/
guidedog build        # 本书(guidedog dsc:SID 记录)

运行

# Shield(默认):PoW + WAF,代理到 :3000
sibuna -p 8080 -u 3000 -s /etc/sibuna/secret
# Gate:仅 PoW
sibuna --gate -p 8080 -u 3000 -s /etc/sibuna/secret
# 位于 Nginx/Caddy 之后的 forward auth(信任 X-Forwarded-For)
sibuna -m forward_auth --host 127.0.0.1 -p 8080 -s /etc/sibuna/secret
# Edge:持久策略、信誉和取证数据存放在 <dir>/sibuna.db
sibuna -D /var/lib/sibuna -s /etc/sibuna/secret
# 来自受信任入口代理的 JA4(Cloudflare 的请求头;nginx 模块:x-ja4;ATS:ja4)
sibuna --ja4-header cf-ja4 --trust-forwarded -p 8080 -u 3000 -s /etc/sibuna/secret
# 集群成员:共享 PostgreSQL,节点 ID 唯一
sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 -s /etc/sibuna/secret
head -c 32 /dev/urandom | xxd -p -c 64 > /etc/sibuna/secret

控制台(可选启用的预览功能)

# 在守护进程停止时初始化,然后启动控制台
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446

打开 http://127.0.0.1:19446/console/ 并更换临时密码。加上 --console-location 1.3521,103.8198 可以把节点标注在地球视图上。远程访问需要 HTTPS 代理、明确指定的 origin 和受信任代理的 CIDR;请按照第 IX 部分操作。SID 0007 的状态为 Committed。控制台在无头 Chromium 中通过了它的浏览器工作流测试(SID 0010,标准 5);它的正式性能隔离门槛仍未完成(第 VIII 部分)。

最先需要关注的选项

选项 默认值 含义
-d, --difficulty 16 工作比特(PoSW 深度 = 比特数 - 3)
-a, --algorithm posw posw 或 hashcash
--posw-challenges 16 每个证明的揭示数
--token-ttl 86400 会话秒数
--challenge-ttl 300 挑战秒数
--token-scheme mac mac 或 ed25519
--rate-limit / --rate-window 100 / 10 每个窗口的 GCRA 突发量
--ban-seconds 3600 蜜罐封禁
-w, --workers CPU 数 接受线程
--max-connections 1024 超出后返回 503
--max-connections-per-ip 64 按对端地址(IPv6:按 --ipv6-prefix),超出后返回 503
--trusted-hops 1 客户端 = 从右数第 n 个 X-Forwarded-For 条目
--ja4-header 关闭 包含入口代理所给 JA4 指纹的请求头;仅在受信任时读取
--idle-timeout 15 回收秒数
-P, --policy-file 无 JSON 策略
--trust-forwarded 关闭 forward-auth 模式下开启
--secure-cookie 关闭 加上 Secure

/__sibuna/ 下的端点

路由 应答
challenge 验证中间页 HTML
challenge.json?need=&path= {id, algorithm, difficulty, challenges, expires_at}
verify(POST) {challenge_id, nonce | proof} -> 200 + Set-Cookie,否则 400
wasm/sibuna-pow.wasm 15,181 字节的求解器
worker.js 包含 WASM 和 JS 证明器的 worker
honeypot 封禁调用方,403;子资源或跨站获取返回 404
health {"status":"ok",...}
metrics Prometheus 文本

把它们全部路由到守护进程,绝不路由到源站。

状态码

状态码 时机
200 已准入(forward-auth)、验证中间页、内部路由
400 请求或目标格式错误,解答被拒(响应体为诊断信息)
401 需要挑战:非 HTML 客户端或 forward-auth 模式
403 策略或 WAF 拒绝、封禁、蜜罐
404 未知的 /__sibuna/ 路由,被拒绝的蜜罐命中
413 解答请求体超过 64 KB 缓冲区
414 上报的挑战 URL 超过 8 KiB
417 不支持的请求期望
429 GCRA 限制,Retry-After 秒数
431 头部超过 16 KB
501 chunked 以外的传输编码
502 源站不可达或响应格式错误
503 达到连接限制,或节点正在排空

请求头与响应头

  • 发往上游(代理):X-Forwarded-For(套接字对端;受信任时追加在收到的链之后)、X-Forwarded-Proto、X-Real-IP(被判定的客户端)、X-Sibuna-Status: PASS、X-Sibuna-Rule: <rule>;逐跳字段和其他转发字段会被丢弃,使用下划线拼写的也一样。
  • forward-auth 回复:X-Sibuna-Status、X-Sibuna-Rule、X-Sibuna-Rule-Hash。
  • 挑战回复:X-Sibuna-Status: CHALLENGE。
  • Cookie:__sibuna_token=<75 chars, 139 with ed25519>; Path=/; Max-Age=<ttl>; HttpOnly; SameSite=Lax[; Secure]

策略文件骨架

{ "default_action": "CHALLENGE", "waf": true,
  "thresholds": {"challenge_at": 10, "deny_at": 40, "bits_step": 5},
  "ip_rules": {"10.0.0.0/8": "ALLOW", "2001:db8::/32": "DENY"},
  "rules": [
    {"name": "api", "path": "/api/*", "headers": {"X-Api-Key": ".*"}, "action": "ALLOW"},
    {"name": "checkout", "path": "/checkout/*", "action": "CHALLENGE",
     "challenge": {"difficulty": 20, "algorithm": "posw"}},
    {"name": "login", "path": "^/login$", "action": "CHALLENGE",
     "limits": {"rate": 10, "window_seconds": 60, "ban_seconds": 600}},
    {"name": "old-tls", "ja4": "t12*", "action": "CHALLENGE"},
    {"name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30} ] }

JA4:完整的指纹,或者前缀加 *;没有指纹则不匹配。模式:* 或 .* 匹配任意内容;^...$ 精确匹配;末尾 * 为前缀;以 / 开头为精确路径;其他为不区分大小写的子串。路径按规范形式匹配。顺序:WAF -> 字典树 deny/allow -> 规则 -> 分数 -> 绕过 -> 字典树 challenge -> 机器人 -> 默认。

用 SQL 操作存储(Edge)

INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
  header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
  VALUES ('p1', 'protect', 10, '/checkout/*', 'challenge', 20, 'posw', '{}', '[]', 0, 1,
  unixepoch(), unixepoch());
INSERT INTO ip_reputation (ip_or_cidr, reputation_score, banned_until, trigger_rule, hits, last_seen)
  VALUES ('198.51.100.7', -100, unixepoch() + 86400, 'analyst', 1, unixepoch());
SELECT s.client_ip, s.violation_category, s.path, s.campaign_id
  FROM incidents_fts f JOIN security_incidents s ON s.id = f.rowid
  WHERE incidents_fts MATCH 'union' ORDER BY rank LIMIT 20;

SQLite(sqlite3 <dir>/sibuna.db);动作名为小写。分数 \(\le -50\) -> deny 前缀;\(\ge 50\) -> allow。集群:每个节点使用相同的密钥,一个 PostgreSQL 数据库,--features postgres-tls,--database-url-file <file> --cluster-node N,其中 N 唯一,取值 1 到 8,388,607;没有成员列表、领导者或集群 TLS(SID 0011)。

诊断

标题 含义
MALFORMED CHALLENGE ID 被编辑或截断;获取一个新的
INVALID CHALLENGE TAG 不是由这个种子或节点签发的
CHALLENGE EXPIRED 超过 TTL,或时钟偏差 > 60 s
CLIENT FINGERPRINT MISMATCH 地址或 User-Agent 发生了变化
DIFFICULTY NOT MET nonce 缺少零比特
INVALID PROOF OF SEQUENTIAL WORK 揭示无法到达根
WRONG SOLUTION TYPE 为 PoSW 提交了 nonce,或为 Hashcash 提交了证明
DOUBLE SPEND PREVENTED 挑战已被使用
STORE FULL 已用集合饱和;降低 TTL 或调大 --spent-tags
NETWORK BINDING MISMATCH Cookie 被复制到另一个客户端
INVALID COMMAND LINE 未知选项、错误的值,或已移除的 Zaxonlite 选项

需要告警的指标:denied、rate_limited、overloaded、upstream_errors、incidents_dropped、incident_write_failures、bans_refused、forwarded_invalid(均为 sibuna_*_total)。

需要记住的数字

挑战 ID 70 字符(36 字节载荷 + 16 字节标签);令牌 75 字符(40 + 16),使用 Ed25519 时为 139;证明字节数 \(32(1 + t(n+1))\);PoSW 深度 = 比特数 - 3,范围 4 到 24;请求缓冲区 64 KB;头部上限 16 KB;检查请求体 8 KB;已用集合 1,048,576 个标签(--spent-tags);速率单元每张表 262,144 个(--rate-table-cells);封禁 65,536 个槽(--ban-table-slots);每个客户端地址 64 个连接;事件环 512;批次 32;攻击活动距离 0.35,基于最近的 16,384 个嵌入向量;keep-alive 每个连接 4,096 个请求;源站连接池 256 个套接字;存储任务队列 32。

入口路由

使用第 IX 部分“入口代理之后的 forward-auth”中的 Nginx 或 Caddy 配置方案。直接路由 /__sibuna/*;用原始 URI、方法和受信任的客户端地址对应用请求进行授权。用授权结果替换传入的 Sibuna 审计头。Nginx 需要显式处理挑战、429 和认证服务不可用的情况。

reverse_proxy 承载已准入的 HTTP/1.1 请求体和 WebSocket;forward_auth 只授予准入,由入口代理承载它们。被省略的认证请求体和源站响应无法被 Sibuna 检查或计数。TLS 在入口代理处终止;原生 HTTP/2 推迟实现。上传使用 Content-Length 或分块编码;检查最多只看到 8 KiB 的前缀,文件字节保持不透明。