{"id":41215755,"url":"https://github.com/gadievron/raptor","last_synced_at":"2026-02-01T09:00:48.200Z","repository":{"id":327307020,"uuid":"1078171437","full_name":"gadievron/raptor","owner":"gadievron","description":"Raptor turns Claude Code into a general-purpose AI offensive/defensive security agent. By using Claude.md and creating rules, sub-agents, and skills, and orchestrating security tool usage, we configure the agent for adversarial thinking, and perform research or attack/defense operations.","archived":false,"fork":false,"pushed_at":"2026-01-29T11:10:36.000Z","size":1244,"stargazers_count":1033,"open_issues_count":9,"forks_count":124,"subscribers_count":16,"default_branch":"main","last_synced_at":"2026-01-30T01:52:12.739Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gadievron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-17T10:10:40.000Z","updated_at":"2026-01-29T20:22:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gadievron/raptor","commit_stats":null,"previous_names":["gadievron/raptor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gadievron/raptor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadievron%2Fraptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadievron%2Fraptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadievron%2Fraptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadievron%2Fraptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gadievron","download_url":"https://codeload.github.com/gadievron/raptor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gadievron%2Fraptor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28974246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T08:16:14.655Z","status":"ssl_error","status_checked_at":"2026-02-01T08:06:51.373Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-23T00:01:14.134Z","updated_at":"2026-02-01T09:00:48.194Z","avatar_url":"https://github.com/gadievron.png","language":"Python","funding_links":[],"categories":["Attack Techniques \u0026 Red Teaming","Tools","Pentest \u0026 Red Teaming Agents","Configuration \u0026 Rules","Security \u0026 Compliance","Python","AI Agent Frameworks"],"sub_categories":["LLM \u0026 GenAI Red Teaming","Framework","Security Analysis"],"readme":"```text\n╔═══════════════════════════════════════════════════════════════════════════╗ \n║                                                                           ║\n║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║ \n║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║ \n║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║ \n║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║ \n║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║ \n║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║ \n║                                                                           ║ \n║             Autonomous Offensive/Defensive Research Framework             ║\n║             Based on Claude Code - v1.0-beta                              ║\n║                                                                           ║ \n║             By Gadi Evron, Daniel Cuthbert                                ║\n║                Thomas Dullien (Halvar Flake)                              ║\n║                Michael Bargury                                            ║ \n║                John Cartwright                                            ║ \n║                                                                           ║ \n╚═══════════════════════════════════════════════════════════════════════════╝ \n\n⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣤⣀⣀\n⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⠿⠿⠟\n⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣀⣀⣀⣤⣴⣶⣶⣶⣤⣿⡿⠁⠀⠀⠀\n⣀⠤⠴⠒⠒⠛⠛⠛⠛⠛⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀\n⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⣿⣿⣿⡟⠻⢿⡀⠀⠀⠀⠀⠀\n⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⢿⣿⠟⠀⠸⣊⡽⠀⠀⠀⠀⠀\n⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⣿⡁⠀⠀⠀⠉⠁⠀⠀⠀⠀⠀\n⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⠿⣿⣧⠀ Get them bugs.....⠀⠀⠀⠀⠀⠀⠀⠀\n                                                 \n```\n\n# RAPTOR - Autonomous Offensive/Defensive Security Research Framework, based on Claude Code\n\n[![Run in Smithery](https://smithery.ai/badge/skills/gadievron)](https://smithery.ai/skills?ns=gadievron\u0026utm_source=github\u0026utm_medium=badge)\n[![CodeQL](https://github.com/gadievron/raptor/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/gadievron/raptor/actions/workflows/github-code-scanning/codeql)\n\n\n**Authors:** Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), Michael Bargury \u0026 John Cartwright\n(@gadievron, @danielcuthbert, @thomasdullien, @mbrg \u0026 @grokjc)\n\n**License:** MIT (see LICENSE file)\n\n**Repository:** https://github.com/gadievron/raptor\n\n**Dependencies:** See DEPENDENCIES.md for external tools and licenses\n\n---\n\n## What is RAPTOR?\n\nRAPTOR is an **autonomous offensive/defensive security research framework**, based on\n**Claude Code**. It empowers security research with agentic workflows and automation.\n\nRAPTOR stands for Recursive Autonomous Penetration Testing and Observation Robot.\n(We really wanted to name it RAPTOR)\n\n**RAPTOR autonomously**:\n1. **Scans** your code with Semgrep and CodeQL and tries dataflow validation\n2. **Fuzzes** your binaries with American Fuzzy Lop (AFL)\n3. **Analyses** vulnerabilities using advanced LLM reasoning\n4. **Exploits** by generating proof-of-concepts\n5. **Patches** with code to fix vulnerabilities\n6. **FFmpeg-specific** patching for Google's recent disclosure\n   (https://news.ycombinator.com/item?id=45891016)\n7. **OSS Forensics** for evidence-backed GitHub repository investigations\n8. **Agentic Skills Engine** for security research \u0026 operations ([SecOpsAgentKit](https://github.com/AgentSecOps/SecOpsAgentKit))\n9. **Offensive Security Testing** via autonomous specialist agent with SecOpsAgentKit\n10. **Cost Management** with budget enforcement, real-time tracking, and quota detection\n11. **Reports** everything in structured formats\n\nRAPTOR combines traditional security tools with agentic automation and analysis, deeply\nunderstands your code, proves exploitability, and proposes patches.\n\n**Disclaimer: It's a quick hack, and we can't live without it**:\nWe're proud of RAPTOR (and some of our tools are beyond useful), but RAPTOR itself was hacked\ntogether in free time, held together by vibe coding and duct tape. Consider it an early release.\n\nWhat will make RAPTOR truly transformative is community contributions. It's open source,\nmodular, and extensible.\n\n**Be warned**: Unless you use the devcontainer, RAPTOR will automatically install tools\nwithout asking, check dependencies.txt first.\n\n---\n\n## What's unique about RAPTOR?\n\nBeyond RAPTOR's potential for autonomous security research and community collaboration, it\ndemonstrates how Claude Code can be adapted for **any purpose**, with RAPTOR packages.\n\n**Recent improvements:**\n- **LiteLLM Integration:** Unified LLM interface with Pydantic validation, smart model selection, and cost tracking\n- **SecOpsAgentKit:** Offensive security specialist agent with comprehensive penetration testing capabilities\n- **Cost Management:** Budget enforcement, real-time callbacks, and intelligent quota detection\n- **Enhanced Reliability:** Multiple bug fixes improving robustness across CodeQL, static analysis, and LLM providers\n\n---\n\n### OSS Forensics Investigation\n\nRAPTOR now includes comprehensive GitHub forensics capabilities via the `/oss-forensics` command:\n\n**New Capabilities:**\n- **Evidence Collection:** Multi-source evidence gathering (GH Archive, GitHub API, Wayback Machine, local git)\n- **BigQuery Integration:** Query immutable GitHub event data via GH Archive\n- **Deleted Content Recovery:** Recover deleted commits, issues, and repository content\n- **IOC Extraction:** Automated extraction of indicators of compromise from vendor reports\n- **Evidence Verification:** Rigorous evidence validation against original sources\n- **Hypothesis Formation:** AI-powered evidence-backed hypothesis generation with iterative refinement\n- **Forensic Reporting:** Detailed reports with timeline, attribution, and IOCs\n\n**Architecture:** Multi-agent orchestration with specialized investigators for parallel evidence collection and sequential analysis pipeline.\n\n**Documentation:** See `.claude/commands/oss-forensics.md` and `.claude/skills/oss-forensics/` for complete details.\n\n---\n\n## Quick Start\n\n```bash\nYou have two options, install on your own, or deploy the devcontainer.\n\n**Install**\n# 1. Install Claude Code\n# Download from: https://claude.ai/download\n\n# 2. Clone and open RAPTOR\ngit clone https://github.com/gadievron/raptor.git\ncd raptor\nclaude\n\n# 3. Let Claude install dependencies, and check licenses for the various tools\n\"Install dependencies from requirements.txt\"\n\"Install semgrep\"\n\"Set my ANTHROPIC_API_KEY to [your-key]\"\n\n**devcontainer**\n# 4. Get the devcontainer\nA devcontainer with all prerequisites pre-installed is available. Open in VS Code or any of\nits forks with command Dev Container: Open Folder in Container, or build with docker:\ndocker build -f .devcontainer/Dockerfile -t raptor-devcontainer:latest ..\n\nRuns with --privileged flag for rr.\n\n# 5. Notes\nThe devcontainer is massive (~6GB), starting with Microsoft Python 3.12 massive devcontainer and\nadding static analysis, fuzzing and browser automation tools.\n\n# 6. Getting started with RAPTOR\nJust say \"hi\" to get started\nTry /analyze on one of our tests in /tests/data\n```\n\n**See:** `docs/CLAUDE_CODE_USAGE.md` for complete guide\n\n---\n\n## LLM Configuration \u0026 Cost Management\n\nRAPTOR uses LiteLLM for unified LLM provider integration with automatic fallback, cost tracking, and budget enforcement.\n\n**Key Features:**\n- **Pydantic Validation:** YAML configs validated at load time with clear error messages\n- **Smart Model Selection:** Auto-selects best reasoning/thinking model from config\n- **Real-time Visibility:** Callbacks log model usage, tokens, duration for every call\n- **Budget Enforcement:** Prevents exceeding cost limits with detailed error messages\n- **Quota Detection:** Intelligent rate limit detection with provider-specific guidance\n- **Cost Tracking:** Tracks costs across all LLM calls with per-request breakdown\n\n**Configuration:**\n```yaml\n# litellm_config.yaml example\nmodel_list:\n  - model_name: claude-opus-4.5\n    litellm_params:\n      model: anthropic/claude-opus-4.5\n      api_key: ${ANTHROPIC_API_KEY}\n  - model_name: gpt-5.2-thinking\n    litellm_params:\n      model: openai/gpt-5.2-thinking\n      api_key: ${OPENAI_API_KEY}\n```\n\n**Budget Control:**\n```python\nfrom packages.llm_analysis.llm.config import LLMConfig\n\nconfig = LLMConfig(\n    max_cost_per_scan=1.0  # Prevent exceeding $1 per scan\n)\n```\n\n**See:** `docs/litellm-model-configuration-guide.md` for complete configuration guide\n\n---\n\n## Offensive Security Agent (SecOpsAgentKit)\n\nRAPTOR includes an autonomous offensive security specialist agent with specialized skills from SecOpsAgentKit.\n\n**Capabilities:**\n- Web application security testing (SQLi, XSS, CSRF, auth bypass)\n- Network penetration testing and enumeration\n- Binary exploitation and reverse engineering\n- Fuzzing and vulnerability discovery\n- Exploit development and PoC generation\n- Security code review with adversarial mindset\n\n**Usage:**\n```\nTell Claude: \"Use the offensive security specialist agent to test this application\"\n```\n\n**Safety:** Safe operations auto-execute; dangerous operations require explicit user confirmation.\n\n**See:** `.claude/agents/offsec-specialist.md` and `.claude/skills/SecOpsAgentKit/` for details\n\n---\n\n## DevContainer and Dockerfile for easy onboarding\n\nPre-installed security tools:\n```\nSemgrep (static analysis)\nCodeQL CLI v2.15.5 (semantic code analysis)\nAFL++ (fuzzing)\nrr debugger (deterministic record-replay debugging)\n```\n\nBuild \u0026 debugging tools:\n```\ngcc, g++, clang-format, make, cmake, autotools\ngdb, gdb-multiarch, binutils\n```\n\nWeb testing - STUB, treat as alpha:\n```\nPlaywright browser automation (Chromium, Firefox, Webkit browsers)\n```\n\nRuntime notes:\n```\nRuns with --privileged flag required for rr debugger\nPYTHONPATH configured for /workspaces/raptor imports\nAll Playwright browsers pre-downloaded\nOSS forensics requires GOOGLE_APPLICATION_CREDENTIALS for BigQuery (see DEPENDENCIES.md)\n```\n### Usage\n\nOpen in VS Code or any of its forks with Dev Container: Open Folder in Container command.\n\nOr build it with docker:\n\n```\ndocker build -f .devcontainer/Dockerfile -t raptor-devcontainer:latest .\n```\n\n\n---\n\n## Available Commands\n\n**Main entry point:**\n```\n/raptor   - RAPTOR security testing assistant (start here for guidance)\n```\n\n**Security testing:**\n```\n/scan     - Static code analysis (Semgrep + CodeQL)\n/fuzz     - Binary fuzzing with AFL++\n/web      - Web application security testing (STUB - treat as alpha)\n/agentic  - Full autonomous workflow (analysis + exploit/patch generation)\n/codeql   - CodeQL-only deep analysis with dataflow\n/analyze  - LLM analysis only (no exploit/patch generation - 50% faster \u0026 cheaper)\n```\n\n**Exploit development \u0026 patching:**\n```\n/exploit  - Generate exploit proof-of-concepts (beta)\n/patch    - Generate security patches for vulnerabilities (beta)\n/crash-analysis - Analyze an FFmpeg crash and generate a validated root-cause analysis\n```\n\n**Forensics \u0026 investigation:**\n```\n/oss-forensics - Evidence-backed forensic investigation for public GitHub repositories\n```\n\n**Development \u0026 testing:**\n```\n/create-skill    - Save custom approaches (experimental)\n/test-workflows  - Run comprehensive test suite (stub)\n```\n\n**Expert personas:** (9 total, load on-demand)\n```\nMark Dowd, Charlie Miller/Halvar Flake, Security Researcher, Patch Engineer,\nPenetration Tester, Fuzzing Strategist, Binary Exploitation Specialist,\nCodeQL Dataflow Analyst, CodeQL Finding Analyst\n\nUsage: \"Use [persona name]\"\n```\n\n**See:** `docs/CLAUDE_CODE_USAGE.md` for detailed examples and workflows\n\n---\n\n## Architecture\n\n**Multi-layered system with progressive disclosure:**\n\n**Claude Code Decision System:**\n- Bootstrap (CLAUDE.md) → Always loaded\n- Tier1 (adversarial thinking, analysis-guidance, recovery) → Auto-loads when relevant\n- Tier2 (9 expert personas) → Load on explicit request\n- Agents (offsec-specialist) → Autonomous offensive security operations\n- Alpha (custom skills) → User-created\n\n**Python Execution Layer:**\n- raptor.py → Unified launcher\n- packages/ → 9 security capabilities\n- core/ → Shared utilities\n- engine/ → Rules and queries\n\n**Skills \u0026 Agents:**\n- `.claude/skills/SecOpsAgentKit/` → Offensive security skills (git submodule)\n- `.claude/agents/offsec-specialist.md` → Offensive security agent\n\n**Key features:**\n- **Adversarial thinking:** Prioritizes findings by Impact × Exploitability / Detection Time\n- **Decision templates:** 5 options after each scan\n- **Progressive disclosure:** 360t → 925t → up to 2,500t with personas\n- **Dual interface:** Claude Code (interactive) or Python CLI (scripting)\n\n**See:** `docs/ARCHITECTURE.md` for detailed technical documentation\n\n---\n\n## LLM Providers\n\nModel selection and API use is handled through Claude Code natively.\n\n(very much) Eperimental benchmark for exploit generation:\n\n| Provider             | Exploit Quality         | Cost        |\n|----------------------|-------------------------|-------------|\n| **Anthropic Claude** | ✅ Compilable C code    | ~$0.03/vuln |\n| **OpenAI GPT-4**     | ✅ Compilable C code    | ~$0.03/vuln |\n| **Gemini 2.5**       | ✅ Compilable C code    | ~$0.03/vuln |\n| **Ollama (local)**   | ❌ Often broken         | FREE        |\n\n**Note:** Exploit generation requires frontier models (Claude, GPT, or Gemini). Local\nmodels work for analysis but may produce non-compilable exploit code.\n\n### Environment Variables\n\n**LLM Configuration:**\n- `ANTHROPIC_API_KEY` - Anthropic Claude API key\n- `OPENAI_API_KEY` - OpenAI API key\n- `OLLAMA_HOST` - Ollama server URL (default: `http://localhost:11434`)\n- `LITELLM_CONFIG_PATH` - Path to LiteLLM YAML configuration file (optional)\n\n**Ollama Examples:**\n```bash\n# Local Ollama (default)\nexport OLLAMA_HOST=http://localhost:11434\n\n# Remote Ollama server\nexport OLLAMA_HOST=https://ollama.example.com:11434\n\n# Remote with custom port\nexport OLLAMA_HOST=http://192.168.1.100:8080\n```\n\n**Performance Tuning:**\n\nRemote Ollama servers automatically use longer retry delays (5 seconds vs 2 seconds for local) to account for network latency and processing time, reducing JSON parsing errors.\n\n| Server Type | Base Delay | Retry 1 | Retry 2 | Retry 3 |\n|-------------|------------|---------|---------|---------|\n| **Local** | 2.0s | 2s | 4s | 8s |\n| **Remote** | 5.0s | 5s | 10s | 20s |\n\n---\n\n## Python CLI (Alternative)\n\nFor scripting or CI/CD integration:\n\n```bash\npython3 raptor.py agentic --repo /path/to/code\npython3 raptor.py scan --repo /path/to/code --policy_groups secrets\npython3 raptor.py fuzz --binary /path/to/binary --duration 3600\n```\n\n**See:** `docs/PYTHON_CLI.md` for complete Python CLI reference\n\n---\n\n## Documentation\n\n### User Guides\n- **CLAUDE_CODE_USAGE.md** - Complete Claude Code usage guide\n- **PYTHON_CLI.md** - Python command-line reference\n- **FUZZING_QUICKSTART.md** - Binary fuzzing guide\n- **litellm-model-configuration-guide.md** - LiteLLM configuration and model selection\n- **.claude/commands/oss-forensics.md** - OSS forensics investigation guide\n- **TESTING.md** - Test suite documentation and user stories\n\n### Architecture \u0026 Development\n- **ARCHITECTURE.md** - Technical architecture details\n- **EXTENDING_LAUNCHER.md** - How to add new capabilities\n- **DEPENDENCIES.md** - External tools and licenses\n- **tiers/personas/README.md** - All 9 expert personas\n\n\n## Contribute\n\nRAPTOR is in alpha, and we welcome contributions from anyone, on anything.\n- Your idea here\n- Your second idea here\n\nSubmit pull requests.\n\nA better web exploitation module? YARA signatures generation? Maybe a port into Cursor,\nWindsurf, Copilot, or Codex? Devin? Cline? Antigravity?\n\nHacker poetry? :)\n\nChat with us on the #raptor channel at the Prompt||GTFO Slack:\nhttps://join.slack.com/t/promptgtfo/shared_invite/zt-3kbaqgq2p-O8MAvwU1SPc10KjwJ8MN2w\n\n**See:** `docs/EXTENDING_LAUNCHER.md` for developer guide\n\n---\n\n## License\n\nMIT License - Copyright (c) 2025 Gadi Evron, Daniel Cuthbert, Thomas Dullien (Halvar Flake), and Michael Bargury\n\nSee LICENSE file for full text.\n\nMake sure and review the licenses for the various tools. For example, CodeQL does not allow commercial use.\n\n---\n\n## Support\n\n**Issues:** https://github.com/gadievron/raptor/issues\n**Repository:** https://github.com/gadievron/raptor\n**Documentation:** See `docs/` directory\n\nChat with us on the #raptor channel at the Prompt||GTFO Slack:\nhttps://join.slack.com/t/promptgtfo/shared_invite/zt-3kbaqgq2p-O8MAvwU1SPc10KjwJ8MN2w\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgadievron%2Fraptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgadievron%2Fraptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgadievron%2Fraptor/lists"}