Cloudflare 开源技能包：让 Agent 做多阶段安全审计

security-audit-skill 是 Cloudflare 开源的一套编码 Agent 安全审计技能包；它没有增加新的漏洞特征库，核心机制是把安全审计拆成多个可独立验证的阶段，并为检查标准、风险分级和输出格式设定固定流程，引导模型依序审计，避免随意扫描代码。

它与“帮我审一下这段代码”式 prompt 的主要区别，不在于提示词写得多长，而在于审计知识是否被封装成了可以重复加载的工作资产。普通 prompt 通常把要求集中在一段自然语言指令里；skill 则把检查清单、判断标准、参考资料、辅助脚本和报告模板拆开存放，Agent 加载后再按既定工序执行，结果因此更容易复现和比较。 当然，可复现并不等于绝对正确；这种方式减少的是随意发挥和流程遗漏，而不是消除模型判断误差。

安全审计适合做成 skill，因为 OWASP Top 10、CWE 等分类体系已经相对成熟，注入、越权、弱加密、不安全反序列化等安全问题也有相对明确的判定特征。模型不必从开放式的“看看有没有漏洞”开始推理，而是可以根据不同规则调用资料和工具，再将证据整理为发现项。 传统扫描器仍然适合承担依赖版本比对、敏感信息匹配等确定性工作；security-audit-skill 的差异主要在于组织这些检查、补充代码上下文，并形成一条完整的 Agent 审计流水线。

Skill 的内部组织：规则、参考资料与辅助脚本

从该项目体现的 Agent Skill 组织方式看，Rules、References 和辅助脚本分别处理“如何判断”“依据是什么”和“怎样完成确定性操作”；三者不是彼此独立的工具。

Rules 承载具体的自然语言检查规则，包括检查对象、触发条件、风险判断方式和处理要求。规则被单独拆开后，Agent 不必在一次对话里接收所有检查项，可以在进入每个阶段时加载与当前任务有关的规则。这比把所有 OWASP 条目、代码规范和检查问题一次性塞进上下文更稳定。

References 保存 OWASP 条目、CWE 描述等背景资料，并采用按需加载的方式。平时不把完整参考资料塞进上下文，只有某条规则被触发时，Agent 才读取对应条目，从而节省 token，也减少模型在大量无关文本之间误读规则。

辅助脚本负责依赖扫描、AST 解析和控制流分析等适合确定性执行的任务。自然语言规则负责告诉 Agent 应该查什么，脚本则负责定位代码结构、追踪关键路径或提供可重复的证据，两者结合后，审计结论不再完全依赖模型对源码的即兴阅读。 因此，skill 的价值并不是“让模型背下更多安全资料”，而是把资料、规则和工具组织成一条可以被 Agent 调用的执行链。

多阶段审计的执行流程：从依赖到报告

多阶段审计按检查性质分为“依赖与漏洞库比对、敏感信息扫描、配置审查、核心代码审计、聚合输出”。每个阶段只关注有限的问题和上下文，可以减少模型同时处理大量互不相关规则时出现注意力发散、重复报告或漏检的风险。

第一阶段处理环境与第三方依赖，主要确认项目使用的库和版本是否处于已知漏洞的影响范围。这一阶段以版本证据和漏洞库信息为主，输出应明确指出受影响的组件，而不是只给出“建议升级依赖”这种无法核验的结论。

第二阶段扫描敏感信息，重点寻找硬编码的 API key、密码、token 和私钥。与普通代码缺陷相比，敏感信息通常有更直接的泄漏路径，但发现字符串后也不能立即断言风险成立：仍需判断它是否为示例值、测试数据、公开标识，或者是否已经失效。

第三阶段审查配置危险项，例如生产环境仍开启调试模式、CORS 范围过宽、默认权限过高等。配置问题与源码逻辑问题的证据形态不同，分开处理后，Agent 可以针对配置键、环境和取值逐项核验，而不必把配置文件与核心代码混在一起分析。

