Cloudflare security-audit-skill 拆解：六阶段编排，查证漏洞的 agent 永远不是发现它的那个

一、速览：值不值得你花时间

推荐指数：★★★★☆（4 / 5）

先说这个项目的第一个反常点：22,616 star，只有 14 次提交。

我扒了一下提交历史，14 个 commit 里真正的重构只有两次（2026-09-10 的 “Rework the audit workflow, findings contract, and validators end to end”，和 2026-07-06 的 “Bring the whole skill into one coherent house style”）。仓库总共 21 个文件，其中 14 个是 Markdown 提示词文档，真正能执行的只有 4 个 .cjs（两个校验器 + 两个测试）和 1 个 JSON schema。

所以这不是一个”软件”，是一套”审计方法论的机器可读版本”。 star 数主要来自 Cloudflare 的品牌和那篇 Build your own vulnerability harness 博客 —— README 明说这个 skill 是那套 harness 的「single-repo starting point」，harness 后来长成了 fleet-wide 的多阶段系统。

那为什么还值 4 分？因为它解决的是 AI 审计领域最真实的那个痛点：agent 会说谎。

让 coding agent 审代码，你会得到一堆”发现 SQL 注入”的结论，然后你点进去看，发现它引的函数根本不存在，或者它说的那个入口点压根没被外部触达。原因很简单：agent 在生成结论时的”热情”和生成证据时的”严谨”不是一套机制。Cloudflare 这套流程的解法很朴素 —— 拆成不同的人干：

• 找漏洞的 agent（hunter）不许自己确认漏洞；
• 每个候选交给一个 fresh verifier，它的任务不是”验证”，是证伪；
• 最后还有一轮 record verification，再换一批 fresh agent 去核对”这条 finding 引用的源码到底是不是这么写的”；
• 如果这一步发生了实质性替换，还要再找一个独立验证者复核这次替换。

一个结论要活到 REPORT.md 里，得穿过三批互不知情的 agent。 这在提示词工程里是相当大的一件事。

第二条反常识是它敢写这句设计原则：

Multiple runs improve coverage. In our test runs, a single run found roughly half of the vulnerabilities that repeated runs found in total.

“一次跑只找到反复跑能找到的一半” —— 官方明说单次运行漏掉约 50%。这和 Cisco Skill Scanner 那篇（第 016 期，敢写召回率 7.75%）是同一种诚实。我在这个赛道里反复看到的现象是：所有人都在卷”我发现了多少”，没人说”我漏了多少”。Cloudflare 至少给了个量级。

扣分项也很明确：14 次提交 / 3 个月历史，工程成熟度远配不上 star 数；没有任何量化评测，不像 Cisco 那样给混淆矩阵，”一半”这个数字出自一句设计原则而非基准测试；沙箱要求非常硬，没有 OS 级强制沙箱它会主动把所有 lead 降级成 needs_validation 而不执行目标代码 —— 很多人跑完会发现”什么都没确认”；以及成本，6 阶段 × 多 hunter × 官方建议多次运行，一次全量审计的 token 消耗不是小数。

关键数据（截至 2026-10-07）

适合谁

二次开发

二、它是什么，不是什么

是：

• 一套 Markdown 写的 agent 编排规范，让你的 coding agent 按 6 个阶段做安全审计
• 一个 attack-class 知识库（12 个文档，覆盖从内存安全到 LLM 提示注入）
• 两个 零依赖校验器，用来卡住 findings.json 和 coverage-ledger.json 的结构
• Cloudflare 内部漏洞发现 harness 的公开简化版

不是：

• 不是扫描器。 它不 grep、不跑 SAST、不做污点分析。它指挥你的 agent 去做这些事。你要的是能出 SARIF 的扫描器，看第 012 期 Vigolium（Go 原生 324 个模块）或第 016 期 Cisco Skill Scanner。
• 不是漏洞数据库。 它产出的是你这一次审计的记录，不是 CVE 库。
• 不是确定性工具。 同样的仓库跑两次，结果会不一样。这是设计使然（它靠多轮运行叠加覆盖率），也意味着它不能做 CI 门禁。
• 不保证你找全。 官方原话：单次运行约找到一半。

