security-audit-skill 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

security-audit-skill 是 Cloudflare 发布的编码代理安全审计技能，用多阶段工作流协调相互隔离的审计代理，将代码库审查整理为可追踪、可验证的结构化记录。它的重点不是把一次模型判断直接当作漏洞结论，而是将覆盖规划、候选验证、独立复核与报告生成串联起来。

仓库资料显示，该项目使用 JavaScript，许可证为 MIT，默认分支为 main；GitHub 元信息所列 Star 为 68960、Fork 为 4549。运行工作流需要支持工具调用与并行子代理的编码代理、Node.js，以及对目标代码执行进行操作系统级隔离的沙箱。

定位与目标用户

该项目把安全审计流程包装为编码代理可调用的技能，面向希望在单个代码库中开展有记录、可复核审计的开发团队、安全工程师和代码审查人员。它不是独立运行的扫描器；实际工作由兼容的编码代理执行，并依赖代理能够调用工具和并行子代理。

README 将它描述为 Cloudflare 漏洞发现 harness 的单仓库起点。该 harness 后来扩展为多阶段、面向整个 fleet 的系统；仓库本身提供的是面向单一代码库的技能，不能据此推断它包含该 fleet 系统的规模、服务或运营能力。

核心功能

技能把审计拆成六个阶段，以减少遗漏、降低错误结论进入报告的机会。各阶段的输入输出会写入台账、结构化发现记录和报告，后续阶段能够检查前序阶段留下的证据。

侦察与覆盖台账

第一阶段梳理架构、信任边界、输入面、既有证据和确定性覆盖范围，并生成 architecture.md 与 coverage-ledger.json。侦察结果为后续 hunting 提供范围单元；台账验证器会在台账创建后运行，并在之后每次更新时再次运行。

按覆盖范围开展审查

第二阶段依据覆盖台账中的单元分派相互隔离的审查代理，记录其检查情况，再由覆盖审查代理寻找遗漏。它的触发基础是已整理的覆盖单元，而不是只围绕一个未经归档的漏洞猜测反复搜索；资料没有给出代理数量、并发上限或调度算法。

候选漏洞的反证验证

每个唯一候选发现都会交给一个新的验证代理，尝试推翻该候选。发现者与验证者不是同一个代理，这种安排将候选提出和结论核查分开；验证所依据的代码证据和执行结果需由工作流记录。

结构化发现与独立记录验证

第四阶段将记录写入 findings.json，并使用 report-schema.json 检查格式。记录有 confirmed、needs_validation 和 rejected 三种判定；第五阶段再由新的代理核对最终记录中的源代码主张，若记录被实质性替换，还要再经过一次独立验证。

目标无关的报告生成

最后一个阶段从已验证记录和覆盖台账派生 REPORT.md、FINDINGS-DETAIL.md 与 NEEDS-VALIDATION.md。这种派生关系让报告与机器可读记录保持关联；README 未说明报告模板的全部字段或可配置格式。

“Only confirm established boundary failures. Keep a source-grounded blocked lead as needs_validation with its exact unresolved fact.”

来源：README。其含义是，只有建立了边界失效证据的候选项才进入确认结论；有源码依据但仍受阻的线索，应保留未解决事实，而不是补写严重性判断。

系统架构与关键模块

项目架构由技能说明、按目标类型组织的审计提示、结构化数据模式、校验脚本和报告阶段组成。它不要求把所有攻击类别提示一次性用于所有目标，而是根据目标技术形态选择相关审计材料。

流程与提示文件

