Raptor: The Autonomous Security Agent Top Hackers Are Using

What if your security tools could think like an attacker, not just scan like a robot?

Every security team faces the same brutal reality: you're drowning in alerts, your static analysis tools are screaming about vulnerabilities that don't exist, and your best engineers are spending 80% of their time on false positives instead of actual threats. The gap between "we ran a scanner" and "we understand our real attack surface" has never been wider. Manual penetration testing is expensive, slow, and can't keep pace with modern CI/CD pipelines. Meanwhile, AI-powered coding assistants are transforming how developers write code—so why are security teams still stuck with tools from 2010?

Enter Raptor, the open-source autonomous security framework that's making seasoned security researchers abandon their old workflows. Built by an all-star team including Gadi Evron, Daniel Cuthbert, and Thomas Dullien (Halvar Flake), Raptor doesn't just find bugs—it validates them, exploits them, and patches them. All autonomously. All chained together into a single, terrifyingly effective pipeline. This isn't another scanner. This is what happens when you give Claude Code an adversarial brain and point it at your codebase.

What is Raptor?

Raptor (Recursive Autonomous Penetration Testing and Observation Robot) is an autonomous security research framework built on top of Claude Code—though critically, it's not chained to it. You can plug in your own analysis layer if you prefer. The project was born from the collaboration of five heavyweights in security research: Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury, and John Cartwright.

What makes Raptor genuinely different from the sea of "AI security" tools flooding GitHub? It chains together static analysis, binary analysis, LLM-powered vulnerability validation, exploit generation, and patch writing into a single cohesive workflow. Most tools stop at finding potential issues. Raptor asks: "Is this real? Can I exploit it? What's the patch?"—and answers all three without human intervention.

The authors are refreshingly honest about its maturity: "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." That raw, working energy is exactly what makes it dangerous in the right hands. Version 3.0.0 represents a significant evolution from earlier experiments, with stable commands across the core workflow and a clear architecture separating decision-making from execution.

Raptor is trending now because it solves a problem that $50,000 enterprise tools can't touch: the validation gap. Every security professional knows the pain of Semgrep or CodeQL flooding you with theoretical vulnerabilities. Raptor's multi-stage validation pipeline (Stages A through D, plus the hexadecimal progression for deeper analysis) filters noise before it wastes engineering time. The integration of Z3 SMT solving for path feasibility checking means it can mathematically prove whether a vulnerability is reachable—something no pure-LLM approach can claim.

Key Features That Make Raptor Insane

Full Autonomous Workflow (/agentic): The crown jewel. Raptor can scan your codebase, validate findings through multiple adversarial stages, generate proof-of-concept exploits, and write secure patches—all in one command. The deterministic multi-model correlation means you can run multiple analysis models and get consensus, dramatically reducing hallucinated vulnerabilities.

Intelligent Static Analysis: Combines Semgrep with an offline registry cache (no network calls during scans) and CodeQL with Z3-backed dataflow pre-screening. Before any LLM analyzes a CodeQL path, Z3 checks if the path constraints are actually satisfiable. Unreachable paths get dropped immediately. Reachable paths get concrete candidate inputs fed into the LLM prompt.

Binary Exploitation Pipeline: The /fuzz command runs AFL++ with automated crash analysis. The /crash-analysis command performs autonomous root-cause analysis for C/C++ crashes. For exploit feasibility, Z3 checks whether one-gadget constraints are satisfiable against concrete crash states—ranking gadgets by actual reachability, not heuristics.

Multi-Model Architecture with Budget Control: Configure different models for different roles—cheap models for prefiltering, frontier models for exploit generation, consensus models for second opinions. The fast-tier short-circuit uses Wilson score confidence intervals to safely skip full analysis when cheap models are proven reliable. Set RAPTOR_MAX_COST to cap spending per run.

Project-Based Organization: Named workspaces with merged findings, coverage tracking, run diffs, and persistent history. No more timestamped directories scattered across your filesystem.

OSS Forensics: Evidence-backed investigation of public GitHub repositories using GH Archive BigQuery data, Wayback Machine archives, and local git history. Requires Google Cloud credentials but produces court-admissible forensic timelines.

