防御性代码参考框架

基于自 Claude Mythos 预览版发布以来与多家机构安全团队合作的经验，我们构建了这套用于自主漏洞发现与修复的参考实现。关于这些经验总结及最佳实践，请参阅随附的博客文章（同样收录于 blog-post.md 文件）。如需轻量级 SDK 操作指南，了解相同的“侦察→发现→分类→报告→修复”流程，请参见配套的实践手册。

本仓库不再维护，且不接受外部贡献。

🔒 需要托管方案？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/：自主参考流程（侦察→发现→验证→报告→修复），配置为使用 Docker 和 ASAN 查找 C/C++ 内存漏洞。该框架为参考实现，非正式产品。其整体架构、提示词和沙箱机制可复用，但该框架无法直接适用于所有代码库。运行 /customize 可将其移植至您的语言、检测器或漏洞类型。

⚠️ 安全说明：/quickstart、/threat-model、/vuln-scan 和 /triage 仅执行文件读写操作。对静态发现结果（TRIAGE.json 或 VULN-FINDINGS.json）运行 /patch 同样仅涉及读写操作。/customize 会编辑 harness 代码并运行验证命令。只要你在 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-sec intro + guided first run on the canary target
> /quickstart

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

延伸阅读

• 博客文章 · 附有经验总结与最佳实践的配套博客文章
• 流水线 · 工作原理：示意图、阶段、CLI 参数
• 安全 · 沙箱机制、不应挂载的内容
• 智能体沙箱 · 每个智能体的 gVisor 隔离机制与出站白名单
• 自定义 · 移植到我的技术栈；哪些文件会变更及原因
• 补丁 · 针对已验证的崩溃生成并验证修复方案
• 故障排查 · 重复项、速率限制、子智能体模型固定
• 安全防护 · 阻止危险网络攻击行为

---

逐步推进

与我们合作过的最成功的安全团队，都是那些最快上手实践的团队。虽然花数月时间设计完美流水线很诱人，但我们建议从第一天起从小处着手，随着经验积累逐步构建。以下步骤遵循这一模式，并根据我们的观察设定了一个雄心勃勃（但合理）的推进节奏。

第一步	第一天	构建威胁模型，并运行首次静态扫描与分类
第二步	第二天	在 C/C++ 库上运行参考流水线
第三步	第 3-5 天	针对你的目标自定义流水线
第四步	第二周	启动自主扫描、分类与补丁修复

第一步（第一天）：构建威胁模型，并运行首次静态扫描与分类

第一天的重点是完整走通整个流程。仅使用交互式技能，你将构建威胁模型、运行基于该模型范围的静态扫描、对返回结果进行分类，并草拟候选修复方案。当天结束时，你将获得一个威胁模型、一份按优先级排序的静态发现结果列表，以及候选补丁。

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

# Pin every subagent to the model you want
export CLAUDE_CODE_SUBAGENT_MODEL=<model-id>
claude

# 0. intro + guided first run
> /quickstart

# 1. Build a threat model (aim before you shoot)
> /threat-model bootstrap targets/canary

# 2. Run a static scan, scoped by that threat model
> /vuln-scan targets/canary

# 3. Verify, dedupe, and rank what came back
> /triage targets/canary/VULN-FINDINGS.json

# 4. Generate candidate fixes for the verified findings
> /patch ./TRIAGE.json --repo targets/canary

此流程会生成 THREAT_MODEL.md、VULN-FINDINGS.{json,md}、TRIAGE.{json,md} 以及 PATCHES/ 目录。

步骤 1 中产生的漏洞候选来自 Claude 对源代码的静态审查（不进行任何构建或运行），因此在非测试目标上预期会有更多误报。在步骤 2 中，你将生成经过执行验证的发现结果。

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

步骤 2（第 2 天）：在 C/C++ 库上运行参考流水线

在第 2 天，你将交互式技能升级为首次自主运行，使用参考流水线。你将在自己的环境中，针对一个已知存在漏洞的开源库，运行完整的侦察→发现→验证→报告循环，然后为其发现的问题生成候选补丁。最终你将获得一组可复现的崩溃、可利用性报告和候选补丁，同时了解该流水线的工作方式。

运行流水线很简单：

# One-time setup
python3 -m venv .venv && .venv/bin/pip install -e .
./scripts/setup_sandbox.sh   # installs gVisor, builds the agent images, and verifies isolation; note: requires Docker
export ANTHROPIC_API_KEY=sk-ant-...   # or CLAUDE_CODE_OAUTH_TOKEN; the pipeline requires one in env

