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

第 X 部分:案头参考与诊断

端点、指标、错误目录、策略模式和存储表,集中在一处。

端点

表 27 保留路由
端点 方法 功能
/__sibuna/challenge GET 验证中间页
/__sibuna/challenge.json?need=&path= GET 签发一个无状态挑战:若被挑战的响应中带有要求票据,则由票据决定;否则按规范形式评估上报的 URL(超过 8 KiB 返回 414,路径没有规范形式时返回 400)。返回 {id, algorithm, difficulty, challenges, expires_at}
/__sibuna/verify POST 接受 {"challenge_id", "nonce"} 或 {"challenge_id", "proof"};返回带 Set-Cookie 的 200、带诊断信息的 400,或在请求体大于连接缓冲区时返回 413
/__sibuna/wasm/sibuna-pow.wasm GET 求解器模块,14,744 字节(benchmarks/results/primitives-latest.json 中的 wasm_bytes),可缓存一小时
/__sibuna/worker.js GET 包含 WASM 和 JavaScript 证明器的 Web Worker,可缓存一小时
/__sibuna/honeypot GET 将调用方封禁 --ban-seconds 并记录一条事件;返回 403。只有顶层请求才会触发封禁(没有 Sec-Fetch-Dest 或其值为 document,且 Sec-Fetch-Site 不是跨站);其他请求返回 404 并计数
/__sibuna/health GET JSON 格式的存活状态,包含引擎名称、版本、代理模式和证明算法
/__sibuna/metrics GET Prometheus 文本格式(版本 0.0.4)

/__sibuna/ 下的任何其他路径都返回 404。签发和验证消耗单独的 --challenge-rate-limit 预算,被封禁的地址在每个路由上都以 403 被拒绝。挑战响应带有 X-Sibuna-Status: CHALLENGE;被准入的请求向上游携带 X-Sibuna-Status: PASS 和 X-Sibuna-Rule(在 forward-auth 回复中还有十六进制的 X-Sibuna-Rule-Hash)。不接受 HTML 的客户端收到 401 和 {"error":"challenge_required","challenge":"/__sibuna/challenge.json?need=<ticket>"}。

单独的、需显式启用的管理监听器提供 /console/。先用 sibuna init-admin 在本地初始化管理员,然后在首次登录时更换临时密码。/console/api/stats 和 /console/ws 需要经过认证的会话(包括大屏会话)。WebSocket 以有界的快照、增量和缺口恢复,多路传输统计、事件、节点、策略、挑战和审计数据。管理对等节点连接到 /console/peer,每个 API 路由都位于 /console/api/ 之下。forward-auth 模式下不观测源站错误计数。第 IX 部分记录了控制台的工作流程、HTTPS 部署和 SID 0007 当前的限制。

指标

计数器以 Prometheus 文本格式暴露为 sibuna_<name>_total,顺序如下:

表 28 计数器
计数器 递增时机
incidents_persisted, incident_batches 存储线程已确认提交的记录和事务
incidents_dropped, incident_write_failures 因环已满而被拒绝的入队操作,以及失败的提交尝试
requests 一个解析后的请求到达分派阶段(包括保留路由)
allowed, denied, challenged 作出了一个策略决定(准入、拒绝、签发或重新签发挑战)
challenges_issued /__sibuna/challenge.json 签发了一条挑战记录
solutions_accepted, solutions_rejected /__sibuna/verify 接受或拒绝了一个证明
rate_limited GCRA 拒绝了一个请求(429):请求限制、挑战预算或规则配额
banned 一个被封禁的地址被拒绝,或蜜罐封禁了一个地址
bans_issued 记录了一次封禁(蜜罐或规则配额触发的封禁)
proxied, upstream_errors 一个请求被中继到源站,或源站失败(502)
parse_errors 拒绝了格式错误的头部、重复的 Host、没有规范形式的目标(400),或不支持的传输编码(501)
overloaded 超出 --max-connections 或 --max-connections-per-ip 的连接被回答 503
bans_refused 一次封禁未被记录,因为其键可能占用的每个槽都持有一个仍然有效的封禁
forwarded_invalid 一个受信任的转发客户端地址无法解析;该请求按套接字对端判定
honeypot_refused 一次蜜罐命中没有封禁任何人,因为请求它的是页面而不是人
rate_evictions 一次限制器到达逐出了另一个活跃客户端的单元
ja4_present 在设置 --ja4-header 并信任转发的情况下,请求恰好带有一个该名称的请求头,其中包含一个 JA4 指纹
ja4_invalid 在设置 --ja4-header 并信任转发的情况下,该请求头格式错误或重复;该请求在没有指纹的情况下被判定

重试可能递增 incident_write_failures 而不丢失记录,因为待处理批次会被保留。应监控一段时间内的增量;仅凭总数并不能反映队列深度。

状态码

