用指令/数据通道判定法审计大型 Rust 代码库:XERJ 五阶段白盒方法论与 69 倍 token 节省实测
用指令/数据通道判定法审计大型 Rust 代码库:XERJ 五阶段白盒方法论与 69 倍 token 节省实测
本指南完整解析 XERJ 对自身 Rust 引擎(197 个文件、约 20.1 万行、16 个 crate)执行的"指令/数据(instruction/data)白盒审计"方法论。它把"什么函数危险"压缩成一条可操作的判定法则,并用五阶段可复用流程替代传统分类清单;每一步都给出了真实运行的 XERJ 查询(基于函数、调用边、路由三个索引)与对应的 grep 基线,并给出 tiktoken
cl100k_base实测的 token 开销对比(分阶段合计 69 倍、去重文件并集 19.6 倍)。读完你可以把这套五阶段打法直接套用到任何语言的代码库上,并理解为什么"过滤器真实存在"不等于"漏洞不存在"。
一次"用自己审计自己"的可复现实验
XERJ 的这次安全审计有一个特殊之处:审计工具本身就是被审计对象。审计工作由 AI Agent 完成,但它的检索与推理基底不是"让 Agent 通读全部源码",而是先用 tree-sitter-rust 提取器(docs/examples/rust-ast-audit/)把引擎源码转成三个可查询的 XERJ 索引——函数(rustfns)、调用边(rustcalls)、路由(rustroutes),再让 Agent 像查询文档库一样"审讯"代码,而不是"通读"代码。
本次运行的实测规模(以当前 main 分支为准):
| 指标 | 数值 |
|---|---|
Rust 文件(engine/ 下,不含 target/) |
197 |
| 解析文件 / tree-sitter ERROR 节点 | 197(100%)/ 0 |
| 函数记录 | 5,095(覆盖率 100.0%,独立计数断言) |
| 调用边 | 87,137 |
| 路由注册 | 477 |
| axum 处理器形态函数 | 299 |
| 非测试函数 | 3,437 |
| 处理器形态(非测试) | 298 |
其中"函数覆盖 100%"不是拍脑袋:coverage.json 同时记录独立统计的 function_item AST 节点数和已发射记录数,两者必须相等。第一次提取只有 97.2%——嵌套在函数体内的 fn 项被跳过了,这是提取器真实 bug,修复(遍历器下沉进函数体)后两个计数才对齐。覆盖率是断言出来的,不是假设出来的。
提取器与数据加载的代价很小:提取约 3.2s + 入库约 1.9s,磁盘占用 31 MB,完整复现步骤见 REPRODUCE.md,查询手册见 QUERY_COOKBOOK.md。
核心判定法则:指令与数据共用一个通道
整套方法论只有一条判定原则,它比"危险函数分类清单"更锋利,因为它回答了两件事:为什么某处是风险点,以及修什么才能真修好:
一个函数是危险的,当 INSTRUCTION(指令)与 DATA(数据)共用一个通道,且中间没有任何分隔符。
对应到常见的通道类别:
| 通道 | 指令成分 | 数据成分 | 已分隔(安全)形态 |
|---|---|---|---|
| SQL 字符串 | SELECT、WHERE、,、' |
标识符、字面量 | 绑定参数 ?——解析器在解析之后才解析的结构化占位符。标识符无法绑定,唯一安全形态是方言引号 + 转义加倍,或 schema 白名单 |
| 文件系统路径 | /、..、绝对前缀 |
名称分量 | 经校验的不透明 token,加上任何破坏性操作之前的 canonicalize-then-contain |
| 进程 argv | 前导 -(选项) |
参数值 | -- 选项终止符,或 arg("--opt=VALUE"),或不做任何 getopt 解析的子进程 |
| 序列化字节 | 类型/构造标签 | 字段值 | 无多态标签的固定目标类型,加上大小/深度预算 |
| 查询 DSL / 模板 | JSON 结构、查询键 | 用户参数 | 先解析、再整节点替换;绝不先替换再解析 |
还有一个能抓住多数真实 bug 的推论:
过滤器只有在"从数据通道中移除指令能力"时才是真实的。"它调用了
escape()"并不够——shell 转义只处理元字符,对选项注入毫无作用;一个 containment 检查如果参照点是攻击者提供的,那就不是真检查。
本次审计两个核心漏洞(INJ-01、F-PATH-02)正是推论失败,而不是"过滤器缺失"失败:守卫快照路径的三个过滤器个个真实、写得很好、且有测试——漏洞出在它们谁都没看的未校验的兄弟字段上。
为什么 grep 在数 token 之前就先输两局
方法论文档给出了两个结构性理由,与 token 数量无关:
- 命中的单位不同。 AST 命中是一个函数;grep 命中是一行,而判断一行必须读整个文件。本代码库中这个比例非常残酷:
render_template只有 20 行,躺在 es_compat.rs 这个 31,221 行 / 273,864 token 的文件里。AST 基底直接把 20 行和指向它的 8 条调用边递给你。 - "缺失"无法被 grep。 第 4 阶段的全部工作就是找不存在的检查。
grep -rnE 'path\.repo|repo_allowlist|snapshot_root' crates在这棵树上返回 0 行——这个零恰恰就是 F-PATH-02 漏洞本身(快照位置白名单不存在)。一个must_not子句在 validator 字段上一条查询就表达了;正则根本无法表达"不存在"。这与 PR #69 的 F7/F8 同类——grep 同样够不到。
五阶段流程:每一步都是"XERJ 查询 + grep 基线"的对照实验
基底固定为三个索引:rustfns(5,098 个函数)、rustcalls(87,150 条调用边)、rustroutes(477 条 axum 注册)。所有查询都走 ES 兼容 REST 接口(本案例默认 http://127.0.0.1:9310)。
Stage 1 — 按指令/数据测试标出每个危险的 END 函数(sink)
先按通道类别枚举 sink,再逐个判定数据分量是否保留指令能力:
curl -s "http://127.0.0.1:9310/rustfns/_search" -H 'Content-Type: application/json' -d '{
"query":{"bool":{"filter":[{"term":{"is_test":false}}],
"should":[{"term":{"sinks":"fs_path_join"}},{"term":{"sinks":"fs_write"}},
{"term":{"sinks":"fs_delete"}},{"term":{"sinks":"fs_rename"}},
{"term":{"sinks":"process"}},{"term":{"sinks":"deserialize"}},
{"term":{"sinks":"sql_ish"}},{"term":{"sinks":"net_egress"}}],
"minimum_should_match":1}},
"_source":["crate","file","fn_name","line_start","sinks","validators","path_join_from_param","signature"],
"size":1000}'
→ 318 个函数,投影元数据 40,623 token。
非测试函数的 sink 普查,及指令/数据测试给出的判定:
| sink 类 | 函数数 | 判定 |
|---|---|---|
log_secret |
210 | 启发式,多为良性日志 |
fs_path_join |
149 | 生产力最高的一类——22 个从参数 join 路径 |
deserialize |
147 | 固定目标类型、无多态标签 → 仅信息性 |
fs_write |
49 | 文件名内部生成,唯独快照路径除外 |
spawn |
31 | 内部任务 spawn,无 argv |
fs_rename |
16 | 仅内部 segment/WAL token |
fs_delete |
14 | 全部在已校验或保留前缀的目录下 |
net_egress |
13 | 操作者配置的端点 |
sql_ish |
4 | 1 真 3 假(见精度说明) |
process |
2 | 1 真,且按子进程设计是安全的 |
精度说明(案例研究不隐瞒这点就毫无价值): sinks:sql_ish 很吵——4 个命中只有 1 个是真的。search.rs 里的三个命中(search_bounded:503、execute_bool:1019、execute_dis_max:1124)都是注释里英文单词 "union" 触发的假阳性(// If no must clauses, candidate set is the union of should docs)。不要把 sql_ish 当可信过滤器。这个基底是强过滤器、平庸排序器——每个候选都被人工读过了。
grep 基线(审计者实际会写的 sink 正则并集):
grep -rn --include='*.rs' -E 'Command::new|process::Command|fs::(read|write|remove_file|remove_dir_all|rename|create_dir_all|File::(open|create))|\.join\(|from_str|from_slice|from_reader|reqwest|TcpStream|format!\(.*(SELECT|WHERE|FROM)' crates
→ 1,132 行匹配,散布在 110 个不同文件 = 1,585,177 token 要读。仅仅 Stage 1 一轮扫描就返回了整个代码库的 88%。
Stage 2 — 沿调用图把每个 sink 追回用户输入
curl -s "http://127.0.0.1:9310/rustcalls/_search" -H 'Content-Type: application/json' \
-d '{"query":{"term":{"callee":"render_template"}},
"_source":["caller","file","line","kind","resolvable"],"size":100}'
向上遍历调用者直到命中 rustroutes 的 handler。两个注入/路径示例的遍历路径是:render_template(8 条调用边)→ search_template / msearch_template_impl / render_template_api;create_snapshot(3 条)与 validate_snapshot_path(2 条)→ es_compat::create_snapshot → 路由。
→ 4 次查询、13 条调用边、1,232 token。 结果是有向的:就是这些调用者、这些行。
grep 基线: grep -rn 'render_template|create_snapshot|validate_snapshot_path' → 23 行 / 5 文件 / 374,872 token——而且它是无向的(调用者、定义、测试混在一起无法区分)。更重要的是它只有在你已经知道函数名时才有效——而函数名恰恰是 Stage 1 要告诉你的东西。想用 grep 去"发现"render_template,就得跑通用的"数据拼进已解析字符串"扫描:grep -rln 'serde_json::from_str' → 20 个文件 / 772,182 token。
Stage 3 — 测绘特权模型与每个检查的落点
# 每条路由注册
curl -s ".../rustroutes/_search" -d '{"query":{"match_all":{}},"_source":["method","path","handler","file","line"],"size":500}'
# 每个执行认证检查的函数
curl -s ".../rustfns/_search" -d '{"query":{"bool":{"filter":[{"term":{"is_test":false}},{"term":{"validators":"auth"}}]}}}'
→ 477 条路由 + 24 个认证校验函数,40,218 token。 这让你能说出"认证网络内"而不是靠猜:路由表把 path → handler → file:line 映射好,认证集合显示检查在中间件里而不是每个 handler 里。
它还暴露了整个报告里最重要的限定语,在 auth.rs(当前 main 上该逻辑位于 authenticate 分支):
// Open mode: auth disabled or no admin key configured.
if !cfg.enabled || cfg.admin_api_key.is_empty() {
return Principal::Superuser;
}
auth.enabled = true 是出厂默认(xerj.default.toml 的 [auth] 段),但空的 admin_api_key 直接短路成全开放;文档化的 --insecure 快速启动标志则彻底关闭认证。下面所有标"认证网络内"的严重级别,在这两种配置下都会退化为未认证。
grep 基线: grep -rnE 'auth|api_key|require_admin|is_admin|role|permission|middleware' → 874 行 / 73 文件 / 1,271,510 token——而且它根本产生不了路由表:你真正需要的是 .route() 调用,而它们还要再往前一步 grep。
Stage 4 — 逐条校验每个过滤器的绕过面
这是缺席查询(absence-query)发挥作用的一站:sink 在、过滤器不在。
curl -s "http://127.0.0.1:9310/rustfns/_search" -H 'Content-Type: application/json' -d '{
"query":{"bool":{
"filter":[{"term":{"is_test":false}},{"term":{"path_join_from_param":true}}],
"must_not":[{"term":{"validators":"containment"}},
{"term":{"validators":"explicit_validate"}},
{"term":{"validators":"typed_name"}}]}},
"_source":["crate","file","fn_name","line_start","sinks","validators","path_join_args"],"size":500}'
→ 18 个函数(22 个从参数 join 路径中的 18 个),1,940 token。然后把 18 个全部读完,问推论问题而不是"在场问题"。四个绕过子类:
- 参照点错误。 检查是真的,但参照的是攻击者提供的数据。→ F-PATH-02:
snap_dir.starts_with(repo_canon)中repo_canon来自同一个请求字段,使断言成为同义反复。 - 通道错误。 每个检查都落在你预期攻击出现的字段上;攻击走的是未校验的兄弟字段。→ 还是 F-PATH-02:三个过滤器加固了 repo 名和快照名;没人校验
settings.location。 - 转写错了字母表。 shell 元字符转义 vs 选项注入;HTML 转义 vs JSON 结构。→ INJ-01:
String::replace完全没有 JSON 转义,随后重新解析。 - 操作顺序。 先破坏后校验。这里显式检查过:树上非测试函数中
guard_after_destructive_op为true的恰好 1 个,且那个是检测器假阳性——PR #69 的restore_snapshot中"先remove_dir_all后校验"的 bug 确实已经消失。
grep 基线: 不存在"有 join 且同函数无 containment 检查"的 grep 写法。诚实的替代方案是读每个含 sink 的文件:grep -rnE '\.join\(|Path::new|PathBuf::from|canonicalize' → 711 行 / 66 文件 / 1,317,109 token。收窄到只写 sink(create_dir_all|fs::write|copy_dir_recursive)仍有 137 行 / 27 文件 / 622,709 token。而对缺席的白名单,grep 返回 0 行——没有东西可匹配。
Stage 5 — 状态机:TOCTOU、死锁、跨 await 持锁
curl -s "http://127.0.0.1:9310/rustfns/_search" -H 'Content-Type: application/json' -d '{
"query":{"bool":{"filter":[{"term":{"is_test":false}}],
"should":[{"term":{"lock_across_await":true}},{"term":{"guard_after_destructive_op":true}}],
"minimum_should_match":1}},
"_source":["crate","file","fn_name","line_start","concurrency","lock_across_await","guard_after_destructive_op","is_async"],"size":500}'
→ 16 个函数、1,814 token(15 个 lock_across_await,1 个 guard_after_destructive_op)。完整、可读的总体。
grep 基线: grep -rnE '\.(lock|write|read)\(\)|\.await|Atomic|Ordering::Relaxed|exists\(\)|spawn_blocking|block_on' → 3,377 行 / 96 文件 / 1,381,258 token——而且结构上就是错的:"一个 guard 跨越 await 持有"是两个行之间的关系,行作用域的正则无法表达。你只能得到 .lock() 行和 .await 行两个互不相干的无序集合。
实测对照:5 阶段合计 69 倍、去重并集 19.6 倍
每个 token 数字都是用 tiktoken cl100k_base(公开的 GPT-4 级 BPE,作为 LLM-token 代理)实测的,不是 chars÷4 估算。XERJ 列是实际投影返回的载荷;grep 列是每个 grep 迫使你打开的不同文件之和(因为 grep 命中是一行,而判断需要读整个文件):
| 阶段 | XERJ 查询返回 | XERJ tokens | grep 行 | grep 文件 | grep tokens | 比值 |
|---|---|---|---|---|---|---|
| 1 · 标出危险 sink | 318 函数 | 40,623 | 1,132 | 110 | 1,585,177 | 39× |
| 2 · 追踪到用户输入 | 13 条调用边 | 1,232 | 23 | 5 | 374,872 | 304× |
| 3 · 特权模型与流 | 477 路由 + 24 认证函数 | 40,218 | 874 | 73 | 1,271,510 | 32× |
| 4 · 校验过滤器绕过 | 18 函数 | 1,940 | 711 | 66 | 1,317,109 | 679× |
| 5 · 状态机 | 16 函数 | 1,814 | 3,377 | 96 | 1,381,258 | 761× |
| 合计(分阶段求和) | 85,827 | 6,117 | — | 5,929,926 | 69× | |
| 合计(去重文件并集) | 85,827 | 153 | 1,685,346 | 19.6× |
两个合计是故意的。分阶段求和(69×)是审计者逐阶段推进时实际付出的代价。去重并集(19.6×)是诚实的下限——它带着更刺眼的数字:五轮 grep 扫描合计触碰 197 个 .rs 文件中的 153 个,即整个引擎 1,805,277 token 的 1,685,346(93%)。用 grep 跑这五个阶段就等于通读代码库,只是顺序更糟、还没有调用图。作为参照,直接读全部 197 个文件是 1,805,277 token——只比 grep 并集多 7%,却是 200k 上下文窗口的约 9 倍。
本次 pass 的召回率
| XERJ 基底 | grep 基线 | |
|---|---|---|
| 到达的已确认发现 | 2 / 2 | 原则上可发现 1 / 2 |
| 发布前被驳倒 | 1 | — |
- INJ-01 用 grep 可达,仅当你已经知道
render_template这个名字(2 个文件,便宜)。不知道名字去发现它,要花通用 20 文件 / 772,182 token 的扫描,而且缺陷在 273,864 token 文件的第 23,160 行。 - F-PATH-02 的 sink 可被 grep(
create_dir_all在 27 文件集合里)。缺陷本身不可:它是 (a) 一个不存在的白名单——grep -rnE 'path\.repo|repo_allowlist|snapshot_root'= 0 行——以及 (b) 判断"一个真实 containment 检查正对着攻击者数据测量"。两者都无法表达为正则。这里记为 grep 不可达,并说明为什么,而不是声称 grep 看不见create_dir_all。
先前在有标签真值上的校准
PR #69 的六个已知 bug 上的校准见 DETECTION-QUALITY.md:6/6 vs grep 的 4/6,triage 开销 84,122 vs 2,715,003 token(32 倍)。那次运行第一次尝试只得 3/6——比 grep 还差;测试集暴露了三个真实的提取器缺陷(参数解析在第一个 ) 截断、污点来源不跟一跳进局部变量、validator 检测只看在场不看顺序)。修复后到 6/6,且每个修复都验证过在已打补丁的代码上保持安静——它判别而非仅仅匹配。没有标签集的召回声明一文不值。
方法不覆盖什么(诚实的边界)
- 宏生成代码、trait 对象动态分发、
build.rs代码生成对基底不可见(见 COVERAGE.md)。 - callee 解析基于名字。 方法调用边(
is_method: true)不解析;只有自由/路径调用(resolvable: true)构成可靠图。穿过 trait 对象的污点路径会被漏掉。方法边被刻意排除:按裸名解析会把同名的 603 个函数缠成一个伪强连通分量,反而掩盖真实的递归环。 - 精度是弱轴。 五阶段候选 16 个进入验证、8 个确认。基底把几千个函数过滤成可读集合;它不排序,而且会产生自信的假阳性(
sql_ish/"union" 案)。没有验证器的查找器会把它们发布出去。 - 一半的拟议发现被驳倒(8 确认、8 驳倒,50% 剔除率)。那个剔除——包括一个所有代码观察都对、结论仍然错的例子——正是对抗式反驳步骤存在的理由,而不是脚注。综合层也需要同样的审视:它的自动摘要把确认集少算成 2,是靠对原始逐条判定对账才抓出来的。
复现整套结果
从零可复现,脚本在 docs/examples/rust-ast-audit/。要点:
# 0. 前置
python3 -m venv venv && . venv/bin/activate
pip install tree-sitter==0.26.0 tree-sitter-rust==0.24.2
cargo build --release -j 32 -p xerj-server # 产出 engine/target/release/xerj
# 1. 构建基底(提取一次,约 3.2s)
cd docs/examples/rust-ast-audit
python3 rust_ast_index.py ../../../engine --out ./ast-out
# → files_total=197 files_parsed=197 error_nodes_total=0
# ast_function_nodes=5095 emitted_function_records=5095 function_coverage_pct=100.0
# call_edges=87137 routes=477 unsafe_block_sites=23 unsafe_fn_declarations=2
# 2. 启动隔离实例并入库(约 1.9s)
cat > audit.toml <<'TOML'
[server]
rest_port = 8390
grpc_port = 8391
es_compat_port = 9310
bind_address = "127.0.0.1"
data_dir = "./auditdata"
TOML
../../../engine/target/release/xerj --insecure -c audit.toml &
until [ "$(curl -s -o /dev/null -w '%{http_code}' -m2 localhost:9310/)" = "200" ]; do sleep 1; done
python3 ingest.py ./ast-out --url http://127.0.0.1:9310
# → rustfns 5095/5095, rustcalls 87137/87137, rustroutes 477/477 — 全部 match:true
# 3. 有标签真值召回测试(索引 PR #69 修复前的提交)
git worktree add /tmp/pre69 --detach $(git rev-parse <PR#69-merge>^1)
python3 rust_ast_index.py /tmp/pre69/engine --out ./ast-pre69
python3 ingest.py ./ast-pre69 --url http://127.0.0.1:9310 --suffix _pre69
python3 detection_quality.py --url http://127.0.0.1:9310 --suffix _pre69 \
--tree /tmp/pre69 --astdir ./ast-pre69
# → RECALL XERJ 6/6 grep 4/6
# TRIAGE XERJ 84,122 tokens grep 2,715,003 tokens
注意:grep max_actions_per_bulk 在修复前的树上返回 0 行——F7、F8 是缺失的代码,任何 grep 都找不到。修复后 evolve_schema_* 的 reads_config_limit 字段从 false 变 true,一条前缀查询即可区分。
方法论产出的真实漏洞:指令/数据判定如何落地
五阶段跑在 XERJ 自己身上,经对抗式验证后确认 8 项、驳倒 8 项。全部细节、污点路径与线上复现记录见 FINDINGS-V2.md,问题草案见 ISSUES.md。三个应用层 High 已在分支 58fc73f 修复(带回归测试与线上前后证明);DESER-EGRESS-01 作为集群 Raft 认证 Phase-2 项跟踪。两个最典型的例子正好是方法论里"推论失败"的两类:
INJ-01 — 搜索模板参数未转义拼进查询后重新解析(High,已修复)
render_template 用原始 String::replace 合并参数、零转义,然后 serde_json::from_str 重新解析合并串——参数里携带 JSON 结构 token("、,、多余的 "query" 键)就被当作查询结构解释。在数字位置("size": {{size}})的参数甚至不需要破引号。线上证明:模板编码了 ACL 过滤器并接受不受信的 size,注入值 "50,\"query\":{\"match_all\":{}}" 让可见性过滤器被丢弃(serde 保留重复 query 键的最后一个),私有文档被返回。修复后的当前源码(es_compat.rs)对 Value::String 先 serde_json::to_string 再剥外层引号输出已转义的内部内容:值永远是单个 JSON token,恶意值在裸值位置变成非法 \" 序列、重解析直接失败;同文件附带的 render_template_security_tests 回归测试验证同一 payload 现在渲染成 template rendered to invalid JSON。路由在 router.rs:POST /:index/_search/template、/_msearch/template、/_render/template。
F-PATH-02 — 快照仓库 settings.location 是无校验根(High,已修复)
三个守卫快照名的过滤器真实有效,但仓库位置本身是客户端经 PUT /_snapshot/{repo} 提供的绝对路径,名过滤器谁也不看它。修复前 engine.rs 的 validate_snapshot_path 里 repo_canon 来自请求自身的 repo_path,断言是空转的:PUT /_snapshot/evil {"type":"fs","settings":{"location":"/tmp/EVIL"}} 后,所有索引的 segment 文件被递归复制到 data_dir 之外;restore_snapshot 是镜像问题(可从任意位置读攻击者预置文件进索引)。修复引入 limits.snapshot_repo_allowlist(ES path.repo 等价物,默认空 = 仅 data_dir,见 xerj.default.toml 的 <a href="https://link.gitcode.com/i/5d8ea09c0fda179a53fd3592428e2d3c" target="_blank">limits] 段),当前 [engine.rs 的 validate_snapshot_path 拒绝含 .. 分量、拒绝 canonicalize 后落在 data_dir 或白名单之外的 location。这是 PR #69 明确推迟的项目("no path.repo equivalent")。
其余确认项:S5-1 会话吊销丢失更新(High,已修复)、DESER-EGRESS-01 集群端口未认证 Raft 控制消息(High,受 cluster.enabled 门控,跟踪中)、S5-4 x-forwarded-for 被当身份(Medium,已修复,新增 server.trusted_proxies 默认空)、S5-3 magic-link 一次性消费 TOCTOU(Medium,未修复)、S5-5 显式映射路径绕过 max_fields_per_index(Low,未修复)、AUTHZ-2 cluster/info 未认证披露(Info,未修复)。被驳倒的一半同样有分量:最富教育意义的 F-PATH-01 每个代码观察都对、结论仍错——它以为缺失的 guard 其实在调用者里。没有独立反驳优先验证器的查找器,早就把它发布了。
延伸阅读(均在当前仓库内): 方法论原文 METHODOLOGY.md;校准与召回 DETECTION-QUALITY.md;覆盖边界 COVERAGE.md;完整查询手册 QUERY_COOKBOOK.md;提取器、环查找器与质量 harness 源码在 docs/examples/rust-ast-audit/。同一方法此前应用于 WordPress 代码库的审计见 docs/case-studies/wordpress-security-audit/。