有一个容易误解的点要单独讲：它扫的不是”skill”，是”任意代码库”。 名字里带 skill 是因为它本身是个 agent skill —— 和第 015 期 SkillSpector（NVIDIA 扫 3.1 万个 skill）、第 016 期 Cisco Skill Scanner 是完全不同的品类。那两个是扫别人写的 skill 有没有恶意，这个是给你自己的仓库做安全审计。

三、核心能力

3.1 三批互不知情的 agent（对抗式验证）

这是整套设计的地基。README 里写得很直白：

Adversarial validation. The agent that checks a finding is never the agent that found it.

流程上是四道：

1. Hunter（Phase 2）从 ledger 单元领任务，做完记录自己的检查项；
2. Verifier（Phase 3）拿一个全新的上下文，任务是证伪（tries to disprove it），不是复述；
3. Record verifier（Phase 5）再换一批 fresh agent，专门核对最终记录里引用的源码声明是不是真的；
4. 若第 3 步发生了实质性替换（material replacement），再找另一个独立验证者复核这次替换。

第 4 条是我觉得最狠的 —— 连”修正”本身都不信任。

3.2 覆盖账本（coverage-ledger.json）

这是它和传统 SAST 最本质的差别：按”覆盖”组织，不按”规则”组织。

Phase 1 侦察的产物是 architecture.md + coverage-ledger.json。ledger 把代码库切成审计单元，每个 hunter 领单元干活、记录自己查了什么。然后有专门的 coverage critics 去找空洞 —— 哪些单元没人认领、哪些声称查了但记录里没有对应证据。

父进程在创建 ledger 之后、以及之后每次 ledger 更新后都跑一次 validate-coverage-ledger.cjs。这个”每次更新都校验”的设定很关键：它防止 ledger 在长流程中被悄悄写坏。

好处是多次运行是叠加的：

Multiple runs against the same repo are additive. The skill uses prior ledgers and findings to target gaps, revalidate changed source, and carry forward current-source evidence without treating stale or unresolved work as covered.

最后半句是关键 —— 陈旧的和未解决的工作不会被当成”已覆盖”。很多增量扫描工具会犯这个错：上次扫过的文件这次跳过，结果上次那个 needs_validation 永远不会被重新处理。

3.3 三种裁决，语义严格分离

needs_validation 不给 severity 这条设计我很认同 —— 没验证完的东西凭什么有评级。它强制你把它当”待办”而不是”低危漏洞”，避免那种”一堆 INFO 级告警淹没真问题”的经典死法。

rejected 也记录而不是丢弃，这个也值得学：被证伪的路径本身是审计证据（告诉下一个 hunter 这条路走过了，别再走）。

3.4 几条”反直觉但正确”的判定原则

这几条我觉得比流程本身更值钱：

• Only confirm established boundary failures. 只确认已成立的边界失效。够不上就放 needs_validation，写清楚那个精确的未解决事实。
• Severity requires impact. 严重度 = 可能性 × 影响，不是”偏离 checklist 的程度”。这条直接对着 CVSS 打分玄学来的。
• Defense-in-depth gaps are not vulnerabilities. 如果 A 层已经挡住了攻击，B 层缺失只是加固建议，不是漏洞。 这条能砍掉一半的无效工单。
• Target-neutral reporting. 报告对目标中立 —— 不因为你审的是自家项目就放水。

四、架构：6 个阶段在干什么

校验器的调用时机是刻意设计的：

• validate-coverage-ledger.cjs —— Phase 1 建完就跑，之后每次 ledger 更新都跑（Phases 1–5）
• validate-findings.cjs —— Phase 4 跑一次，Phase 5 每次替换后再跑

这个”每次变更后重新校验”的模式，是长流程 agent 编排的标准答案。 6 个阶段跑下来可能几十分钟，中间产物极易漂移，靠末端一次性校验是拦不住的。

12 个攻击类文档

这是它真正的内容资产，也是唯一能脱离流程单独用的部分：

