第 3 章 · 03 source-aware 白盒协调

第 3 章 · 03 source-aware 白盒协调

本节摘要:当目标仓库的源码可用时,Strix 的多代理编排会切换到一套更强的协调策略——source-aware 白盒协调。它的核心思想是「静态分诊排优先级,动态验证坐实」:先用源码感知工具栈(Semgrep / ast-grep / tree-sitter / gitleaks+trufflehog / trivy)对仓库做一轮快速静态分诊,排出高风险路径,再用分诊结果指导动态 PoC 验证。关键纪律是「静态发现只是假设,没有动态验证就不报告」。本节讲清这套协调的工作流、源码感知分诊栈的覆盖目标、子代理委派指南,以及三条验证护栏。

内容来源:原项目文档 strix/skills/coordination/source_aware_whitebox.md,汉化并套用体系化模板。

⚠️ 仅限授权测试:白盒测试需要源码访问权;仅对你拥有或获书面授权的代码仓库进行。

学习目标

阅读完本节,你应当能够:

1. 说清 source-aware 白盒协调的核心目标(静态分诊 + 动态验证,提升白盒覆盖)。
2. 描述四步推荐工作流(建源码图 → 静态分诊 → 动态验证优先级 → 证据驱动)。
3. 列举源码感知分诊栈的五个工具及各自职责。
4. 掌握每个仓库的覆盖目标(四类各一次:semgrep / AST / secrets / trivy)。
5. 说明子代理委派时何时优先用 source_aware_sast 技能。
6. 复述三条验证护栏——尤其「静态发现只是假设」这条红线。

一、核心目标:用源码感知扩大白盒覆盖

白盒测试相比黑盒的优势在于「看得见」——能直接读路由、参数处理、SQL 拼接、鉴权逻辑。但白盒也有陷阱:静态扫描器容易产生海量「疑似」,如果直接报告,误报率会很高;如果全靠人工/动态验证逐条核实,效率又跟不上。

source-aware 白盒协调解决的就是这个矛盾。它的目标用一句话概括:

通过把源码感知分诊(source-aware triage)与动态验证(dynamic validation)结合起来,提升白盒覆盖率。当源码可用时,源码感知工具默认启用。

它和上一节的 root agent 编排并不冲突,而是白盒场景下的增强策略:root agent 依然负责拆分与调度,但当源码在手,子代理优先走「静态分诊 → 动态验证」这条路,而非纯黑盒的盲测。

二、四步推荐工作流

2.1 第一步:建源码图(至少一次 AST 结构化扫描)

在深入利用之前,先快速建立源码图——至少做一次 AST 结构化扫描(sg 或 tree-sitter),范围限定在相关路径上。这一步的目的是先把「代码长什么样」搞清楚:路由表、入口点、数据流、危险函数调用点。

• sg(ast-grep)基线:先从 semgrep.json 的作用域(paths.scanned,回退到去重后的 results[].path)推导出 sg-targets.txt,再对该列表 xargs ... sg run。
• 只有当 semgrep 作用域不可用时,才回退到路径启发式。

💡 为什么从 semgrep 作用域推导 sg 目标:semgrep 已经圈定了扫描范围,直接复用它的作用域列表给 ast-grep,保证两个工具看的是同一批文件,结果可对照、可去重,避免范围漂移。

2.2 第二步:首轮静态分诊,排出高风险路径

用源码感知分诊栈(见第三节)跑首轮静态分诊,目标是排序高风险路径——哪些文件/函数最可能藏漏洞,值得优先做动态验证。

2.3 第三步:用分诊结果指导动态 PoC 验证

静态分诊的产出不是终点,而是优先级输入。分诊指出的高风险点(如某处直接拼接 SQL、某路由缺鉴权),交由利用与验证子代理做动态 PoC 验证——真的去跑、真的去试,证实可利用性。

2.4 第四步:证据驱动,无验证不报告

⚠️ 红线:没有验证,就没有报告。静态发现只是假设(hypothesis),动态利用证据才是报告的前提。这条纪律保证白盒的发现同样可信、可复现,不退化成 SAST 式的「可能有问题」清单。