表 29 数据平面的状态码
状态码 时机
200 已准入(forward-auth)、验证中间页(需要挑战的 HTML 导航)、内部路由
302 当前协议不使用;验证返回 200,页面重新加载
400 格式错误的请求、重复的 Host 字段、没有规范形式的目标、无效的转发元数据、格式错误的请求体,或带有 Elm 风格诊断信息的被拒解答
401 对不接受 HTML 的客户端或在 forward-auth 模式下要求挑战
403 策略或 WAF 拒绝、被封禁的地址、蜜罐
404 /__sibuna/ 下的未知路径,或不是顶层请求的蜜罐命中
413 解答的请求体大于 64 KB 的连接缓冲区
414 上报的挑战 URL 超过 8 KiB
417 不支持的请求期望;100-continue 在本地处理
429 超出 GCRA 限制;Retry-After 以秒为单位
431 请求头部超过 16 KB
501 Transfer-Encoding 使用了 chunked 以外的编码
502 源站不可达,或其响应头部格式错误或大于 16 KB
503 达到连接限制(--max-connections 或 --max-connections-per-ip),或节点正在排空;回复后关闭套接字

错误目录

对于守护进程不认识的任何选项、超出文档所述范围的任何值,以及无效、缺失或重复的模式选择,INVALID COMMAND LINE 会终止启动。错误块会指出选项、给定的值、期望的范围和错误(UnknownOption、MissingValue、InvalidValue、InvalidMode、MissingMode、DuplicateMode;Zaxonlite 集群选项对应 RemovedOption,两个互斥的存储选项对应 ConflictingOptions,没有 --cluster-node 的数据库 URL 对应 MissingOption),并以一条提示结尾。数据库 URL 显示为 [redacted]。请只提供一次 --mode reverse_proxy 或 --mode forward_auth;-m 是等价的短选项。被拒绝的策略文件会打印一个以其错误命名标题的错误块(例如 INVALID POLICY ACTION),其中包含文件、错误名称、规则、字段和值。任何指纹都无法匹配的 ja4 模式会打印 INVALID POLICY JA4(InvalidJa4);带有这种模式的控制台管理文档会以同一个错误名称被拒绝。控制台选项单独检查:CONSOLE002 指出格式错误或重复的控制台选项,CONSOLE001 指出违反规则的控制台配置(没有存储时的 StorageRequired)。

表 30 挑战与会话错误
错误 原因 提示
MalformedChallenge 标识符不是格式正确的挑战记录 获取一个新挑战,并原样提交
InvalidChallengeTag 标签认证失败;不是由本集群签发,或已被编辑 挑战无法伪造;请重新请求挑战
ChallengeExpired 超过挑战 TTL,或签发时间在未来 请求一个新挑战
FingerprintMismatch 从不同的地址或 User-Agent 提交 从获取挑战的那个客户端提交
DifficultyNotMet Hashcash nonce 缺少所需的零比特 继续搜索 nonce
InvalidProof 顺序工作量证明无法揭示已承诺的标签 按签发的深度和揭示数完整运行证明器
WrongSolutionType 为 PoSW 挑战提交了 nonce,或为 Hashcash 提交了证明 让解答字段与算法相符
DoubleSpendAttempt 挑战已被使用 挑战只能使用一次
StoreFull 已用集合已满 降低挑战 TTL,或调大 --spent-tags
InvalidTokenSignature Cookie 的标签或签名校验失败 通过验证中间页重新认证
TokenExpired Cookie 已过期 重新认证
TokenBoundAddressMismatch Cookie 由不同的客户端身份出示 Cookie 不能共享

控制台 API 以 {"error":"<CODE>","hint":"<sentence>"} 报告失败;其中的 hint 就是界面显示的文字(crates/console/src/http/reply.rs)。

表 31 与运维人员相关的控制台失败代码
状态码 状态码 含义
CONSOLE002 400 请求格式错误、过大,或其形式不被允许
CONSOLE003 503 / 429 存储任务队列已满(32 个任务),或密码验证器繁忙
CONSOLEQUORUM 503 数据库未在请求的 10 秒等待时间内应答;结果未知,数据平面继续使用最后应用的策略
CONSOLE004 503 服务无法应答:此构建中不可用、正在停止,或发生内部故障
CONSOLENODE 400 / 409 / 503 节点命令被拒绝:它指向另一个节点(400),启动或控制修订版本已过时(409),或者它在另一条命令运行时到达,或某次完成无法被记录(503);重试之前请检查操作回执
CONSOLEMUTATION 429 一个会话在一分钟内发起了超过六十次管理变更

策略模式

