第 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 的前缀,文件字节保持不透明。