Security Audit Skill 零基础使用教程：让 AI 编程智能体给你的代码做一次安全审计

分类：开发工具｜难度：入门｜类型：实操教程｜软件：Security Audit Skill
标签：开源、安全审计、AI 智能体、代码安全、Cloudflare｜预计阅读：约 10 分钟

一、这是什么

Security Audit Skill 是 Cloudflare 开源的一款「编程智能体安全审计技能」（coding-agent skill）：它把你常用的 AI 编程智能体（例如 Claude Code、Codex 这类支持工具调用与并行子智能体的工具）变成一名安全审计员，按一套固定流程给代码库做安全审计。它在 2026 年 11 月 8 日登上 GitHub 当日热门榜，核实时主仓库已有约 6.57 万个 star，当日新增约 2,085 个，许可证为 MIT。

它的来头不小：这是 Cloudflare 漏洞发现流水线（vulnerability discovery harness）的起点，官方博客《Build your own vulnerability harness》介绍过这套流水线如何从单仓库技能演变成多阶段的舰队级系统。这个开源技能就是那套系统的单仓库 starting point。

和「随口问智能体一句有没有漏洞」不同，它跑的是一套六阶段的固定流程：

1. 侦察（Reconnaissance）：摸清架构、信任边界、输入面和已有证据，写成 architecture.md 与 coverage-ledger.json（覆盖台账）。
2. 覆盖驱动的猎捕（Coverage-led hunting）：按台账分派相互隔离的猎捕智能体逐个检查，再由覆盖评审员找出遗漏。
3. 候选验证（Candidate validation）：每个可疑发现都交给一个全新的验证智能体，专门尝试推翻它。
4. 结构化输出（Structured output）：把结果写进 findings.json，分三档——confirmed（已确认）、needs_validation（待验证）、rejected（已证伪），并用 report-schema.json 校验格式。
5. 独立记录核查（Independent record verification）：再派新的智能体独立核查最终报告里的每一条源码引用，改动过的内容还要再过一遍验证。
6. 目标中立报告（Target-neutral reporting）：从已核查的记录和覆盖台账生成 REPORT.md、FINDINGS-DETAIL.md 与 NEEDS-VALIDATION.md。

关键设计原则有四条，都写在 README 里：只确认「已经证实的边界失效」，没证实的就老实标为待验证；检查发现的智能体绝不能是发现它的那个（对抗式验证）；严重程度要看实际影响，不是照着检查表打分；某一层防护缺失、但另一层已经挡住攻击的，只能算加固建议，不算漏洞。

它适合这些人：想给自己的项目做一次系统安全检查的开发者；已经在用 Claude Code、Codex 等编程智能体，想让它们按规范流程审计代码的人；以及对 AI 安全审计流程本身感兴趣、想照着学一遍的人。

二、开始前先确认

• 先装好一个编程智能体：官方要求使用「支持工具调用与并行子智能体的模型」的编程智能体，例如 Claude Code、Codex 等，并完成登入。Security Audit Skill 本身不提供模型，它只是给智能体的一套审计工作法。
• 装好 Node.js：审计过程中用到的两个校验器 validate-findings.cjs 与 validate-coverage-ledger.cjs 是零依赖的 Node.js 脚本，需要本机有 Node.js 才能运行。
• 只审计你有权审计的代码：审计你自己的项目、公司的项目（经授权），或明确允许审计的开源项目。不要拿它去扫别人的私有代码或未经授权的目标。
• 准备好沙箱环境：官方要求，凡是目标代码控制的构建、测试、进程、浏览器、模拟器、模糊测试与 fixture，都必须在操作系统强制隔离的沙箱里跑：禁用外部网络、使用经过清理的白名单环境变量、限制资源、只允许写入指定的临时路径。没有这些控制时，工作流不会执行目标代码，而是把相关线索保留为 needs_validation。
• 审计结果不是最终判决：confirmed 是有完整源码 trace 与可观测结果的已确认发现；needs_validation 是还有未解事实、没有严重程度的待验证线索；rejected 是已被证伪的候选。看报告时要按这个分档理解，不要把三档混为一谈。
• 多跑几次覆盖更好：官方实测，单次运行大约只找到多次运行总共发现的漏洞的一半。同一仓库多次运行是叠加的：它会利用已有的台账与发现去补缺口、复核改动过的源码。

三、操作步骤

步骤 1：确认编程智能体与 Node.js 已就绪

先确认两件事。第一，你的编程智能体已经安装并登入，例如 Claude Code 或 Codex 能正常打开并对话。第二，本机装有 Node.js，在终端执行：

