anthropics/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`](docs/blog-post.md) 中查看）。如需通过轻量级 SDK 演练相同的侦察 → 发现 → 分类 → 报告 → 补丁循环，请参阅[配套指南](https://platform.claude.com/cookbook/claude-agent-sdk-06-the-vulnerability-detection-agent)。 本代码库不再维护，也不接受贡献。 ## 目录 - **Claude Code 技能**：`/quickstart`、`/threat-model`、`/vuln-scan`、`/triage`、`/patch`、`/customize`：用于交互式的范围界定、扫描、分类和修复。在 Claude Code 中打开此代码库并运行 `/quickstart` 即可快速上手。 - **`harness/`**：自主参考流水线（侦察 → 发现 → 验证 → 报告 → 补丁），配置为使用 Docker 和 ASAN 查找 C/C++ 内存漏洞。此框架是一个**参考实现，而非产品**。其整体架构、prompt 和沙箱设计是可以复用的，但该框架无法在开箱即用的状态下适用于所有代码库。请运行 `/customize` 将其移植到您的语言、检测器或漏洞类别。 ## 快速开始 ``` git clone https://github.com/anthropics/defending-code-reference-harness cd defending-code-reference-harness claude # 30秒简介 + 在 canary target 上的首次引导运行 > /quickstart > /quickstart how do I port the pipeline to Java? > /quickstart how do I triage all these bugs? ``` ## 延伸阅读 - [**博客文章**](docs/blog-post.md) · 随附的博客文章，包含经验总结与最佳实践 - [**流水线**](docs/pipeline.md) · 运行机制：流程图、阶段、CLI 标志 - [**安全性**](docs/security.md) · 沙箱机制及不应挂载的内容 - [**Agent 沙箱**](docs/agent-sandbox.md) · 针对每个 Agent 的 gVisor 隔离 + 出站允许列表 - [**自定义**](docs/customizing.md) · 移植到我的技术栈；需要更改哪些文件及其原因 - [**修复**](docs/patching.md) · 生成并验证针对已确认崩溃的修复补丁 - [**故障排除**](docs/troubleshooting.md) · 重复项、速率限制、子 Agent 模型固定 - [**安全防护**](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude) · 针对危险网络操作的拦截机制 ## 快速进阶 与我们合作过的最成功的团队，往往是那些最快将理论付诸实践的团队。尽管花几个月时间设计完美的流水线很诱人，但我们建议您在第一天从小处着手，并随着经验的积累逐步构建。以下步骤遵循这一模式，并根据我们的经验设定了一个雄心勃勃（但合理）的节奏。 | | | | |-------------------------------------------------------------------------------------|--------------|--------------------------------------------------------------| | [步骤 1](#step-1-day-1-build-a-threat-model-and-run-your-first-static-scan--triage) | **第 1 天** | 构建威胁模型，并运行您的首次静态扫描和分类 | | [步骤 2](#step-2-day-2-run-the-reference-pipeline-on-a-cc-library) | **第 2 天** | 在 C/C++ 库上运行参考流水线 | | [步骤 3](#step-3-days-3-5-customize-the-pipeline-for-your-target) | **第 3-5 天** | 针对您的目标定制流水线 | | [步骤 4](#step-4-week-2-start-autonomous-scanning-triage-and-patching) | **第 2 周** | 开始自主扫描、分类和修复 | ### 步骤 1（第 1 天）：构建威胁模型，并运行您的首次静态扫描和分类 第 1 天的重点是端到端地了解整个流程。仅使用交互式技能，您将构建一个威胁模型，在其范围内运行静态扫描，对发现的问题进行分类，并起草候选修复补丁。这一天结束时，您将得到一个威胁模型、一份排序后的静态漏洞列表以及候选补丁。 相关技能**仅读取和写入**您代码库中的文件。只要您以交互方式运行 Claude Code 并批准每一次工具调用，就不需要使用沙箱。 ``` # 将每个 subagent 固定到你想要的 model export CLAUDE_CODE_SUBAGENT_MODEL= claude # 0. 简介 + 首次引导运行 > /quickstart # 1. 构建 threat model（射击前先瞄准） > /threat-model bootstrap targets/canary # 2. 运行静态扫描，由该 threat model 确定范围 > /vuln-scan targets/canary # 3. 验证、去重并对返回的结果进行排名 > /triage targets/canary/VULN-FINDINGS.json # 4. 为已验证的 findings 生成候选修复 > /patch ./TRIAGE.json --repo targets/canary ``` 此流程会生成 `THREAT_MODEL.md`、`VULN-FINDINGS.{json,md}`、`TRIAGE.{json,md}` 和 `PATCHES/`。 步骤 1 中生成的漏洞候选项来自 Claude 对源代码的静态审查（不构建或运行任何内容），因此对于非 Canary 目标，预计会出现更多的误报。在步骤 2 中，您将生成经过*执行验证*的发现结果。 ### 步骤 2（第 2 天）：在 C/C++ 库上运行参考流水线 在第 2 天，您将从交互式技能过渡到使用参考流水线进行首次自主运行。您将在自己的环境中对一个已知存在漏洞的开源库运行完整的侦察 → 发现 → 验证 → 报告循环，然后针对发现的问题生成候选补丁。完成后，您将获得一组可重现的崩溃、可利用性报告和候选补丁，同时也会对流水线的运行机制有所了解。 运行流水线非常简单： ``` # 一次性设置 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 # 运行 recon → find → verify → report 循环 bin/vp-sandboxed run drlibs --model --runs 3 --parallel --stream --auto-focus # 为每个 finding 生成候选补丁 bin/vp-sandboxed patch results/drlibs// --model # 或者，要求 Claude Code 启动 pipeline 并为你监控运行 claude > run the pipeline on drlibs and explain findings as they come ``` 循环的运行结果会存放在 `results/drlibs//` 目录中。使用 `--stream` 标志，第一份报告将在几分钟内出现在 `reports/bug_NN/` 目录下。 在底层，流水线会依次经过七个阶段： 1. **构建**：将目标编译为包含 ASAN（用于 C 和 C++ 的内存错误检测器）的 Docker 镜像。流水线会在首次运行时使用目标的 `Dockerfile` 自动构建此镜像。 2. **侦察**：一个轻量级的 Agent 在网络隔离的容器内读取源代码，并提出分区方案，即*“这里有 N 个不同的输入解析子系统值得单独攻击”*，以便并行的发现 Agent 能够探索不同的区域，而不是集中在同一个 bug 上。如果不使用 `--auto-focus` 标志，流水线将使用目标 `config.yaml` 中的 `focus_areas` 列表。 3. **发现**：N 个 Agent 并行运行，每个都在各自独立的容器中。每个 Agent 读取源代码，构造畸形输入，并运行 ASAN 二进制文件，直到某个输入连续 3 次触发崩溃（3/3）。 4. **验证**：一个独立的评分 Agent 在发现 Agent 从未接触过的新容器中重现每次崩溃。从发现 Agent 传递给评分 Agent 的唯一内容，就是它生成的概念验证。 5. **去重**：判定 Agent 将已验证的崩溃与已报告的 bug 进行比较，决定每个崩溃是新的 bug、已知 bug 的更好示例，还是应该跳过的重复项。 6. **报告**：报告 Agent 针对每个唯一的 bug 编写结构化的可利用性分析报告，包括关于原语类别、可达性、提权路径和严重程度的详细信息。 7. **修复**（即上文的独立修复命令）：修复 Agent 编写提议的修复补丁，随后评分 Agent 会确认新代码能否构建、原始的概念验证输入是否不再导致崩溃、目标的测试套件是否依然通过，并且全新的发现 Agent 是否无法找到绕过该修复的方法。 如需了解更多详情，请参阅 [docs/pipeline.md](docs/pipeline.md)。 ### 步骤 3（第 3-5 天）：针对您的目标定制流水线 在第 3 到 5 天，您将为自己的目标定制框架。首先，您将把步骤 1 中的技能指向您的代码，然后使用 `/customize` 将流水线移植到您的技术栈。到本周末，您将获得一个流水线可以对其运行的 `targets//` 目录，该目录已通过流水线的一次冒烟测试验证，并为步骤 4 的扩展运行做好准备。 尽管参考流水线专门用于发现 C 和 C++ 代码中的内存漏洞，但其架构是通用的。将其移植到新的漏洞类别或语言，只需针对您的目标技术栈回答以下问题： | 问题 | C/C++ 参考 | 您的目标（示例） | |-----------------------------------------|-----------------------------------|------------------------------------------------| | 什么标志着一次发现？ | ASAN 崩溃特征 | 异常 / Canary 文件 / 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 --runs 1 ``` 如需了解更多详情，请参阅 [docs/customizing.md](docs/customizing.md)。 ### 步骤 4（第 2 周）：开始自主扫描、分类和修复 在第 2 周，您将在自己的目标上使用步骤 3 中定制的流水线，在内部流水线循环的基础上添加一个*外部*循环 —— 运行多次流水线扫描，对跨这些运行的漏洞发现进行分类，根据优先级生成补丁，并不断重复。 ``` # Scan - 针对 your target 运行一波并行运行 bin/vp-sandboxed run my-service --model --runs 5 --parallel --stream --auto-focus # Triage - 使用 your threat model 对所有波次中的每个 finding 进行去重和排名 > /triage results/my-service/ --repo ~/code/my-service --auto --votes 5 # Patch - 生成并验证修复，从 triage 排名最高的开始 > /patch results/my-service// --model ``` 特定的流水线运行已经验证并去重了其自身的发现结果。`/triage` 则可以处理跨多次流水线运行的结果。当指向 `results/` 目录时，它会合并所有运行中的重复项（以及如果存在的来自 `/vuln-scan` 的任何静态发现结果），根据您的威胁模型重新校准严重性评级，并尝试将每个漏洞发现路由给对应的组件所有者。在条件允许时，快速修复漏洞发现有助于保持外部循环的高效运转。当漏洞被修复后，模型无法再次发现它们，而是会挖掘出全新的、通常更深层次的问题。随着您运行更多的流水线波次，发现问题的数量可能会下降，但问题的复杂性可能也会随之上升。如果无法快速修复漏洞，即便只是将以前的发现记录在目标的 `known_bugs` 中，也有助于引导未来的运行转向更新的 bug。 自主分类和修复目前仍是待解决的开放性问题，这个参考框架也不能完全解决它们。`/patch` 中的验证策略有助于提高标准，但严重性和优先级最终仍是对您所在环境的判断，而且经过验证的补丁并不总是能被上游接受。许多合作伙伴反馈这些步骤是他们目前的瓶颈，因此您应该为它们预留充足的工程时间。 如需了解更多详情，请参阅 [docs/triage.md](docs/triage.md) 和 [docs/patching.md](docs/patching.md)。 ## 展望未来 在初步完成快速进阶后，与我们合作的团队往往会倾向于在以下几个方向进行投资： 1. 审查他们所有的内部代码库和关键的开源依赖项，对哪些最重要、需要优先扫描进行排序（例如，基于其暴露程度、CVE 历史记录、业务关键性），然后按优先级顺序依次进行扫描。 2. 建立专用的扫描基础设施，将扫描任务从笔记本电脑或临时虚拟机上转移出去。最成功的团队会克制住在大规模扩展之前构建完美扫描平台的冲动。 3. 将扫描纳入其 SDLC。一些团队设置了定期扫描（例如，每日、每周），或者将扫描加入到他们的 CI 流水线中。 4. 对模型进行测试和实验，以找出最适合他们的方案。

标签：AI智能体, C/C++, DevSecOps, DNS 反向解析, 上游代理, 事务性I/O, 插件系统, 自动化安全防护, 请求拦截, 逆向工具