raptor - Raptor turns Claude Code into a general-purpose AI

项目说明

<a href=" src="

Authors: Gadi Evron, Daniel Cuthbert, Thomas Dullien (Hal), Michael Bargury, John Cartwright
(, , , , )

Licence: MIT, see LICENSE. Note that CodeQL has its own licence and does not permit commercial use.

Repository:

---

What is RAPTOR?

RAPTOR is an autonomous security research 框架 built on top of Claude 代码 (but not tied to it -- you can plug in your own analysis layer too). It chains together static analysis, binary analysis, LLM-powered , exploit generation, and patch writing into a single workflow you can run against a codebase or binary.

It is not polished software. It was built in free time, held together with enthusiasm and duct tape, and it works well enough that we can't stop using it. If you want to make it better, open a PR.

RAPTOR stands for Recursi Penetration Testing and Obser Robot. We really wanted to call it RAPTOR.

How it's built

RAPTOR is mostly AI-generated 代码. The humans set direction, review
output, and make design decisions; the AI writes the implementation.
Mechanical (tests, static analysis, corpus calibration) keeps
the quality bar where it needs to be regardless of who — or what — wrote
the code.

---

Prerequisites

For the analysis dispatch layer (the LLM that analyses indi findings), Claude 代码 itself handles e by default -- no extra API keys needed. If you want multi-model analysis (e.g. Claude + GPT + Gemini) or a fully local setup, you will need to configure the other provider(s). See Using a different LLM below.

Quick Start

Option 1: Install manually

The raptor launcher is the recommended way to start a session, and it works from any directory -- it resolves the RAPTOR installation, remembers the directory you launched from (so commands like /scan default to it), runs the pre-flight trust and project checks, loads the co plugin, and sanitises the en before handing off to Claude 代码. It also takes an optional target path and flags like --project, --continue, and --model -- see raptor --help.

Running plain claude from inside the repo directory also works -- Claude 代码 picks up RAPTOR's configuration from the checkout -- but you skip e the launcher does above: no pre-flight checks, no co tracking, and commands that default to "the directory you ran this from" can't see it.

Important: RAPTOR loads its configuration from the repo directory. If you run claude from any other directory, you get plain Claude 代码, not RAPTOR. The raptor launcher avoids this failure mode entirely.

Option 2: Run in a container (recommended)

Using containers is a common security practice to restrict agents from accessing areas of your filesystem you don't want them to, as well as limiting the blast radius of any malicious 代码 that may execute (e.g attack). The image is large (around 6 GB). It starts from the Microsoft Python 3.12 de and adds static analysis, fuzzing, and browser automation tooling.

You can pull down a pre-built image:

or build it locally using the included Dockerfile:

The image expects the RAPTOR 框架 (this repo) to be mounted into /workspaces/raptor on startup. You can optionally mount a target folder for local analysis.

To start the container:

To mount a target folder as well:

Add --pri if you need the rr deterministic debugger.

VS 代码 de are also supported. To mount a target folder, add it to the mounts section of .de/de.json:

Then open the repo in VS Code — it will prompt you to reopen in the container:

Either way, once you're inside the container, run raptor to get started.

---

What to expect on a first run

The simplest thing you can do:

This runs Semgrep (plus Coccinelle when spatch is installed; add --codeql for CodeQL) against the target, deduplicates findings, and writes a SARIF report. No LLM analysis, no API keys beyond Claude 代码. Takes a few minutes on a typical repository.

To add LLM-powered :

This runs the full pipeline: scan, deduplicate, then send each finding through the stages (A-F). On a medium-sized codebase with ~50 findings, expect 10-30 minutes and $2-8 in analysis-layer LLM costs (depending on the model). The default cost cap is $10 per run; adjust with --max-cost-usd.

Cost note: The Claude 代码 orchestration layer uses your Claude subscription. The analysis dispatch layer makes separate LLM API calls that are billed per token. If you only use Claude 代码 as the analysis model (the default), there is no extra cost beyond your subscription. If you configure external models (OpenAI, Gemini, etc.), those API calls are billed to those pro.