Nine Expert Personas: On-demand loading of specialized perspectives—from Mark Dowd's binary exploitation expertise to Charlie Miller's reverse engineering mindset. These aren't toy prompts; they're structured adversarial thinking frameworks.

Air-Gapped Operation: Semgrep runs fully offline with cached rule packs. CodeQL needs network only for initial setup. The devcontainer includes everything pre-installed for isolated environments.

Real-World Use Cases Where Raptor Dominates

1. Enterprise Codebase Security Assessment Imagine you're onboarding a critical acquisition's codebase. Traditional approach: run Semgrep, get 2,000 findings, spend three weeks manually triaging. With Raptor, you create a project, run /understand --map to build attack surface context, then /agentic to autonomously validate, exploit, and patch. The multi-model correlation filters out noise before human review. Your team focuses on confirmed, exploitable vulnerabilities with PoCs already written.

2. Binary Vulnerability Research You're analyzing a closed-source network daemon for memory corruption. Raptor's /fuzz spins up AFL++ with intelligent corpus design. When crashes arrive, /crash-analysis autonomously traces root cause. For promising crashes, Z3 evaluates one-gadget feasibility against the concrete register and memory state—telling you which exploitation paths are mathematically possible before you touch a debugger.

3. Supply Chain Security Investigation A dependency in your project had a suspicious commit pattern. /oss-forensics queries GH Archive via BigQuery for immutable event history, cross-references Wayback Machine snapshots, and builds an evidence-backed timeline of developer behavior. This isn't OSINT guesswork—it's structured forensic investigation with reproducible evidence chains.

4. Continuous Security in CI/CD The Python^{↗ Bright Coding Blog} execution layer runs independently of Claude Code. In your pipeline: python3 raptor.py scan --repo . produces structured SARIF output. Flagged findings feed into /validate for autonomous triage. True positives auto-generate tickets with exploit PoCs and patch suggestions. Security shifts left without becoming a bottleneck.

5. Adversarial Red Team Automation Configure Raptor with the Penetration Tester persona, point it at a target codebase, and let it map trust boundaries, trace data flows, and identify attack chains across multiple findings. The cross-finding analysis at the end of /agentic finds shared root causes—vulnerabilities that compound into critical exploits when combined.

Step-by-Step Installation & Setup Guide

Option 1: Manual Installation

# Clone the repository
git clone https://github.com/gadievron/raptor.git
cd raptor

# Install Python dependencies
pip install -r requirements.txt

# Install Claude Code (required for orchestration layer)
npm install -g @anthropic-ai/claude-code

# Install Semgrep (required for static analysis)
pip install semgrep

# Optional: Install Z3 for enhanced path feasibility checking
pip install z3-solver

# Launch interactive session
claude

Option 2: Devcontainer (Recommended)

The devcontainer includes all dependencies pre-configured, including the rr deterministic debugger which requires --privileged container access:

# Build the container (approximately 6 GB image)
docker↗ Bright Coding Blog build -f .devcontainer/Dockerfile -t raptor:latest .

# Run with privileged flag for rr debugger support
docker run --privileged -it raptor:latest

Or open directly in VS Code: Dev Containers: Open Folder in Container.

Multi-Model Configuration

Create ~/.config/raptor/models.json for analysis dispatch:

{
  "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"
    }
  ]
}

Or use environment variables for quick setup:

export ANTHROPIC_API_KEY=sk-ant-...    # Primary analysis
export OPENAI_API_KEY=sk-...           # Secondary analysis for correlation
export RAPTOR_MAX_COST=5.00            # Budget cap per run

Project Initialization

# Inside Claude Code session
/project create myapp --target /path/to/code -d "Production API service"
/project use myapp

REAL Code Examples from the Repository

Example 1: Full Autonomous Workflow

The /agentic command is Raptor's most powerful feature. Here's how the pipeline executes:

# First, understand what you're attacking
/understand --map                              # Build attack surface context

# Then unleash the full autonomous pipeline
/agentic                                       # Scan → Validate → Exploit → Patch

# Review consolidated results
/project findings                              # All confirmed vulnerabilities
/project findings --detailed                   # Full technical details

The /understand --map command is critical—it builds a context map of entry points, trust boundaries, and sinks before any scanning happens. Without this, /agentic would be flying blind. The mapping identifies where untrusted data enters, where sensitive operations occur, and the paths between them. This context feeds into smarter scan targeting and better validation.

