╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ ██████╗ █████╗ ██████╗ ████████╗ ██████╗ ██████╗ ║
║ ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗ ║
║ ██████╔╝███████║██████╔╝ ██║ ██║ ██║██████╔╝ ║
║ ██╔══██╗██╔══██║██╔═══╝ ██║ ██║ ██║██╔══██╗ ║
║ ██║ ██║██║ ██║██║ ██║ ╚██████╔╝██║ ██║ ║
║ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ║
║ ║
║ 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.....⠀⠀⠀⠀⠀
Authors: Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury, John Cartwright
(@gadievron, @danielcuthbert, @thomasdullien, @mbrg, @grokjc)
Licence: MIT, see LICENSE. Note that CodeQL has its own licence and does not permit commercial use.
Repository: https://github.com/gadievron/raptor
What is RAPTOR?
RAPTOR is an autonomous security research framework built on top of Claude Code (but not tied to it -- you can plug in your own analysis layer too). It chains together static analysis, binary analysis, LLM-powered vulnerability validation, 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 Recursive Autonomous Penetration Testing and Observation Robot. We really wanted to call it RAPTOR.
How it's built
RAPTOR is mostly AI-generated code. The humans set direction, review
output, and make design decisions; the AI writes the implementation.
Mechanical verification (tests, static analysis, corpus calibration) keeps
the quality bar where it needs to be regardless of who — or what — wrote
the code.
Prerequisites
- Claude Code with an active subscription (Max, Pro, Team, or Enterprise) or an Anthropic API key. This is the orchestration layer -- RAPTOR runs inside a Claude Code session.
- Python 3.10+ and Node.js 18+.
- Semgrep (
pip install semgrep) for static analysis. CodeQL is optional but recommended.
For the analysis dispatch layer (the LLM that analyses individual findings), Claude Code itself handles everything by default -- no extra API keys needed. If you want multi-model analysis (e.g. Claude + GPT + Gemini), you will need API keys for each provider. See Using a different LLM below.
Quick Start
Option 1: Install manually
# 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
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 coverage-tracking plugin, and sanitises the environment before handing off to Claude Code. 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 Code picks up RAPTOR's configuration from the checkout -- but you skip everything the launcher does above: no pre-flight checks, no coverage 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 Code, 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 code that may execute (e.g via supply-chain attack). The image is large (around 6 GB). It starts from the Microsoft Python 3.12 devcontainer and adds static analysis, fuzzing, and browser automation tooling.
You can pull down a pre-built image:
docker pull danielcuthbert/raptor:latest
or build it locally using the included Dockerfile:
docker build -f .devcontainer/Dockerfile -t raptor:latest .
The image expects the RAPTOR framework (this repo) to be mounted into /workspaces/raptor on startup. You can optionally mount a target folder for local analysis.
To start the container:
docker run -it \
-v "$(pwd):/workspaces/raptor" \
raptor:latest
To mount a target folder as well:
docker run -it \
-v "$(pwd):/workspaces/raptor" \
-v "/path/to/target-folder:/workspaces/target" \
raptor:latest
Add --privileged if you need the rr deterministic debugger.
VS Code devcontainers are also supported. To mount a target folder, add it to the mounts section of .devcontainer/devcontainer.json:
"mounts": [
// ...existing entries...
"source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]
Then open the repo in VS Code — it will prompt you to reopen in the container:
cd /path/to/raptor
code .
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:
/scan /path/to/code
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 Code. Takes a few minutes on a typical repository.
To add LLM-powered validation:
/agentic /path/to/code
This runs the full pipeline: scan, deduplicate, then send each finding through the validation 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 Code 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 Code 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 providers.
Security model
RAPTOR runs LLM-generated code and analyses untrusted repositories. Subprocesses that handle untrusted content are sandboxed using Linux namespaces, Landlock, and seccomp. The sandbox blocks network access, restricts filesystem visibility, and limits resource consumption. See docs/sandbox.md for the full threat model and configuration.
Environment variables that could inject code into the launcher chain are stripped at startup (core/security/_dangerous_env_strip.sh). File paths from scanned repositories are never interpolated into shell strings — all subprocess calls use list-based arguments.
What RAPTOR can do
| Command |
What it does |
Status |
/agentic |
Full autonomous workflow: scan, validate, exploit, patch |
Stable |
/scan |
Static analysis with Semgrep and CodeQL |
Stable |
/understand |
Map attack surface, trace data flows, hunt vulnerability variants |
Stable |
/binary |
Black-box binary investigation, runtime evidence, graph queries and handoff |
Beta |
/ghidra |
Ghidra RE bridge: attach/import .gpr projects, cross-version diff, findings export |
Beta |
/audit |
Hypothesis-driven, tool-grounded systematic code review |
Beta |
/review |
Query audit state: findings, gaps, coverage, operator notes |
Stable |
/annotate |
Attach free-form per-function prose annotations (operator review notes) |
Stable |
/validate |
Multi-stage exploitability validation pipeline (Stages 0-F) |
Stable |
/diagram |
Mermaid visual maps from /understand and /validate 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 |
/sca |
Software composition analysis: dependencies, advisories, supply-chain signals, SBOMs, and fixes |
Beta |
/cve-diff |
Discover and diff the fix commit for a CVE across OSV, NVD, GitHub, and GitLab |
Beta |
/cve-env |
Build and verify a Docker environment running a CVE's affected application at its pre-patch version |
Experimental |
/exploit |
Generate proof-of-concept exploit code |
Beta |
/patch |
Generate secure patches for confirmed vulnerabilities |
Beta |
/fuzz |
Binary fuzzing with AFL++ and crash analysis |
Stable |
/crash-analysis |
Autonomous root-cause analysis for C/C++ crashes |
Stable |
/oss-forensics |
Evidence-backed forensic investigation for GitHub repositories |
Stable |
/project |
Named workspaces to organise runs and track findings over time |
Stable |
/describe |
Describe a target: language mix, build system, tool 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 via Frida |
Alpha |
/web |
Web application scanning: crawl, ffuf/nuclei integration, oracle-verified injection, blind SSRF callbacks |
Beta |
How the pipeline works
Start by creating a project so all your runs land in one place:
/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
For a compiled artefact, the equivalent starting point is:
/binary investigate /path/to/binary # build the evidence-backed binary map
/binary graph <run-dir> --edges --json # query the persisted graph
/binary trace-parser <run-dir> # collect runtime parser evidence
/binary harness <run-dir> # draft a harness only when the boundary is explicit
/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 validation using the exploitation-validator 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 version into /understand, autonomous analysis, and /validate. Existing project threat models are preserved unless 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 code evidence or oracle-backed confirmation. See docs/threat-model.md.
- Stage A: is the pattern actually a vulnerability, or is the tool pattern-matching noise?
- Stage B: what does an attacker need to reach it, and what gets in the way?
- Stage C: does the code path actually exist? can it be reached from outside?
- Stage D: final call -- is this test code, does it need unrealistic preconditions, is the model hedging?
- Stage E: binary exploit feasibility (when a compiled artefact is available)
- Stage F: self-review -- did any earlier stage hedge or contradict itself?
Findings that clear validation get exploit PoCs and patches generated. A cross-finding analysis runs at the end to find shared root causes and attack chains.
/validate runs this same pipeline as a standalone step if you already have findings from a previous scan.
For a compiled artefact, /binary <path> now runs an evidence-first
investigation rather than dumping a pile of raw reverse-engineering artefacts
on the operator. Underneath it still builds the SHA-256-bound manifest,
evidence ledger, context map, checklist and SQLite graph from file metadata,
imports and radare2 xrefs. Mach-O apps also get slice inventory, bundle
metadata and Objective-C / Swift class selectors; high-value pseudocode is
persisted rather than disappearing inside the run. PE DLL exports, Windows
driver dispatchers 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 investigation 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 unproven hypotheses. Frida observations, fuzz crash
witnesses, explicit Z3 checks and binary diffs can then add stronger evidence
later. RAPTOR also keeps the internal call graph needed to recover bounded
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 investigation report in place. /binary investigate --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
evidence-backed harness spec for the chosen ingress and only emits candidate
source 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 CVE lookup: 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 OSV advisories, CISA KEV, EPSS, CISA Vulnrichment/SSVC, reachability, exploit-evidence signals, hygiene checks, supply-chain heuristics, licence policy findings, and optional LLM review/triage. It emits RAPTOR-native findings plus SBOM and CI-friendly output:
findings.json - canonical RAPTOR findingsreport.md - human-readable summarysbom.cdx.json - CycloneDX SBOM with VEX datafindings.sarif - GitHub/GitLab code-scanning output
Common commands:
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
Useful subcommands include fix, check, upgrade, diff, verify, 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. Everything 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 devcontainer. 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 network access.
For registry packs (p/security-audit, p/owasp-top-ten, etc.), the cache directory ships empty. A cache tool (`engine/semgrep/too
RAPTOR 把 Claude Code 会话变成一个攻防两用的安全代理：通过 Claude.md 规则、子代理和技能来编排 radare2、Frida、Z3、CodeQL 等工具，用于二进制逆向工程、漏洞利用可行性研究和软件供应链（SCA）分析。