node --version

能印出版本号（例如 v22.x.x）即可。没有 Node.js 的话，先去 Node.js 官网下载安装包安装，或用包管理器安装，装好后再回到这一步。

这两项是官方 Requirements 里明确列出的前置条件：智能体负责执行审计，Node.js 负责运行校验器。

图 1：先确认编程智能体与 Node.js 就绪，再安装审计技能的示意。图片为 AI 生成的操作示意图，实际界面以终端输出为准。

步骤 2：安装 Security Audit Skill

官方推荐用 Skills CLI 安装。在终端执行：

npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit

这条命令会把 security-audit 这个技能装到当前项目。想装成用户级、所有项目都能用，加上 --global：

npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit --global

想查看支持哪些智能体、非交互式安装等选项，执行：

npx skills --help

安装完成后，技能文件就在你的智能体技能目录里，包括 SKILL.md（安装说明、核心原则与工作流总览）与各阶段的提示词文件（RECONNAISSANCE.md、HUNTING.md、ATTACK-CLASSES.md、VALIDATION-AND-REPORTING.md 等），以及 report-schema.json 与两个校验器脚本。

步骤 3：打开目标代码库，发起审计

启动你的编程智能体，进入（或指向）要审计的代码库，然后直接用自然语言下指令，例如：

security audit this codebase

也可以限定范围或指定输出位置：

find security vulnerabilities in ./src

do a security review, output to ~/audits/my-project

技能会在请求匹配触发条件（security audit、find vulnerabilities、pen-test the code 等）时自动激活。直接要求审计代码库或做渗透测试时，用的是完整审计模式；只是问安全问题、做聚焦的漏洞分析时，默认用指导模式，除非你明确要求输出报告文件。

完整审计模式下，如果没有指定输出目录，报告默认写到 ~/security-audit-skill/<仓库名>/run-<N>。注意：工作流只在你明确选择了一个「版本控制会忽略的目录」时，才会在目标仓库内部写文件。

审计跑起来后，智能体会按六个阶段推进：先侦察并生成架构说明与覆盖台账（每更新一次台账都会跑 validate-coverage-ledger.cjs 校验），再分派隔离的猎捕智能体逐个检查，接着由全新验证智能体逐条尝试推翻候选发现，最后生成结构化结果并独立核查报告里的源码引用。这个过程可能比较久，让它在后台慢慢跑，不用一直盯着。

图 2：编程智能体按六阶段流程审计代码库的示意。图片为 AI 生成的操作示意图。

步骤 4：读懂审计报告

审计完成后，到输出目录里看这几份文件：

• REPORT.md：总报告，先读它，了解整体结论与已确认发现的数量。
• FINDINGS-DETAIL.md：每条发现的详情，包括源码位置与证据链。
• NEEDS-VALIDATION.md：待验证线索清单，每条都写明了「具体哪个事实还没确认」。
• findings.json：机器可读的结构化结果，三档 verdict 分别是 confirmed、needs_validation、rejected，已用 report-schema.json 校验过格式。
• architecture.md 与 coverage-ledger.json：侦察阶段的产物，前者是架构与信任边界说明，后者是覆盖台账——哪些面查过、哪些还没查，一目了然。

读报告的顺序建议：先看 REPORT.md 的结论，再按 confirmed 的严重程度逐条看 FINDINGS-DETAIL.md，最后看 NEEDS-VALIDATION.md，决定哪些线索值得你手动跟进验证。

图 3：阅读审计报告、按确认程度处理发现的示意。图片为 AI 生成的操作示意图。

步骤 5（进阶）：多跑几次、复核与处理发现

官方实测表明单次运行只能找到约一半的漏洞，所以值得多跑几次：同一仓库的多次运行是叠加的，技能会利用已有的台账与发现去补覆盖缺口、复核改动过的源码，而不会把过时或未解决的工作当成已覆盖。

处理发现时按分档来：

• confirmed：有完整源码 trace 与可观测结果，按严重程度排期修复，修完后可以再跑一次审计复核。
• needs_validation：每条都有明确的「未解事实」，手动验证这个事实，确认了就升级处理，证伪了就记为拒绝。
• rejected：已被验证智能体证伪的候选，留档即可，不用再跟进。

想自己校验结构化结果的格式，可以直接跑技能自带的零依赖校验器：

node validate-findings.cjs findings.json

node validate-coverage-ledger.cjs coverage-ledger.json

