RAPTOR

What It Does

RAPTOR (Recursive Autonomous Penetration Testing and Observation Robot) is an autonomous offensive and defensive security research framework built on top of Claude Code. It chains static analysis (Semgrep, CodeQL), binary analysis (AFL++, frida), LLM-powered vulnerability validation, exploit generation, and patch writing into a single workflow you run against a codebase or binary. You drive it through 30 Claude Code slash commands (/scan, /understand, /validate, /exploit, /patch, /fuzz, /sca, /agentic) and 16 specialist subagents, backed by a 638,295-line Python engine and 52 executable wrapper scripts under libexec/. The target users are security researchers, AppSec teams, vulnerability researchers, and consultants who want Claude Code to run a disciplined find-then-prove-then-patch pipeline instead of ad hoc prompting. The authors are named, working security practitioners rather than an anonymous account, which matters for a tool that generates exploits.

The Good

The authorship and engineering rigor are exceptional for an agent skill. The five credited authors are Gadi Evron (founder of Security BSides and the RSA Conference cybersecurity track), Thomas Dullien publishing as Halvar Flake (founder of zynamics and a foundational figure in binary analysis), Daniel Cuthbert, Michael Bargury, and John Cartwright. The repo carries 638,295 lines of Python across 26 packages, 988 test files, and 18,678 collected tests (277 deselected as integration or slow). In two sampled runs, packages/cve_diff passed 675 of 675 in 13 seconds and packages/cvss packages/osv packages/exploit_feasibility passed 763 of 769 in 15 seconds. This is not a prompt wrapped in a README. It is a tested codebase.

The SCA works against real data today, without Claude Code or an API key. Running raptor.py sca check PyPI django 4.2.10 spun up an egress proxy bound to a 23-host allowlist (api.osv.dev, services.nvd.nist.gov, www.cisa.gov, pypi.org, and friends), queried the live advisory sources, and returned a structured markdown report: a "Block" verdict with 9 CVEs, each carrying a CVSS vector, an EPSS score, and a fixed-in version. The dependency check also emits CycloneDX SBOMs with VEX data and SARIF for GitHub code scanning. For a team that wants a supply-chain gate, the SCA module alone earns its keep before you ever launch Claude Code.

The framework takes its own security seriously, and documents it. The docs/security/ directory ships a genuine adversarial repository threat model (adversarial-repo-threat-model.md) built around the premise that "the thing being analysed is also trying to attack the analyst." It enumerates attack scenarios (the honeypot repo with prompt-injection payloads buried in comments, the trojan .claude/settings.json) and maps them to defenses: a per-call nonce envelope that defeats tag-forgery injection, a preflight regex corpus for natural-language injection, and scoped permissions in .claude/settings.json that allow only specific libexec/raptor-* scripts. The binary analysis path runs under a Linux Landlock or macOS seatbelt sandbox, and when the sandbox cannot apply its profile it fails loud with an explicit error and the instruction "RAPTOR will not silently downgrade for you." That fail-loud behavior is exactly the right default for a tool that writes exploit PoCs.

The CI pipeline scans its own supply chain, which is the strongest possible signal for a security tool. The 17 GitHub workflows include codeql.yml (RAPTOR runs CodeQL on itself), sca-pr-gate.yml and sca-compromise-check.yml (it gates PRs on its own dependency advisories), sca-self-bump.yml (it keeps its own pinned dependencies current), typosquat-reaudit.yml, and tests.yml. A check_command_metadata.py CI script enforces that every slash command has a parseable dispatch: field whose target exists on disk, so documentation drift between commands and the scripts they invoke gets caught at PR time. The requirements.txt pins exact versions under a stated "no loose deps" policy and cites CVE-2025-69872 (the diskcache vulnerability) as the reason an instructor version was bumped.

The validation methodology is a real discipline, not a prompt suggestion. The /validate command (206 lines) defines a nine-stage pipeline (Stages 0, A, B, C, D, E, F, 1) where Claude is the reasoning engine and Python prep scripts handle the mechanical merge and schema work. Each stage writes a small stage-X.json that a prep script merges into a cumulative findings.json, and Claude never touches the findings file directly. Eight MUST-GATEs are enforced (ASSUME-EXPLOIT, STRICT-SEQUENCE, NO-HEDGING, PROOF, POC-EVIDENCE, and others). The package also includes concept-novel capabilities that are rare even in commercial tooling: packages/zkpox assembles zero-knowledge proof-of-exploit disclosure bundles, and a Z3 SMT integration does constraint-based path feasibility before any LLM call.

