返回更新列表
新发布Sep 8, 2026

raptor v3.1.0

自动化安全研究框架,集成静态分析、二进制分析、模糊测试、基于大语言模型的漏洞验证、漏洞利用生成及补丁编写,支持攻击与防御操作。

分享
╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             Autonomous Offensive/Defensive Research Framework             ║
║             Based on Claude Code (v3.1.0)                                 ║
║                                                                           ║
║             Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake)    ║
║             Michael Bargury, John Cartwright                              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀
⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀

作者: Gadi Evron、Daniel Cuthbert、Thomas Dullien (Halvar Flake)、Michael Bargury、John Cartwright (@gadievron@danielcuthbert@thomasdullien@mbrg@grokjc)

许可证: MIT,详见 LICENSE。请注意,CodeQL 拥有自己的许可证,不允许商业使用。

仓库: https://github.com/gadievron/raptor


什么是 RAPTOR?

RAPTOR 是一个自主安全研究框架,构建于 Claude Code 之上(但并非绑定于它——你也可以接入自己的分析层)。它将静态分析、二进制分析、基于 LLM 的漏洞验证、漏洞利用生成和补丁编写串联成一个统一的工作流,你可以针对代码库或二进制文件运行它。

它并非精雕细琢的软件。它是在空闲时间构建的,靠热情和胶带拼凑而成,但运行效果足够好,以至于我们无法停止使用它。如果你想让它变得更好,欢迎提交 PR。

RAPTOR 代表递归自主渗透测试与观察机器人(Recursive Autonomous Penetration Testing and Observation Robot)。我们真的很想叫它 RAPTOR。

它是如何构建的

RAPTOR 大部分是 AI 生成的代码。人类负责设定方向、审查输出并做出设计决策;AI 负责编写实现。机械验证(测试、静态分析、语料库校准)确保质量水准始终达标,无论代码是谁——或是什么——编写的。


前置条件

  • Claude Code,需拥有有效订阅(Max、Pro、Team 或 Enterprise)或 Anthropic API 密钥。这是编排层——RAPTOR 在 Claude Code 会话中运行。
  • Python 3.10+Node.js 18+
  • Semgreppip install semgrep)用于静态分析。CodeQL 为可选但推荐使用。

对于分析调度层(分析单个发现结果的 LLM),Claude Code 本身默认处理一切——无需额外的 API 密钥。如果你想进行多模型分析(例如 Claude + GPT + Gemini),则需要为每个提供商准备 API 密钥。请参阅下方的使用不同的 LLM

快速开始

选项 1:手动安装```bash

Clone the repo

git clone https://github.com/gadievron/raptor.git cd raptor

Install Python dependencies

pip install -r requirements.txt

Install Claude Code (if you don't already have it)

npm install -g @anthropic-ai/claude-code

Install Semgrep (required for scanning)

pip install semgrep

Add the launcher to your PATH -- put this in your shell profile to make it

permanent. Append rather than prepend, so system directories stay ahead of

the repo. (Alternatively, symlink bin/raptor into a directory already on PATH.)

export PATH="$PATH:$PWD/bin"

Launch RAPTOR

raptor

`raptor` 启动器是启动会话的推荐方式,它可以从任何目录运行——它会解析 RAPTOR 的安装位置,记住你启动时所在的目录(因此像 `/scan` 这样的命令默认以该目录为基准),执行预检信任与项目检查,加载覆盖率跟踪插件,并在移交给 Claude Code 之前净化环境。它还可以接受可选的目标路径以及 `--project`、`--continue` 和 `--model` 等标志——参见 `raptor --help`。

在仓库目录内直接运行 `claude` 也可以——Claude Code 会从检出目录中读取 RAPTOR 的配置——但你会跳过上述启动器所做的所有工作:没有预检检查,没有覆盖率跟踪,而且默认以“你运行此命令的目录”为基准的命令无法识别该目录。

**重要提示:** RAPTOR 从仓库目录加载其配置。如果你从任何其他目录运行 `claude`,你得到的是普通的 Claude Code,而不是 RAPTOR。`raptor` 启动器完全避免了这种失败模式。

### 选项 2:在容器中运行(推荐)

使用容器是一种常见的安全实践,用于限制代理访问你不想让其访问的文件系统区域,同时限制可能执行的恶意代码(例如通过供应链攻击)的爆炸半径。该镜像较大(约 6 GB)。它以 Microsoft Python 3.12 devcontainer 为基础,并添加了静态分析、模糊测试和浏览器自动化工具。

你可以拉取一个预构建的镜像:```bash
docker pull danielcuthbert/raptor:latest