---

Security model

RAPTOR runs LLM-generated 代码 and analyses untrusted repositories. Subprocesses that handle untrusted content are sandboxed using Linux namespaces, Landlock, and seccomp. The sandbox blocks 网络 access, restricts filesystem , and limits resource consumption. See docs/sandbox.md for the full threat model and configuration.

En that could inject 代码 into the launcher chain are stripped at startup (core/security/_dangerous_en.sh). File paths from scanned repositories are ne into shell strings — all subprocess calls use list-based arguments.

---

What RAPTOR can do

| Command | What it does | Status |
|---------|-------------|--------|
| /agentic | Full autonomous workflow: scan, , exploit, patch | Stable |
| /scan | Static analysis with Semgrep and CodeQL | Stable |
| /understand | Map attack surface, trace data flows, hunt | Stable |
| /binary | Black-box binary in, runtime e, graph queries and handoff | Beta |
| /ghidra | Ghidra RE bridge: attach/import .gpr projects, cross- diff, findings export | Beta |
| /audit | Hypothesis-driven, 工具-grounded systematic 代码 review | Beta |
| /review | Query audit state: findings, gaps, co, operator notes | Stable |
| /annotate | Attach free-form per-function prose annotations (operator review notes) | Stable |
| / | Multi-stage exploitability pipeline (Stages 0-F) | Stable |
| /diagram | Mermaid maps from /understand and / JSON outputs | Beta |
| /codeql | CodeQL-only deep analysis with SMT dataflow pre-screening | Stable |
| /analyze | Analyse existing SARIF findings with LLM, without re-scanning | Stable |
| /openant | OpenAnt LLM 源码-代码 scan: AST analysis plus per-function LLM reasoning | Beta |
| /sca | Software composition analysis: dependencies, ad, supply-chain signals, SBOMs, and fixes | Beta |
| /c | Discover and diff the fix commit for a C OSV, N, and GitLab | Beta |
| /c | Build and a Docker en running a CVE's affected application at its pre-patch | Experimental |
| /exploit | Generate proof-of-concept exploit code | Beta |
| /patch | Generate secure patches for confirmed | Beta |
| /fuzz | Binary fuzzing with AFL++ and crash analysis | Stable |
| /crash-analysis | Autonomous root-cause analysis for C/C++ crashes | Stable |
| /oss-forensics | E forensic in for GitHub repositories | Stable |
| /project | Named workspaces to organise runs and track findings over time | Stable |
| /describe | Describe a target: language mix, build system, 工具 gaps, cost estimate (read-only) | Stable |
| /threat-model | Create, inspect, and maintain per-project threat models | Stable |
| /sage | Persistent memory layer (store, recall, link, corroborate) | Stable |
| /ask | Send a free-form prompt to any configured LLM model | Stable |
| /scorecard | Inspect per-model reliability across decision classes | Stable |
| /frida | Dynamic instrumentation | Alpha |
| /web | Web application scanning: crawl, ffuf/nuclei integration, oracle- injection, blind SSRF callbacks | Beta |

---

How the pipeline works

Start by creating a project so all your runs land in one place:

For a compiled artefact, the equi starting point is:

/understand builds a context map of entry points, trust boundaries, and sinks before a line of scanning happens. /agentic then runs Semgrep and CodeQL, deduplicates findings, and dispatches each one for using the exploitation- methodology:

With --threat-model, RAPTOR runs the map first, creates threat-model.json and THREAT_MODEL.md if the project does not already have them, then feeds a compact into /understand, autonomous analysis, and /. Existing project threat models are preser you pass --threat-model-refresh; stale fallback maps are refused unless you explicitly pass --threat-model-use-stale. It also turns mapped unchecked flows into candidate SARIF so scanner misses do not kill the run. It is operator-owned context, not magic proof: findings still need 代码 e or oracle-backed confirmation. See docs/threat-model.md.