这两个脚本都在技能目录里（validate-findings.cjs 与 validate-coverage-ledger.cjs），审计流程在第 1、4、5 阶段也会自动调用它们。

四、恢复办法

• 终端提示 npx: command not found：本机没有 Node.js，先安装 Node.js（步骤 1），再重新执行安装命令。
• 智能体没有激活技能：确认技能已安装（npx skills add 是否成功执行），并用明确的触发说法下指令，例如 security audit this codebase；也可以直接要求「用 security-audit 技能审计这个代码库」。
• 审计中途报错或停住：先看智能体的输出与报错信息；多数情况下重新下一次审计指令即可，已生成的台账与发现会被下一轮利用，不用从头再来。
• 报告里全是 needs_validation：很可能是沙箱控制不到位——没有操作系统强制隔离时，工作流不会执行目标代码，相关线索只能保留为待验证。按步骤 1 的要求配好沙箱（禁外部网络、白名单环境变量、资源限制、只写指定临时路径）后再跑。
• 想换个输出位置：下指令时直接指定，例如 do a security review, output to ~/audits/my-project；默认输出在 ~/security-audit-skill/<仓库名>/run-<N>。
• 不想用了：删除技能目录里的 security-audit 技能文件与输出目录即可，审计本身不留后台进程，也不改你的代码库。

五、注意事项（必读）

• 只审计有权审计的代码：自己的项目、经授权的项目或明确允许审计的开源项目；不要扫未经授权的目标。
• 沙箱不到位就别跑目标代码：目标代码控制的构建、测试与模糊测试必须在操作系统强制隔离的沙箱里跑；没有这些控制时，工作流只会把线索标为待验证，不会执行目标代码。
• 严重程度看影响，不看检查表：官方原则是「Severity requires impact」——按实际影响定级；某一层防护缺失、但另一层已挡住攻击的，只是加固建议，不是漏洞。
• 验证者不能是发现者：对抗式验证是这套流程的核心，检查发现的智能体绝不能是发现它的那个；手动复核时也一样，换个人、换个角度再看一遍。
• 单次运行覆盖有限：一次大约只能找到一半，多跑几次、让覆盖台账去补缺口，效果才完整。
• 报告要按分档读：confirmed、needs_validation、rejected 是三档不同的结论，不要把待验证线索当成已确认漏洞去报，也不要把已证伪的候选再翻出来。
• 它还很新：仓库创建于 2026 年 6 月，目前只有 14 个提交、没有正式 Release；流程与个别文件以后可能调整，遇到与本教程不一致的地方，以官方 README 与技能文件为准。

六、官方资源链接

• GitHub 项目：https://github.com/cloudflare/security-audit-skill
• 官方博客（漏洞发现流水线介绍）：https://blog.cloudflare.com/build-your-own-vulnerability-harness
• Skills CLI：https://skills.sh
• 联系邮箱：security-ai-research@cloudflare.com

七、常见问题

Security Audit Skill 是免费的吗？

是。项目采用 MIT 许可证，开源免费；它用的是你自己的编程智能体与模型订阅，不另外收模型费用。

它和直接问智能体「有没有漏洞」有什么不同？

直接问是一次性回答；这个技能跑的是六阶段固定流程：侦察建台账、隔离猎捕、对抗式验证、结构化输出、独立核查、生成报告，每条发现都有源码 trace 与明确的分档结论。

一定要用 Claude Code 吗？

不一定。官方要求是「支持工具调用与并行子智能体的模型」的编程智能体，Claude Code、Codex 等符合条件的工具都可以用；安装时用 npx skills --help 查看支持的智能体选择。

审计要跑多久？

取决于代码库大小与模型速度。六个阶段、多轮隔离验证，完整审计通常比一次问答慢得多，让它在后台慢慢跑即可。

报告默认存在哪里？

完整审计模式下，未指定输出目录时默认在 ~/security-audit-skill/<仓库名>/run-<N>；下指令时也可以直接指定，例如 output to ~/audits/my-project。

它会改我的代码吗？

不会。工作流只在你明确选择了一个版本控制会忽略的目录时，才会在目标仓库内部写文件；报告默认写在仓库外面。

没有沙箱能用吗？

能用，但有限制：没有操作系统强制隔离时，工作流不会执行目标代码，相关线索会保留为 needs_validation，而不是直接验证。

多跑几次真的有用吗？

官方实测：单次运行大约只找到多次运行总共发现的漏洞的一半；多次运行是叠加的，会利用已有台账补缺口、复核改动过的源码。