# Run the recon → find → verify → report loop
bin/vp-sandboxed run drlibs --model <model-id> --runs 3 --parallel --stream --auto-focus
# Generate a candidate patch for each finding
bin/vp-sandboxed patch results/drlibs/<timestamp>/ --model <model-id>

# Or, ask Claude Code to launch the pipeline and watch the run for you
claude
> run the pipeline on drlibs and explain findings as they come

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

⚠️ run 命令会生成自主智能体。流水线会在 gVisor 容器内运行每个智能体，并将出站流量限制为仅能访问 Claude API。除非显式覆盖，否则生成智能体的子命令拒绝在容器外启动。更多信息请参阅 docs/security.md 和 docs/agent-sandbox.md。

在底层，该流水线会经历七个阶段：

1. 构建：将目标编译为包含 ASAN（C 和 C++ 的内存错误检测器）的 Docker 镜像。流水线在首次运行时，会使用目标的 Dockerfile 自动构建此镜像。
2. Recon（侦察）：一个轻量级智能体读取网络隔离容器内的源代码，并提出分区方案，例如“这里有 N 个不同的输入解析子系统，值得分别攻击”，这样并行的 Find（查找）智能体就能探索不同区域，而不会集中到同一个漏洞上。如果没有 `--auto-focus` 标志，流程会使用目标 `config.yaml` 中的 `focus_areas` 列表。
3. Find（查找）：N 个智能体并行运行，每个都在自己独立的隔离容器中。每个智能体读取源代码，构造畸形输入，并运行 ASAN 二进制文件，直到某个输入连续三次导致崩溃。
4. Verify（验证）：一个独立的评分智能体在一个全新的、Find 智能体从未接触过的容器中复现每次崩溃。从 Find 智能体传递到评分智能体的唯一内容就是它生成的漏洞验证概念（PoC）。
5. Dedupe（去重）：一个裁决智能体将已验证的崩溃与已报告的漏洞进行比较，判断每个崩溃是新漏洞、已知漏洞的更优示例，还是需要跳过的重复项。
6. Report（报告）：一个报告智能体针对每个独特漏洞编写结构化的可利用性分析，包括原语类型、可达性、利用升级路径和严重性等细节。
7. Patch（补丁，即上述独立的 patch 命令）：一个补丁智能体编写建议的修复方案，然后一个评分智能体确认新代码能编译通过、原始漏洞验证输入不再导致崩溃、目标的测试套件仍然通过，并且一个新的 Find 智能体无法绕过该修复。

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

第 3 步（第 3-5 天）：为你的目标定制流程

在第 3-5 天，你将为自己的目标定制测试框架。首先，将第 1 步的技能指向你的代码，然后使用 `/customize` 将流程移植到你的技术栈。到本周末，你将拥有一个 `targets/<your-service>/` 目录，流程可以针对该目录运行，并通过一次简单的冒烟测试验证，为第 4 步的规模化扩展做好准备。

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

问题	C/C++ 参考	你的目标（示例）
什么信号表明发现了一个结果？	ASAN 崩溃特征	异常 / 金丝雀文件 / DNS 回调
概念验证是什么样的？	导致崩溃的输入文件	HTTP 请求序列 / 事务列表 / 测试框架
目标程序是如何构建和运行的？	Dockerfile（使用 clang + ASAN）	在容器中构建你的语言环境

在自定义之前，先将步骤 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 中自定义的管道，为内部管道循环添加一个外层循环——运行多次管道扫描，对多次运行的结果进行分类，根据优先级进行修复，然后重复此过程。

# Scan - run a wave of parallel runs against your target
bin/vp-sandboxed run my-service --model <model-id> --runs 5 --parallel --stream --auto-focus

# Triage - dedupe and rank every finding across all waves using your threat model
> /triage results/my-service/ --repo ~/code/my-service --auto --votes 5

# Patch - generate and validate fixes, starting with what triage ranked the highest
> /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. 搭建专用的扫描基础设施，将扫描任务从笔记本电脑或一次性虚拟机上迁移出来。最成功的团队会克制住先构建完美扫描平台再扩大规模的冲动。
3. 将扫描纳入软件开发生命周期。部分团队已设置定期扫描（例如每日或每周），或已将扫描集成到 CI 流水线中。
4. 测试并实验各类模型，以找到最适合自身需求的方案。

关于

涵盖威胁建模、扫描、分类、补丁的技能，以及一个可自定义的自主扫描工具链

claude.com/blog/using-llms-to-secure-source-code

贡献者

编程语言

• Python 93.0%
• Shell 3.4%
• C 2.4%
• Dockerfile 1.2%