防御代码参考框架

一个基于我们与多个组织的安全团队合作的经验，使用 Claude 进行自主漏洞发现与修复的参考实现。关于这些经验及最佳实践的详细说明，请参阅随附博客文章（也可在 blog-post.md 中找到）。如需仅使用 SDK 的轻量级相同 recon → find → triage → report → patch 循环指南，请参阅配套食谱。

本仓库不被维护且不接受贡献。

🔒 需要托管方案？ Anthropic 提供 Claude Security，一个托管产品， 可在多个项目中查找并修复源代码中的漏洞。Claude Security 扫描您的仓库以发现漏洞， 应用多阶段验证流程以减少误报，并允许您管理发现的整个生命周期：分类、修复验证 和快速修复生成。

本仓库是一个基于使用 Claude 查找漏洞的通用最佳实践的开源参考实现。您可以使用它 构建自己的漏洞发现管道，自定义逻辑，并且可以与您拥有的任何 Claude API 访问方式 一起使用（包括 Bedrock、Vertex 或 Azure）。

目录

• Claude Code 技能：/quickstart、/threat-model、/vuln-scan、 /triage、/patch、/customize：交互式范围界定、扫描、分类 和修补。在 Claude Code 中打开此仓库并运行 /quickstart 以熟悉环境。
• harness/：自主参考管道（recon → find → verify → report → patch）， 配置为使用 Docker 和 ASAN 查找 C/C++ 内存漏洞。此框架是参考，而非产品。 通用结构、提示和沙箱可重复使用，但该框架并非开箱即用于所有代码库。运行 /customize 以将其移植到您的语言、检测器或漏洞类别。

⚠️ 安全性： /quickstart、/threat-model、/vuln-scan 和 /triage 仅读取和写入文件。对静态发现结果（TRIAGE.json 或 VULN-FINDINGS.json）运行 /patch 同样是只读和只写操作。/customize 编辑 框架代码并运行验证命令。只要您在 Claude Code 中审查并批准每次工具使用，这些技能 都可以在无沙箱环境下安全运行。 自主参考管道（包括对管道结果运行 /patch）会执行目标代码，因此除非显式覆盖， 否则它会拒绝在 gVisor 沙箱之外运行。要进行设置，请运行一次 scripts/setup_sandbox.sh， 然后通过 bin/vp-sandboxed 调用管道。更多详情请参阅 docs/security.md 和 docs/agent-sandbox.md。

快速开始

git clone https://github.com/anthropics/defending-code-reference-harness
cd defending-code-reference-harness
claude

# 30秒入门 + 在 canary 目标上引导首次运行
> /quickstart

> /quickstart how do I port the pipeline to Java?
> /quickstart how do I triage all these bugs?

进一步阅读

• 博客文章 · 随附博客文章，包含经验 + 最佳实践
• 管道 · 工作原理：图表、阶段、CLI 标志
• 安全性 · 沙箱化，不应挂载的内容
• 代理沙箱 · gVisor 隔离 + 每个代理的出站允许列表
• 自定义 · 移植到您的技术栈；哪些文件需要更改及原因
• 修补 · 生成并验证已验证崩溃的修复
• 故障排除 · 重复、速率限制、子代理模型固定
• 安全防护 · 阻止危险网络工作

逐步提升

与我们合作的最成功的安全团队是那些最快速动手实践的团队。尽管很容易花费数月设计完美管道，但我们建议从第一天开始小规模尝试，并在学习过程中逐步构建。以下步骤遵循这一模式，并根据我们所见设定了一个雄心勃勃（但合理）的节奏。

步骤 1（第 1 天）：构建威胁模型并运行首次静态扫描 + 分类

第 1 天的重点是端到端查看整个循环。仅使用交互式技能，您将构建威胁模型、运行按此模型限定的静态扫描、对返回结果进行分类，并草拟候选修复。您将在当天结束时获得威胁模型、静态发现排名列表和候选补丁。

相关技能仅读取和写入您仓库中的文件。只要您以交互方式运行 Claude Code 并批准每次工具使用，则无需沙箱。

# 将每个子代理固定到您想要的模型
export CLAUDE_CODE_SUBAGENT_MODEL=<model-id>
claude

# 0. 介绍 + 引导首次运行
> /quickstart

