anthropics/defending-code-reference-harness 来源：https://github.com/anthropics/defending-code-reference-harness

Defending Code Reference Harness

一个基于 Claude 的自主漏洞发现与修复参考实现，源于我们自 Claude Mythos Preview 发布以来与多家组织安全团队合作的经验（https://www.anthropic.com/glasswing）。

相关经验总结与最佳实践，请参阅配套博客文章（https://claude.com/blog/using-llms-to-secure-source-code）（也可在 blog-post.md 中查阅）。

如需仅使用 SDK 的轻量级演示，涵盖同样的“侦察 → 发现 → 分类 → 报告 → 修补“完整流程，请参阅配套 cookbook（https://platform.claude.com/cookbook/claude-agent-sdk-06-the-vulnerability-detection-agent）。

本仓库不进行维护，也不接受贡献。

🔒 需要托管方案？ Anthropic 提供 Claude Security（https://claude.com/product/claude-security），这是一款托管产品， 可跨多个项目发现并修复源代码中的漏洞。Claude Security 扫描您的仓库以查找漏洞， 应用多阶段验证流水线以减少误报，并允许您全生命周期管理发现结果：包括分类、 修复验证和快速生成修复方案。

本仓库是基于通用漏洞发现最佳实践的开源参考实现。您可以用它构建自己的漏洞发现 流水线，自定义逻辑，并可与您拥有访问权限的任何 Claude API 配合使用（包括 Bedrock、Vertex 或 Azure）。

内容

• Claude Code 技能：/quickstart、/threat-model、/vuln-scan、/triage、/patch、/customize：交互式范围界定、扫描、分类和修补。在 Claude Code 中打开本仓库并运行 /quickstart 以快速上手。
• harness/：自主参考流水线（侦察 → 发现 → 验证 → 报告 → 修补），配置为使用 Docker 和 ASAN 发现 C/C++ 内存漏洞。本 harness 是参考实现，而非产品。其整体结构、提示词和沙箱机制均可复用，但并非对所有代码库开箱即用。运行 /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 秒介绍 + 在 canary 目标上的引导式首次运行
> /quickstart
> /quickstart 我如何将流水线移植到 Java？
> /quickstart 如何对这些 bug 进行分类？

延伸阅读

• 博客文章 · 配套博客文章，包含经验总结与最佳实践
• 流水线 · 工作原理：流程图、阶段、CLI 参数
• 安全性 · 沙箱机制、挂载注意事项
• Agent 沙箱 · 每个 agent 的 gVisor 隔离 + 出口白名单
• 自定义 · 适配到我的技术栈；哪些文件需要修改以及原因
• 修补 · 为已验证的崩溃生成并验证修复方案
• 故障排除 · 重复项、速率限制、子 agent 模型固定
• 安全防护（https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude）· 拦截危险网络安全操作

快速上手路径

我们合作过的最成功的安全团队，都是那些最快上手实践的团队。虽然花数月时间设计完美的流水线很诱人，但我们建议第一天就从小处着手，随着积累经验不断完善。以下步骤遵循这一原则，并根据我们的实际观察制定了积极（但合理）的节奏。

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

第 1 天的目标是端到端地看清整个流程。仅使用交互式技能，您将构建威胁模型、基于该模型运行范围明确的静态扫描、对结果进行分类，并起草候选修复方案。完成当天工作后，您将得到一个威胁模型、一份静态发现结果排名列表以及候选补丁。

相关技能仅读写文件，只要您在 Claude Code 中以交互方式运行并批准每次工具调用，无需沙箱。

# 将每个子 agent 固定到您想要的模型
export CLAUDE_CODE_SUBAGENT_MODEL=<model>
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 会正确排除测试/ 固件代码中的 bug。如需查看完整的确认/去重/误报流程，请在精选固件上运行 （/triage .claude/skills/triage/fixtures/canary-findings.json --repo targets/canary）， 或将第 1 步的技能指向您自己的代码。

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

第 2 天，您将从交互式技能转向首次使用参考流水线的自主运行。您将在自己的环境中对一个已知存在漏洞的开源库完整执行“侦察 → 发现 → 验证 → 报告“循环，然后为发现结果生成候选补丁。完成后，您将获得一组可复现的崩溃、可利用性报告和候选补丁，并对流水线的工作方式有直观认识。

运行流水线非常简单：

# 一次性设置
python3 -m venv .venv && .venv/bin/pip install -e .
./scripts/setup_sandbox.sh  # 安装 gVisor，构建 agent 镜像，验证隔离；注意：需要 Docker
export ANTHROPIC_API_KEY=sk-ant-...  # 或 CLAUDE_CODE_OAUTH_TOKEN；流水线需要其中一个

# 运行侦察 → 发现 → 验证 → 报告循环
bin/vp-sandboxed run drlibs --model <model> --runs 3 --parallel --stream --auto-focus

# 为每个发现结果生成候选补丁
bin/vp-sandboxed patch results/drlibs/<run-id>/ --model <model>

# 或者，请 Claude Code 启动流水线并监看运行过程
claude
> 在 drlibs 上运行流水线，并在结果出来时逐一解释

循环结果保存在 results/drlibs/<run-id>/ 目录中。使用 --stream 参数时，第一份报告将在数分钟内出现在 reports/bug_NN/ 下。

