VulnHunter扫荡阶段:从一个漏洞到全库同类根因模式的Sweep策略
VulnHunter扫荡阶段:从一个漏洞到全库同类根因模式的Sweep策略
使用 VulnHunter 的 /vulnhunter-fix 修复技能时,很多人只盯着"修好这一个漏洞",却忽略了更关键的一步——扫荡阶段(Sweep)。它是 VulnHunter 修复流程中的 Phase 3c,负责从一个已验证的漏洞出发,在全代码库范围内挖掘所有同根因、同模式的"兄弟缺陷"(sibling defects),让一次修复覆盖一类问题,而不是打一场永远打不完的补丁仗。本文用大白话讲清楚 Sweep 策略的两遍扫描算法、六列汇总表和降级规则。
为什么修完一个漏洞还不够?
想象你在一个接口里修好了 SQL 注入:把字符串拼接换成了参数化查询。但代码库里可能还有 7 处一模一样的拼接写法散落在别的文件里——扫描器当初只报了最显眼的那一处,其余的会在下次扫描时再次出现。
Sweep 阶段的目标就是:以已修复的漏洞为"根因样本",把全库同类风险一网打尽。它发生在 Phase 3b(Verify,验证修复是否真正生效)之后、Phase 4(Deliver,交付 PR)之前。只有状态为 VERIFIED 的发现才会进入扫荡;已修复、无法自动修复、需要人工决策等状态会被跳过。详见 prompts/sweep.md。
Sweep 两遍扫描算法:先精确,后兜底
Sweep 的核心是一套两遍算法(Two-Pass Algorithm),由 scripts/sweep-root-causes.py 实现,算法细节记录在 references/sweep-algorithm.md。
Pass 1:符号扫荡(图谱锚定)
这是高精度的一遍,思路非常直观:
- 从 triage 侧车文件里读出这个漏洞的污点汇聚点符号(
sink_symbol),比如某条危险 SQL 函数; - 在调用图谱中执行
callers_of(sink_symbol),找出所有调用它的地方; - 凡是没有走"已修复安全路径"的调用者,统统判定为兄弟缺陷。
🎯 一句话理解:修好的是"水管接口",Pass 1 去找的是所有还插着这根水管的老位置。
图谱查询原语(callers_of、callees_of、reachable_from)定义在 vulnhunter_fix/graph/query.py。
Pass 2:模式扫荡(正则兜底)
有些兄弟缺陷图谱上"看不见"——比如复制粘贴出来的代码、通过字符串分发才能到达的调用。这时 Pass 2 出手:
- 根据漏洞的 CWE 编号确定它的CWE 类别(授权、注入、加密、资源、配置五大类);
- 从 references/sweep-patterns.md 加载该类对应的正则模式表;
- 扫描 Pass 1 没标记过的所有源文件,命中的位置记为候选兄弟。
以注入类为例,模式表里包含 os.system((命令注入)、pickle.loads((不安全反序列化)、.innerHTML =(DOM XSS)等典型危险写法,见 sweep-patterns.md 注入部分。
⚠️ 诚实声明:Pass 2 的正则命中一律视为低置信度结果,预期会有误报,需要在合并前人工复核。如果整库图谱本身就处于 grep 降级模式,Sweep 会明确标注 Captured (regex-only),提醒读者结论只来自正则。
读懂六列扫荡汇总表
每个根因漏洞都会产出一行汇总,格式如下:
| Root cause | Pattern | Found | Captured | Mitigated | Remaining |
|---|---|---|---|---|---|
| VULN-001 | SQL concat | 7 | 7 | 5 | 2 |
各列含义:
- Found:两遍扫描共发现的兄弟缺陷总数
- Captured:执行器决定纳入本次处理的数量
- Mitigated:真正被"中和"的数量(进 PR 或开出后续工单)
- Remaining:
Found − Mitigated。只要不为 0,就触发范围修订或后续跟踪
Remaining 列是整个 Sweep 的心跳——它强迫流程对每一个没处理的兄弟缺陷给出交代。
两条处置路径:A 路并进 PR,B 路开后续工单
对每个捕获到的兄弟缺陷,Sweep 按位置分两条路走(sweep-algorithm.md 路由路径):
| 路径 | 适用场景 | 动作 |
|---|---|---|
| Path A — 范围修订 | 兄弟缺陷就在当前 PR 的 worktree 内、文件已在修改清单中 | 直接扩充 PR 范围,顺手一起修 |
| Path B — 后续工单 | 兄弟缺陷在其他文件或 worktree 中 | 为它单独开一个带 vulnfix-sweep-detected 标签的 issue,不擅自改动当前 PR |
这样设计的好处是:PR 的边界始终清晰、可回溯,不会因为"顺手"把无关模块搅浑。
降级规则:FULL 不是永恒的勋章
这是 Sweep 策略里最值得新手记住的一条诚实性规则:
如果某个修复之前被判定为
VERIFIED_FULL(完全修复),但 Sweep 随后又挖出了未被处理的兄弟缺陷,该修复必须降级为VERIFIED_MITIGATION(缓解),并设置sweep_revised = true,在残余风险章节中逐一列出每个未缓解的兄弟向量。
换句话说:Sweep 有能力把"满分修复"打回"及格修复"。这条降级不是靠人拍脑袋,而是由 sweep-root-causes.py 中的 sweep 函数 机械计算并写进输出 JSON,下游交付流程直接消费。
验证表第 8 列:Sweep 完成与否的三种答案
Sweep 结果最终汇入 PR 里的验证表(Verification Table)第 8 列 Sweep complete?,只有三种取值(sweep_ok 判定逻辑):
yes (n/a)— 该根因没有任何兄弟缺陷(Found == 0)yes— 捕获的兄弟全部被中和(Remaining == 0)no— 仍有残留,判定从 FULL 降为 MITIGATION
而在 PR 正文层面,只要跑过 Sweep,## Sweep Summary 章节就是强制项——交付前的 Gate 2(check-body-completeness.py)会机械检查它是否存在。PR 模板中对应的位置见 templates/pr_body_cluster.md。
特殊场景:PR-diff 模式下的 PRE-EXISTING 发现
如果你运行的是 PR-diff 扫描模式(只审查本次 PR 的变更),Sweep 挖出的 PRE-EXISTING(历史遗留)问题会:
- 仅作为信息性条目列在跟踪 issue 中
- 不自动修复(超出本次 PR 范围)
- 不创建后续工单(留给下一次全量扫描处理)
核心文件速查
想深入源码时,按这个顺序读:
- 调用流程与阶段定位:prompts/sweep.md
- 两遍算法与路由规则:references/sweep-algorithm.md
- 按 CWE 分类的正则模式表:references/sweep-patterns.md
- 算法实现(Pass 1 / Pass 2 / 降级计算):scripts/sweep-root-causes.py
- 图谱查询原语:vulnhunter_fix/graph/query.py
- 行为测试:tests/test_sweep_and_verification.py
小结
VulnHunter 的 Sweep 策略本质上是一种根因驱动的缺陷清剿机制:用调用图谱做第一遍精确锚定,用 CWE 正则模式做第二遍兜底覆盖,再用六列汇总、双路径路由和 FULL→MITIGATION 降级规则,保证每一个被发现的同类风险都有明确去向。它回答的是安全修复中最实际的问题——"修完这一处,库里还剩几处同样的坑?" 而这正是它与传统 SAST 扫描最大的区别:不止于报告,而是追踪到清零。