Cloudflare / security-audit-skill

security-audit is a coding-agent skill that turns your agent into a security auditor. It orchestrates isolated agents through reconnaissance, coverage-led hunting, candidate validation, structured output, independent record verification, and target-neutral reporting. This is the skill that seeded Cloudflare’s vulnerability discovery harness, described in Build your own vulnerability harness. The harness grew into a multi-stage, fleet-wide system; this skill is the single-repo starting point it evolved from.

security-audit 是一项编码代理技能，可将您的代理转变为安全审计员。它通过侦察、覆盖率引导的挖掘、候选验证、结构化输出、独立记录验证和目标中立报告来编排隔离的代理。这项技能是 Cloudflare 漏洞发现工具（详见《构建您自己的漏洞工具》）的雏形。该工具后来发展成为一个多阶段、全舰队范围的系统；而此技能正是它最初演化而来的单仓库起点。

What it does / 功能概述

The skill runs a structured audit in six phases: 该技能分六个阶段进行结构化审计：

• Reconnaissance: Map architecture, trust boundaries, input surfaces, prior evidence, and deterministic coverage in architecture.md and coverage-ledger.json. 侦察：在 architecture.md 和 coverage-ledger.json 中映射架构、信任边界、输入表面、既往证据和确定性覆盖范围。
• Coverage-led hunting: Assign isolated hunters from ledger units, record their checks, and use coverage critics to find gaps. 覆盖率引导的挖掘：从账本单元分配独立的挖掘者，记录他们的检查，并使用覆盖率评估器来发现漏洞。
• Candidate validation: Give every unique candidate to a fresh verifier that tries to disprove it. 候选验证：将每个唯一的候选漏洞交给一个新的验证者，由其尝试推翻该结论。
• Structured output: Write confirmed, needs_validation, and rejected records to findings.json and validate them against report-schema.json. 结构化输出：将 confirmed（已确认）、needs_validation（需验证）和 rejected（已拒绝）记录写入 findings.json，并根据 report-schema.json 进行验证。
• Independent record verification: Fresh agents verify final source claims. Material replacements receive another independent verifier. 独立记录验证：由新的代理验证最终的来源声明。实质性的替换内容会接受另一名独立验证者的检查。
• Target-neutral reporting: Derive REPORT.md, FINDINGS-DETAIL.md, and NEEDS-VALIDATION.md from the verified records and coverage ledger. 目标中立报告：根据已验证的记录和覆盖率账本生成 REPORT.md、FINDINGS-DETAIL.md 和 NEEDS-VALIDATION.md。

The parent runs validate-coverage-ledger.cjs after creating the ledger and after each later ledger update. It runs validate-findings.cjs in Phase 4 and again after every Phase 5 replacement. The verdicts are distinct: confirmed has a complete source trace and bounded observed result, needs_validation has an exact unresolved fact and no severity, and rejected records a disproved candidate. 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.

父进程在创建账本后以及后续每次更新账本后都会运行 validate-coverage-ledger.cjs。它在第 4 阶段运行 validate-findings.cjs，并在第 5 阶段的每次替换后再次运行。结论分为明确的几类：confirmed 具有完整的来源追踪和有限的观察结果；needs_validation 具有确切的未解决事实且无严重性评级；rejected 则记录了被推翻的候选漏洞。针对同一仓库的多次运行是累加的。该技能利用先前的账本和发现结果来定位差距、重新验证已更改的源代码，并延续当前源代码的证据，而不会将陈旧或未解决的工作视为已覆盖。

Files / 文件说明

File	Purpose
SKILL.md	Setup, core principles, platform terminology, workflow overview, and audit anti-patterns
RECONNAISSANCE.md	Phase 1 reconnaissance prompts and synthesis instructions
HUNTING.md	Phase 2 orchestration, hunting methodology, and validation rules
ATTACK-CLASSES.md	Core, wildcard, and obvious-things attack prompts
MEMORY-SAFETY-AND-BINARY.md	Memory-safety, binary, and kernel hunting classes for native targets
AI-AND-LLM.md	Prompt-injection, agent/tool, and output-handling hunting classes for LLM-backed targets
WEB-PROTOCOL-AND-AUTH.md	HTTP request-framing, cache, and authentication-protocol hunting classes
CLIENT-SIDE.md	DOM-injection, messaging-trust, UI-redress, and prototype-pollution hunting classes
SUPPLY-CHAIN-AND-RELEASE.md	Dependency, CI, release, signing, update, plugin, and extension hunting classes
CLOUD-AND-DEPLOYMENT.md	IAM, infrastructure-as-code, container, serverless, ingress, and runtime-configuration hunting classes
PROTOCOLS-RPC-AND-MESSAGING.md	RPC, serialization, queue, broker, webhook, and streaming-protocol hunting classes
RESOURCE-EXHAUSTION-AND-AVAILABILITY.md	Shared resource, quota, queue, worker, and operator-spend hunting classes
DATA-ISOLATION-AND-LIFECYCLE.md	Tenant isolation, cache, search, export, backup, migration, deletion, and restore hunting classes
DESKTOP-MOBILE-AND-LOCAL-IPC.md	Native app, deep-link, webview, exported-component, helper, daemon, and local-IPC hunting classes
VALIDATION-AND-REPORTING.md	Phases 3–6 candidate validation, structured output, record verification, and reporting
report-schema.json	JSON schema for all three findings.json verdicts
validate-findings.cjs	Zero-dependency validator for findings.json in Phases 4 and 5
validate-coverage-ledger.cjs	Zero-dependency validator for coverage-ledger.json in Phases 1–5