⚠️ run 会启动自主 agent。 流水线在 gVisor 容器内运行每个 agent， 出口流量限制为仅允许访问 Claude API。除非明确覆盖设置，否则 agent 启动子命令 拒绝在沙箱外启动。更多信息请参阅 docs/security.md 和 docs/agent-sandbox.md。

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

1. 构建：将目标编译为带有 ASAN（C 和 C++ 内存错误检测器）的 Docker 镜像。流水线在首次运行时使用目标的 Dockerfile 自动构建此镜像。
2. 侦察：一个轻量级 agent 在网络隔离容器中读取源码，提出分区方案，即“以下 N 个独立的输入解析子系统值得分别攻击“，以便并行发现 agent 探索不同区域，而不是聚焦于同一个 bug。不使用 --auto-focus 参数时，流水线使用目标 config.yaml 中的 focus_areas 列表。
3. 发现：N 个 agent 并行运行，每个在独立的隔离容器中。每个 agent 读取源码，构造畸形输入，并运行 ASAN 二进制，直到某个输入连续 3 次产生崩溃。
4. 验证：一个独立的评分 agent 在全新容器中复现每次崩溃，该容器与发现 agent 使用的容器互不影响。从发现 agent 传递到评分 agent 的唯一内容是其生成的概念验证。
5. 去重：一个裁判 agent 将已验证的崩溃与已报告的 bug 进行比较，判断每个是新 bug、已知 bug 的更好示例，还是需要跳过的重复项。
6. 报告：一个报告 agent 为每个唯一 bug 撰写结构化的可利用性分析，包含原语类别、可达性、提权路径和严重性等详情。
7. 修补（上述独立的 patch 命令）：一个修补 agent 编写提议的修复方案，一个评分 agent 确认新代码可以构建、原始概念验证输入不再引发崩溃、目标测试套件仍然通过，且全新的发现 agent 无法绕过该修复。

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

第 3 步（第 3-5 天）：为您的目标自定义流水线

第 3-5 天，您将为自己的目标自定义 harness。首先将第 1 步的技能指向您的代码，然后使用 /customize 将流水线适配到您的技术栈。到本周末，您将拥有一个流水线可以运行的 targets/<your-target>/ 目录，经过单次冒烟测试验证，并准备好在第 4 步中扩大规模。

参考流水线专为发现 C 和 C++ 代码中的内存漏洞而设计，但其结构是通用的。将其移植到新的漏洞类型或语言，只需回答以下关于目标技术栈的问题：

自定义前，先将第 1 步的技能指向您自己的代码。再次提醒，这些技能仅读写文件，可在非沙箱环境中运行。

claude
> /quickstart 如何为 ~/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 技能中使用这些技能生成的产出物，该技能会为您的代码库修改 harness。

> /customize 使用 ~/code/my-service/{THREAT_MODEL.md,VULN-FINDINGS.json} 和 ./TRIAGE.md

/customize 完成后，您将获得一个已设置好的 targets/my-service/ 目录。在扩大规模前，用一次流水线冒烟测试进行验证。

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

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

第 4 步（第 2 周）：启动自主扫描、分类和修补

第 2 周，您将在第 3 步自定义的流水线上针对自己的目标使用，在内部流水线循环之外添加一个外部循环——运行多轮流水线扫描，对多轮结果进行分类，按优先级进行修补，然后重复。

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

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

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

⚠️ 遵循与 第 2 步 相同的沙箱指南

单次流水线运行已会验证并去重自身的发现结果。/triage 跨多次流水线运行工作。当指向 results/ 目录时，它会折叠所有运行（以及 /vuln-scan 产生的任何静态发现，如有）中的重复项，针对您的威胁模型重新校准严重性评级，并尝试将每个发现路由到对应组件的负责人。

尽可能快速修补发现结果有助于保持外部循环的高效性。当发现结果被修复后，模型无法再次发现它们，而是会浮现出全新的、通常更深层的问题。随着您运行更多波次的流水线，发现数量可能会减少，但复杂性也可能随之上升。如果无法快速修补，即便只是在目标的 known_bugs 中记录已有发现，也有助于引导未来的运行发现新 bug。

自主分类和修补仍是开放性问题，本参考 harness 并未完全解决。/patch 中的验证策略有助于提高标准，但严重性和优先级归根结底是对您自身环境的判断，且已验证的补丁并不总是可以直接提交上游。许多合作伙伴反映这些步骤是当前的瓶颈，您应该为此留出充足的工程时间。

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

展望未来

完成初始上手后，与我们合作过的团队通常会在以下几个方向持续投入：

1. 审查所有内部仓库和关键开源依赖项，按扫描优先级排名（例如，基于暴露面、CVE 历史、业务关键性），然后按优先级顺序逐一扫描。
2. 搭建专用的扫描基础设施，将扫描任务从笔记本电脑或临时虚拟机上迁移出去。最成功的团队会抵制在扩大规模之前先构建完美扫描平台的冲动。
3. 将扫描纳入 SDLC。一些团队已设置定期扫描（例如每日、每周），或将扫描加入 CI 流水线。
4. 测试和实验不同模型，找到最适合自己的方案。