{
  "default_action": "ALLOW" | "DENY" | "CHALLENGE",
  "waf": true | false,
  "inspection": { "path_traversal" | "sqli" | "xss" | "rce": "disabled" | "audit" | "enforce" },
  "thresholds": { "challenge_at": int, "deny_at": int, "bits_step": int },
  "ip_rules": { "<cidr>": "ALLOW" | "DENY" | "CHALLENGE", ... },
  "rules": [                                                    // 最多 128 条
    {
      "name": "<kebab-case>",                                   // 1 到 128 个可打印字节
      "path" | "path_regex": "<pattern>",                       // 最多 512 字节
      "user_agent" | "user_agent_regex": "<pattern>",
      "headers" | "headers_regex": { "<Header>": "<pattern>" }, // 最多 4 个
      "remote_addresses" | "cidrs": ["<cidr>", ...],            // 最多 8 个,IPv4 或 IPv6
      "action": "ALLOW" | "DENY" | "CHALLENGE" | "WEIGH",
      "weight": int,                                            // 仅用于 WEIGH,-1000..1000
      "challenge": { "difficulty": <work bits>, "algorithm": "hashcash" | "posw" },
      "limits": { "rate": int, "window_seconds": int, "ban_seconds": int },
      "ja4": "<fingerprint>" | "<prefix>*"                      // 36 字节,或前缀加 *
    }
  ]
}

challenge_at 和 deny_at 的取值范围为 -1000 到 1000,并且 deny_at 不小于 challenge_at;bits_step 的取值范围为 1 到 1000。challenge 块只属于 CHALLENGE 规则,工作比特为 1 到 64。limits 为规则设定自己的配额:rate(1 到 1,000,000)和 window_seconds(1 到 86,400)是必需的,ban_seconds(最多 86,400)是可选的,WEIGH 规则不能带有 limits。ja4 是一个完整的 JA4 指纹,此时必须与之相等,或者是一个后跟 * 的前缀,此时指纹必须以它开头;单独的 * 匹配任何指纹,没有指纹的请求不匹配任何 ja4 规则。任何指纹都无法匹配的模式会以 InvalidJa4 被拒绝(第 IX 部分“来自入口代理的 JA4 指纹”)。ip_rules 的信誉字典树最多容纳 8,192 个节点。每条规则对每个条件只能使用一种写法。

模式语法:.* 或 * 匹配任何内容;^...$ 锚定一个精确路径;末尾的 *、/* 或 .* 表示前缀;以 / 开头的模式是精确路径;其他情况是不区分大小写的子串。路径模式匹配规范形式的路径(段之间只有一个斜杠,没有点段,非保留字符不转义,其他转义使用大写十六进制数字),因此包含 ;、%2F、%5C 或 \ 的模式不会匹配任何内容,并且路径匹配区分大小写(SID 0003)。

存储表

policy_revision、policies(含可为空、最多 37 字节的 ja4_pattern 条件)、policy_inspection、ip_reputation、incident_receipts、security_incidents(含 256 字节的嵌入向量和可为空的 36 字节 ja4 指纹)、全文索引(SQLite 上为 incidents_fts,即基于规范词元的 FTS5;PostgreSQL 上为带 GIN 索引的 tsvector 列 search)以及 sibuna_schema;控制台另外增加 33 张 console_* 表。存储的动作、算法和模式名称均为小写。事件 ID 为 node_id << 40 | sequence,无需协调即可在集群内保持唯一;节点 ID 的范围为 1 到 8,388,607。

构建目标

表 32 构建与仓库命令
命令 结果
cargo build --release -p sibuna 带 SQLite 存储和控制台的守护进程(默认特性)
cargo build --release -p sibuna --no-default-features 不带存储和控制台、也不依赖任何外部 crate 的内存型守护进程
cargo build --release -p sibuna --features postgres-tls 还能通过经验证的 TLS 连接共享 PostgreSQL 数据库的守护进程(只启用 postgres 特性时不使用 TLS 连接)
cargo test 单元测试、针对运行中守护进程的集成测试、存储和控制台测试(设置 SIBUNA_TEST_DATABASE_URL 时包括 PostgreSQL 测试)
cargo clippy --all-targets, cargo fmt --check lint 和格式化(max_width = 99)
cargo xtask check 70 行函数、1,408 行文件和 99/108 列的行长度限制;不允许制表符
cargo xtask browser 在无头 Chromium 中进行的检查(sibuna-browser)
cargo xtask bench <primitives|product|latency> release 模式的基准测试;结果位于 benchmarks/results/<command>-latest.json
cargo build -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm 只构建浏览器模块(控制台界面用 -p sibuna-console-ui)
cargo run -p sibuna-geoip --bin geoip-snapshot -- ... 校验国家数据,并写出一个可嵌入的 GeoIP 快照
guidedog build / guidedog dsc 本书 / SID 记录

守护进程的构建脚本(cmd/sibuna/build.rs)用 wasm profile 把两个 WebAssembly 模块构建到工作区的目标目录中,并在控制台界面超过 768 KiB 时使构建失败。对于没有 wasm32-unknown-unknown 目标的构建,可以用 SIBUNA_POW_WASM 和 SIBUNA_CONSOLE_WASM 指定预先构建的模块。SIBUNA_GEOIP_DATA 指定要嵌入的 GeoIP 快照;它在构建时解码,不带控制台的构建会拒绝它(GEOIP001)。