第四阶段深入核心代码逻辑，检查注入、越权、弱加密和不安全反序列化等问题。单纯依靠文本匹配，很难确认输入是否真正到达危险操作，也难以判断授权判断、校验逻辑或加密调用所处的控制流位置，因此这一阶段更需要 AST 解析和控制流辅助脚本提供证据。

最后一个阶段负责聚合发现项。前面各阶段产生的结果不能只是互不关联的日志，而要整理为发现项，统一记录位置、严重度、证据、复现步骤和修复建议，并在聚合时保留信息来自哪个检查阶段。这样既能生成面向开发者的报告，也能为 CI 检查提供稳定输入。

多阶段流程并不能证明“所有漏洞都已覆盖”。它解决的是审计组织问题：把大问题拆成边界更清楚的小问题，让每个阶段可以独立执行、重新验证并定位失败原因。整个流程仍然可能出现漏报，尤其是依赖业务语义才能成立的缺陷，不能靠流程拆分自动消除。

审计结果的验证与阻断：机读发现项、误报控制及 PR 合并控制

报告应输出一组机器可消费的结构化发现项，而不只是自然语言审计结论。资料中明确涉及的核心字段包括漏洞位置、严重等级、复现步骤和修复建议；独立验证还需要保留支撑结论的证据及验证方式。 下列内容只是字段关系的示意，并不代表仓库当前固定的 JSON schema：

{
  "location": {
    "file": "<repository-relative-path>",
    "line": "<line-or-range>"
  },
  "severity": "<severity-level>",
  "evidence": "<supporting-code-or-configuration-evidence>",
  "reproduction_steps": [
    "<step>"
  ],
  "remediation": "<suggested-fix>",
  "verification": {
    "method": "<script-or-manual-replay>",
    "result": "<verification-result>"
  }
}

“独立可验证”是这些发现项与普通模型回答的关键区别。每个结论都应能通过单独脚本重跑，或者由人工按照复现步骤回放；如果无法定位证据、描述触发路径或确认修复结果，它就更接近待调查线索，而不是已经完成验证的漏洞。 AST 和控制流脚本可以把源码位置、数据流或分支条件变成可以重复检查的证据。

机读输出使 PR 自动阻断成为可能，但 skill 本身主要负责生成发现项，真正阻止合并还需要工程侧读取报告、应用严重度阈值，并让 PR 检查返回失败结果。也就是说，阻断能力来自“审计技能、报告格式、CI 策略”三者的连接，而不是技能文件天然拥有合并权限。

误报控制可以由三条机制共同完成。第一条是量化阈值：使用 CVSS 等指标划分严重程度，让高危发现优先进入阻断流程。但严重度不等于检测置信度，CVSS 分数不能代替独立验证，真实性和风险等级仍应分别记录。

第二条是上下文管理。阶段化执行和 References 按需加载，能够减少无关代码与规则同时进入上下文造成的干扰；当单个阶段需要处理的代码范围过大时，Agent 也更容易出现遗漏或把无害模式误判为漏洞。

第三条是跨阶段交叉验证。例如，敏感信息扫描先发现疑似 token，再由配置或代码调用关系确认它是否可能被暴露；依赖扫描发现受影响版本后，还需要结合组件是否进入实际执行路径判断影响。不同阶段的证据互相佐证，可以降低单个检测器或单次模型判断带来的噪声，但跨阶段未命中也不能直接证明代码安全。

接入 Claude Code、Codex、OpenCode、Spring AI 等编码 Agent 时，宿主先加载并调用 skill，再由 CI 读取它生成的结构化报告。Agent 可以在写代码、改代码、审代码和提交 PR 等环节触发审计，但具体加载和触发配置仍取决于各宿主当前采用的技能机制，不能认为“挂载 skill”对应一条对所有 Agent 都通用、完全相同的安装命令。

security-audit-skill 的合理定位是编码流水线中的工程化自查和标准化安全闸门，可以提前发现并拦截一部分有证据支持、能够复现的问题；复杂业务逻辑漏洞、完整攻击面建模以及多组件联动风险，仍需要专业安全工程师通过渗透测试和深度人工审计覆盖。