• SKILL.md：技能设置、核心原则、平台术语、工作流概览和审计反模式。
• RECONNAISSANCE.md：第一阶段的侦察提示和汇总说明；HUNTING.md：第二阶段的编排、审查方法和验证规则。
• ATTACK-CLASSES.md：核心、通配和显而易见事项的审查提示。
• MEMORY-SAFETY-AND-BINARY.md、AI-AND-LLM.md、WEB-PROTOCOL-AND-AUTH.md、CLIENT-SIDE.md：分别覆盖原生目标、LLM 支持目标、HTTP 协议与认证目标，以及浏览器和客户端目标。
• SUPPLY-CHAIN-AND-RELEASE.md、CLOUD-AND-DEPLOYMENT.md、PROTOCOLS-RPC-AND-MESSAGING.md：分别聚焦供应链与发布、云和部署、RPC 与消息传递。
• RESOURCE-EXHAUSTION-AND-AVAILABILITY.md、DATA-ISOLATION-AND-LIFECYCLE.md、DESKTOP-MOBILE-AND-LOCAL-IPC.md：分别覆盖资源与可用性、数据隔离与生命周期、桌面移动端与本地进程间通信。
• VALIDATION-AND-REPORTING.md：第三至第六阶段的候选验证、结构化输出、记录复核和报告生成。

数据约束与验证器

report-schema.json 描述三类发现记录的结构；validate-findings.cjs 与 validate-coverage-ledger.cjs 则分别校验发现文件和覆盖台账。README 将它们标为零依赖验证器，并说明发现校验在第四阶段执行、第五阶段替换记录后再次执行。

仓库同时包含两个验证器的测试文件：validate-findings.test.cjs 和 validate-coverage-ledger.test.cjs。资料没有给出测试命令、测试框架或 CI 工作流细节，因此不应据此推断具体的验证命令。

依赖与运行环境

执行完整工作流需要具备工具调用能力和并行子代理能力的编码代理，并需要 Node.js 执行两个零依赖验证器。README 未提供 Node.js 版本范围，也未列出编码代理的版本兼容矩阵。

运行时隔离是明确的前置要求，而非可选优化。操作系统强制执行的沙箱需要禁用外部网络、使用经过清理且按允许列表限定的环境、实施资源限制，并且只允许向分配的临时路径写入。

• 没有符合要求的沙箱时，不应运行目标代码、构建过程、测试、浏览器、模拟器、模糊测试器或目标夹具。
• README 指出，缺少这些控制时，工作流会将相关线索保留为 needs_validation，而不是执行目标代码。
• 代理工具、沙箱实现、资源限制数值和操作系统兼容范围：官方仓库未提供该信息，建议以最新 README 为准。

快速开始

最小使用路径是先安装技能，再在待审计代码库中启动兼容的编码代理并提出审计请求，最后检查生成的发现记录和报告。执行前应确认目标属于获准审计范围，并已配置 README 要求的操作系统级隔离。

安装

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

这条命令来自 README。若需要按用户级别安装，README 提供了 --global 选项；CLI 的代理选择和非交互参数应通过其帮助命令核对。

npx skills --help

运行与验证

在目标代码库目录中，或在编码代理明确指向该代码库的情况下，发起完整审计请求。下面的请求是 README 给出的实际用法；是否产生完整审计工件，取决于代理是否将请求识别为完整审计模式。

security audit this codebase

审计完成后，应检查工作流生成的 findings.json 与覆盖台账，并查看派生报告。README 规定会运行相应的零依赖校验器，但未提供从仓库根目录直接执行这些脚本的示例命令，所以本文不补写未经资料确认的命令行。

输出目录示例

若明确要求将报告写到指定位置，可以使用 README 中的目录示例。技能只会在用户明确选择了版本控制忽略的目录时写入目标仓库；完整审计未指定输出目录时，默认位置为 ~/security-audit-skill/<repo-name>/run-<N>。

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

该命令只是仓库提供的请求文本，不保证路径一定被版本控制忽略。执行前应自行核对目标仓库的忽略规则；README 未规定该示例目录是否自动满足忽略条件。

配置说明

README 没有提供 package.json、环境变量样例、配置文件示例或一组可配置参数。下表列出资料中能够确认的工作流约定，并将未给出的字段明确标记，避免把目录约定误写为配置接口。

表中的沙箱策略是安全运行要求，不是已证实的技能配置字段。具体环境变量名、沙箱配置格式、资源配额及输出路径参数的接口签名，官方仓库未提供该信息，建议以最新 README 为准。

进阶用法