文件名	用途
SKILL.md	设置、核心原则、平台术语、工作流概述及审计反模式
RECONNAISSANCE.md	第一阶段侦察提示词及综合说明
HUNTING.md	第二阶段编排、挖掘方法论及验证规则
ATTACK-CLASSES.md	核心、通配符及显而易见漏洞的攻击提示词
MEMORY-SAFETY-AND-BINARY.md	针对原生目标的内存安全、二进制及内核挖掘类
AI-AND-LLM.md	针对 LLM 后端目标的提示词注入、代理/工具及输出处理挖掘类
WEB-PROTOCOL-AND-AUTH.md	HTTP 请求帧、缓存及认证协议挖掘类
CLIENT-SIDE.md	DOM 注入、消息信任、UI 伪装及原型污染挖掘类
SUPPLY-CHAIN-AND-RELEASE.md	依赖、CI、发布、签名、更新、插件及扩展挖掘类
CLOUD-AND-DEPLOYMENT.md	IAM、基础设施即代码、容器、无服务器、入口及运行时配置挖掘类
PROTOCOLS-RPC-AND-MESSAGING.md	RPC、序列化、队列、代理、Webhook 及流协议挖掘类
RESOURCE-EXHAUSTION-AND-AVAILABILITY.md	共享资源、配额、队列、工作进程及运营成本挖掘类
DATA-ISOLATION-AND-LIFECYCLE.md	租户隔离、缓存、搜索、导出、备份、迁移、删除及恢复挖掘类
DESKTOP-MOBILE-AND-LOCAL-IPC.md	原生应用、深度链接、WebView、导出组件、助手、守护进程及本地 IPC 挖掘类
VALIDATION-AND-REPORTING.md	第 3-6 阶段候选验证、结构化输出、记录验证及报告
report-schema.json	findings.json 中三种结论的 JSON 模式
validate-findings.cjs	第 4 和 5 阶段 findings.json 的零依赖验证器
validate-coverage-ledger.cjs	第 1-5 阶段 coverage-ledger.json 的零依赖验证器

Installation / 安装

Install the skill with the Skills CLI: 使用 Skills CLI 安装该技能：

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

Use --global for a user-level installation: 使用 --global 进行用户级安装：

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

Run npx skills --help for agent-selection and non-interactive options. 运行 npx skills --help 查看代理选择和非交互式选项。

Usage / 使用方法

Start your coding agent in (or pointed at) the codebase you want to audit, then ask it to do a security audit: 在您想要审计的代码库中（或指向该代码库）启动您的编码代理，然后要求它进行安全审计：

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

The skill activates automatically when the request matches its trigger (security audit, find vulnerabilities, pen-test the code, etc.). A direct codebase audit or pen-test request uses full audit mode. Security questions and focused vulnerability work use guidance mode unless you request report artifacts. In full audit mode, an unspecified output directory defaults to ~/security-audit-skill/<repo-name>/run-<N>. The workflow writes inside the target repository only when you explicitly select a directory that version control ignores.

当请求匹配其触发条件（安全审计、查找漏洞、代码渗透测试等）时，该技能会自动激活。直接的代码库审计或渗透测试请求将使用“全量审计模式”。安全问题咨询和针对性的漏洞工作将使用“指导模式”，除非您明确要求输出报告工件。在全量审计模式下，如果未指定输出目录，默认路径为 ~/security-audit-skill/<repo-name>/run-<N>。只有当您明确选择了一个版本控制忽略的目录时，工作流才会写入目标仓库内部。

Requirements / 要求

• A coding agent with a model that supports tool use and parallel sub-agents. 支持工具使用和并行子代理模型的编码代理。
• Node.js for the zero-dependency findings and coverage-ledger validators. 用于零依赖发现结果和覆盖率账本验证器的 Node.js 环境。
• An OS-enforced sandbox for target-controlled builds, tests, processes, browsers, emulators, fuzzers, and fixtures. It must disable external networking, use a sanitized allowlisted environment, enforce resource limits, and allow writes only to assigned scratch paths. Without these controls, the workflow keeps the lead as needs_validation instead of executing target code. 用于目标控制的构建、测试、进程、浏览器、模拟器、模糊测试器和固件的操作系统级沙箱。它必须禁用外部网络，使用经过清理的白名单环境，强制执行资源限制，并仅允许写入指定的临时路径。如果没有这些控制措施，工作流会将线索保留为 needs_validation，而不是执行目标代码。

Design principles / 设计原则

• Only confirm established boundary failures. 仅确认已确立的边界故障。
• Keep a source-grounded blocked lead as needs_validation with its exact unresolved fact. 将有来源依据但受阻的线索保留为 needs_validation，并附带其确切的未解决事实。
• Adversarial validation. The agent that checks a finding is never the agent that found it. 对抗性验证。检查漏洞的代理绝不是发现该漏洞的代理。
• Severity requires impact. Likelihood x impact, not deviation. 严重性取决于影响。严重性 = 可能性 x 影响，而非仅仅是偏差。