When /agentic runs, it executes: Semgrep and CodeQL scanning → finding deduplication → multi-stage validation (Stages A-D) → exploit PoC generation for confirmed issues → patch generation → cross-finding analysis for attack chains. The entire workflow persists into your project for later review.

Example 2: Multi-Model Analysis with Deterministic Correlation

Raptor's multi-model support isn't just "try another API"—it's structured consensus with statistical rigor:

# Command-line multi-model execution
python3 raptor.py agentic --repo /code \
  --model claude-opus-4-6 \
  --model gpt-5.4 \
  --aggregate claude-sonnet-4-6

This runs two independent analysis models on every finding. The deterministic correlation engine compares their verdicts—only findings where models agree (or where disagreement triggers mandatory human review) proceed. The --aggregate model generates the final narrative synthesis written to agentic-report.md.

The fast-tier short-circuit optimizes this further. When your analysis model has a cheaper sibling (Opus → Haiku, GPT-5.4 → 4o-mini), Raptor uses the cheap model as a prefilter. But it doesn't blindly trust it—the system tracks agreement rates per (model, decision_class) using Wilson 95% confidence intervals. Only when the upper-bound miss-rate falls below 5% does short-circuiting activate. You can inspect accumulated trust with /scorecard:

/scorecard                    # Interactive review
libexec/raptor-llm-scorecard list   # Direct CLI access

The scorecard persists globally at out/llm_scorecard.json—lessons learned in one project improve efficiency across all future runs.

Example 3: Project-Based Workflow with Differential Analysis

Raptor's project system transforms scattered runs into organized security campaigns:

# Create and configure project
/project create myapp --target /path/to/code -d "Short description"
/project use myapp

# Execute security workflow
/scan
/understand --map
/validate

# Analyze evolution over time
/project status                # All runs with pass/fail status
/project diff myapp run1 run2  # Compare two specific runs
/project coverage --detailed   # Which files were actually reviewed
/project clean --keep 3        # Retention management
/project export myapp /tmp/myapp.zip   # Portable archive

The /project diff command is particularly powerful for regression testing. After patching vulnerabilities, run a new scan and diff against the baseline—any new findings or unresolved issues surface immediately. The coverage tracking ensures you're not getting false confidence from scans that never touched critical code paths.

Example 4: Z3-Enhanced CodeQL Analysis

Raptor's Z3 integration demonstrates sophisticated symbolic execution without requiring manual constraint writing:

# Z3 is pre-installed in devcontainer
# For manual installs:
pip install z3-solver

# CodeQL with automatic Z3 pre-screening
/codeql

When CodeQL produces a path result, this happens automatically:

1. Path constraint extraction: CodeQL's dataflow path is converted to SMT-LIB constraints
2. Satisfiability check: Z3 attempts to find satisfying inputs
3. Unreachable path elimination: If unsat, the path is dropped—no LLM call wasted
4. Concrete input generation: If sat, Z3 produces example inputs that traverse the path
5. Enhanced LLM prompting: The concrete inputs feed into the analysis prompt, giving the model specific values to reason about rather than abstract patterns

For binary exploitation, the same Z3 integration evaluates one-gadget feasibility:

# After crash analysis identifies potential gadgets
# Z3 automatically checks: given the concrete register/memory state at crash,
# which gadget's constraints are satisfiable?

Gadgets are ranked by actual reachability, not heuristic proximity. This eliminates hours of manual debugging gadgets that could never work.

Advanced Usage & Best Practices

Layer Your Models Strategically: Don't use one model for everything. Configure a cheap, fast model for analysis prefiltering, a frontier model for code generation (exploits/patches), and a strong model for consensus second opinions. The aggregate role is optional—use it when you need polished reports for stakeholders.

Always Start with /understand --map: Skipping attack surface mapping is like performing surgery without imaging. The context Raptor builds here improves every downstream stage's accuracy. The --map flag specifically traces data flows and identifies trust boundaries.

Leverage Personas for Specialized Analysis: When you're stuck on a complex finding, invoke expert perspective: "Use the Binary Exploitation Specialist" or "Use the CodeQL Dataflow Analyst." These personas load structured adversarial thinking frameworks that can break analysis paralysis.