该技能区分完整审计模式和指导模式。直接审计代码库或要求进行渗透测试时使用完整审计流程；只咨询安全问题或开展范围较窄的漏洞工作时，默认进入指导模式，除非明确要求生成报告工件。

用户可将审查范围指向特定目录，例如 README 给出的 find security vulnerabilities in ./src。这是对审查目标的请求描述，不应被理解为可绕过授权、隔离或证据验证的指令。

多次运行采用累积策略：既有覆盖台账和发现记录用于定位空白、复核已改变的源码，并承接当前源码证据。旧记录或尚未解决的工作不会自动视为已覆盖；因此，重复运行的价值在于针对缺口补充审查，而不是简单重复同一份结论。

README 提到，在项目测试运行中，单次审计发现的漏洞约为多次运行合计发现数的一半。这是仓库作者报告的测试观察，不是性能基准，也没有提供样本量、目标集或统计方法；不应将该数据外推为任何特定仓库的发现率承诺。

可观测性与运维

此项目的可追踪性主要来自工件，而不是一个在线仪表盘或服务端监控面板。侦察文档记录架构和信任边界，覆盖台账记录审查单元与检查情况，发现文件记录候选项判定，最终报告由这些经核验的数据派生。

运维时应把覆盖台账和发现文件的校验纳入每轮流程。README 明确规定，台账在创建后及每次后续更新后均要校验；发现文件在第四阶段和第五阶段每次记录替换后都要校验。

• 核对覆盖台账是否通过对应校验器，避免无效或不完整数据进入后续审查。
• 核对发现文件的结构校验结果，并确认报告与最终验证后的记录相符。
• 区分当前源码证据、过期证据和未解决线索；重复运行时，不把过期或未解决工作记作已覆盖。
• 监控界面、日志格式、指标名称、审计耗时和资源指标：官方仓库未提供该信息，建议以最新 README 为准。

安全与合规边界

这是具备安全审计和目标代码执行能力的工作流，应只用于获得授权的代码库和测试环境。授权范围应覆盖仓库、相关数据、构建与测试依赖，以及代理可能调用的本地工具；本文不提供针对未授权目标的攻击步骤或规避检测方法。

执行目标控制的构建、测试、进程、浏览器、模拟器、模糊测试器和夹具前，必须使用操作系统强制执行的沙箱。README 对沙箱提出四项要求：禁用外部网络、使用清理后的允许列表环境、执行资源限制，并将写入限制在分配的临时路径。

没有这些控制时，工作流应将线索保留为 needs_validation，而不是运行目标代码。该设计牺牲了缺少隔离环境时的执行验证能力，以避免把不受控目标进程直接暴露给代理运行环境；具体的合规评估、数据保留规则和隐私政策，官方仓库未提供该信息，建议以最新 README 为准。

严重性需要建立在影响证据上，而不是仅凭与检查清单不一致来定级。README 还明确区分防御纵深缺口与漏洞：如果已有的 A 层控制能够阻止攻击，缺少 B 层控制应记为加固建议，而不能直接确认为漏洞。

许可证与商用条款

仓库附带的 LICENSE 声明该项目采用 MIT 许可证，版权标记为 Copyright (c) 2025-2026 Cloudflare, Inc. 该许可证允许任何人不受限制地使用、复制、修改、合并、发布、分发、再许可及出售软件副本，因此允许商用。

分发软件或其重要部分时，必须在副本或重要部分中保留版权声明和许可证许可声明。软件按“原样”提供，不附带明示或默示担保；其他责任限制以仓库 LICENSE 原文为准，不能将上述授权解释为 Cloudflare 对审计结果、适用性或商业使用效果的保证。

局限性与已知限制

技能的审计结论依赖编码代理执行质量、覆盖台账准确性、代理工具能力以及验证阶段是否真正独立。README 强调反证和独立复核，但没有承诺发现全部漏洞，也没有提供可据以估算审计完备性的量化指标。

不具备操作系统级沙箱时，目标代码执行验证被明确阻止，相关线索会留在待验证状态。对依赖动态执行证据的候选问题而言，这意味着输出中可能存在有源码依据但尚不能确认的记录。