# 1. 构建威胁模型（先瞄准再射击）
> /threat-model bootstrap targets/canary

# 2. 运行静态扫描，按该威胁模型限定范围
> /vuln-scan targets/canary

# 3. 验证、去重并对返回结果进行排序
> /triage targets/canary/VULN-FINDINGS.json

# 4. 为已验证的发现生成候选修复方案
> /patch ./TRIAGE.json --repo targets/canary

此流程产生 THREAT_MODEL.md、VULN-FINDINGS.{json,md}、TRIAGE.{json,md} 和 PATCHES/。

步骤 1 中产生的漏洞候选来自 Claude 对源代码的静态审查（未构建或运行任何内容），因此在对非 canary 目标时预期会有更多误报。在步骤 2 中，您将产生经执行验证的发现。

注意： 在 canary 目标上，/triage 可能会将扫描结果视为误报而丢弃。entry.c 声明自己是故意存在漏洞的演示代码，/triage 正确排除了测试/固定代码中的错误。要查看完整的确认/去重/误报流程，请在精心策划的固定数据上运行它（/triage .claude/skills/triage/fixtures/canary-findings.json --repo targets/canary）或将步骤 1 技能指向您自己的代码。

步骤 2（第 2 天）：在 C/C++ 库上运行参考管道

在第 2 天，您将从交互式技能转向使用参考管道进行首次自主运行。您将在您的环境中对已知存在漏洞的开源库运行完整的 recon → find → verify → report 循环，然后为其发现的漏洞生成候选补丁。您将获得一组可重现的崩溃、可利用性报告和候选补丁，同时了解管道的工作原理。

运行管道很简单：

# 一次性设置
python3 -m venv .venv && .venv/bin/pip install -e .
./scripts/setup_sandbox.sh   # 安装 gVisor、构建代理镜像并验证隔离；注意：需要 Docker
export ANTHROPIC_API_KEY=sk-ant-...   # 或 CLAUDE_CODE_OAUTH_TOKEN，或 Bedrock — 参见 docs/agent-sandbox.md

# 运行 recon → find → verify → report 循环
bin/vp-sandboxed run drlibs --model <model-id> --runs 3 --parallel --stream --auto-focus
# 为每个发现生成候选补丁
bin/vp-sandboxed patch results/drlibs/<timestamp>/ --model <model-id>

# 或者，让 Claude Code 启动管道并为您监控运行
claude
> run the pipeline on drlibs and explain findings as they come

循环结果将保存在 results/drlibs/<timestamp>/ 目录中。使用 --stream 标志，第一份报告将在几分钟内出现在 reports/bug_NN/ 下。

⚠️ run 会生成自主代理。 管道在 gVisor 容器内运行每个代理，出站流量仅限于 Claude API。除非显式覆盖，否则生成代理的子命令拒绝在容器外启动。更多信息请参阅 docs/security.md 和 docs/agent-sandbox.md。

在底层，管道经历七个阶段：

1. 构建：将目标编译为带有 ASAN（C 和 C++ 的内存错误检测器）的 Docker 镜像。管道在首次运行时使用目标的 Dockerfile 自动构建此镜像。
2. 侦察：一个轻量级代理在网络隔离的容器中读取源代码，并提出分区方案，即*“这里有 N 个不同的输入解析子系统，值得分别攻击”*，以便并行查找代理探索不同区域，而不是聚集在同一个漏洞上。如果没有 --auto-focus 标志，管道将使用目标 config.yaml 中的 focus_areas 列表。
3. 查找：N 个代理并行运行，每个代理位于自己隔离的容器中。每个代理读取源代码，构造格式错误的输入，并运行 ASAN 二进制文件，直到某个输入连续 3 次产生崩溃。
4. 验证：一个独立的评分代理在查找代理未接触过的新容器中重现每个崩溃。从查找代理传递到评分代理的唯一内容是它产生的概念验证。
5. 去重：一个判断代理将验证后的崩溃与已报告的漏洞进行比较，并决定每个漏洞是新漏洞、已知漏洞的更好示例，还是应跳过的重复项。
6. 报告：一个报告代理为每个唯一漏洞编写结构化可利用性分析，包括原始类型、可达性、升级路径和严重性等详细信息。
7. 修补（上述单独的 patch 命令）：一个修补代理编写建议的修复方案，一个评分代理确认新代码可以构建，原始的概念验证输入不再导致崩溃，目标的测试套件仍然通过，并且一个新的查找代理无法绕过修复。

