Clearwing 是一款 AI 驱动的源代码漏洞挖掘与安全测试框架，其 SourceHunt 流水线（clearwing/sourcehunt/runner.py）将一次完整的漏洞猎杀拆解为 11 个严格分阶段的流水线：预处理、文件排序、Fuzz 种子、分层 Hunter 并发狩猎、对抗式验证、补丁预言机、机制记忆、变体挖掘、PoC 利用分诊、自动修复与最终报告。本文将带你逐阶段理解它的设计思路，帮助新手快速掌握这条"从文件排序到 PoC 验证"的完整链路。

为什么采用"分阶段"而非"单模型死磕"？

早期方案让单个大模型在一个超长对话里完成读码、假设、追踪、验证等全部工作，前沿模型的端到端成功率约 60%，而本地小模型只有约 30%（详见 docs/sourcehunt_improvement.md）。Clearwing 的做法是把每个认知任务拆成独立阶段，每个阶段产出都是下一阶段的结构化输入——流水线是 staged（分阶段）的，不是 loop（死循环）的。

🎯 核心收益：

• 每个阶段可以独立评估、独立换模型（便宜模型干粗活，前沿模型干难活）
• 阶段间有 checkpoint 落盘，中断后可恢复
• 预算按阶段记账，超限自动降级而非整体崩溃

官方架构图文档位于 docs/architecture.md#L77-L133，是理解全流程的最佳入口。

全流程总览：11 阶段一览

阶段 1：Preprocess——给整个仓库做"体检"

流水线从克隆仓库开始，预处理阶段会：

• 枚举所有源文件，并按关注点打标签：memory_unsafe（内存不安全）、parser（解析器）、crypto（加密）、auth_boundary（认证边界）、fuzzable（可模糊测试）
• 用 tree-sitter 构建调用图（callgraph），并传播攻击者可达性
• 可选运行 Semgrep sidecar 静态扫描 + 过程内污点分析（追踪 source→sink 路径）

这些"静态提示"会像线索一样注入后续每个 Hunter 的提示词，相当于给猎手一张预先画好的藏宝图。

阶段 2：Rank——文件排序决定预算花在刀刃上

仓库动辄几千个文件，全量精读不现实。排序器对每个文件打三个轴的分数：

最终得分 = surface × 0.5 + influence × 0.2 + reachability × 0.3

其中influence（影响力）轴专门用来捕捉"无聊但危险"的文件——它们的函数定义会传播到大量调用方，单轴排序器恰恰会把这类文件漏掉。排序入口在 clearwing/sourcehunt/ranker.py，runner 中的调用点见 runner.py#L2062。

💡 实战技巧：如果你只想看排序结果而不烧钱，可以用--stop-after rank在排序完成后提前退出。

阶段 3：Harness 生成——先让 Fuzzer 替你把崩溃"钓"出来

--depth deep模式下，流水线会为每个高优先级（rank 4+）的解析器/可 Fuzz 的 C/C++ 文件，让 LLM 编写libFuzzer harness，在带 ASan 的沙箱里编译运行，捕获崩溃。

妙处在于：这些"种子崩溃"会被注入对应文件的 Hunter 提示词。猎手拿到的不再是冷冰冰的"找找看有没有漏洞"，而是"解释一下这个 ASan 崩溃报告"——问题难度断崖式下降（实现在 harness_generator.py）。

阶段 4：Tiered Hunt——分层 Hunter 是整条流水线的火力核心

这是最复杂也最值得剖析的阶段，执行器是 clearwing/sourcehunt/pool.py 中的HunterPool。

4.1 A/B/C 三层文件分桶

排序后的文件按优先级被assign_tier（pool.py#L200）分到三层：

• Tier A：高优先级文件，预算占比70%
• Tier B：中优先级，占25%
• Tier C：长尾文件，占5%，且只给一套窄工具集（无编译/运行，仅 grep/read/record），保持低成本

预算不足时支持rollover（滚存）：A 层没用完的钱可以顺延给后续层。

4.2 fast/standard/deep 三档带宽晋升

文件在层内还会经历fast → standard → deep的带宽晋升（pool.py 中的BAND_ORDER）：先用最便宜的 fast 档快速过一遍，发现值得深挖才晋升到更贵的档位，避免把预算浪费在"一眼安全"的文件上。