项目资料未提供受支持代理列表、模型列表、Node.js 最低版本、安装 CLI 版本范围、资源配额、运行时长、并发限制或完整配置参考。使用者应从仓库当前 README 和 CLI 帮助核实这些随工具环境变化的信息，不要将 GitHub Star、Fork 数或单次测试观察误当成可靠性、安全效果或服务级别指标。

适合谁 / 不适合谁

是否采用，取决于团队能否提供兼容代理、明确的授权范围和满足要求的隔离环境。以下判断信号来自项目的已述流程和运行约束；属于适用性判断的部分，按根据本文作者的经验判断标注。

适合的情况

• （根据本文作者的经验判断）团队需要对单一代码库开展分阶段审计，并希望保留覆盖记录、结构化发现和报告工件。
• 组织已有支持工具调用与并行子代理的编码代理，且能安排独立代理验证候选发现。
• 具备能够禁网、清理环境、限制资源并约束可写路径的操作系统级沙箱。
• （根据本文作者的经验判断）审计工作需要多轮累积，团队愿意维护台账并依据源码变更重新验证旧证据。
• 用户能够接受将未充分验证的线索标记为待验证，而不是要求系统强行给出严重性结论。

不适合的情况

• 没有可用的工具调用型编码代理，或代理不支持并行子代理。
• 无法提供禁网、资源限制、环境清理和路径约束等沙箱控制，却仍计划执行目标构建或测试。
• 需要对生产目标进行未授权探测，或试图把技能用于突破目标访问控制；此类用途不符合本文列明的授权边界。
• （根据本文作者的经验判断）项目要求固定模型版本、确定性审计覆盖、审计耗时保证或量化检出率，但团队无法接受仓库未提供这些承诺。
• 只需要快速回答单个安全问题且不需要报告工件；README 对此提供的是指导模式，完整多阶段审计未必符合该任务的工作量预期。

常见问题与排查（FAQ / Troubleshooting）

排查时先确认请求触发的是完整审计还是指导模式，再检查代理能力、输出位置和安全隔离是否符合要求。对仓库未记载的错误码、日志格式或接口行为，不应凭经验补造答案。

为什么只得到建议，没有审计报告？

安全问题咨询和聚焦的漏洞工作默认使用指导模式；直接审计代码库或渗透测试请求才使用完整审计模式。若需要报告工件，应明确要求完整代码库审计或报告输出，并检查请求是否指向正确的代码库。

为什么候选问题没有被确认为漏洞？

确认结论要求完整源码追踪和有边界的已观察结果。若尚有精确的未解决事实，或执行验证因缺少沙箱而无法开展，应保留为 needs_validation；如果候选已被反证，则记录为 rejected。

为什么代理没有运行测试或构建？

README 要求目标控制的构建、测试和进程在满足条件的操作系统沙箱中执行。若环境不能禁用外部网络、清理环境变量、限制资源并约束写入目录，工作流应避免执行目标代码，并将线索留在待验证状态。

如何处理多次审计留下的历史结果？

使用先前的覆盖台账和发现记录定位缺口，并针对改变过的源码重新验证。旧证据只有在仍与当前源码相符时才有参考价值；未解决工作和过期记录不能被算作当前覆盖。

验证器失败时先检查什么？

先确认校验目标是对应的 coverage-ledger.json 或 findings.json，再核对文件是否由当前工作流按预期格式生成，并根据技能说明修正数据。具体错误文本、退出码和手动运行命令：官方仓库未提供该信息，建议以最新 README 为准。

安装参数或代理选择方式不明确怎么办？

README 给出的查询命令是 npx skills --help，可用于查看 CLI 的代理选择和非交互选项。CLI 版本范围及各参数在不同版本中的差异，官方仓库未提供该信息，建议以最新 README 为准。

项目地址与资源

可从仓库 README 核对安装方式、工作流文件清单和安全前提；许可证正文以仓库内的 LICENSE 文件为准。下列资源均来自项目资料中出现的仓库或官方页面。

• Cloudflare security-audit-skill GitHub 仓库
• Skills CLI 官方站点
• Build your own vulnerability harness