Findings that clear get exploit PoCs and patches generated. A cross-finding analysis runs at the end to find shared root causes and attack chains.

/ runs this same pipeline as a standalone step if you already ha from a previous scan.

For a compiled artefact, /binary <path> now runs an e
in rather than dumping a pile of raw re artefacts
on the operator. Underneath it still builds the SHA-256-bound manifest,
e ledger, context map, checklist and SQLite graph from file metadata,
imports and radare2 xrefs. Mach-O apps also get slice in, bundle
metadata and Objective-C / Swift class selectors; high-value pseudocode is
persisted rather than disappearing inside the run. PE DLL exports, Windows
dri and Linux kernel-module ioctl handlers are handled as
their own ingress candidates too, with PE architecture read from the COFF
header rather than guessed. The in layer then queries that graph,
ranks external ingress before generic sink leads, discovers declared
helper/sibling binaries, and writes a compact report split into facts,
structural inferences and unpro. Frida obser, fuzz crash
witnesses, explicit Z3 checks and binary diffs can then add stronger e
later. RAPTOR also keeps the internal call graph needed to reco
ingress-to-parser candidates, so an app callback can be narrowed to the
internal function that actually calls XML_Parse, d2i_X509,
jpeg_read_header or another real parser surface without pretending that is
taint proof. /binary trace-parser <run-dir> is the explicit dynamic follow-on:
it runs the narrow Frida parser trace, then refreshes the same context map,
handoff, graph and in report in place. /binary in --active maps first and only launches a real
fuzz campaign when a concrete harness boundary exists; app, DLL and driver
targets get a harness or snapshot step instead. /binary harness writes an
e harness spec for the chosen ingress and only emits candidate
源码 when the ABI or IOCTL contract is explicit. It does not blag its way from “memcpy exists” to “this is
exploitable”: imports, selectors and call edges stay candidates until
something mechanical proves more. See docs/binary-analysis.md.

---

Software Composition Analysis

/sca analyses the dependency and supply-chain side of a project. It is not just a requirements-file C: RAPTOR discovers manifests, lockfiles, inline install commands, workflow dependencies, and container/base-image package sources, then normalises them into a single dependency view.

The scan enriches dependencies with OS, CISA KEV, EPSS, CISA /SS, exploit-e signals, hygiene checks, supply-chain heuristics, licence policy findings, and optional LLM review/triage. It emits RAPTOR-nati plus SBOM and CI-friendly output:

Common commands:

Useful subcommands include fix, check, upgrade, diff, , health, render, suppress, and clean-cache. See docs/sca.md for the full reference.

---

Z3 SMT integration

RAPTOR has a two-layer Z3 integration (pip install z3-solver). It is optional. E works without it, but the results are better with it.

Dataflow pre-screening (CodeQL)

When CodeQL produces a path result, the path constraints are checked for satisfiability before any LLM call is made. Paths that are provably unreachable get dropped immediately. For paths that are reachable, Z3 produces concrete candidate inputs that go into the analysis prompt, so the LLM has something specific to reason about rather than abstract patterns.

One-gadget constraint analysis (binary feasibility)

During binary exploit feasibility assessment, Z3 checks whether a one-gadget's register and memory constraints are satisfiable against the concrete crash state. Gadgets are ranked by actual reachability rather than heuristics, so you spend time on gadgets that can actually work.

Z3 is pre-installed in the de. For manual installs: pip install z3-solver.

---

Running offline and in air-gapped pipelines

RAPTOR's custom rules under engine/semgrep/rules/ are fully local and run without 网络 access.

For registry packs (p/security-audit, p/owasp-top-ten, etc.), the cache directory ships empty. A cache 工具 (engine/semgrep/tools/cache-packs.py) handles population:

Once populated, the scanner resolves pack IDs to local files and no 网络 call happens. Without the cache, RAPTOR will attempt to fetch registry packs from semgrep.dev at scan time; if offline, it drops uncached packs gracefully and runs with custom rules only.