RESOURCE-EXHAUSTION 里专门列了 operator spend（运营者支出）这一类 —— 在 AI agent 时代这是真实的攻击面（让你的 agent 疯狂烧 token / 疯狂调付费 API），传统 checklist 里很少见。

五、生态与基准

这里必须说清楚：它没有基准测试。

Cisco Skill Scanner（016 期）给了带混淆矩阵的评测，SkillSpector（015 期）扫了 3.1 万个 skill 出了统计。Cloudflare 这个一个数字都没有，唯一可引用的量化陈述是设计原则里那句 “a single run found roughly half of the vulnerabilities that repeated runs found in total”。

这句话的出处是 “In our test runs”，不是公开基准。 我把它当作量级参考，不当作可复现指标。

不过它有几个别的”可信度来源”：

• 血统：README 明写这是 Cloudflare 内部漏洞发现 harness 的起点，harness 已长成 fleet-wide 系统。这是”我们在生产里真跑”的声明，虽然不可验证。
• 52 个 open issue（相对 22.6k star 比例极低，说明要么用的人少要么问题少，两者都有可能）。
• 1,315 fork，说明二次修改的人不少 —— 对一套提示词来说 fork 是主要的”使用”方式。

和同类的横向位置：

它的独特位置是：唯一一个把”防 agent 自我欺骗”作为核心设计目标的公开产物。 其他工具都在提升”发现能力”，它在提升”结论可信度”。

六、部署

安装

1
2
3
4
5
6
7
8

# 项目级
npx skills add https://github.com/cloudflare/security-audit-skill \
  --skill security-audit

# 用户级
npx skills add https://github.com/cloudflare/security-audit-skill \
  --skill security-audit \
  --global

需要在目标仓库里（或指向它）启动你的 coding agent，然后直接说：

1
2
3

security audit this codebase
find security vulnerabilities in ./src
do a security review, output to ~/audits/my-project

skill 会在请求匹配触发词（security audit / find vulnerabilities / pen-test the code 等）时自动激活。

两种模式

• Full audit mode —— 直接的”审这个代码库 / 做渗透测试”请求。产出完整报告产物。
• Guidance mode —— 安全提问、聚焦的漏洞分析。默认走这个，除非你明确要求报告产物。

输出目录不指定时默认 ~/security-audit-skill/<repo-name>/run-<N>。注意这个 run-<N> —— 它就是为”多次运行叠加”设计的，第二次跑会开 run-2 并读 run-1 的 ledger。

硬性前置条件（这条最容易踩）

1. 支持工具调用 + 并行子 agent 的 coding agent（Claude Code / Codex 这类；不支持并行 sub-agent 的 agent 跑不了多 hunter）
2. Node.js —— 只为跑那两个零依赖校验器
3. OS 强制沙箱，用于执行目标控制的代码（build / test / process / browser / emulator / fuzzer / fixture）。要求：
   • 禁用外部网络
   • 使用净化过的白名单环境
   • 强制资源上限
   • 只允许写入指定的 scratch 路径

第 3 条不是建议，是开关。README 原话：

Without these controls, the workflow keeps the lead as needs_validation instead of executing target code.

没有沙箱 → 所有 lead 停在 needs_validation → 你拿到一份”什么都确认不了”的报告。 这是安全设计（审恶意代码时绝不裸跑），但如果你没配好沙箱，体验就是”这工具没用”。

关于”不写回仓库”

README 有一句很克制的话：

The workflow writes inside the target repository only when you explicitly select a directory that version control ignores.

默认产物全在 ~/security-audit-skill/ 下，不会污染你的 git 工作区。对比一些会往仓库里塞 .audit/ 目录的 agent 工具，这个默认行为很体面。

七、边界与风险

1. 14 次提交 / 3 个月历史，别被 22k star 骗了。
Star 数来自 Cloudflare 品牌 + 那篇博客，不是代码成熟度。提交集中在两个人（literally-dan、Dan Jones）。这是一份高质量的方法论草案，不是一个 hardened 的产品。