The Bad

The CLI crashes on stock macOS Python and the requirements do not say so. raptor.py uses PEP 604 union syntax (str | None) throughout, which requires Python 3.10 or newer. On macOS 26.5 the system python3 is 3.9.6, and the very first call fails with TypeError: unsupported operand type(s) for |: 'type' and 'NoneType' at line 60. The requirements.txt comments reference tomli for "Python <3.11" and tomllib for "3.11+", which implies a 3.11 expectation, but there is no python_requires pin in a pyproject.toml and no engine banner. A first-time user who runs pip install -r requirements.txt && python3 raptor.py doctor on an unmodified Mac gets a traceback before the tool ever prints help. The fix is one line (brew install python@3.12 or uv venv --python 3.12), but it should be stated up front.

The full capability set is heavy and the recommended environment is a 6GB privileged container. CodeQL, Semgrep, AFL++, frida, gdb, rr, and coccinelle are all optional but load-bearing for different commands. The devcontainer image is described as roughly 6GB and requires docker run --privileged for the rr deterministic debugger. The doctor command mitigates this honestly (it reported 0 failures, 9 warnings, 7 passed on my host and listed exactly which commands were unavailable and why), but assembling the complete toolchain outside Docker is real work, and several headline features (binary fuzzing, crash root-cause analysis, dynamic instrumentation) are effectively Linux-only because rr and the Landlock sandbox have no macOS equivalent.

GitHub reports the license as "NOASSERTION," which can trip corporate approval. The LICENSE file is plain MIT, but the README notes that CodeQL "has its own licence and does not permit commercial use," and GitHub's license detector consequently returns spdx_id: NOASSERTION for the repo. Automated license scanners and corporate procurement pipelines will flag this for manual review even though the framework's own code is MIT. For a tool adoption-minded teams will want to run in CI, that is a friction point worth knowing about before you commit to it.

The headline agent workflow is tightly coupled to Claude Code. The 30 slash commands, the 16 subagents, the dispatch: frontmatter convention, and the 422-line CLAUDE.md operational file all assume Claude Code as the host. The Python CLI (doctor, sca, and the engine under packages/) is agent-agnostic and runs standalone, but the scan-to-validate-to-exploit pipeline that is the actual product only fires inside Claude Code with an LLM in the loop. Users of Hermes, Cursor, or a plain terminal get the SCA and the engine but not the orchestration. The README does say it is "not tied to" Claude Code and that you can "plug in your own analysis layer," but there is no documented alternate harness today.

Version reporting is inconsistent. The raptor.py version command prints a git short hash (db6f967), while CITATION.cff declares version: "3.0.0" with a release date of 2026-05-22. There are no git tags in the clone. For a framework that emits SARIF and SBOM artifacts meant to be consumed by downstream tooling, a semver on the CLI would be more useful than a commit hash.

Smoke Test Results

Tested on a macOS host (aarch64) with a clean Python 3.12 venv created via uv. The repo was shallow-cloned to /tmp/raptor-review and core requirements installed with uv pip install. Full evidence is in the functional log.

Run A. Fresh host, core requirements only

$ uv venv /tmp/raptor-venv --python 3.12 && uv pip install -r requirements.txt
Resolved + installed 16 packages (requests, pydantic, typer, instructor, packaging, defusedxml, ...)

$ python3 raptor.py --help # macOS system python 3.9.6
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType' FAIL (needs 3.10+)

$ /tmp/raptor-venv/bin/python raptor.py doctor
RAPTOR doctor ... version: db6f967
WARNINGS: codeql/semgrep/afl++/frida/gdb/rr/jadx/bigquery not found (9 warnings)
Summary: 0 failure(s), 9 warning(s), 7 passed. PASS

$ /tmp/raptor-venv/bin/python raptor.py version
db6f967 PASS (but prints hash, not 3.0.0)

Pass rate: 3 of 4. The one failure is the Python version mismatch on stock macOS, which is environmental and fixed by using 3.12.

