╔═══════════════════════════════════════════════════════════════════════════╗ 
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║ 
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║ 
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║ 
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║ 
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║ 
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║ 
║                                                                           ║ 
║             Autonomous Offensive/Defensive Research Framework             ║
║             Based on Claude Code - v1.0-beta                              ║
║                                                                           ║ 
║             By Gadi Evron, Daniel Cuthbert                                ║
║                Thomas Dullien (Halvar Flake)                              ║
║                Michael Bargury                                            ║ 
║                John Cartwright                                            ║ 
║                                                                           ║ 
╚═══════════════════════════════════════════════════════════════════════════╝ 

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀
⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀⠀⠀⠀
                                                 

RAPTOR - Autonomous Offensive/Defensive Security Research Framework, based on Claude Code

Authors: Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury & John Cartwright (@gadievron, @danielcuthbert, @thomasdullien, @mbrg & @grokjc)

License: MIT (see LICENSE file)

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

Dependencies: See DEPENDENCIES.md for external tools and licenses

---

What is RAPTOR?

RAPTOR is an autonomous offensive/defensive security research framework, based on Claude Code. It empowers security research with agentic workflows and automation.

RAPTOR stands for Recursive Autonomous Penetration Testing and Observation Robot. (We really wanted to name it RAPTOR)

RAPTOR autonomously:

1. Scans your code with Semgrep and CodeQL and tries dataflow validation
2. Fuzzes your binaries with American Fuzzy Lop (AFL)
3. Analyses vulnerabilities using advanced LLM reasoning
4. Exploits by generating proof-of-concepts
5. Patches with code to fix vulnerabilities
6. FFmpeg-specific patching for Google's recent disclosure (https://news.ycombinator.com/item?id=45891016)
7. OSS Forensics for evidence-backed GitHub repository investigations
8. Agentic Skills Engine for security research & operations (SecOpsAgentKit)
9. Offensive Security Testing via autonomous specialist agent with SecOpsAgentKit
10. Cost Management with budget enforcement, real-time tracking, and quota detection
11. Reports everything in structured formats

RAPTOR combines traditional security tools with agentic automation and analysis, deeply understands your code, proves exploitability, and proposes patches.

Disclaimer: It's a quick hack, and we can't live without it: We're proud of RAPTOR (and some of our tools are beyond useful), but RAPTOR itself was hacked together in free time, held together by vibe coding and duct tape. Consider it an early release.

What will make RAPTOR truly transformative is community contributions. It's open source, modular, and extensible.

Be warned: Unless you use the devcontainer, RAPTOR will automatically install tools without asking, check dependencies.txt first.

---

What's unique about RAPTOR?

Beyond RAPTOR's potential for autonomous security research and community collaboration, it demonstrates how Claude Code can be adapted for any purpose, with RAPTOR packages.

Recent improvements:

• LiteLLM Integration: Unified LLM interface with Pydantic validation, smart model selection, and cost tracking
• SecOpsAgentKit: Offensive security specialist agent with comprehensive penetration testing capabilities
• Cost Management: Budget enforcement, real-time callbacks, and intelligent quota detection
• Enhanced Reliability: Multiple bug fixes improving robustness across CodeQL, static analysis, and LLM providers

---

OSS Forensics Investigation

RAPTOR now includes comprehensive GitHub forensics capabilities via the /oss-forensics command:

New Capabilities:

• Evidence Collection: Multi-source evidence gathering (GH Archive, GitHub API, Wayback Machine, local git)
• BigQuery Integration: Query immutable GitHub event data via GH Archive
• Deleted Content Recovery: Recover deleted commits, issues, and repository content
• IOC Extraction: Automated extraction of indicators of compromise from vendor reports
• Evidence Verification: Rigorous evidence validation against original sources
• Hypothesis Formation: AI-powered evidence-backed hypothesis generation with iterative refinement
• Forensic Reporting: Detailed reports with timeline, attribution, and IOCs

Architecture: Multi-agent orchestration with specialized investigators for parallel evidence collection and sequential analysis pipeline.