CodeQL needs 网络 access only during initial setup to download the CLI and query packs. Once installed it runs offline.

---

Custom rules

RAPTOR ships over 200 custom static analysis rules, ad tested to eliminate false positives:

Browse the rules directly: engine/semgrep/rules/, engine/coccinelle/rules/, engine/codeql/queries/. These complement the Semgrep registry packs RAPTOR pulls in (p/security-audit, p/owasp-top-ten, p/secrets always; per-policy-group packs like p/command-injection, p/jwt, p/xss on top) — o is minimal.

---

How RAPTOR checks itself

RAPTOR dogfoods a fair bit of its own security tooling, but it is worth being honest about what actually blocks a PR and what just runs in the background to keep us honest. Some of this is a hard gate, some of it is a scheduled check, and some of it is just a benchmark we keep around so we can tell when we have made things worse. The fuller breakdown, including the actual parameters and how to reproduce the checks, is in docs/ci-controls.md.

| Control | What it checks | Trigger | Config / e |
|---|---|---|---|
| Ruff | Python correctness linting (F401, F811, F821, F841) | PR diff gate, plus weekly full-tree audit | pyproject.toml, .github/workflows/lint.yml |
| Pytest | Fast unit/integration boundaries, subsystem-specific tiers ( dispatch), prompt-en audit | PRs, pushes to main, merge queue, scheduled full suite | pytest.ini, .github/workflows/tests.yml, .github/workflows/nightly.yml |
| CodeQL Ad | Python, C/C++, and GitHub Actions 代码 scanning with import-graph scope narrowing | PRs, pushes to main, merge queue, weekly schedule | .github/workflows/codeql.yml, .github/codeql/codeql-config.yml |
| Workflow hardening | SHA-pinned third-party Actions, least-pri permissions, command metadata linting | Every workflow change and every lint run | .github/workflows/, .github/scripts/check_command_metadata.py |
| Corpus label lint | Audit corpus label schema and upstream pin | PRs (changed labels), weekly full sweep | .github/workflows/corpus-labels.yml |
| RAPTOR SCA PR gate | Dependency and supply-chain regressions introduced by a PR | Manifest / lockfile / workflow changes | .github/workflows/sca-pr-gate.yml |
| RAPTOR SCA self-bump | Mechanical dependency hardening and safe upgrade proposals | Weekly schedule, manual run | .github/workflows/sca-self-bump.yml |
| SCA compromise corpus | Whether known dependency compromises still trigger the expected signal | Weekly schedule, relevant PR changes | test/data/sca-e2e/compromise-corpus/, .github/workflows/sca-compromise-check.yml |
| Repo-in detectors | Dead-代码 / wrong-call detection, env- drift, guardrails, canonical-JSON byte forms, optional-dep import lint | PR gate (lint.yml repo-in job), plus daily sweep | .github/workflows/lint.yml, .github/workflows/miswiring-scan.yml, .github/scripts/*_baseline.json |
| SCA calibration + stress corpus | Whether risk scoring and parser co drift over time | Weekly / monthly scheduled jobs | packages/sca/data/calibration/, .github/workflows/refresh-sca-calibration.yml, .github/workflows/sca-stress-sweep.yml |
| Dataflow corpus | Precision / recall / FP-category tracking for behaviour | De benchmark and corpus tests | core/dataflow/corpus/, core/dataflow/scripts/corpus-metrics |
| CI controls doc guard | Documented paths exist, ruff config matches, README links to the doc | PRs | .github/tests/test_ci_controls_docs.py |

Not currently enforced: mypy is pinned in pyproject.toml but does not block anything; Ruff formatting is not enforced; Semgrep is part of RAPTOR's scanner surface, but we do not yet have a dedicated "scan RAPTOR with RAPTOR" Semgrep workflow.

---

Using a different LLM

RAPTOR has two separate model layers, and it is worth knowing how both work before you change anything.

The orchestration layer is Claude 代码 -- but only for the interactive raptor shell (this con, slash-command layer). The CLAUDE.md, skills, and commands all run as Claude 代码 instructions there. To change which Claude model orchestrates that layer, use Claude 代码's --model flag or the /model command inside a session. If you don't want this layer at all, see Running fully standalone below.

The analysis dispatch layer is the LLM that analyses indi findings. This is separate from the orchestration layer and can be any supported provider. Configure it in ~/.config/raptor/models.json:

Or skip the config file and set en . RAPTOR will detect them automatically:

Model roles let you assign different models to different tasks:

| Role | What it does |
|------|-------------|
| analysis | and analyses each finding (Stages A-F) |
| code | Writes exploit PoCs and patch code |
| consensus | Second-opinion vote on true positives |
| aggregate | Optional. LLM-written narrati on top of the deterministic multi-model correlation, written to aggregation.json and the final agentic-report.md |
| fallback | Used if the primary model fails or hits rate limits |

If no roles are set, the first model in the list handles e. For multi-model
源码-代码 analysis, configure two or more analysis models — you'll get the
deterministic correlation by default. The aggregate role is optional and adds an
LLM-written summary on top:

Budget control:

Ollama works well for analysis; reliability for exploit/patch 代码 generation tracks model scale and quantization rather than being a fixed property of local models — see Quality Tradeoffs in the LLM guide, and check /scorecard for what your specific model is actually measuring.

Running fully standalone (no Claude 代码)

bin/raptor -- the interacti with the banner and slash commands, i.e. this con layer -- execs straight into the Claude 代码 CLI and always needs its own login. The actual mechanics underneath it don't: python3 raptor.py <mode> is a plain Python CLI with no Claude 代码 dependency at all.

libexec/raptor-* scripts (including raptor-project-manager -- raptor.py has no project mode, project management li exclusively) are also plain Python, but they refuse to run unless CLAUDECODE is set (true automatically inside a Claude 代码 session) or _RAPTOR_TRUSTED=1 is set explicitly -- a guard against being invoked outside the launcher's en sanitisation. Set it once for standalone use:

Point models.json / OLLAMA_HOST at a local Ollama instance (see above) and this whole path ne to Anthropic -- useful for airgapped boxes or local-only hardware. You lose the con slash-command layer (this chat); the scan/analysis/exploit pipeline itself is unaffected.

Fast-tier short-circuit + the model scorecard

When your analysis-tier model has a same-provider cheaper sibling (Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), RAPTOR will use it as a prefilter on consumers that wire into the substrate (codeql today; SCA and others as follow-ups land). The cheap model only e on confident false positives; ambiguous cases and confident-TPs always run the full analysis. Trust accumulates per (model, decision_class) cell — RAPTOR records cheap- agreement and only short-circuits once the Wilson 95% upper-bound on the cell's miss-rate falls at or below 5%.

To inspect what your models are good at, use /scorecard (or directly: libexec/raptor-llm-scorecard list). The scorecard is global (lessons carry across projects) and persists at out/llm_scorecard.json.

---

Projects

Without a project, each run gets its own timestamped directory under out/. With a project, e goes into one place and you get merged findings, co tracking, and diffs between runs.

---

Architecture

RAPTOR is two layers.

The Python execution layer (raptor.py, packages/, core/, engine/) handles the hea: running Semgrep and CodeQL, managing subprocesses, parsing SARIF, deduplicating findings, dispatching LLM API calls, tracking costs, writing output files. It does not make decisions. It executes.

The Claude Code decision layer (.claude/, tiers/, CLAUDE.md) makes the calls: which findings to prioritise, how to interpret results, what the attack scenario is, whether the exploit is realistic. Implemented as Claude 代码 skills, commands, and agents that load progressively.

The split means you can run the Python layer from a CI pipeline (python3 raptor.py scan --repo ...) and get structured SARIF output without Claude 代码, or run it interactively with the full agentic workflow.

---

OSS forensics

/oss-forensics in public GitHub repositories using e from multiple sources: the GitHub API, GH Archi event history ), the Wayback Machine, and local git history. It runs a structured pipeline from e collection through hypothesis formation to a final forensic report.

Requires GOOGLE_APPLICATION_CREDENTIALS for BigQuery access. See .claude/commands/oss-forensics.md for details.

---

Expert personas

Eight expert personas are a on demand. Load one when you want a different perspective on a finding or a specific technique:

Tell Claude which one to use, e.g. "Use the Binary Exploitation Specialist".

---

Documentation

See docs/README.md for the full index. Key guides:

| File | Contents |
|------|----------|
| docs/commands.md | Complete slash-command reference with every flag |
| docs/architecture.md | Codebase structure and directory tree |
| docs/llm.md | LLM provider configuration, Bedrock, multi-model workflows |
| docs/sandbox.md | Process isolation: profiles, Landlock, namespaces |
| docs/troubleshooting.md | Self-test, sandbox setup errors (mount-ns/uidmap on Ubuntu 24.04+), EDR interaction |
| docs/agent-security.md | Agent capabilities, 工具 boundaries, 网络 controls, human approval |
| docs/audit.md | Systematic 代码 review: hypotheses, tools, strategies, gates |
| docs/.md | Exploitability pipeline (stages 0--1) |
| docs/static-analysis.md | Semgrep and Coccinelle rules |
| docs/codeql.md | CodeQL integration and autonomous analysis |
| docs/binary-analysis.md | Binary oracle, /binary, exploit feasibility |
| docs/fuzzing.md | AFL++ and libFuzzer |
| docs/crash-analysis.md | Autonomous crash root-cause analysis |
| docs/sca.md | Software composition analysis |
| docs/frida.md | Dynamic instrumentation |
| docs/security.md | RAPTOR's own security model |
| docs/ci-controls.md | CI controls, workflows, and benchmark e |
| docs/threat-model.md | Per-project threat model feature |
| docs/python-cli.md | Python CLI reference for scripting and CI |
| docs/concepts.md | Core concepts: two-layer model, finding lifecycle, choosing a command |
| docs/agentic.md | Autonomous workflow: /agentic pipeline, enrichment flags, multi-model |
| docs/sage.md | SAGE persistent memory: setup, HMAC key, CPU/GPU, use cases |
| docs/dependencies.md | External tools, , and licences |
| tiers/personas/README.md | Expert persona reference |

---

Contributing

RAPTOR is open 源码. Good places to start if you want to contribute:

Releases are tagged as vX.Y.Z and built automatically by CI. Commit prefixes determine what goes in the changelog: feat: for new features, fix: for bug fixes, security: for security changes, docs: for documentation. Anything without a prefix lands in "Other changes". No strict con required, but it helps.

Submit pull requests. Chat with us on the #raptor channel in the Prompt||GTFO Slack:

---

Licence

MIT -- Copyright (c) 2025-2026 Gadi Evron, Daniel Cuthbert, Thomas Dullien (Hal), Michael Bargury, John Cartwright.

See LICENSE for the full text. Review the licences for all dependencies before commercial use -- CodeQL in particular does not permit it.

Issues:

---

Python Dependencies

RAPTOR uses pyproject.toml and uv.lock as the source of truth for
Python dependencies. The checked-in requirements.txt remains as a
compatibility export for users who prefer pip install.

Useful installs:

Keeping /web, Z3, SAGE and cloud provider SDKs as optional extras avoids
making the default RAPTOR install heavier and more brittle than it needs to be.

项目信息

开发语言：Python

Star 数：3858

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Raptor turns Claude 代码 into a general-purpose AI offensive/defensive security agent. By using Claude.md and creating rules, sub-agents, and skills, and orchestrating security 工具 usage, we configure the agent for adversarial thinking, and perform research or attack/defense operations.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。