Run B. Functional verification (does it do what it claims?)

$ raptor.py sca check PyPI django 4.2.10
[INFO] egress proxy listening on 127.0.0.1:58318 (allowlist: 23 hosts)
# raptor-sca check: pkg:pypi/django@4.2.10
**Verdict:** Block
- [Critical / CVSS 9.1 / EPSS 0.19] CVE-2025-64459 SQL injection. Fix 4.2.26
- [Critical / CVSS 9.8] CVE-2024-53908 SQL injection Oracle. Fix 4.2.17
... 9 advisories total with CVSS, EPSS, and fixed-in versions PASS

$ python -m pytest packages/cve_diff -q
675 passed, 7 deselected in 13.00s PASS

$ python -m pytest packages/cvss packages/osv packages/exploit_feasibility -q
6 failed, 763 passed, 1 skipped in 15.24s
 (all 6 failures: SandboxSetupError: macOS seatbelt profile did not apply;
 RAPTOR refuses to silently downgrade. Environmental, not a code defect.) PASS

$ python -m pytest --collect-only -q
18678/18955 tests collected (277 deselected) in 18.99s PASS

Functional pass rate: 4 of 4. The SCA produces correct, real-world output. The two test samples pass at 99.2% and 99.2% respectively, with every failure traceable to a missing binary-analysis toolchain or the deliberate fail-loud sandbox policy rather than a logic error.

What the runs tell you

The Python engine and the SCA are production-grade and verifiable on any host with Python 3.10 or newer. The agent-side pipeline (the actual /agentic to /validate to /exploit flow) is the product's reason for existing, but it cannot be exercised without a live Claude Code session, an LLM, and the external scanners, so it stays at a "partial" functional rating by honest necessity. The fail-loud sandbox behavior is a feature: the framework would rather error than run binary analysis without isolation, which is the correct posture for a tool that generates exploits.

Setup Walkthrough

1. Install Python 3.10 or newer. On macOS, brew install python@3.12 or use uv venv --python 3.12. Stock python3 (3.9.6) will fail on the first import.
2. Clone and install the core dependencies: git clone https://github.com/gadievron/raptor.git && cd raptor && uv pip install -r requirements.txt. This is enough to run raptor.py doctor and raptor.py sca.
3. Run python raptor.py doctor immediately. It prints exactly which capabilities are available and which external tools are missing, with install hints. Treat its output as your setup checklist.
4. For the full agent workflow, install Claude Code (npm install -g @anthropic-ai/claude-code) and at least one scanner (pip install semgrep; CodeQL from the GitHub CLI binaries releases). Then launch claude from the repo root so it picks up CLAUDE.md, the slash commands, and the subagents.
5. For binary analysis, fuzzing, and crash root-cause work, use the devcontainer. Pull danielcuthbert/raptor:latest and run with --privileged (required for rr). Building it locally takes time and the image is large.

Post-install gotcha: the libexec/ wrapper scripts refuse to run unless one of CLAUDECODE, _RAPTOR_TRUSTED, or RAPTOR_DIR is set in the environment, and several modules read RAPTOR_DIR at import time and raise KeyError if it is unset. The conftest.py sets both for the test suite. If you invoke engine modules directly outside Claude Code, export RAPTOR_DIR to the repo root first.

Alternatives

1. 0xSteph/pentest-ai (ptai) - an offensive-security MCP server with a similar "no proof, no finding" philosophy, but delivered as a pip-installable MCP server with an oracle-verification gate rather than a Claude Code slash-command framework. Prefer ptai if you want a protocol-level tool that works across MCP clients; prefer RAPTOR if you live in Claude Code and want the deeper static and binary analysis surface.
2. NVIDIA/SkillSpector - a static security scanner for agent skills (SKILL.md, plugin manifests, MCP configs). It is a supply-chain scanner for the skill format itself, not a vulnerability research framework. Use it to vet the skills you install; use RAPTOR to vet the code those skills help you write.
3. Semgrep + CodeQL directly - the two engines RAPTOR orchestrates. Running them by hand gives you the raw findings without the LLM-driven validation, dedup, exploit, and patch stages. RAPTOR's value is the pipeline that sits on top of them, not a replacement for either scanner.