2. 零量化评测。
“单次找到一半”来自设计原则里的一句 “in our test runs”。没有测试集、没有混淆矩阵、没有可复现脚本。你没法评估它在你的代码库上到底能覆盖多少。 这一点上它明显不如 Cisco Skill Scanner 诚实 —— 后者把难看的数字（召回 7.75%）写成了专门的章节。

3. 成本是真门槛。
6 阶段 × 多 hunter × coverage critics × 三轮验证 × 官方建议多次运行。一次全量审计的 token 消耗可能比你想的高一个量级，而”要跑到约 100% 覆盖需要多跑几次”是官方明说的。在大仓库上先小范围试。

4. 沙箱没配好 = 白跑。
见上一节。这是最常见的”装完发现没用”的原因。

5. 它不产出合规交付物。
findings.json 是自定义 schema，不是 SARIF。进不了 DefectDojo / Jira 安全工单这类现有流程，得自己写映射。

6. 非确定性。
同样输入两次跑，结果不同。绝对不要拿它当 CI 门禁 —— 你会得到一堆 flaky 的构建失败。它的定位是”定期人工触发的深度审计”，不是”每次 commit 的卡点”。

7. 提示词注入的面。
审的是你自己仓库还好；如果你拿它审第三方 / 不可信代码库，代码里的注释和文档本身就是注入载体（AI-AND-LLM.md 里明确列了 prompt injection 类）。官方的沙箱要求能挡一部分执行面，但 agent 读到的文本是挡不住的。

8. 51 个 open issue 里可能有你关心的问题。
相对 22.6k star 这个比例不高，但项目只有 3 个月，issue 沉淀才刚开始。

八、上手建议（按这个顺序来）

1. 先只读 SKILL.md 和 VALIDATION-AND-REPORTING.md。 前者有”audit anti-patterns”（审计反模式）一节，后者是 Phase 3–6。这两篇读完你就知道它想干什么了，比直接跑省时间。
2. 单独抽 ATTACK-CLASSES.md 用。 哪怕你不用这套流程，那份攻击类清单当人工 code review 的 checklist 也值。审 LLM 应用看 AI-AND-LLM.md，审 Web 看 WEB-PROTOCOL-AND-AUTH.md。
3. 先把沙箱配好再跑第一次。 禁用外网 + 资源上限 + 只写 scratch 路径。这一步偷懒，后面全是 needs_validation。
4. 第一次跑用小目录，别上整个仓库。 用 find security vulnerabilities in ./src 这类限定路径的指令先试水，摸清 token 消耗。
5. 确认你的 agent 支持并行子 agent。 不支持的话多 hunter 退化成串行，时间会非常长。
6. 显式指定输出目录（do a security review, output to ~/audits/my-project），别让它默认堆 run-<N>。
7. 至少跑两次再看结论。 官方明说单次约一半。第二次跑会读第一次的 ledger 去填空洞 —— 这才是这套设计真正发挥作用的时刻。
8. 先看 NEEDS-VALIDATION.md，不是 REPORT.md。 那份”精确的未解决事实”清单，往往比已确认项更能告诉你这套流程在你的代码上卡在哪。
9. 想接自己的平台，从 report-schema.json 入手。 它是标准 JSON Schema，映射成你自己的 finding 格式不难。
10. 别拿它当门禁。 定期人工触发的深度审计，不是 CI 卡点。

九、一句话结论

Cloudflare security-audit-skill 值 22k star 不是因为它多成熟（14 次提交、零量化评测、才 3 个月），而是因为它是我见过的唯一一个把「如何让 agent 不对自己的结论撒谎」写成可执行流程的公开产物 —— 三批互不知情的 agent、被证伪也要记录、陈旧工作不算覆盖、单次只找到一半，这四条任何一条单独拿走都能改进你现有的 AI 审计实践。

给开发者的第一动作：npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit --global → 把 ATTACK-CLASSES.md 当 checklist 用起来 → 配好沙箱 → 拿 ./src 下一个小模块跑第一次，先看 NEEDS-VALIDATION.md。 即便你最后不用这套流程，那份 6 阶段设计和 12 个攻击类文档也值得读一遍 —— 它最好的部分不是代码，是那 14 个 Markdown 文件里的判断力。