或使用附带的 Dockerfile 在本地构建:```bash docker build -f .devcontainer/Dockerfile -t raptor:latest .

该镜像期望在启动时将 RAPTOR 框架(本仓库)挂载到 `/workspaces/raptor`。您可以选择挂载一个目标文件夹用于本地分析。

要启动容器:```bash
docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

要挂载目标文件夹,还可以使用:```bash docker run -it
-v "$(pwd):/workspaces/raptor"
-v "/path/to/target-folder:/workspaces/target"
raptor:latest

添加 `--privileged`(如果你需要 `rr` 确定性调试器)。

VS Code 开发容器(devcontainers)同样受支持。要挂载目标文件夹,请将其添加到 `.devcontainer/devcontainer.json` 的 `mounts` 部分:```jsonc
"mounts": [
  // ...existing entries...
  "source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]

然后在 VS Code 中打开该仓库——它会提示你在容器中重新打开:```bash cd /path/to/raptor code .

无论采用哪种方式,一旦进入容器,运行 `raptor` 即可开始。

---

## 首次运行时的预期

你可以做的最简单的事情:```
/scan /path/to/code

此操作会对目标运行 Semgrep(若已安装 spatch,还会运行 Coccinelle;添加 --codeql 可启用 CodeQL),对发现结果进行去重,并生成 SARIF 报告。不涉及 LLM 分析,除 Claude Code 外无需任何 API 密钥。在典型仓库上运行仅需几分钟。

如需添加基于 LLM 的验证:``` /agentic /path/to/code

这将运行完整流程:扫描、去重,然后将每个发现依次送入验证阶段(A-F)。在包含约 50 个发现的中型代码库上,预计耗时 10-30 分钟,分析层 LLM 成本为 2-8 美元(取决于所用模型)。默认成本上限为每次运行 10 美元;可通过 `--max-cost-usd` 调整。

**成本说明:** Claude Code 编排层使用你的 Claude 订阅。分析调度层会进行独立的 LLM API 调用,按 token 计费。如果你仅将 Claude Code 用作分析模型(默认设置),除订阅外不会产生额外费用。如果你配置了外部模型(OpenAI、Gemini 等),这些 API 调用将按相应提供商计费。

---

## 安全模型

RAPTOR 会运行 LLM 生成的代码并分析不受信任的仓库。处理不受信任内容的子进程使用 Linux 命名空间、Landlock 和 seccomp 进行沙箱隔离。沙箱会阻止网络访问、限制文件系统可见性,并限制资源消耗。完整威胁模型和配置请参阅 `docs/sandbox.md`。

可能向启动器链注入代码的环境变量会在启动时被剥离(`core/security/_dangerous_env_strip.sh`)。来自被扫描仓库的文件路径绝不会被插入到 shell 字符串中——所有子进程调用均使用基于列表的参数。

---

## RAPTOR 能做什么

| 命令 | 功能 | 状态 |
|---------|-------------|--------|
| `/agentic` | 全自主工作流:扫描、验证、利用、修补 | 稳定 |
| `/scan` | 使用 Semgrep 和 CodeQL 进行静态分析 | 稳定 |
| `/understand` | 映射攻击面、追踪数据流、搜寻漏洞变体 | 稳定 |
| `/binary` | 黑盒二进制调查、运行时证据、图查询与交接 | 测试版 |
| `/ghidra` | Ghidra 逆向工程桥接:附加/导入 `.gpr` 项目、跨版本差异对比、发现导出 | 测试版 |
| `/audit` | 假设驱动、工具支撑的系统化代码审查 | 测试版 |
| `/review` | 查询审计状态:发现、缺口、覆盖率、操作员备注 | 稳定 |
| `/annotate` | 为每个函数附加自由格式的散文注释(操作员审查备注) | 稳定 |
| `/validate` | 多阶段可利用性验证流水线(阶段 0-F) | 稳定 |
| `/diagram` | 从 `/understand` 和 `/validate` 的 JSON 输出生成 Mermaid 可视化地图 | 测试版 |
| `/codeql` | 仅使用 CodeQL 的深度分析,带 SMT 数据流预筛选 | 稳定 |
| `/analyze` | 使用 LLM 分析现有 SARIF 发现,无需重新扫描 | 稳定 |
| `/sca` | 软件组成分析:依赖项、安全公告、供应链信号、SBOM 和修复方案 | 测试版 |
| `/cve-diff` | 跨 OSV、NVD、GitHub 和 GitLab 发现并对比 CVE 的修复提交 | 测试版 |
| `/cve-env` | 构建并验证运行 CVE 受影响应用补丁前版本的 Docker 环境 | 实验性 |
| `/exploit` | 生成概念验证利用代码 | 测试版 |
| `/patch` | 为已确认漏洞生成安全补丁 | 测试版 |
| `/fuzz` | 使用 AFL++ 进行二进制模糊测试及崩溃分析 | 稳定 |
| `/crash-analysis` | C/C++ 崩溃的自主根因分析 | 稳定 |
| `/oss-forensics` | 针对 GitHub 仓库的基于证据的取证调查 | 稳定 |
| `/project` | 命名工作区,用于组织运行并随时间追踪发现 | 稳定 |
| `/describe` | 描述目标:语言构成、构建系统、工具缺口、成本估算(只读) | 稳定 |
| `/threat-model` | 创建、检查并维护每个项目的威胁模型 | 稳定 |
| `/sage` | 持久记忆层(存储、召回、关联、佐证) | 稳定 |
| `/ask` | 向任何已配置的 LLM 模型发送自由格式提示 | 稳定 |
| `/scorecard` | 检查各模型在决策类别上的可靠性 | 稳定 |
| `/frida` | 通过 Frida 进行动态插桩 | Alpha |
| `/web` | Web 应用扫描:爬取、ffuf/nuclei 集成、oracle 验证的注入、盲 SSRF 回调 | 测试版 |

---

## 流水线工作原理

首先创建一个项目,以便你所有的运行都归集到一处:```
/project create myapp --target /path/to/code   # create a project first
/project use myapp                             # set it as active
/understand --map                              # map the attack surface
/agentic --threat-model --validate             # map, model, scan, validate
/project findings                              # review everything in one place

对于编译后的工件,等效的起点是:```text /binary investigate /path/to/binary # build the evidence-backed binary map /binary graph --edges --json # query the persisted graph /binary trace-parser # collect runtime parser evidence /binary harness # draft a harness only when the boundary is explicit

`/understand` 在扫描开始前构建入口点、信任边界和汇聚点的上下文映射。随后 `/agentic` 运行 Semgrep 和 CodeQL,对发现结果去重,并使用 exploitation-validator 方法将每条结果分派进行验证:

使用 `--threat-model` 时,RAPTOR 会先运行映射,如果项目尚未拥有 `threat-model.json` 和 `THREAT_MODEL.md` 则创建它们,然后将精简版本输入 `/understand`、自主分析和 `/validate`。除非你传入 `--threat-model-refresh`,否则现有项目威胁模型会被保留;除非你明确传入 `--threat-model-use-stale`,否则过时的回退映射会被拒绝。它还会将映射出的未检查数据流转化为候选 SARIF,这样扫描器遗漏不会导致运行失败。这是操作者拥有的上下文,而非魔法证明:发现结果仍需代码证据或预言机支持的确认。参见 `docs/threat-model.md`。

- 阶段 A:该模式是否真的是漏洞,还是工具在模式匹配噪声?
- 阶段 B:攻击者需要什么才能触达它,又有什么阻碍?
- 阶段 C:代码路径是否真实存在?能否从外部触达?
- 阶段 D:最终裁决——这是测试代码吗,是否需要不切实际的前置条件,模型是否在含糊其辞?
- 阶段 E:二进制利用可行性(当编译产物可用时)
- 阶段 F:自我审查——早期阶段是否有含糊或自相矛盾之处?

通过验证的发现结果会生成利用 PoC 和补丁。运行结束时还会进行跨发现分析,以找出共享根因和攻击链。

如果你已有先前扫描的发现结果,`/validate` 会作为独立步骤运行同一流程。

对于编译产物,`/binary <path>` 现在运行的是证据优先的调查,而不是向操作者倾倒一堆原始逆向工程产物。底层仍会从文件元数据、导入和 radare2 交叉引用构建 SHA-256 绑定的清单、证据台账、上下文映射、检查清单和 SQLite 图。Mach-O 应用还会获得切片清单、捆绑元数据和 Objective-C / Swift 类选择器;高价值伪代码会被持久化,而不是在运行中消失。PE DLL 导出、Windows 驱动分发器和 Linux 内核模块 ioctl 处理器也会作为各自的入口候选被处理,PE 架构从 COFF 头读取而非猜测。调查层随后查询该图,在通用汇聚点线索之前对外部入口进行排序,发现声明的辅助/兄弟二进制文件,并写出一个分为事实、结构推断和未证实假设的精简报告。Frida 观察、模糊测试崩溃见证、显式 Z3 检查和二进制差异随后可添加更强的证据。RAPTOR 还保留恢复有界入口到解析器候选所需的内部调用图,因此应用回调可被缩小到实际调用 `XML_Parse`、`d2i_X509`、`jpeg_read_header` 或其他真实解析器表面的内部函数,而不会假装那是污点证明。`/binary trace-parser <run-dir>` 是显式的动态后续步骤:它运行窄范围的 Frida 解析器跟踪,然后就地刷新相同的上下文映射、交接、图和调查报告。`/binary investigate --active` 先进行映射,并且仅在存在具体 harness 边界时才启动真正的模糊测试活动;应用、DLL 和驱动目标则改为获得 harness 或快照步骤。`/binary harness` 为所选入口写出有证据支持的 harness 规范,并且仅在 ABI 或 IOCTL 契约明确时才生成候选源码。它不会从“存在 `memcpy`”硬扯到“这可利用”:导入、选择器和调用边在有机机制证明更多之前始终只是候选。参见 `docs/binary-analysis.md`。

---

## 软件组成分析

`/sca` 分析项目的依赖和供应链侧。它不仅仅是 requirements 文件的 CVE 查询:RAPTOR 会发现清单、锁文件、内联安装命令、工作流依赖以及容器/基础镜像包来源,然后将它们归一化为单一依赖视图。

扫描会用 OSV 公告、CISA KEV、EPSS、CISA Vulnrichment/SSVC、可达性、利用证据信号、卫生检查、供应链启发式、许可证策略发现以及可选的 LLM 审查/分诊来丰富依赖信息。它输出 RAPTOR 原生发现结果以及 SBOM 和 CI 友好输出:

- `findings.json` - 规范的 RAPTOR 发现结果
- `report.md` - 人类可读摘要
- `sbom.cdx.json` - 带 VEX 数据的 CycloneDX SBOM
- `findings.sarif` - GitHub/GitLab 代码扫描输出

常用命令:```bash
python3 raptor.py sca --repo /path/to/project
python3 raptor.py sca --repo /path/to/project --no-llm
python3 raptor.py sca --repo /path/to/project --fail-on-severity high --fail-on-kev
python3 raptor.py sca --repo /path/to/project fix
python3 raptor.py sca check PyPI django 4.2.10

有用的子命令包括 fixcheckupgradediffverifyhealthrendersuppressclean-cache。完整参考请参阅 docs/sca.md


Z3 SMT 集成

RAPTOR 具有两层 Z3 集成(pip install z3-solver)。这是可选的。没有它一切都能正常工作,但有了它结果会更好。

数据流预筛选(CodeQL)

当 CodeQL 产生路径结果时,在任何 LLM 调用之前都会检查路径约束的可满足性。可证明不可达的路径会被立即丢弃。对于可达的路径,Z3 会生成具体的候选输入并放入分析提示中,这样 LLM 就有具体的内容可以推理,而不是抽象的模式。

单 gadget 约束分析(二进制可行性)

在二进制漏洞利用可行性评估期间,Z3 会检查单 gadget 的寄存器和内存约束是否针对具体的崩溃状态可满足。Gadget 根据实际可达性而非启发式方法进行排序,因此你可以将时间花在真正可行的 gadget 上。

Z3 已预装在 devcontainer 中。手动安装:pip install z3-solver


离线及气隙管道中运行

RAPTOR 在 engine/semgrep/rules/ 下的自定义规则完全本地化,无需网络即可运行。

对于注册表包(p/security-auditp/owasp-top-ten 等),缓存目录以空状态交付。缓存工具(engine/semgrep/tools/cache-packs.py)负责填充:```bash

On a connected machine — update the local cache directly:

python3 engine/semgrep/tools/cache-packs.py update

Or fetch into a zip bundle for airgap transfer:

python3 engine/semgrep/tools/cache-packs.py fetch

→ produces semgrep-cache-YYYY-MM-DD.zip

On the airgapped machine — import the bundle:

python3 engine/semgrep/tools/cache-packs.py import semgrep-cache-2026-07-16.zip

Check what's cached:

python3 engine/semgrep/tools/cache-packs.py list

一旦填充完毕,扫描器会将包 ID 解析为本地文件,不再发生网络调用。如果没有缓存,RAPTOR 会在扫描时尝试从 semgrep.dev 获取注册表包;如果处于离线状态,它会优雅地丢弃未缓存的包,仅使用自定义规则运行。

CodeQL 仅在初始设置期间需要网络访问,以下载 CLI 和查询包。安装完成后即可离线运行。

---

## 自定义规则

RAPTOR 内置了 200 多条自定义静态分析规则,经过对抗性测试以消除误报:

- **Semgrep(145 条规则)** — 针对 Python、Go、Java 和 JS/TS 的污点跟踪和模式规则。涵盖 SQLi、XSS、SSRF、SSTI、命令注入、反序列化、XXE、LDAP/NoSQL 注入、路径遍历、开放重定向、日志/标头注入、eval 注入、ReDoS、原型污染、JWT 配置错误、弱加密、不安全 TLS 以及硬编码密钥。
- **Coccinelle(63 条规则)** — 针对 C/C++ 的结构化匹配。内存安全(双重释放、释放后使用、释放非基址指针、释放栈数组、mmap 内存、关闭后使用)、整数缺陷(溢出、符号扩展、双重 sizeof)、资源泄漏(popen/fclose 不匹配、fdopendir 双重关闭)、缓冲区处理(无 NUL 的 strncpy、copy_user 大小不匹配、malloc/strlen 差一错误)、信号处理器安全性、API 误用(fcntl 标志域、SIGKILL/SIGSTOP、双重字节交换、inet_ntoa 静态缓冲区)、编译器死存储消除、内核 IS_ERR/PTR_ERR 混淆、格式字符串注入、TOCTOU 竞态等。
- **CodeQL(8 条查询)** — 针对 C++(格式字符串注入、整数截断、移动后使用、迭代器失效)和 Java(XXE、不安全反序列化、日志注入、Spring SSRF)的过程间污点跟踪。

直接浏览规则:`engine/semgrep/rules/`、`engine/coccinelle/rules/`、`engine/codeql/queries/`。这些规则与 RAPTOR 拉取的 Semgrep 注册表包(始终包含 `p/security-audit`、`p/owasp-top-ten`、`p/secrets`;按策略组额外添加 `p/command-injection`、`p/jwt`、`p/xss` 等包)互为补充 — 重叠极少。

---

## RAPTOR 如何自我检查

RAPTOR 大量使用自身的安全工具,但值得坦诚说明哪些检查真正会阻止 PR 合并,哪些只是在后台运行以保持我们的自律。其中一些是硬性门禁,一些是定时检查,还有一些只是我们保留的基准测试,以便在情况恶化时能够察觉。更详细的分类(包括实际参数以及如何复现检查)见 `docs/ci-controls.md`。

| 控制项 | 检查内容 | 触发时机 | 配置 / 证据 |
|---|---|---|---|
| Ruff | Python 正确性 lint(`F401`、`F811`、`F821`、`F841`) | PR 差异门禁,外加每周全树审计 | `pyproject.toml`、`.github/workflows/lint.yml` |
| Pytest | 快速单元/集成边界、按子系统分层的测试(通过导入图分发)、提示词封装审计 | PR、推送到 `main`、合并队列、定时全量测试套件 | `pytest.ini`、`.github/workflows/tests.yml`、`.github/workflows/nightly.yml` |
| CodeQL Advanced | Python、C/C++ 和 GitHub Actions 代码扫描,带导入图范围收窄 | PR、推送到 `main`、合并队列、每周定时任务 | `.github/workflows/codeql.yml`、`.github/codeql/codeql-config.yml` |
| 工作流加固 | SHA 固定的第三方 Actions、最小权限、命令元数据 lint | 每次工作流变更和每次 lint 运行 | `.github/workflows/`、`.github/scripts/check_command_metadata.py` |
| 语料库标签 lint | 审计语料库标签模式验证和上游固定版本校验 | PR(变更的标签)、每周全量扫描 | `.github/workflows/corpus-labels.yml` |
| RAPTOR SCA PR 门禁 | PR 引入的依赖和供应链回归 | 清单 / 锁文件 / 工作流变更 | `.github/workflows/sca-pr-gate.yml` |
| RAPTOR SCA 自动升级 | 机械性依赖加固和安全升级建议 | 每周定时任务、手动运行 | `.github/workflows/sca-self-bump.yml` |
| SCA 攻破语料库 | 已知依赖攻破是否仍触发预期信号 | 每周定时任务、相关 PR 变更 | `test/data/sca-e2e/compromise-corpus/`、`.github/workflows/sca-compromise-check.yml` |
| 接线错误扫描 | 死代码 / 错误调用检测、环境变量文档漂移、词汇表护栏、可选依赖导入 lint | 每日定时任务 | `.github/workflows/miswiring-scan.yml`、`.github/scripts/*_baseline.json` |
| SCA 校准 + 压力语料库 | 风险评分和解析器覆盖率是否随时间漂移 | 每周 / 每月定时任务 | `packages/sca/data/calibration/`、`.github/workflows/refresh-sca-calibration.yml`、`.github/workflows/sca-stress-sweep.yml` |
| 数据流语料库 | 验证器行为的精确率 / 召回率 / 误报类别跟踪 | 开发者运行的基准测试和语料库测试 | `core/dataflow/corpus/`、`core/dataflow/scripts/corpus-metrics` |
| CI 控制文档守卫 | 文档中路径存在、ruff 配置匹配、README 链接到该文档 | PR | `.github/tests/test_ci_controls_docs.py` |

当前未强制执行:`mypy` 已安装在 `requirements-dev.txt` 中但不阻止任何操作;Ruff 格式化未强制执行;Semgrep 是 RAPTOR 扫描器表面的一部分,但我们尚未建立专门的“用 RAPTOR 扫描 RAPTOR”的 Semgrep 工作流。

---

## 使用不同的 LLM

RAPTOR 有两个独立的模型层,在更改任何内容之前,值得了解两者的工作方式。

**编排层**始终是 Claude Code。CLAUDE.md、技能和命令都以 Claude Code 指令的形式运行。要更改编排 RAPTOR 的 Claude 模型,请使用 Claude Code 的 `--model` 标志或会话内的 `/model` 命令。

**分析分发层**是分析单个漏洞发现的 LLM。该层与编排层分离,可以是任何受支持的提供商。在 `~/.config/raptor/models.json` 中配置:```json
{
  "models": [
    {
      "provider": "anthropic",
      "model": "claude-opus-4-6",
      "api_key": "sk-ant-...",
      "role": "analysis"
    },
    {
      "provider": "openai",
      "model": "gpt-5.4",
      "api_key": "sk-...",
      "role": "analysis"
    },
    {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "api_key": "sk-ant-...",
      "role": "aggregate"
    }
  ]
}

或者跳过配置文件,直接设置环境变量。RAPTOR 会自动检测到它们:```bash export ANTHROPIC_API_KEY=sk-ant-... # Anthropic Claude export OPENAI_API_KEY=sk-... # OpenAI export GEMINI_API_KEY=... # Google Gemini export MISTRAL_API_KEY=... # Mistral export OLLAMA_HOST=http://localhost:11434 # Local Ollama

模型角色允许你将不同的模型分配给不同的任务:

| 角色 | 作用 |
|------|-------------|
| `analysis` | 验证并分析每项发现(阶段 A-F) |
| `code` | 编写漏洞利用 PoC 和补丁代码 |
| `consensus` | 对真实阳性结果进行第二意见投票 |
| `aggregate` | 可选。在确定性多模型关联之上,由 LLM 编写的叙述性综合,写入 `aggregation.json` 和最终的 `agentic-report.md` |
| `fallback` | 当主模型失败或达到速率限制时使用 |

如果未设置任何角色,则列表中的第一个模型将处理所有任务。对于多模型
源代码分析,请配置两个或更多 `analysis` 模型——默认情况下你将获得
确定性关联。`aggregate` 角色是可选的,并在其上添加
LLM 编写的摘要:```bash
python3 raptor.py agentic --repo /code \
  --model claude-opus-4-6 \
  --model gpt-5.4 \
  --aggregate claude-sonnet-4-6

预算控制:```bash

Cap analysis-layer LLM spend at $5 for this run (default: $10)

python3 raptor.py agentic --repo /code --max-cost-usd 5.00

Ollama 可用于分析,但生成的漏洞利用和补丁代码不可靠。对于代码生成任务,请使用前沿模型。

### 快速层短路 + 模型记分卡

当你的分析层模型拥有同一提供商更便宜的同类模型时(Anthropic Opus → Haiku、OpenAI 5.x → 4o-mini、Gemini Pro → Flash-Lite、Mistral Large → Small),RAPTOR 会将其用作接入底层系统的消费者(目前为 codeql;SCA 及其他功能将陆续落地)的预过滤器。廉价模型仅在**确信的误报**上短路;模糊案例和确信的真阳性始终运行完整分析。信任度按 `(model, decision_class)` 单元累积——RAPTOR 记录廉价模型与完整分析的一致性,并且仅在该单元漏报率的 Wilson 95% 置信上限降至 5% 或以下时才启用短路。

要查看你的模型擅长什么,请使用 `/scorecard`(或直接运行:`libexec/raptor-llm-scorecard list`)。记分卡是全局性的(经验可跨项目传承),并持久化存储在 `out/llm_scorecard.json`。

---

## 项目

如果没有项目,每次运行都会在 `out/` 下获得一个带时间戳的独立目录。有了项目后,所有内容都会归入同一位置,你将获得合并后的发现、覆盖率跟踪以及各次运行之间的差异。```bash
/project create myapp --target /path/to/code -d "Short description"
/project use myapp

/scan
/understand --map
/validate

/project status                # all runs, pass/fail, timestamps
/project findings              # merged findings across all runs
/project findings --detailed   # per-finding detail
/project coverage --detailed   # which files were reviewed
/project diff myapp run1 run2  # compare two runs
/project report                # full merged report
/project clean --keep 3        # remove old runs, keep the last 3
/project export myapp /tmp/myapp.zip
/project none                  # clear active project

架构

RAPTOR 分为两层。

Python 执行层raptor.pypackages/core/engine/)负责繁重的工作:运行 Semgrep 和 CodeQL、管理子进程、解析 SARIF、对发现结果去重、调度 LLM API 调用、跟踪成本、写入输出文件。它不做决策,只负责执行。

Claude Code 决策层.claude/tiers/CLAUDE.md)负责做出判断:优先处理哪些发现结果、如何解释结果、攻击场景是什么、漏洞利用是否现实。它通过 Claude Code 技能、命令和代理实现,并逐步加载。``` CLAUDE.md always loaded -- bootstrap, routing, security rules .claude/commands/ slash commands (/agentic, /scan, /validate, etc.) .claude/skills/ methodology detail, loaded on demand tiers/ adversarial thinking, recovery, expert personas .claude/agents/ specialist sub-agents (offsec, crash analysis, forensics)

拆分意味着你可以从 CI 流水线运行 Python 层(`python3 raptor.py scan --repo ...`),无需 Claude Code 即可获得结构化的 SARIF 输出,也可以交互式运行完整的智能体工作流。

---

## 开源取证

`/oss-forensics` 使用来自多个来源的证据调查公开的 GitHub 仓库:GitHub API、GH Archive(通过 BigQuery 的不可变事件历史)、Wayback Machine 以及本地 git 历史。它运行一个结构化的流水线,从证据收集到假设形成,最终生成取证报告。

需要 `GOOGLE_APPLICATION_CREDENTIALS` 才能访问 BigQuery。详情请参阅 `.claude/commands/oss-forensics.md`。

---

## 专家角色

可按需加载七种专家角色。当你希望对某个发现或特定技术获得不同视角时,可加载其中一个:```
Exploit Developer (Mark Dowd)                  Exploit PoC generation
Crash Analyst (Charlie Miller / Halvar Flake)  Crash analysis and exploitability assessment
Security Researcher                            General adversarial code review
Patch Engineer                                 Secure fix generation
Penetration Tester                             Realistic attack scenario assessment
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption

告诉 Claude 使用哪一个,例如“使用二进制利用专家”。


文档

完整索引请参阅 docs/README.md。关键指南:

文件内容
docs/commands.md完整的斜杠命令参考,包含每个标志
docs/architecture.md代码库结构和目录树
docs/llm.mdLLM 提供商配置、Bedrock、多模型工作流
docs/sandbox.md进程隔离:配置文件、Landlock、命名空间
docs/audit.md系统性代码审查:假设、工具、策略、关卡
docs/validation.md可利用性验证流水线(阶段 0--1)
docs/static-analysis.mdSemgrep 和 Coccinelle 规则
docs/codeql.mdCodeQL 集成和自主分析
docs/binary-analysis.md二进制预言机、/binary、利用可行性
docs/fuzzing.mdAFL++ 和 libFuzzer
docs/crash-analysis.md自主崩溃根因分析
docs/sca.md软件成分分析
docs/frida.md动态插桩
docs/security.mdRAPTOR 自身的安全模型
docs/ci-controls.mdCI 控制、工作流和基准证据
docs/threat-model.md按项目的威胁模型功能
docs/python-cli.md用于脚本编写和 CI 的 Python CLI 参考
docs/concepts.md核心概念:两层模型、发现生命周期、选择命令
docs/agentic.md自主工作流:/agentic 流水线、富化标志、多模型
docs/sage.mdSAGE 持久记忆:设置、HMAC 密钥、CPU/GPU、用例
docs/dependencies.md外部工具、版本和许可证
tiers/personas/README.md专家角色参考

贡献

RAPTOR 是开源的。如果你想贡献,以下是一些不错的起点:

  • 为 Web 扫描器增加浏览器引擎爬取和 DOM XSS 覆盖(Playwright 已固定但未使用)
  • 为注解驱动框架(Spring @RequestParam、FastAPI 类型化参数)增加 SSRF 规则覆盖——semgrep 无法匹配这些来源,因此欢迎替代方法
  • YARA 签名生成
  • 移植到其他 AI 编码工具(Cursor、Windsurf、Copilot、Cline)
  • 更好的固件分析覆盖
  • 任何你认为缺失的内容

版本以 vX.Y.Z 形式标记,并由 CI 自动构建。提交前缀决定变更日志中的内容:feat: 用于新功能,fix: 用于错误修复,security: 用于安全变更,docs: 用于文档。没有前缀的内容归入“其他变更”。没有严格约定,但有帮助。

提交拉取请求。在 Prompt||GTFO Slack 的 #raptor 频道与我们交流: https://join.slack.com/t/promptgtfo/shared_invite/zt-3v2b4sll3-SfyzFRw2lykx_XQX7F3uNQ


许可证

MIT -- 版权所有 (c) 2025-2026 Gadi Evron、Daniel Cuthbert、Thomas Dullien(Halvar Flake)、Michael Bargury、John Cartwright。

完整文本请参阅 LICENSE。商业使用前请审查所有依赖项的许可证——尤其是 CodeQL 不允许商业使用。

问题: https://github.com/gadievron/raptor/issues

分类