gadievron/raptor

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             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. CodeQL and other third-party components have their own licence terms; see third-party notices and dependencies.

Repository: https://github.com/gadievron/raptor

---

What is RAPTOR?

Built by hackers, for hackers.

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 supports security research and human review; its reports do not certify that a codebase is secure.

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.

Start here: Capabilities · Quick start · First run · Security · Documentation

What RAPTOR can do

• Take a codebase from first look to candidate fixes. Map its attack surface, investigate suspicious code, assess scanner findings, test exploitability, and generate PoCs and patches for review. Start with /agentic; use /understand or standalone /audit when you need a focused investigation.
• Check what your software ships with. Inspect application dependencies, container packages, and workflow components; identify advisory and supply-chain risks, produce an SBOM, and plan fixes or upgrades with /sca.
• Investigate an unfamiliar binary or a crash. Recover entry points and parser boundaries, collect runtime evidence, fuzz a target, and investigate the failure with /binary, /fuzz, and /crash-analysis.
• Test running applications. Explore web endpoints with /web and inspect selected runtime behavior with Frida instrumentation through /frida.
• Investigate an open-source project's history. Correlate GitHub activity, archived events, and local git evidence with /oss-forensics.

Maturity varies by workflow. The complete catalogue lists commands and their status; the workflow index helps you choose a starting point.

Why RAPTOR?

• LLM-assisted false-positive filtering. Semgrep, CodeQL, and other tools produce candidate alerts mechanically. RAPTOR examines the surrounding code and data flows to assess whether each alert describes a real bug.
• An audit engine beyond scanner output. Hypothesis-driven investigation uses analysis tools to examine gaps scanners may miss, tracking evidence and coverage. /agentic uses audit capabilities within its workflow; standalone /audit offers a dedicated systematic review. See the audit engine.
• Eight-stage exploitability validation. /validate investigates whether a candidate vulnerability is reachable by an attacker, whether its preconditions can be met, and what mitigations prevent exploitation. Mechanical feasibility checks and self-review support the assessment; dynamic verification depends on available artefacts and execution permissions. See validation.
• Broad software composition analysis. Dependencies, container packages, workflow components, advisories, reachability, and supply-chain signals come together with SBOMs and fix planning. See SCA.
• Connected source and binary evidence. Runtime traces, fuzz witnesses, and optional SMT checks can strengthen findings from source review. Custom detection rules complement upstream scanners.
• A custom, purpose-built sandboxing layer. RAPTOR isolates generated PoCs, target builds, and research tools with policies matched to each tool and execution phase. See the security model below.
• Research that accumulates. Projects retain findings, coverage, annotations, and cross-run comparisons. Threat models, persistent memory, and specialist personas help each investigation build on earlier work.

Security model

The repository being analysed can attack the analyst: through malicious code, repo-controlled configuration, prompt injection, or content rendered in a report. RAPTOR addresses those surfaces with several boundaries:

• Layered process isolation. The custom sandbox combines Linux namespaces, Landlock, seccomp, and resource limits; macOS uses Seatbelt. Policies constrain filesystem access, network connections, syscalls, process creation, and resource consumption according to the tool, platform, and profile.
• Restricted host access. Untrusted-execution policies keep target inputs read-only, limit writes to granted output/scratch paths, and use a private home instead of exposing the operator's normal home directory.
• Controlled egress. Tool policies block networking or route it through an allowlisted proxy. Networked investigators also have agent-specific URL gates.
• Credential separation. The launcher-managed LLM dispatcher holds provider credentials in the parent process; workers use its socket without receiving API keys. Direct Python CLI use does not provide that same dispatcher boundary.
• Startup and configuration checks. Launcher preflights inspect repository hooks, MCP configuration, and dangerous environment settings. Environment sanitisation and isolated interpreter startup protect the launcher chain.
• Agent capability and consent boundaries. Tool restrictions and attendance/ containment gates constrain agents handling hostile inputs. Agent messages cannot grant operator authority. Untrusted execution refuses when required containment is unavailable; reduced protection requires explicit consent.
• Adversarial input and output handling. Source excerpts are treated as untrusted data, and report sanitisation strips markup that could trigger automatic external fetches.

Prompt injection remains possible. Guarantees differ between untrusted execution, trusted-tool entry points, platforms, and operator-selected profiles; these controls are not a claim that all agent actions are isolated. Containers add a deployment boundary. See sandbox guarantees and limitations, agent security, the threat model, and WSL requirements for the exact contracts and residual risks.

Prerequisites

• Manual checkout: Python 3.12+, uv, and the tools needed by your workflow. Semgrep is needed for default source scans; standalone SCA does not require it.
• Interactive shell: Claude Code with an active subscription or an Anthropic API key. The installation route below also uses Node.js 18+.
• Standalone CLI: Claude Code is optional. LLM-assisted analysis needs a configured provider; mechanical scans can run without an LLM.