Documentation: See .claude/commands/oss-forensics.md and .claude/skills/oss-forensics/ for complete details.

---

Quick Start

You have two options, install on your own, or deploy the devcontainer.

**Install**
# 1. Install Claude Code
# Download from: https://claude.ai/download

# 2. Clone and open RAPTOR
git clone https://github.com/gadievron/raptor.git
cd raptor
claude

# 3. Let Claude install dependencies, and check licenses for the various tools
"Install dependencies from requirements.txt"
"Install semgrep"
"Set my ANTHROPIC_API_KEY to [your-key]"

**devcontainer**
# 4. Get the devcontainer
A devcontainer with all prerequisites pre-installed is available. Open in VS Code or any of
its forks with command Dev Container: Open Folder in Container, or build with docker:
docker build -f .devcontainer/Dockerfile -t raptor-devcontainer:latest ..

Runs with --privileged flag for rr.

# 5. Notes
The devcontainer is massive (~6GB), starting with Microsoft Python 3.12 massive devcontainer and
adding static analysis, fuzzing and browser automation tools.

# 6. Getting started with RAPTOR
Just say "hi" to get started
Try /analyze on one of our tests in /tests/data

See: docs/CLAUDE_CODE_USAGE.md for complete guide

---

LLM Configuration & Cost Management

RAPTOR uses LiteLLM for unified LLM provider integration with automatic fallback, cost tracking, and budget enforcement.

Key Features:

• Pydantic Validation: YAML configs validated at load time with clear error messages
• Smart Model Selection: Auto-selects best reasoning/thinking model from config
• Real-time Visibility: Callbacks log model usage, tokens, duration for every call
• Budget Enforcement: Prevents exceeding cost limits with detailed error messages
• Quota Detection: Intelligent rate limit detection with provider-specific guidance
• Cost Tracking: Tracks costs across all LLM calls with per-request breakdown

Configuration:

# litellm_config.yaml example
model_list:
  - model_name: claude-opus-4.5
    litellm_params:
      model: anthropic/claude-opus-4.5
      api_key: ${ANTHROPIC_API_KEY}
  - model_name: gpt-5.2-thinking
    litellm_params:
      model: openai/gpt-5.2-thinking
      api_key: ${OPENAI_API_KEY}

Budget Control:

from packages.llm_analysis.llm.config import LLMConfig

config = LLMConfig(
    max_cost_per_scan=1.0  # Prevent exceeding $1 per scan
)

See: docs/litellm-model-configuration-guide.md for complete configuration guide

---

Offensive Security Agent (SecOpsAgentKit)

RAPTOR includes an autonomous offensive security specialist agent with specialized skills from SecOpsAgentKit.

Capabilities:

• Web application security testing (SQLi, XSS, CSRF, auth bypass)
• Network penetration testing and enumeration
• Binary exploitation and reverse engineering
• Fuzzing and vulnerability discovery
• Exploit development and PoC generation
• Security code review with adversarial mindset

Usage:

Tell Claude: "Use the offensive security specialist agent to test this application"

Safety: Safe operations auto-execute; dangerous operations require explicit user confirmation.

See: .claude/agents/offsec-specialist.md and .claude/skills/SecOpsAgentKit/ for details

---

DevContainer and Dockerfile for easy onboarding

Pre-installed security tools:

Semgrep (static analysis)
CodeQL CLI v2.15.5 (semantic code analysis)
AFL++ (fuzzing)
rr debugger (deterministic record-replay debugging)

Build & debugging tools:

gcc, g++, clang-format, make, cmake, autotools
gdb, gdb-multiarch, binutils

Web testing - STUB, treat as alpha:

Playwright browser automation (Chromium, Firefox, Webkit browsers)

Runtime notes:

Runs with --privileged flag required for rr debugger
PYTHONPATH configured for /workspaces/raptor imports
All Playwright browsers pre-downloaded
OSS forensics requires GOOGLE_APPLICATION_CREDENTIALS for BigQuery (see DEPENDENCIES.md)

Usage

Open in VS Code or any of