三、源码感知分诊栈

source-aware 白盒协调依赖一组专门工具做静态分诊。下表对齐五个工具的职责:

每仓库覆盖目标

每个仓库要保证四类各跑一次:

• 一次 semgrep 扫描(安全优先分诊);
• 一次 AST 结构化扫描(sg 和/或 tree-sitter);
• 一次 secrets 扫描(gitleaks 和/或 trufflehog);
• 一次 trivy fs 扫描(依赖与配置)。

💡 为什么四类各一次:这四类覆盖了白盒最关心的高价值面——代码漏洞模式(semgrep)、结构化危险点(AST)、硬编码密钥(secrets)、供应链与配置(trivy)。凑齐这四类,静态分诊才算「完整」,缺一类都可能漏掉一整片攻击面。

四、子代理委派指南

在 root agent 的调度框架下,白盒场景的子代理委派有三条额外指引:

1. 按漏洞/组件保持专门化:和通用编排一样,子代理仍按漏洞类或组件切分(SQLi 代理、认证代理、用户模块代理……),不要一个代理包打天下。
2. 源码密集子任务优先用 source_aware_sast 技能:当子任务重在读代码、做静态分析时,优先创建带 source_aware_sast 技能的子代理——它内置了上述分诊栈的工作流。
3. 用源码发现塑造 payload 与端点选择:静态分诊发现的危险点(如某参数直拼 SQL、某路由缺鉴权),直接指导动态测试的 payload 构造和端点选择——这是白盒相对黑盒的核心优势,别浪费。

五、三条验证护栏

白盒协调最容易踩的坑就是「静态扫到就报」。三条护栏拦住这个陷阱:

1. 静态发现只是假设,直到被验证——semgrep/ast-grep 的告警是「这里可能有问题」,不是「这里有漏洞」。是否真有问题,必须动态验证。
2. 报告漏洞前仍需动态利用证据——和 Strix 全局纪律一致:PoC,而非误报。白盒不豁免这条。
3. 扫描器输出要简洁、去重、映射到具体代码位置——静态工具动辄产出成百上千条,必须裁剪、去重,并把每条映射到具体 code_locations,否则下游代理和报告会被噪声淹没。

⚠️ 「静态即假设」是白盒的纪律底线:Semgrep 报了一条 SQL 注入模式,不代表真有注入——可能参数已被上游过滤、可能是死代码、可能是误报。只有动态验证跑通(如 sqlmap 证实可注入、或 PoC 拿到数据),才能写进报告。这条护栏让 Strix 的白盒发现同样可信。

本节要点回顾

1. 核心目标:源码可用时,用「源码感知分诊 + 动态验证」提升白盒覆盖;源码感知工具默认启用,是 root agent 编排在白盒场景下的增强策略。
2. 四步工作流:建源码图(至少一次 AST 结构化扫描,sg 目标从 semgrep 作用域推导)→ 首轮静态分诊排高风险路径 → 分诊结果指导动态 PoC 验证 → 证据驱动,无验证不报告。
3. 分诊栈五工具:Semgrep(安全分诊)、ast-grep/sg(结构化模式)、tree-sitter(符号/路由提取)、gitleaks+trufflehog(密钥)、trivy fs(依赖/配置/许可证)。
4. 每仓库覆盖目标:semgrep 一次、AST 结构化一次、secrets 一次、trivy fs 一次——四类齐全才算完整分诊。
5. 子代理委派:按漏洞/组件专门化;源码密集任务优先用 source_aware_sast 技能;用静态发现塑造动态 payload 与端点选择。
6. 三条验证护栏:静态发现只是假设、报告前必须动态证据、扫描器输出要简洁去重并映射到具体代码位置。
7. 纪律底线:白盒不豁免 Strix 全局的「PoC 而非误报」——静态扫到只是起点,动态跑通才是终点。

至此第 3 章完成。下一章我们转向「能力」——代理能用什么工具、沙箱里预装了什么、怎么接 CI/CD。模型决定上限,编排决定逼近上限的方式,工具决定每一步能走多远。