See installation and dependencies for platform requirements and optional tools.

Accounts and costs

The shell's Claude Code login is independent of the credentials used for finding analysis, which can use Claude Code, another provider, or a local model.

Subscription-backed Claude Code analysis has no separate API bill; API-backed Claude Code and external providers follow their backend's billing. The source-review examples below each set a $5 main-run ceiling (/agentic defaults to $10). Optional helpers have separate ceilings, so this is not an end-to-end cap across all processes. See model setup and billing for details. Offline operation requires prepared tools/data and appropriate egress controls.

Quick Start

RAPTOR runs from your checkout. The Docker image supplies its tools and dependencies. Use the stable RAPTOR release (v3.1.0) for normal use. Contributors should follow the developer setup.

Run these commands in your terminal to mount the release checkout in the tools container. The image digest pins the tools environment separately from RAPTOR:

git clone --branch v3.1.0 https://github.com/gadievron/raptor.git
cd raptor
docker pull docker.io/danielcuthbert/raptor:latest@sha256:c0c9526481f34dc402d86419767f85b98f5c9996ee667aa47828323a8907c121
docker run -it \
  -v "$PWD:/workspaces/raptor" \
  -v "/path/to/target-folder:/workspaces/target" \
  docker.io/danielcuthbert/raptor:latest@sha256:c0c9526481f34dc402d86419767f85b98f5c9996ee667aa47828323a8907c121

Replace the target path with your own, or omit that mount. For an existing checkout, switch to v3.1.0 first. Inside the container, run raptor.

For setup without Docker, see manual installation. Local builds, VS Code devcontainers and debugger requirements are covered in container installation.

What to expect on a first run

Use slash commands inside a RAPTOR session; run Python commands in your terminal from the checkout with its environment activated.

Source code

/agentic /path/to/code --max-cost-usd 5

Read agentic-report.md and the generated PoCs and patches in the run directory. Patches are not applied to the target. Expect minutes to tens of minutes, depending on the target and model. See workflow and outputs. For a mechanical scan without LLM analysis, use /scan /path/to/code.

Optional: standalone audit

/audit /path/to/code --budget 50 --max-cost 5

For a dedicated systematic review, examine up to 50 functions, with tool evidence and coverage recorded alongside findings. See the audit output-file reference for the files written by a run.

Dependencies without an LLM or Claude Code

python3 raptor.py sca --repo /path/to/project --no-llm

The SCA scan writes findings, a report, an SBOM, and SARIF.

Binary investigation

/binary investigate /path/to/binary

The default investigation maps the artefact and ranks leads without executing or fuzzing it. See binary analysis for outputs and the explicit steps that add runtime evidence.

What a finding tells you

Corpus illustration: a condensed walkthrough of a labelled WebGoat regression case:

Candidate: SQL injection in SqlInjectionLesson13.java
Evidence:  The request value is bound with PreparedStatement.setString
           before the prepared query is executed.
Verdict:   False positive for SQL injection on this path (corpus label).
Limit:     This does not establish that other paths or the application are safe.

Compare the candidate and code evidence with the label and rationale.

How RAPTOR checks itself

RAPTOR dogfoods a fair bit of its own security tooling. Some controls block PRs, some run on a schedule, and others measure whether results are drifting:

• PR and merge checks: Ruff, subsystem tests, prompt-envelope audits, workflow hardening, corpus-label lint, repository invariants, documentation guards, and the SCA dependency-regression gate.
• Code scanning: CodeQL analyses Python, C/C++, and GitHub Actions on PRs, pushes, the merge queue, and a weekly schedule.
• Scheduled assurance: full-tree lint and test sweeps, corpus-pin checks, dependency self-bumps, and known-compromise checks provide recurring coverage.
• Quality measurement: dataflow benchmarks and SCA calibration/stress corpora track precision, recall, false positives, and drift.

CI controls documents the exact triggers, evidence, limitations, and reproduction commands.

Documentation

Next step	Guide
Install or configure tools	Installation
Choose a workflow or look up a command	Guides and command catalogue
Diagnose a failed or stalled run	Troubleshooting
Understand isolation and trust boundaries	Security and sandbox
Contribute to RAPTOR	Contributing and developer guide

Contributing

RAPTOR is open source; contributions are welcome. See contributor guidance for opportunities and development conventions.

Submit pull requests. Chat with us on the #raptor channel in the Prompt||GTFO Slack: https://join.slack.com/t/promptgtfo/shared_invite/zt-3v2b4sll3-SfyzFRw2lykx_XQX7F3uNQ

Licence

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

See LICENSE for the full text. Third-party components retain their own terms; see third-party notices, dependencies, and the CodeQL licence terms.

Issues: https://github.com/gadievron/raptor/issues