第 IX 部分:运维与部署¶
我们介绍两种形态、每个命令行选项、forward-auth 配置方案、策略文件、SQLite 或 PostgreSQL 中的持久存储、基于一个共享数据库的集群,以及打包。
形态与配置¶
选择形态¶
- Gate(
--gate,别名--no-waf):工作量证明准入、会话、声明式规则、信誉、GCRA 限制、封禁。 - Shield(默认,
--shield,别名--waf):Gate 加上语义防火墙。 - 分布式部署(两种形态都可选用):
--data-dir把策略、信誉和取证数据保存在本地 SQLite 文件中;--database-url加上--cluster-node把多个节点连接到同一个 PostgreSQL 数据库(SID 0011)。
命令行参考¶
下表列出 sibuna --help 的每个选项。范围是解析器强制执行的范围。
| 选项 | 默认值 | 含义 |
|---|---|---|
--port, -p |
8080 |
监听端口,1 到 65535 |
--host, -h |
0.0.0.0 |
监听地址,一个 IP 地址字面量 |
--upstream-host |
127.0.0.1 |
源站主机(反向代理模式) |
--upstream-port, -u |
3000 |
源站端口 |
--mode, -m |
reverse_proxy |
reverse_proxy 或 forward_auth(也可写作 proxy 和 auth),只能给出一次 |
--workers, -w |
每个 CPU 一个 | 共享监听套接字的接受线程,0(每个 CPU 一个)到 64;之后每个被接受的连接都有自己的线程 |
--max-connections |
1024 |
同时服务的连接数,1 到 8192;超出的连接被回答 503 |
--max-connections-per-ip |
64 |
一个套接字对端地址可以持有的连接数,0(不限)到 8192;IPv6 对端按其 --ipv6-prefix 网络计数,转发头不起作用;超出的连接被回答 503 |
--idle-timeout |
15 |
最长静默时间(秒),0 到 86400。请求头部必须在此时间内到达。源站响应每次读取都会刷新它,因此只要有字节流动,慢速流就能存活,而静默的源站会在两个套接字上都被切断。经代理的上传必须在每个周期内传送 16 KiB(防御慢速请求体攻击的最低速率)。客户端套接字带有同样长度的写超时,因此一个在这么长时间内不接收任何字节的客户端会失去连接 |
--websocket-idle-timeout |
300 |
升级连接的空闲期限(秒),0 到 86400 |
--trust-forwarded |
关闭;forward-auth 模式下开启 | 信任对端发来的 X-Forwarded-For / X-Real-IP |
--no-trust-forwarded |
关闭 | 即使在 forward-auth 模式下也从不信任它们 |
--trusted-hops |
1 |
信任转发身份时,以从右数第 N 个 X-Forwarded-For 条目作为客户端,N 为该选项的值,取 1 到 8 |
--ja4-header |
关闭 | 受信任的入口代理用来发送客户端 JA4 TLS 指纹的请求头,例如 cf-ja4;1 到 64 个 token 字符,不能是 X-Forwarded-*、X-Real-IP、X-Sibuna-* 或 Forwarded。只有信任转发身份时才读取它(见“来自入口代理的 JA4 指纹”) |
--ipv6-prefix |
64 |
速率限制、封禁和按客户端连接上限所作用的 IPv6 前缀长度,32 到 128 |
--algorithm, -a |
posw |
posw 或 hashcash |
--difficulty, -d |
16 |
工作比特,1 到 64:Hashcash 的零比特数,或 PoSW 深度加三 |
--posw-challenges |
16 |
每个顺序工作量证明的揭示数,1 到 32 |
--token-scheme |
mac |
mac(带密钥 BLAKE3)或 ed25519 |
--token-ttl |
86400 |
会话有效期,秒(1 到 31,536,000) |
--challenge-ttl |
300 |
挑战有效期,秒(1 到 86,400) |
--secret-file, -s |
随机 | 64 个十六进制字符或 32 个原始字节;也接受 SIBUNA_SECRET(64 个十六进制字符) |
--cookie-name |
__sibuna_token |
会话 Cookie 名称,1 到 64 个 token 字符 |
--secure-cookie |
关闭 | 添加 Secure 属性 |
--gate / --shield |
shield | 形态选择 |
--rate-limit |
100 |
每个客户端每个窗口内的请求数(GCRA 突发量) |
--rate-window |
10 |
窗口长度(秒),1 到 86400 |
--challenge-rate-limit |
30 |
每个客户端每个窗口内的挑战签发和验证次数,与请求预算分开计算 |
--ban-seconds |
3600 |
蜜罐封禁时长,0 到 31,536,000 |
--policy-file, -P |
无 | 声明式 JSON 策略 |
--rate-table-cells |
262144 |
每张速率限制器表的单元数,每个 16 字节,4,096 到 16,777,216,向上取整为 2 的幂 |
--ban-table-slots |
65536 |
封禁表槽数,每个 24 字节,1,024 到 16,777,216,向上取整为 2 的幂 |
--spent-tags |
1048576 |
为防重放而记住的已解挑战数,每个 24 字节,65,536 到 16,777,216 |
--data-dir, -D |
无 | 单节点:持久化到 SQLite 文件 <path>/sibuna.db |
--database-url |
无 | 集群:共享的 PostgreSQL 数据库(postgres:// 或 postgresql://) |
--database-url-file |
无 | 从一个仅所有者可读的文件中读取数据库 URL |
--cluster-node |
无 | 本节点的 ID;绑定挑战密钥和事件标识符的高位;使用数据库 URL 时必需 |
--storage-poll-ms |
500 |
存储节拍间隔,1 到 60,000 ms |
--verbose, -v |
关闭 | 详细日志 |
--help / --version |
打印帮助(编译了控制台时,控制台选项列在最前)或版本号,然后退出 |
--data-dir 与数据库 URL 互斥,--database-url 与 --database-url-file 也互斥。没有 --cluster-node 的数据库 URL 会被拒绝。Zaxonlite 的集群选项 --cluster-listen、--cluster-peer、--cluster-secret-file 以及 --cluster-tls-cert、--cluster-tls-key 和 --cluster-tls-ca 已被移除;给出其中任何一个都会以 RemovedOption 终止启动,并附带一条指向 SID 0011 的提示。控制台的选项列在下一章。
控制台预览¶
默认的 console 特性会把控制台编译进守护进程,但只有使用 --console 时才会启动。它需要存储:没有 --data-dir 或 --database-url 的 --console 会以 CONSOLE001(StorageRequired)被拒绝。使用 cargo build --release -p sibuna --no-default-features --features sqlite 可以把它排除在编译之外;只用 --no-default-features 的构建既没有存储也没有控制台。在守护进程停止时于本地完成初始化:
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446
sibuna console init-admin 是同一个命令。打开 http://127.0.0.1:19446/console/ 并更换生成的临时密码;该密码必须在首次登录时修改,一小时后过期。登录后的导航提供动画国家地球、请求和挑战统计、事件调查、策略和检查编辑器、用户、限定范围的 API 令牌、审计以及服务节点控制。认证界面不加载任何地球几何数据或遥测数据。界面是一个由守护进程的构建脚本从 cmd/console-ui(crate sibuna-console-ui)构建的 WebAssembly 模块;它和已提交的样式表随普通构建一起发布。
| 选项 | 含义 |
|---|---|
--console <ip:port> |
在这个监听地址上启动控制台(IPv6 放在方括号中,端口非零);需要 --data-dir 或 --database-url |
--console-key-file <path> |
64 个十六进制字符,仅所有者可访问;保护存储的第二因素密钥和 webhook 密钥 |
--console-origin <https-origin> |
代理之后的规范 HTTPS origin |
--console-behind-proxy |
每个请求都经由一个终止 TLS 的代理送达 |
--console-trusted-proxy <cidr> |
一个其连接可以携带转发字段的网络;可重复,最多 16 个 |
--console-advertise <origin> |
其他控制台为本控制台显示的链接 |
--console-location <latitude,longitude> |
本节点在地球上声明的位置 |
--console-probe <node-id>=<http://ip:port> |
一个需要健康检查的对等数据平面监听地址;可重复,最多八个 |
--console-peer <node-id>=<https://origin> |
一个管理对等节点;可重复,最多八个 |
--console-peer-key-file <path> |
对等密钥:仅所有者可访问,64 个十六进制字符,独立于控制台密钥 |
--console-peer-ca-file <path> |
可选的对等节点 PEM 信任锚,替代系统根证书 |
--console-query-steps <n> |
每次聚合读取的 SQLite 步数,100,000 到 50,000,000,默认 4,000,000 |
--console-capture-heads |
为每个事件存储脱敏后的请求头部和源站响应头部;默认关闭 |
--console-capture-header <name> |
在存储的头部中保留这个头字段的值;可重复,最多 16 个;需要 --console-capture-heads |
--console-cookie-secure |
在没有代理的情况下为控制台 Cookie 加上 Secure 属性(解析器接受,但不在 --help 中列出) |
没有 --console 的控制台选项、重复的选项或格式错误的值,会以 CONSOLE002 和该选项的错误名称终止启动。违反控制台规则的配置(例如没有受信任代理却监听非回环地址)会以 CONSOLE001 终止启动。
控制台导览¶
下面的截图来自一个 release 构建,运行在一个带 SQLite 存储的回环节点上,策略是在默认挑战之上加四条 ALLOW 规则,截图前运行了大约四分钟的合成流量:来自文档地址段的地址、SQL 注入和跨站脚本探测、三次蜜罐命中,以及在无头 Chromium 中解出的七个挑战。因此,每个数字都只是示意。我们用 cargo xtask browser console --viewport-only 截取它们,该命令在 1440 x 960 像素的 Chromium 中遍历控制台,并检查每个页面。每个页面回答其标题中提出的一个问题,并在同样的位置显示产品、服务节点、当前页面和返回路径。
waf:sqli 和 waf:xss)。未记录的值会如实说明,而不是显示为零:信誉指标卡片显示 “Not recorded”。页面再往下是按六十个等宽时间桶统计的检出结果、攻击类别和被攻击的路径。¶
--console-capture-heads 时,脱敏的请求头部(对于经反向代理、处于审计模式的准入,还有源站响应头部)可以按需展开,以 UTF-8 或 Latin-1 渲染,并注明响应情况(已捕获、本地响应、forward-auth 下未观测、源站不可用),附带一条 “复制为 cURL” 命令;只保留列出的头字段的值,--console-capture-header <name> 可以向该列表中添加。否则头部显示为未记录。拒绝和放行动作会打开 IP 组表单,并预先填好地址。¶
可选的 --console-location <latitude,longitude> 声明本节点的位置,例如新加坡的部署为 1.3521,103.8198。地球最初以该点为中心;旋转之后,Center Sibuna 会回到该点。各国的活动沿着朝向节点的动画大圆弧显示,背面半球和平面地图上的日期变更线会被裁剪。国家位置是具有代表性的中心点,箭头表示观测到的六十秒窗口,而不是单个连接。未设置的服务器位置明确保持为未知。遥测中断期间,配置的标记仍然可见;过时的流量不会产生动画。
策略预览会构建一个包含已配置文件规则的私有候选。保存时会比较预期的修订版本,并要求确认字段对比。历史回退会与当前规则比较,并创建一个新的修订版本。已提交的修订版本与本地已应用的修订版本是不同的。审计详情保留有界的决策变化以及实际生效的执行角色。匹配器的值会被脱敏,缺少上下文的旧记录明确保持为缺失。排空、恢复和清除本地封禁需要先预览命令。当节点上另一条命令正在运行时到达的命令会以 503 CONSOLENODE 被拒绝,而不是排队。丢失响应后,先检查持久化的回执再重试;仅凭已提交的意图并不能说明运行时效果已经完成。
远程运维时,请使用 HTTPS 代理,并配置 --console-origin、--console-behind-proxy、明确的 --console-trusted-proxy CIDR 和 --console-key-file。密钥文件包含 64 个十六进制字符,权限仅限所有者,用于保护存储的第二因素密钥;重启时要保留它,并与挑战种子分开保存。对于非回环访问,配置的 HTTPS origin 和代理允许列表是必需的。Sibuna 在控制台监听地址上同样不终止入站 TLS;控制台只在其出站连接中通过 rustls 使用 TLS(SID 0012)。
原生 CLI 通过相同的授权和存储约定访问运行中的控制台。它从私有文件中读取凭据,而不是从命令行参数中读取:
sibuna console geoip update --version 2026-09-09 \
--origin http://127.0.0.1:19446 --username admin \
--password-file ./admin-password
请使用仅所有者可读的密码文件,先完成密码设置,并在需要时为认证器代码或恢复代码加上 --factor-file;对于账户和 GeoIP 操作,--token-file 可以代替用户名和密码。客户端使用 HTTP/1.1,除字面量回环地址外都要求 HTTPS,从不跟随重定向,并把每个请求限制在 20 秒以内、每个回复限制在 16 KiB 以内。geoip status 读取当前生效的数据代。更新时通过 HTTPS 下载所选提供方发布的文件(默认是公有领域的 user-country 数据集,或用 --provider dbip --version YYYY-MM 选择 DB-IP Lite),校验发布者的校验和(或 --checksum 给出的校验和),通过 sibuna-geoip 验证有界的地址范围,持久化新的数据代并在本地激活。失败的更新会保留之前的数据代。CLI 超时(--timeout,默认 1200 秒)只是停止等待;它不会取消已提交的存储工作。DB-IP Lite 要求 CC BY 4.0 署名,只在其数据生效期间显示。使用 SIBUNA_GEOIP_DATA=<snapshot> 的构建会嵌入一个经过验证的快照(由 geoip-snapshot 工具写出),直到第一次持久导入为止;不带控制台的构建会以 GEOIP001 拒绝它。未知地址、样本丢失和过时数据都保持可见;导入国家数据不会产生流量,也不会补充已经过期的样本。
集群成员在启动时、每分钟一次,以及已应用的策略或控制修订版本变化后的两秒内,通过共享数据库的成员表(console_nodes)通告自己,并出现在每个控制台的节点页面上。没有领导者选举:SQLite 节点报告角色 single 并以自己为领导者,PostgreSQL 节点报告角色 unknown 且没有领导者,因为 PostgreSQL 的故障切换对 Sibuna 不可见(SID 0007)。为需要由本控制台对其数据平面监听地址进行健康检查的对等节点配置 --console-probe <node-id>=<http://ip:port>,并用 --console-advertise <origin> 配置其他控制台显示的链接。直接的实时遥测使用 --console-peer <node-id>=<https://origin>(可重复,最多八个)和专用的 --console-peer-key-file。对等节点需要 --console-behind-proxy。两端必须相互列出对方,并使用受信任的 HTTPS 入口。对等密钥是一个仅所有者可访问、包含 64 个十六进制字符的文件,与控制台密钥和挑战种子分别配置。对等节点之间通过一个经过认证的 TLS WebSocket 通信,使用带 ring 提供方的 rustls(SID 0012)。--console-peer-ca-file 可选地为私有管理 PKI 提供 PEM 信任锚;否则客户端使用系统根证书。主机名验证始终生效且无法关闭:每个管理 origin 的主机(DNS 名称或 IP 地址字面量)必须出现在对等节点的证书中。被拒绝的证书会把该对等节点标记为 rejected,并写入一条 peer.rejected 审计记录。轮换密钥和更换 CA 文件需要协调重启;对等节点的证书可以在不重启的情况下续期。节点 API 及其订阅会报告接收时延、时钟偏差、启动变化和采样丢失。缺失的观测保持为不可用,断开连接的值保持为过时;收到的统计数据永远不会变成另一个节点自己的贡献。仪表板的 Live traffic scope 选择一个节点,或合并已配置的各节点。Node coverage and locations 标出缺失、过时和存在时钟偏差的来源、观测时间和配置的目标位置。国家排名显示由被省略的来源行带来的不确定性。箭头保留其接收节点,缺失的节点位置不会被凭空捏造。只要任何一个参与的来源缺少一个连续的时间间隔,合并后的速率就保持为未观测。选择一个节点可以查看它保留的秒级数据和当前分钟的路径排名。远程查询使用经过认证的对等连接;查询结果必须能放进一条 4 KiB 的 WebSocket 消息,因此当一页放不下时,提供服务的控制台会把该页的行数减半。缺失的对等节点保持为不可用,历史游标不能跨越节点重启。分钟历史保留它自己的节点选择和按节点的行。导航栏和移动端页头标识的是提供服务的控制台节点,与所选的流量来源无关。本地命令仍然按节点执行。
流量指标卡片默认显示所选节点最近 24 小时保留的已结束分钟记录。时间段控件还提供一小时、七天或九十天,以及实时的本次启动总数。与昨天的偏差需要每个所选节点都有完整匹配的覆盖。地球和迷你走势图仍然描述它们各自独立的实时 60 秒窗口。保留数据的扫描在完成一分钟后刷新,在被替换之前保持之前的值及其时效可见;更换来源或时间段会丢弃旧的范围。缺失的历史永远不会变成零。
Compare retained traffic 把两个已结束的分钟窗口并排显示:昨天的同一窗口、前一个时间段,或另一个节点。时长和结束偏移控件会冻结两个 UTC 范围。每次操作每侧最多读取十六个紧凑页面,每页 96 条存储记录。这可以在一个批次中覆盖一个不跨越重启的 24 小时窗口;Continue 会为更长的扫描保持相同的边界。完整覆盖、不完整覆盖和缺失历史都会明确标出。速率百分比要求在相等的 UTC 窗口中有完整且不重叠的时间间隔,并按观测到的毫秒数归一化;参考值为零而出现新流量时显示 “New”。主流量时间段保持独立。分钟格式不记录历史的代理模式,因此源站响应的比较保持为不可用,而不是把 forward-auth 下的零解读为观测到的响应。
Compare retained path rankings 选择两个已结束的窗口或节点。节点 0 包括所有保留的节点,包括已退役的成员。一次操作最多读取十六个不可变的归档,检查它们的标识和校验和,并在选择显示行之前合并所有计数器。归档在 60 秒的迟到样本窗口之后封存,因此最新的已结束分钟可能仍在等待中。Continue 保持原来的窗口和游标。边界描述的是抽样的路径前缀,而不是精确的请求总数。页面会显示部分扫描、截断、保留期边界和报告的队列丢失;缺失的归档不能证明流量为零或覆盖完整。
安全视图默认显示最近 24 小时,并把所选时间段分成六十个等宽的时间桶。它的聚合在存储线程上运行,并受一个工作量上界的约束。在 SQLite 上,这个上界是 --console-query-steps 个虚拟机步数(100,000 到 50,000,000,默认四百万)。它与 --console 一起设置;无效或重复的值会被拒绝。在 PostgreSQL 上,这个上界是在读取事务中设置的 2,000 ms 语句超时(SID 0013);修改 --console-query-steps 不会改变它。耗尽上界的查询会提示缩小时间段。步数限制的是查询工作量,而不是经过的时间。各图表共享同一刻度;展开趋势值可以看到 UTC 区间的起点和精确的分组计数。这些都是保留的检出结果,因此缺失的事件覆盖不能被解读为没有攻击。
大屏显示使用大屏会话。在 Account 下,运维人员为显示屏命名,然后选择 Create display code。显示屏需要在十分钟内把这个一次性代码粘贴到登录表单中;它的会话是只读的,仅限于统计,并在十二小时内过期。账户页面在导航离开或被隐藏时会清除显示的代码。隐藏不会撤销一个尚未使用的授权;兑换期限仍然有效。代码绝不应出现在 URL 中。流量和安全视图共用显示屏:安全视图显示聚合的模块趋势和请求结果,不显示事件地址或载荷证据。自动轮播是可选的,初始关闭,在减少动态效果、数据过时或 Pause 时暂停。
通知目标(针对拒绝激增、封禁、不可达成员和领导者变更的签名 webhook 和 syslog)位于 Settings 下;webhook 密钥需要 --console-key-file。领导者变更这一类型仍然保留定义,以便已存储的目标保持其含义,但没有任何节点会触发它,因为没有领导者选举。每个目标有自己的冷却时间和三次尝试的重试预算。投递审计记录显示结果;已完成的队列历史限制为七天和 4,096 个事件。webhook 包含一个稳定的 Idempotency-Key,使接收方可以在网络完成情况不确定时抑制重复的效果。webhook 通过 HTTPS 发送,只有发往字面量回环地址时才使用普通 HTTP,回复体最多读取 64 KiB。syslog 的 UDP/TCP 选择只适用于出站通知,与受保护的 Web 流量无关。手动测试会在审计中记录意图和完成情况,并刷新目标的结果;未确认的审计完成情况会在运维人员重试之前明确显示。
Settings 还控制保留期:分钟历史为 1 到 90 天,排名为 1 到 7 天,事件为 1 到 30 天,审计为 1 到 365 天。上限值即默认值;排名保持其 512 MiB 的配额。保存保留期的值需要确认,因为清理会以有界批次永久删除较旧的记录。之后再增大这个值也不会恢复已删除的历史。过时的修改会被拒绝,成功的修改会出现在审计中。
响应页面(挑战、拒绝、限速、封禁、过载)可以在 Settings 下以带固定占位符的有界 HTML 形式编辑;草稿在一个沙箱标签页中预览,保存的页面从下一个策略快照开始提供。
策略页面上的策略工作流程:对托管规则重新排序,针对保留的检查检出结果重放草稿,管理 IP 组和固定到当前 GeoIP 数据代的国家封锁,以及导出或以原子方式导入托管规则集(也可以用 sibuna console policies export 和 sibuna console policies import --file <set.json>)。一次导入是一个请求,携带 1 到 128 个文档,每个最多 4 KiB,总计最多 256 KiB;对于超过约 96 KiB 的规则集,页面说明会指出命令行导入方式。已应用的规则显示今天记录的命中次数、按小时的迷你走势图和一张无障碍表格。一次命中是指一次成功的声明式匹配器评估:匹配的 WEIGH 规则和第一个终止性匹配都会计数;更早的检查或信誉决定可能使评估不会发生。私有测试不会递增这些计数器。Compare rule hits 为一个已记录的节点冻结两个已结束的时间段。修订历史提供 Compare hits around this edit,它排除修改所在的那一分钟,并使用不超过所选时长的相等可用时间段。可选的已应用修订版本筛选器可以把无关的数据代排除在比较之外。启动、切换、缺失的写入和保留期都会留下可见的覆盖缺口;百分比要求两侧都有完整覆盖。规则观测以及按小时/按天的汇总遵循分钟保留期设置。在一次修改前后观测到的变化只是一种比较,并不能证明是这次修改导致了流量变化。
导入较新的 GeoIP 数据代不会自动刷新已有的、由国家派生的信誉行。先预览国家动作,比较新增、保留和移除的前缀;在应用之前翻阅审阅过的差异。替换会移除该国家所拥有的过时行,并保留独立管理的前缀。数据代或策略修订版本发生变化后需要重新预览,相互重叠的独立修改会被拒绝。事件页面包含保留的 WAF 检出结果和蜜罐事件;它不是完整的访问日志。加载了 GeoIP 时,存储线程会在事件批次的事务中记录每个事件的国家和数据代。这是持久化时的归属,而不是重建出的请求时刻位置。之后的导入不会改变已记录的映射。国家筛选器接受一个大写的两字母代码,unknown 表示不在已加载数据代中的地址,not_recorded 表示没有映射数据的事件。来源分组会明确报告混合的国家或覆盖情况。地球的 View events 动作保持所选节点,并打开该国家最近一小时内保留的事件。统计页面的 Security 视图把实时的限速、挑战和封禁速率,与一小时、一天、七天或三十天内保留的检查和蜜罐检出结果结合起来。类别、来源和路径链接以相同的节点和固定的时间边界打开常规的事件工作流程。应用事件筛选器会开始一个新的时间段。检出结果包括审计记录,与被阻止请求的总数不同;缺失的信誉和规则命中归属显示为未记录。事件和审计筛选器让标签与其控件保持在一起,把 Apply 动作单独对齐,并让列宽适应可用的内容宽度。一个经过认证的 WebSocket 在导航过程中始终存活,承载统计、事件摘要、节点状态、策略修订版本、挑战和审计摘要。新的事件和审计记录在 Load latest records 之后等待,使表格在阅读时保持不动。策略更新会显示当前已提交和已应用的修订版本,而不会替换打开的草稿。流量计数器实时更新;所选的非默认挑战计时分区需要显式刷新。历史查询、详情读取和变更操作仍然是 HTTP 请求。
页面片段可以加入书签;后退和前进会重新打开需要认证的页面。侧边栏还会在本浏览器中记住主题和间距设置,默认主题为 System。SID 0007 的状态为 Committed。控制台在无头 Chromium 中通过了黄金样例和浏览器工作流测试(cargo xtask browser console,SID 0010 标准 5)。它的端到端测试套件是 cmd/sibuna/tests/console_*.rs,其中的 PostgreSQL 集群场景在设置了 SIBUNA_TEST_DATABASE_URL 时运行。SID 0010 记录:无论控制台是编译进来但停用、只启用存储,还是启用但空闲,16 个产品工作负载与不含控制台的守护进程构建之间的差异都在约 1% 以内,处于噪声范围。SID 0007 的正式隔离门槛,即在负载下运行八个活动仪表板,尚未测量(第 VIII 部分)。完整的 WebAssembly 应用有 768 KiB 的未压缩上限,守护进程的构建脚本在超出时使构建失败;另有 640 KiB 的审查阈值。在 1.0.0-beta.3 中,该模块大小为 724,330 字节(gzip 压缩后 272,568 字节),超过了审查阈值,SID 0007 已将其记录待审。这些项目限制为控制台的工作流留出了空间;它们不能代替对浏览器加载速度和响应速度的测量。模块的线性内存按需增长,声明的上限为 16 MiB。
部署拓扑¶
反向代理¶
sibuna --port 80 --upstream-host 127.0.0.1 --upstream-port 3000 \
--secret-file /etc/sibuna/secret --difficulty 16 --algorithm posw
被准入的请求带着 X-Forwarded-For、X-Forwarded-Proto、X-Real-IP、X-Sibuna-Status 和 X-Sibuna-Rule 头到达源站。逐跳头、Sibuna 自己写入的字段以及其他转发字段(Forwarded、X-Forwarded-Host、X-Forwarded-Port)都会被剥离,客户端用下划线拼写这些名称(X_Forwarded_For)时也是如此。X-Real-IP 是判定请求所依据的客户端。X-Forwarded-For 只是套接字对端,从不包含客户端写入的条目;信任转发身份时,它是收到的链后面再加上套接字对端。因此,源站必须从 X-Real-IP 或 X-Forwarded-For 的右侧读取客户端,绝不能读取其最左边的条目。源站收到的路径是策略所判定的规范形式(SID 0009);没有规范形式的路径会被回答 400。
HTTP/1.1 WebSocket 升级在源站的握手被接受之前,要先通过准入和策略检查。子协议和扩展的协商保持端到端。两个线程中继字节,每个方向一个,各自使用一个固定的缓冲区,包括预取的字节和半关闭;因此,一个升级后的连接占用两个线程,当所有连接都被升级时,连接线程的数量可以达到 --max-connections 的两倍。升级后的套接字仍然受普通连接配额和关闭登记表的约束,但使用 --websocket-idle-timeout(默认 300 秒),与 HTTP 空闲期限相互独立。任一方向的流量都会刷新这个上界,但如果一个对端在整个周期内不接收任何字节,无论另一个方向多么繁忙,中继都会结束。握手之后的帧不是 WAF 检查的输入。HTTPS/WSS 需要在 Sibuna 私有的 HTTP/1.1 监听地址之前放置一个终止 TLS 的入口代理;Sibuna 自己不终止浏览器的 TLS。
入口代理可以与浏览器协商 HTTP/2,并以 HTTP/1.1 转发给 Sibuna。Sibuna 对原生 HTTP/2 的支持推迟到以后的更新;这种安排不能为原生 gRPC 之类的应用提供端到端的 HTTP/2 语义。
带 Content-Length 的请求体以流方式通过固定缓冲区,字节和 MIME 头都保持不变。multipart 上传保留边界、重复的字段名、文件名和各部分的类型。WAF 最多检查请求体的前 8 KiB:multipart 元数据和非文件字段仍然作为文本检查的输入,而文件载荷是不透明的。filename 为空的部分是普通字段。属于已识别的二进制顶层 MIME 类型(SVG 以外的图像、音频、视频、PDF、ZIP、gzip、7z、protobuf 和 octet-stream)的请求体,只有当其前缀看起来也是二进制时才被视为不透明,即每十六个字节中至少有一个是制表符、换行、垂直制表、换页和回车以外的控制字节;否则按文本检查(SID 0004)。JSON、XML、SVG、URL 编码表单和未知类型保持文本检查。含糊或格式错误的 MIME 元数据会回退到文本检查。multipart 解析在同一前缀内限制为 32 个部分、每部分 2 KiB 的头部,并接受分隔符之后符合 RFC 2046 的传输填充。
这是上传兼容性,而不是文件验证或恶意软件扫描。后端必须自己强制执行可接受的媒体类型,而不是信任客户端声明的 Content-Type。检查前缀之后的字段(包括大文件上传之后的字段)不会被检查。压缩的载荷不会为检查而解压。上传仍然要经过准入、路径、查询和请求头检查,并受连接期限的约束。分块请求体在检查之前于连接缓冲区内解码(SID 0009)。在缓冲区内结束的请求体以 Content-Length 到达后端。更长的请求体由 Sibuna 重新分块,每次读取一个块,因此后端永远看不到客户端的块大小、扩展或尾部字段。包含单独的 CR 或 LF、大小两侧有空白、扩展格式错误或超过 4 KiB 的块行会以 400 被拒绝。超过 16 KiB 的尾部字段段也是如此。使用其他编码的 Transfer-Encoding 会收到 501。无法解析分块请求的后端,对于约 44 KiB 以下的请求体仍然会收到 Content-Length。承载过请求体的源站连接在交换结束后关闭,永远不会回到连接池。等待 100-continue 的客户端会在发送请求体之前从本地收到它;不支持的期望会收到 417。Expect 头在转发给后端之前被消费掉。
入口代理之后的 forward-auth¶
在 --mode forward_auth 下,守护进程对入口代理的子请求回答 200(外加审计头 X-Sibuna-Status、X-Sibuna-Rule 和 X-Sibuna-Rule-Hash),需要挑战时回答 401,拒绝时回答 403,被限速时回答 429。入口代理必须转发客户端地址和原始 URL;forward-auth 模式默认信任它们。请把这个监听地址绑定在私有网络上,使只有入口代理能够连接。X-Forwarded-Uri(Caddy)或 X-Original-URI(Nginx)以及 X-Forwarded-Method 为策略评估还原应用请求;原始路径会像请求行中的路径一样被转换为规范形式。重复或相互冲突的原始 URL 字段,以及不是 origin-form 的原始 URI,会以 400 被拒绝。守护进程的内部路由始终使用实际的请求 URI。forward auth 不检查入口代理省略的请求体。
map $http_upgrade $sibuna_connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
location / {
auth_request /__sibuna_auth;
auth_request_set $sibuna_auth_status $upstream_status;
auth_request_set $sibuna_retry_after $upstream_http_retry_after;
auth_request_set $sibuna_status $upstream_http_x_sibuna_status;
auth_request_set $sibuna_rule $upstream_http_x_sibuna_rule;
auth_request_set $sibuna_rule_hash $upstream_http_x_sibuna_rule_hash;
error_page 401 = @sibuna_challenge;
error_page 500 = @sibuna_auth_error;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $sibuna_connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Sibuna-Status $sibuna_status;
proxy_set_header X-Sibuna-Rule $sibuna_rule;
proxy_set_header X-Sibuna-Rule-Hash $sibuna_rule_hash;
proxy_read_timeout 300s;
proxy_pass http://127.0.0.1:3000;
}
location = /__sibuna_auth {
internal;
proxy_pass http://127.0.0.1:8080/;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Uri "";
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header User-Agent $http_user_agent;
proxy_set_header Cookie $http_cookie;
}
location @sibuna_challenge {
rewrite ^ /__sibuna/challenge break;
proxy_pass http://127.0.0.1:8080;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
location @sibuna_auth_error {
add_header Retry-After $sibuna_retry_after always;
if ($sibuna_auth_status = 429) { return 429; }
return 503;
}
location /__sibuna/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
example.com {
handle /__sibuna/* {
reverse_proxy localhost:8080
}
handle {
forward_auth localhost:8080 {
uri /
header_up X-Forwarded-For {remote_host}
header_up -X-Original-URI
copy_headers X-Sibuna-Status X-Sibuna-Rule X-Sibuna-Rule-Hash
}
reverse_proxy localhost:3000
}
}
在两种配置方案中,/__sibuna/* 命名空间(验证中间页、挑战、验证、求解器资源)都必须直接到达守护进程。nginx 的错误页面会传递原始 URI 和方法,使验证中间页携带授权所决定的要求;没有它们时页面仍然可用,签发会回退为评估浏览器上报的 URL。Caddy 自己提供原始 URI 和方法的元数据。互斥的 handle 块确保挑战和验证路由不会进入 forward-auth 预检查。对于应用的 WebSocket,Nginx 需要上面所示的显式 Upgrade/Connection 头。Nginx 的错误处理器渲染内部挑战路由时,不会进行第二次授权决定,也不会消耗上传的请求体。它的 auth 模块只直接接受 2xx、401 和 403,因此示例把限速导致的认证错误转换回带 Retry-After 的 429;其他授权失败以 503 保持关闭。Nginx 提供它自己的 403 响应体,而 Caddy 转发 Sibuna 的拒绝页面。两种配置方案都会用实际的授权响应替换传入的 Sibuna 审计头。请在入口代理上配置常规的 TLS 证书以及应用的上传和期限限制;示例只展示路由逻辑。仓库目前还没有针对真实运行的入口代理测试这些配置方案;它们所依赖的转发元数据规则由 sibuna-http 中的单元测试覆盖。
来自入口代理的 JA4 指纹¶
JA4 指纹概括了客户端如何建立 TLS 连接。它根据客户端的第一条握手消息,即 ClientHello,计算得出。客户端的 TLS 库在发送任何 HTTP 字节之前就确定了这条消息,因此客户端无法在自己的 HTTP 请求内部改变它的指纹。浏览器、库和机器人的指纹各不相同。这使 JA4 成为比 User-Agent 值更强的信号,因为后者任何客户端都可以随意填写(SID 0014)。JA4 由 FoxIO 定义。一个指纹有 36 个字符,分为三部分,用 _ 连接:
t13d1516h2_8daaf6152771_02713d6af862
^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^^
a b c
a 协议(t 为 TCP,q 为 QUIC,d 为 DTLS),TLS 版本(13 即 TLS 1.3),
带 SNI 为 d、不带为 i,密码套件数(两位数字),
扩展数(两位数字),ALPN 代码(h2 即 HTTP/2)
b 排序后的密码套件的哈希,12 位小写十六进制数
c 排序后的扩展和签名算法的哈希,
12 位小写十六进制数
只有终止 TLS 的组件才能看到 ClientHello,因此只有它能计算 JA4。Sibuna 不终止 TLS:它在入口代理之后提供普通的 HTTP/1.1 服务,由入口代理与浏览器使用 TLS、HTTP/2 和 HTTP/3 通信。已经有几种入口代理能够计算 JA4。因此,我们让入口代理计算指纹并通过一个请求头发送,Sibuna 从该请求头中读取它。
--ja4-header <name> 指定这个请求头。它默认关闭,也没有默认名称;我们总是写出入口代理所用的请求头名称。Sibuna 以小写形式保存该名称,匹配时不区分大小写。它拒绝自己写入或剥离的字段名(X-Forwarded-*、X-Real-IP、X-Sibuna-* 和 Forwarded,也包括用 _ 代替 - 的写法)。设置该选项后,启动横幅会打印一行,例如 JA4: from cf-ja4 (trusted)。
只有信任转发字段时才会读取该请求头。这与决定是否信任 X-Forwarded-For 的条件相同:--trust-forwarded,或者没有 --no-trust-forwarded 的 forward-auth 模式。来自不受信任对端的该请求头会被忽略。在信任的情况下,当恰好存在一个该名称的字段且其值符合 JA4 格式时,请求才带有指纹。格式错误的值或重复的字段会使请求没有指纹。两个计数器观测这一点:sibuna_ja4_present_total 统计带有指纹的请求,sibuna_ja4_invalid_total 统计请求头格式错误或重复的请求。来自不受信任对端的请求不会增加任何一个计数器。
在反向代理模式下,只有当 Sibuna 信任该请求头时,源站才能看到它。不信任时,Sibuna 会从发往源站的请求中删除所有该名称的字段,客户端用 _ 代替 - 拼写名称时也是如此。因此,客户端无法以该名称向源站递交伪造的指纹。信任时,该字段以其原有的拼写原样通过,而使用 _ 的别名仍会被删除。没有 --ja4-header 时,该名称的字段只是一个普通字段。
Cloudflare。 托管转换 “Add bot protection headers” 会在发往源站的请求中加入 cf-ja4,与 cf-bot-score、cf-verified-bot 和 cf-ja3-hash 并列。它需要带有 Bot Management 的 Enterprise 套餐。Cloudflare 与 Sibuna 之间的入口代理必须原样传递该字段。我们这样启动 Sibuna:
sibuna --ja4-header cf-ja4 --trust-forwarded -s /etc/sibuna/secret
Sibuna 前面的入口代理必须只接受来自 Cloudflare 地址的连接;否则客户端可以绕过 Cloudflare,发送它自己的 cf-ja4。
nginx。 FoxIO 的 ja4-nginx-module 在 nginx 内部计算 JA4,并将其作为 $http_ssl_ja4 提供。它需要 nginx 1.26 或更高版本,并打上该模块的 ClientHello 捕获补丁,使用 --with-http_ssl_module 构建。proxy_set_header 会替换客户端发来的同名字段,因此每个到达 Sibuna 的 location 都自己设置该请求头:
# 反向代理:Sibuna 以 --ja4-header x-ja4 --trust-forwarded 运行
location / {
proxy_set_header X-JA4 $http_ssl_ja4;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_pass http://127.0.0.1:8080;
}
# Forward auth:Sibuna 以 --mode forward_auth --ja4-header x-ja4 运行
location = /__sibuna_auth {
internal;
proxy_pass http://127.0.0.1:8080/;
proxy_set_header X-JA4 $http_ssl_ja4;
# ... 上文 forward auth 配置中的其余字段
}
在 forward-auth 配置方案中,同样的 proxy_set_header X-JA4 $http_ssl_ja4; 这一行也应放在 @sibuna_challenge 和 location /__sibuna/ 中。省略它的 location 会把客户端自己的 X-JA4 传给 Sibuna,而 Sibuna 会信任它。
Apache Traffic Server。 ja4_fingerprint 插件通过 plugin.config 中的 ja4_fingerprint.so 这一行启用。它没有选项。它会在每个 TLS 连接的请求中加入一个带有指纹的 ja4 字段,以及一个带有代理名称的 x-ja4-via 字段。我们用 --ja4-header ja4 --trust-forwarded 启动 Sibuna。该插件的文档没有说明它是否会替换客户端发送的 ja4 字段。在信任该值之前,我们必须针对自己使用的版本确认这一点,或者在插件加入自己的字段之前删除客户端的字段。
规则用 ja4 字段匹配指纹(第 X 部分“策略模式”)。该值要么是一个完整的指纹,此时必须与之相等;要么是一个后跟 * 的前缀,此时指纹必须以它开头。单独的 "*" 匹配任何指纹。没有指纹的请求永远不会匹配 ja4 规则。加载器会以 INVALID POLICY JA4 拒绝任何指纹都无法匹配的模式,例如大写的 T13D*。匹配只比较字节,不分配任何内存。
{ "rules": [
{ "name": "deny-known-scanner", "action": "DENY",
"ja4": "t13i010400_0f2cb44170f4_5c4c70b73fa0" },
{ "name": "weigh-no-sni", "ja4": "t13i*", "action": "WEIGH", "weight": 15 },
{ "name": "weigh-headless", "user_agent": "Headless", "action": "WEIGH",
"weight": 30 },
{ "name": "challenge-tls12-checkout", "path": "/checkout/*", "ja4": "t12*",
"action": "CHALLENGE" }
] }
第一条规则精确拒绝一个指纹;该值只是一个示例,并不是某个已知的扫描器。接下来的两条规则不直接作出决定,而是为请求的分数增加权重:一个没有发送服务器名称的 TLS 1.3 客户端,以及一个通过 User-Agent 识别出的无头浏览器。如果后面没有规则先作出决定,同时表现出这两个信号的请求得分为 45,达到默认的拒绝阈值 40,而只表现出其中一个信号的请求会被挑战。最后一条规则按前缀挑战在结账路径上通过 TCP 协商 TLS 1.2 的每个客户端。它选择挑战而不是拒绝,因为许多合法的旧客户端仍在使用 TLS 1.2。规则应该像这样把 JA4 与其他信号结合起来。JA4 值指明的是一个 TLS 库及其配置,而不是一个人或一台设备。许多客户端共用同一个库,而专门的库可以模仿浏览器的 ClientHello。JA4 提高了自动化的成本;它不能证明身份。出于同样的原因,Sibuna 的封禁和信誉始终以地址为键,从不以指纹为键。
事件(WAF 拒绝、蜜罐命中和审计检出结果)在其请求带有指纹时会记录该指纹,保存在 security_incidents.ja4 列中。控制台在事件证据中以 “JA4 fingerprint” 显示它,内容为该值或 “Not recorded”。事件页面的筛选器接受指纹或前缀。托管规则编辑器有一个 JA4 字段,保存在 policies.ja4_pattern 中;策略测试表单也接受指纹。
声明式策略¶
{
"default_action": "CHALLENGE",
"waf": true,
"thresholds": { "challenge_at": 10, "deny_at": 40, "bits_step": 5 },
"ip_rules": { "10.0.0.0/8": "ALLOW", "192.0.2.0/24": "DENY", "2001:db8::/32": "DENY" },
"rules": [
{ "name": "deny-cf-workers", "headers": { "CF-Worker": ".*" }, "action": "DENY" },
{ "name": "deny-amazonbot", "user_agent": "Amazonbot", "action": "DENY" },
{ "name": "api-with-key", "path": "/api/*", "headers": { "X-Api-Key": ".*" },
"action": "ALLOW" },
{ "name": "protect-checkout", "path": "/checkout/*", "action": "CHALLENGE",
"challenge": { "difficulty": 20, "algorithm": "posw" } },
{ "name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30 },
{ "name": "internal-vpc", "remote_addresses": ["10.0.0.0/8", "fd00::/8"],
"action": "ALLOW" }
]
}
加载器采用失败即关闭(fail closed)的策略:一个未知的键、一个拼错的动作、一个格式错误的地址或一个超出范围的数字都会使整个文件被拒绝,诊断信息会指出规则和字段,守护进程不会启动。带有未知选项或超出范围的值的命令行也以同样方式被拒绝。存在 rules 时,它替换内置的规则表;ip_rules 为信誉字典树提供数据,可以扩展到数千个前缀;waf: false 从文件中选择 Gate 形态。模式中还有两个键(第 X 部分):inspection 把每个 WAF 类别设置为 disabled、audit 或 enforce,规则的 limits 对象为它设定自己的配额。规则的 ja4 字段匹配受信任的入口代理转发的 JA4 指纹,可以精确匹配,也可以按后跟 * 的前缀匹配;它需要 --ja4-header(见“来自入口代理的 JA4 指纹”)。路径模式匹配规范形式的请求路径(SID 0003),因此模式必须以这种形式书写。
持久存储与集群¶
--data-dir /var/lib/sibuna 打开 SQLite 文件 /var/lib/sibuna/sibuna.db(WAL 模式,synchronous=NORMAL,设置忙等待超时),并启动存储线程。--database-url(或 --database-url-file)则改为连接一个 PostgreSQL 数据库。存储线程拥有一个单线程的 tokio 运行时和一个小型连接池;它是唯一执行 SQL 的地方。在启动时、每当策略修订版本变化时(对 policies、ip_reputation 或 policy_inspection 的写入),以及信誉条目过期时,该线程都会从策略文件和数据库重建引擎并发布它;请求从不等待 SQL。一次重建会在加载前后各读取一次修订版本,如果期间有写者提交,就丢弃这次的候选。
模式¶
| 表 | 用途与键 |
|---|---|
policy_revision |
策略修订版本,一行;三张策略表上的触发器会推进它。 |
policies |
有序的动态规则,以 id 为键。可为空的 ja4_pattern 保存规则的 JA4 条件,最多 37 字节。 |
policy_inspection |
每个类别存储的 WAF 模式,一行。 |
ip_reputation |
分数、命中次数和过期时间,以地址或前缀为键。 |
incident_receipts |
每个节点的持久事件回执(其最后一个已提交批次之后的下一个序号),以节点为键。 |
security_incidents |
一条有界的事件记录及其 64 维嵌入向量(256 字节),以 node_id << 40 | sequence 为键。可为空的 ja4 保存请求的 JA4 指纹,恰好 36 字节。 |
incidents_fts |
在 SQLite 上:一张基于路径和载荷规范词元的 FTS5 表。在 PostgreSQL 上,同样的词元存放在 security_incidents 的 tsvector 列 search 中,并带有 GIN 索引。 |
sibuna_schema |
每次已应用的迁移,以组件和版本为键。 |
核心模式位于 crates/storage/src/schema.rs,每种方言各写一份。启用控制台时,组件 console 会增加 33 张名称以 console_ 开头的表(SID 0013;crates/console-storage/src/schema/)。迁移按组件编号并编译进可执行文件。核心迁移 2 增加这两个 JA4 列;在它之前创建的数据库会在启动时迁移。所有待执行的迁移在一个事务中运行,如果数据库中某个组件的版本比节点所知道的更新,节点会拒绝该数据库。打印出来的简略模式不是升级脚本。SQLite 的表是 STRICT 的,CHECK 约束与 Rust 类型相对应,因此数据库会拒绝守护进程无法表示的行。枚举值以小写存储:直接写入 'DENY' 会被拒绝。
日常运维¶
在 sibuna.db 上使用 sqlite3 shell(WAL 模式允许在守护进程运行时读取),或在集群数据库上使用 psql:
-- 添加一条动态规则;每个节点在下一个节拍重建引擎。
INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
VALUES ('p-checkout', 'protect-checkout', 10, '/checkout/*', 'challenge', 20, 'posw',
'{"X-Api": "v2"}', '["10.0.0.0/8"]', 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.id, 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 编写的。在 PostgreSQL 上,enabled 为 TRUE,时间用 CAST(extract(epoch FROM now()) AS BIGINT) 代替 unixepoch(),搜索则在 security_incidents 上写作 WHERE search @@ CAST('union' AS tsquery)。path 和 offending_payload 保存原始请求字节(BLOB 或 BYTEA)。违反约束的直接写入会被数据库拒绝,永远不会到达节点。在 PostgreSQL 下,修订版本触发器还会发出 NOTIFY sibuna_policy,使其他节点立即执行一次节拍;轮询仍然是最终保证。
分数不高于 \(-50\) 的在字典树中成为 deny 前缀,分数不低于 \(50\) 的成为 allow,banned_until 限定封禁的期限。蜜罐命中会自动插入一条 \(-100\) 的记录,因此在共享 PostgreSQL 数据库时,一个节点上触发的陷阱会在所有节点上封禁该地址。
事务回执使重试变得安全¶
存储线程最多收集 32 条待处理记录,并构建一个 SQL 事务。该事务插入事件、更新全文索引,并应用蜜罐带来的信誉变化。每个签发者(节点)都有一个单调递增的回执,即它在 incident_receipts 中的那一行。每条修改数据的语句都受该回执的保护;事务最后才推进回执,并且从不回退。
提交失败时,待处理批次保留在内存中,并递增 incident_write_failures。节拍仍然会尝试轮询策略。512 条记录的队列满时计入 incidents_dropped;它从不为等待磁盘而阻塞 HTTP 响应。待处理批次额外提供 32 条记录的空间。进程在提交之前死亡可能丢失排队的数据:这是一条有界的异步取证路径,而不是在入队时就保证持久的消息队列。
攻击活动聚类¶
每个事件的载荷都通过对字节三元组(数字折叠、大小写折叠)使用哈希技巧,嵌入为一个 64 维单位向量,并以 256 字节存储在 security_incidents.embedding 中。存储线程在内存中保存所有节点最近的 16,384 个嵌入向量(4 MiB),并在每次节拍时从数据库刷新。插入之前,它在其中找出最近的一个(包括同一批次中较早的记录);如果余弦距离不超过 \(0.35\),新事件就加入该事件的 campaign_id,否则以自己的标识符为名开始一个新的攻击活动。早于这个窗口的事件不参与比较。相似性只是一种启发式:回归示例会把相关的 SQL 载荷分到一组,但这并不保证每一对攻击都属于同一个攻击活动。这里没有运行任何模型,也没有训练任何东西。
集群¶
集群是共享同一个 PostgreSQL 数据库的一组节点。使用 postgres-tls 特性构建(cargo build --release -p sibuna --features postgres-tls;它隐含 postgres),并用数据库和各自的节点 ID 启动每个成员:
sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 \
--secret-file /etc/sibuna/secret
每个成员都必须使用相同的主密钥,以及一个唯一的、取值 1 到 8,388,607 的 --cluster-node。URL 文件保存一个 postgres:// URL,并且必须只有其所有者可读;启动横幅从不打印 URL。写入发往 PostgreSQL 主库。每个节点的存储线程看到已提交的修订版本变化(通过 NOTIFY 或轮询)后重建自己的引擎。
节点通过网络访问共享数据库,因此我们对这条连接进行加密和验证。我们为服务器颁发一张由自己的证书颁发机构签名的证书,并在 URL 中指定该机构:postgres://sibuna:...@db.internal:5432/sibuna?sslmode=verify-full&sslrootcert=/etc/sibuna/db-ca.pem。在服务器上,我们只通过 pg_hba.conf 中的 hostssl 行接受 TCP 连接。
启动时,守护进程会打印一行关于数据库连接的信息。使用 verify-full 时,它说明证书和主机名都已验证。使用任何更弱的模式时,它会打印一条警告和一条提示。没有 sslmode 时,模式为 prefer:只有当服务器提供 TLS 时连接才会加密,并且不验证服务器。不带 postgres-tls 构建的守护进程会拒绝 require、verify-ca 和 verify-full,并指出缺少的特性;它从不回退为明文。被拒绝的证书会立即终止启动;提示会要求我们检查 sslrootcert,以及 URL 中的主机是否是服务器证书中的名称。sslrootcert 把我们的证书颁发机构添加到系统信任存储中;它不会移除系统的证书颁发机构(SID 0011,SID 0012)。
Sibuna 不复制自己的数据库,也不选举领导者。复制、故障切换和备份都由 PostgreSQL 负责(流复制、Patroni 或托管服务)。控制台的节点视图中没有领导者:SQLite 节点显示角色 single,PostgreSQL 节点显示 unknown,quorum 只表示该节点最近一次数据库往返成功了。如果数据库不可达,最后发布的引擎继续提供服务,事件在有界环中排队,环满后被丢弃并计数,存储线程以退避方式重试;节点在重新连接之前保持它最后的策略。Zaxonlite 的数据目录(SID 0005)不会被读取;策略通过 sibuna console policies export 和 sibuna console policies import 迁移,取证历史不会迁移。
集群中的挑战路由¶
挑战密钥与 --cluster-node 绑定;请让挑战的签发和验证发生在同一个成员上。令牌使用共享种子,在其他成员上也有效。本地速率配额不会变成全局配额,进程重启会清空已用集合。在一个本地 PostgreSQL 上运行三个节点时,直接写入的策略行会在一个节拍内到达全部三个节点,一个节点上的蜜罐封禁会到达其他节点,事件标识符也从不冲突(crates/storage/tests/multi_node.rs,SID 0011 标准 2;设置 SIBUNA_TEST_DATABASE_URL 时运行)。
打包¶
GitHub 上的每个发行版都为每个平台提供相同的可执行文件,它们从发行标签以默认特性构建:SQLite 存储和控制台。PostgreSQL 集群需要我们自己构建(见下文)。
| 平台 | 发行版文件 |
|---|---|
| Linux x86-64, ARM64 | sibuna-linux-amd64.tar.gz 和 sibuna-linux-arm64.tar.gz 包含一个静态 musl 可执行文件,可在任何 Linux 发行版上运行。sibuna_<version>-1_amd64.deb、sibuna_<version>-1_arm64.deb、sibuna-<version>-1.x86_64.rpm 和 sibuna-<version>-1.aarch64.rpm 会连同一个 systemd 服务一起安装它;sibuna-bin-<version>-1-x86_64.pkg.tar.zst 在 Arch Linux 上做同样的事。 |
| macOS arm64, x86-64 | sibuna-macos-arm64.tar.gz、sibuna-macos-amd64.tar.gz,适用于 macOS 12 或更高版本。 |
| Windows x86-64 | sibuna-windows-amd64.zip 包含 sibuna.exe,适用于 Windows 10 或 Server 2016 及更高版本。 |
| FreeBSD 15.1, OpenBSD 7.9 (amd64) | sibuna-<version>-freebsd-15.1-amd64.pkg 和 sibuna-<version>.tgz。 |
| Homebrew、Kubernetes、容器 | sibuna.rb、helm-sibuna-<version>.tgz,以及适用于 amd64 和 arm64 的镜像 ghcr.io/insanai/sibuna:<version>,其摘要记录在 IMAGE-DIGEST.txt 中。 |
| 源码 | sibuna-<version>-source.tar.gz。 |
每个压缩包和软件包都包含 LICENSE、NOTICE、LICENSES/(其中有 THIRD-PARTY-RUST.txt,即可执行文件中的 crate)、README.md、SECURITY.md 和 sibuna.build.json。这份构建清单记录版本、提交、Rust 目标、编译器版本、特性,以及可执行文件和它的两个 WebAssembly 模块的 SHA-256。发布工作流在发布任何内容之前,会在每个可执行文件自己的平台上启动它,并在 Debian、Fedora、Arch Linux、FreeBSD 和 OpenBSD 上安装、重新安装和移除这些软件包。
这些文件没有签名。安装之前,我们用同一发行版中的 SHA256SUMS 校验下载的文件:
sha256sum --ignore-missing -c SHA256SUMS # Linux
shasum -a 256 --ignore-missing -c SHA256SUMS # macOS, FreeBSD
sha256 -C SHA256SUMS sibuna-1.0.0-beta.3.tgz # OpenBSD
在 macOS 上,通过浏览器下载的文件带有隔离属性,它会阻止未签名的可执行文件运行;校验之后,xattr -d com.apple.quarantine sibuna 可以移除该属性。
systemd 服务¶
Debian、RPM 和 Arch 软件包会安装 /usr/bin/sibuna、单元 sibuna.service、账户 sibuna(通过 systemd-sysusers 创建)、辅助脚本 /usr/lib/sibuna/seed.sh 和设置文件 /etc/sibuna/service.env。安装不会启动任何东西。我们在设置文件中设置源站(一个 IP 地址字面量),然后启动服务:
sudoedit /etc/sibuna/service.env # SIBUNA_UPSTREAM_HOST, SIBUNA_UPSTREAM_PORT
sudo systemctl enable --now sibuna
curl -s http://127.0.0.1:8080/__sibuna/health
除非 SIBUNA_HOST 和 SIBUNA_PORT 另有设置,服务监听 127.0.0.1:8080。SIBUNA_OPTIONS 传递更多选项,以空格分隔,例如 --mode forward_auth 或 --console 127.0.0.1:19446。每次启动之前,如果准入种子 /var/lib/sibuna/admission.seed 不存在,seed.sh 就会创建它(64 个十六进制字符,权限 0600,属主为 sibuna);它从不替换已有的种子,因为新种子会终结所有会话。守护进程把它的 SQLite 数据库保存在 /var/lib/sibuna 中,这是一个权限为 0700 的目录。该单元运行时不带任何 capabilities,系统只读(ProtectSystem=strict),/tmp 和设备是私有的,并且不能获得新权限。
升级会保留设置文件、种子和状态,并且不会重启服务;我们在备份之后再重启它。卸载会停止并禁用服务,但保留账户、种子、设置和状态;我们在让主机退役时自己删除它们。
FreeBSD 和 OpenBSD 软件包只安装 /usr/local/bin/sibuna 及其文档(使用 pkg add;对于不是来自 OpenBSD 镜像站点的软件包,使用 pkg_add -D unsigned)。它们不创建服务、账户或状态:我们以一个非特权用户运行守护进程,并为它配置私有的种子和数据目录。
Homebrew¶
sibuna.rb 安装适合本机的发行版压缩包:macOS 或 Linux,arm64 或 x86-64。它不从源码构建,因为 Homebrew 的 Rust 没有 wasm32-unknown-unknown 的标准库,而构建两个嵌入的 WebAssembly 模块需要它;压缩包中是发布工作流已经检查过的可执行文件。Homebrew 只从 tap 安装 formula,因此我们把这个 formula 放进一个本地 tap:
brew tap-new "$USER/local"
cp sibuna.rb "$(brew --repository)/Library/Taps/$USER/homebrew-local/Formula/"
brew install "$USER/local/sibuna"
这个 formula 不启动任何服务。它的 caveats 说明了如何创建种子;它的测试在同一个数据目录上两次启动守护进程。
容器和 Kubernetes¶
镜像 ghcr.io/insanai/sibuna:<version> 在一个 distroless 基础镜像上包含这个静态可执行文件:CA 证书、用户 65532,没有 shell,也没有包管理器。入口点是 sibuna,因此参数就是守护进程的选项。发布工作流以只读方式运行它,不带任何 capabilities,以只读方式挂载种子,并为状态挂载一个卷,然后把它重启一次:
docker run -d --read-only --cap-drop=ALL --security-opt=no-new-privileges \
-v "$PWD/admission.seed:/run/admission.seed:ro" -v sibuna-state:/var/lib/sibuna \
-p 8080:8080 ghcr.io/insanai/sibuna:1.0.0-beta.3 \
--host 0.0.0.0 --secret-file /run/admission.seed --data-dir /var/lib/sibuna/data \
--upstream-host 10.0.0.5 --upstream-port 3000
Helm chart helm-sibuna-<version>.tgz 运行该镜像的一个 Pod。它需要一个由我们创建的 Secret(secret.existingSecret,键为 admission.seed),因此种子从不出现在 values 或模板中。Pod 以 UID 65532 运行,根文件系统只读,符合 Restricted Pod 安全标准。单个副本加上 Recreate 升级方式,使 ReadWriteOnce 卷上始终只有一个写入者,Sibuna 把它的 SQLite 状态保存在该卷的 data/ 中;卸载时会保留卷声明(claim)。探针调用 /__sibuna/health。Service 的类型是 ClusterIP,chart 不创建 ingress,也不创建控制台,它的 NetworkPolicy 会拒绝所有流量,直到 networkPolicy.ingressFrom 和 networkPolicy.egressTo 放行客户端和源站。upstream.host 必须是一个 IP 地址字面量,extraArgs 传递更多守护进程选项。工作流在一个强制执行 Restricted 标准的 kind 集群中安装、升级和卸载该 chart。
kubectl -n sibuna create secret generic sibuna-admission --from-file=admission.seed
helm install gateway ./helm-sibuna-1.0.0-beta.3.tgz --namespace sibuna \
--set secret.existingSecret=sibuna-admission \
--set upstream.host=10.0.0.5 --set upstream.port=3000
从源码构建¶
我们使用 Rust 1.100 构建和测试;最低支持版本仍为 Rust 1.94。
我们使用 rustup toolchain install 1.100.0 --profile minimal --target wasm32-unknown-unknown 安装发行工具链,并在以下命令中使用 cargo +1.100.0 选择它。
cargo build --release -p sibuna以默认特性(SQLite 存储和控制台)生成target/release/sibuna。sqlx 自带 SQLite,ring(rustls)在构建时需要 C 编译器;可执行文件动态链接系统 C 运行时。构建脚本还会构建 WebAssembly 求解器和控制台界面,这需要rustup target add wasm32-unknown-unknown;SIBUNA_POW_WASM=<path>和SIBUNA_CONSOLE_WASM=<path>可以改为嵌入预先构建的模块。cargo build --release -p sibuna --no-default-features生成完全不依赖外部 crate 的内存型防火墙;此时--data-dir和--database-url会在启动时以StorageDisabled被拒绝,sibuna console则以CONSOLEBUILD被拒绝。cargo build --release -p sibuna --features postgres-tls增加 PostgreSQL 集群支持,并对数据库连接使用经过验证的 TLS。它不需要 OpenSSL。- 发行版中的静态 Linux 可执行文件来自
cargo build --release --locked -p sibuna --target x86_64-unknown-linux-musl(或aarch64-unknown-linux-musl),并以musl-gcc作为 C 编译器(CC_x86_64_unknown_linux_musl=musl-gcc)。
release profile 使用 fat LTO 和单个代码生成单元。工作流只构建一次这两个 WebAssembly 模块,并把它们传给每个平台,因此同一发行版的所有可执行文件都嵌入逐字节相同的模块。依赖变化之后,cargo xtask licenses 会重新生成 LICENSES/THIRD-PARTY-RUST.txt。
在 Windows 上,守护进程在收到 Ctrl+C、Ctrl+Break 和控制台窗口关闭事件时停止;它不作为 Windows 服务运行。Windows 文件没有权限位,因此 Sibuna 无法拒绝其他人可能读取的密钥文件、凭据文件或数据库 URL 文件:我们用 ACL 限制这些文件的访问。控制台的内存和 CPU 仪表读取自 /proc,在其他系统上不可用。