更多详情请参见 docs/pipeline.md。

步骤 3（第 3-5 天）：为您的目标自定义管道

在第 3-5 天，您将为自己的目标自定义框架。首先，将步骤 1 的技能指向您的代码，然后使用 /customize 将管道移植到您的技术栈。到本周末，您将拥有一个管道可以运行的 targets/<your-service>/ 目录，通过一次管道烟雾测试验证，并准备好在步骤 4 中扩展。

虽然参考管道设计用于查找 C 和 C++ 代码中的内存漏洞，但其结构是通用的。将其移植到新的漏洞类别或语言只需为您的目标技术栈回答以下问题：

在自定义之前，先将步骤 1 的技能指向您自己的代码。提醒一下，它们是只读和只写操作，因此可以无沙箱运行。

claude

> /quickstart how do I customize this for ~/code/my-service?

> /threat-model bootstrap-then-interview ~/code/my-service
> /vuln-scan ~/code/my-service
> /triage ~/code/my-service/VULN-FINDINGS.json --repo ~/code/my-service

然后，在 /customize 技能中使用这些技能产生的工作成果，该技能会修改框架以适应您的代码库。

> /customize use ~/code/my-service/{THREAT_MODEL.md,VULN-FINDINGS.json} and ./TRIAGE.md

当 /customize 完成后，您将拥有一个设置好的 targets/my-service/ 目录。在扩展之前，通过一次管道烟雾测试进行验证。

bin/vp-sandboxed run my-service --model <model-id> --runs 1

更多详情请参见 docs/customizing.md。

步骤 4（第 2 周）：开始自主扫描、分类和修补

在第 2 周，您将在自己的目标上使用步骤 3 中自定义的管道，为内部管道循环添加一个外部循环——运行多次管道扫描、对来自这些运行的发现进行跨次分类、基于优先级进行修补，然后重复。

# 扫描 - 对您的目标运行一波并行运行
bin/vp-sandboxed run my-service --model <model-id> --runs 5 --parallel --stream --auto-focus

# 分类 - 使用您的威胁模型对所有波次中的每个发现进行去重和排序
> /triage results/my-service/ --repo ~/code/my-service --auto --votes 5

# 修补 - 生成并验证修复，从分类排名最高的开始
> /patch results/my-service/<timestamp>/ --model <model-id>

⚠️ 遵循与 步骤 2 中相同的沙箱指南。

给定的管道运行已经验证并对其自身发现进行了去重。/triage 跨多次管道运行工作。当指向 results/ 目录时，它会折叠所有运行中的重复项（以及来自 /vuln-scan 的任何静态发现，如果有），根据您的威胁模型重新校准严重性评级，并尝试将每个发现路由到组件所有者。

如果可能，快速修补发现有助于保持外部循环尽可能高效。当发现被修复后，模型无法重新发现它们，而是会浮现出全新的、通常更深层的问题。当您运行更多管道波次时，发现数量可能会减少，但复杂性也可能会增加。如果快速修补不可行，即使只是将先前的发现记录在目标的 known_bugs 中，也能帮助引导未来的运行转向更新颖的错误。

自主分类和修补仍然是开放性议题，本参考框架并未完全解决它们。/patch 中的验证策略有助于提高标准，但严重性和优先级最终是关于您环境的判断，且经过验证的补丁不一定能向上游提交。许多合作伙伴报告这些步骤是当前的瓶颈，您应该为此分配实际的工程时间。

更多详情请参见 docs/triage.md 和 docs/patching.md。

展望未来

在初始提升阶段之后，与我们合作的团队往往会在以下几个方向上投入精力：

1. 审查所有内部仓库和关键开源依赖项，根据重要性（例如，基于其暴露程度、CVE 历史、业务关键性）对要扫描的仓库进行排序，然后按优先顺序逐一扫描。
2. 建立专门的扫描基础设施，将扫描从笔记本电脑或一次性 VM 上移走。最成功的团队会抵制在扩展之前构建完美扫描平台的冲动。
3. 将扫描纳入其 SDLC。一些团队设置了定期扫描（例如每天、每周），或已将扫描添加到他们的 CI 管道中。
4. 测试和试验模型，以找到最适合他们的方法。