4.3 六大专家 Hunter 按标签分流

每个文件根据其标签 + 语言被分派给 6 类专家之一：memory_safety（内存安全）、crypto_primitive（密码学原语）、web_framework（Web 框架）、logic_auth（逻辑与认证）、kernel_syscall（内核系统调用）、general（通用）。专家提示词来自 clearwing/core/skills/ 下的技能文档。

阶段 5-8：验证与扩散——让"发现"变成"证据"

阶段 5：Adversarial Verify 对抗式验证

Verifier是一个独立上下文的第二模型，它会同时钢人化论证正反两方：既要证明"有漏洞"，也要尽力证明"没漏洞"，最后找平局裁决证据。默认门槛是evidence_level >= static_corroboration，纯猜测（suspicion）级别的发现不会浪费验证预算。被拒的发现会单独写入 rejected 文件备查（verifier.py）。

阶段 6：Patch Oracle 补丁预言机

这是因果验证的杀手锏：写一个最小防御性修复 → 沙箱重编译 → 重跑 PoC。如果崩溃消失，说明漏洞理论被因果验证，证据级别提升到root_cause_explained；如果崩溃依旧，说明理论可疑。

阶段 7：Mechanism Memory 机制记忆

从已验证发现中提取抽象漏洞机制（如"长度字段在分配前被信任；size_t 溢出回绕"），持久化到跨运行的 JSONL 存储。下次扫描同一类代码时，机制召回会把提示注入 Hunter 提示词——流水线越跑越聪明（mechanism_memory.py）。

阶段 8：Variant Loop 变体猎手循环

对每个已验证发现，生成 grep 正则 + 语义描述，在全库中搜索结构性相似的代码，每个命中点作为一个新的变体发现挂到父发现之下。最多迭代 3 轮直到不动点，让"找到一个 = 发现一族"（variant_loop.py）。

阶段 9-10：PoC 验证与自动修复——证据链的最后一公里

阶段 9：Exploit Triage 利用分诊

只有带sanitizer 崩溃证据（evidence_level >= crash_reproduced）的发现才进入利用分诊。PoC 复现成功会把严重级别升到 critical。此外还有Stability 稳定性验证：在全新容器里重跑多次 PoC，成功率过低（unreliable）的发现会被降级，杜绝"碰巧崩溃一次"的假阳性（stability.py）。

阶段 10：Auto-Patch 自动修复（opt-in）

对已验证的 critical/high 且root_cause_explained级别的发现，自动写最小修复、重编译、重跑 PoC。只有 PoC 停止崩溃的补丁才算 validated，可选--auto-pr通过ghCLI 提交 draft PR（始终需要人工审核，见 runner.py#L2863-L2898）。

阶段 11：Report——把证据链变成可审计报告

最终产出SARIF + Markdown + JSON三种格式，发现按证据级别降序排列。--export-disclosures会为每个root_cause_explained级发现预填 MITRE CVE 申请和 HackerOne 披露模板（disclosure.py）。退出码语义也很规范：0=干净，1=medium，2=critical/high，3=不完整/预算耗尽（runner.py#L116）。

快速上手：一条命令跑完全流程

# 标准深度：沙箱化 LLM 猎手 + 对抗验证 + 机制记忆 + 变体循环 clearwing sourcehunt /path/to/repo --depth standard

更多参数与变体（--flow proof证明携带流程、--ndayN-day 利用、--reveng逆向工程）见 docs/cli.md#L49 和 README.md。

总结：这套流水线好在哪里？

1. 预算可控：70/25/5 分层 + 带宽晋升 + 阶段级预算记账，花多少钱、花在哪一步都清清楚楚
2. 证据分级：从 suspicion 到 root_cause_explained 的四级证据阶梯，杜绝"模型说有风险就是风险"
3. 因果闭环：补丁预言机 + PoC 稳定性复跑，让结论经得起重编译与重放
4. 越跑越强：机制记忆 + 历史发现库让跨运行经验沉淀下来

对于安全新手，理解这 11 个阶段后，再去看 clearwing/sourcehunt/ 的源码，每个模块的职责会一目了然——这正是分阶段架构的最大价值：每个阶段都是可以被独立理解、独立替换的小问题，而不是一个黑盒大模型。