Monitor Your Scorecard: Regularly run /scorecard to see which model combinations are reliable for which decision classes. As trust accumulates, fast-tier short-circuiting reduces costs without sacrificing accuracy. The Wilson confidence interval approach means this is statistically grounded, not hopeful guessing.

Budget Cap Everything: Set RAPTOR_MAX_COST even for seemingly small runs. Autonomous agents can spiral if they hit edge cases. The cap is a hard stop, not a warning.

Use Projects for Long Campaigns: Single runs get timestamped directories. Projects get merged findings, coverage tracking, and differential analysis. For any engagement longer than a day, create a project.

Offline-First for Sensitive Environments: The Semgrep registry cache ships in-repo. CodeQL needs network only for setup. Configure once, then operate in air-gapped environments with full functionality.

Comparison with Alternatives

Traditional static analysis tools find candidates; Raptor confirms and exploits them. Commercial AI security tools offer similar marketing but lack Raptor's transparency, multi-model architecture, and cost controls. Generic AI assistants have no security-specific orchestration, no tool integration, and no validation pipeline—they'll happily hallucinate vulnerabilities and generate exploitable "patches."

FAQ

Is Raptor production-ready? The authors describe it as "held together with enthusiasm and duct tape," but core commands (/agentic, /scan, /validate, /fuzz, /crash-analysis, /oss-forensics, /project) are stable. Beta commands (/exploit, /patch) work but may need review. It's already more capable than many commercial tools for autonomous validation.

Do I need Claude Code specifically? The orchestration layer requires Claude Code for interactive use, but the Python execution layer runs independently. You can use python3 raptor.py commands in CI/CD without Claude Code. The analysis dispatch layer supports multiple providers: Anthropic, OpenAI, Google Gemini, Mistral, and local Ollama.

How much does it cost to run? Variable based on codebase size and model choices. Set RAPTOR_MAX_COST to cap per-run spending. The fast-tier short-circuit reduces costs as trust accumulates. Ollama is free but unreliable for exploit/patch generation. A typical run with frontier models might cost $2-10; with optimization, under $1.

Can I use Raptor commercially? Raptor itself is MIT licensed. However, CodeQL does not permit commercial use—review its license separately. Semgrep's open-source engine is fine; registry packs in the cache are pre-downloaded. All other dependencies have their own licenses.

What about false positives? Raptor's entire architecture targets this problem. Z3 pre-screening eliminates provably unreachable paths. Multi-model correlation requires agreement. The four-stage validation pipeline (A: pattern verification, B: attack path analysis, C: reachability confirmation, D: final realistic assessment) filters aggressively. The scorecard system continuously improves accuracy.

How does it compare to Copilot Security or similar? Microsoft's offerings are black-box, single-vendor, and cloud-dependent. Raptor is open-source, multi-model, runs offline, and gives you full control over the analysis pipeline. You can inspect every prompt, every tool invocation, and every decision.

Is my code sent to third parties? With local Ollama: never. With cloud models: only during analysis, subject to your provider's terms. The Semgrep rules run entirely offline. CodeQL runs locally after setup. You control all data flows.

Conclusion

Raptor represents a fundamental shift in security tooling: from detection to autonomous validation and remediation. It doesn't replace human expertise—it amplifies it, letting your team focus on confirmed, exploitable vulnerabilities while the agent handles the grinding work of triage, PoC generation, and patch writing.

The architecture is genuinely thoughtful: separation of execution and decision layers, multi-model consensus with statistical rigor, Z3-backed path feasibility, and a project system that turns scattered scans into organized campaigns. The expert personas and OSS forensics capabilities show deep understanding of how security research actually happens.

Is it perfect? No. The authors are honest about its rough edges. But it's working software that solves real problems today—problems that vendors charge six figures to address with less transparency and flexibility.

If you're still manually triaging every Semgrep alert, still writing exploit PoCs from scratch, still patching without automated assistance—you're working too hard. Clone Raptor, fire up the devcontainer, and point /agentic at your most problematic codebase. The results will surprise you. Join the community in the #raptor channel on Prompt||GTFO Slack and contribute to what might become the definitive open-source security agent.

Get Raptor now: https://github.com/gadievron/raptor