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

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

Wenn Sie `bin/` zu Ihrem PATH hinzufügen (oder `bin/raptor` irgendwo im PATH verlinken), können Sie `raptor` von jedem Verzeichnis aus ausführen – der Launcher löst die RAPTOR-Installation auf und richtet das Arbeitsverzeichnis automatisch ein.

**Wichtig:** RAPTOR lädt seine Konfiguration aus dem Repo-Verzeichnis. Wenn Sie `claude` von einem anderen Verzeichnis aus ausführen, erhalten Sie normales Claude Code, nicht RAPTOR. Gehen Sie entweder zuerst mit `cd` in das Repo oder verwenden Sie den `raptor`-Launcher.

### Option 2: Devcontainer (empfohlen)

Alles vorinstalliert. Öffnen Sie in VS Code mit **Dev Containers: Ordner in Container öffnen** oder ziehen Sie das vorgefertigte Image:```bash
docker pull danielcuthbert/raptor:latest
docker run --privileged -it -v "$(pwd):/workspaces/raptor" danielcuthbert/raptor:latest

Das `--privileged`-Flag wird für den deterministischen Debugger `rr` benötigt. Das Image ist groß (ca. 6 GB). Es basiert auf dem Microsoft Python 3.12 Devcontainer und fügt Werkzeuge für statische Analyse, Fuzzing und Browser-Automatisierung hinzu.

Sobald du drin bist, sag einfach "hi", um loszulegen, oder springe direkt zu einem Befehl.

---

## Was dich beim ersten Start erwartet

Das Einfachste, was du tun kannst:```
/scan /path/to/code

Dies führt die vollständige Pipeline aus: Scannen, Deduplizieren, dann Senden jedes Fundes durch die Validierungsstufen (A-F). Bei einer mittelgroßen Codebasis mit ~50 Funden sind 10-30 Minuten und Kosten von 2-8 US-Dollar für die Analyse-Ebene der LLM zu erwarten (je nach Modell). Die Standard-Kostenobergrenze beträgt 10 US-Dollar pro Lauf; anpassbar mit `--max-cost-usd`.

**Kostenhinweis:** Die Claude Code Orchestrierungsschicht verwendet Ihr Claude-Abonnement. Die Analyse-Dispatch-Schicht führt separate LLM-API-Aufrufe durch, die pro Token abgerechnet werden. Wenn Sie nur Claude Code als Analysemodell verwenden (Standard), entstehen keine zusätzlichen Kosten über Ihr Abonnement hinaus. Wenn Sie externe Modelle konfigurieren (OpenAI, Gemini, etc.), werden diese API-Aufrufe von diesen Anbietern in Rechnung gestellt.

## Sicherheitsmodell

RAPTOR führt LLM-generierten Code aus und analysiert nicht vertrauenswürdige Repositories. Unterprozesse, die nicht vertrauenswürdige Inhalte verarbeiten, werden mit Linux-Namespaces, Landlock und seccomp in einer Sandbox ausgeführt. Die Sandbox blockiert Netzwerkzugriff, schränkt die Sichtbarkeit des Dateisystems ein und begrenzt den Ressourcenverbrauch. Siehe `docs/sandbox.md` für das vollständige Bedrohungsmodell und die Konfiguration.

Umgebungsvariablen, die Code in die Launcher-Kette einschleusen könnten, werden beim Start entfernt (`core/security/_dangerous_env_strip.sh`). Dateipfade aus gescannten Repositories werden niemals in Shell-Strings interpoliert – alle Unterprozessaufrufe verwenden listenbasierte Argumente.

## Was RAPTOR kann

| Befehl | Funktion | Status |
|---------|-------------|--------|
| `/agentic` | Vollautonomer Workflow: scannen, validieren, ausnutzen, patchen | Stable |
| `/scan` | Statische Analyse mit Semgrep und CodeQL | Stable |
| `/understand` | Angriffsfläche kartieren, Datenflüsse verfolgen, Schwachstellenvarianten jagen | Stable |
| `/binary` | Black-Box-Binäruntersuchung, Laufzeitnachweise, Graphabfragen und Übergabe | Beta |
| `/validate` | Mehrstufige Validierungspipeline zur Ausnutzbarkeit (Stufen 0-F) | Stable |
| `/codeql` | CodeQL-Tiefenanalyse mit SMT-Datenfluss-Vorscreening | Stable |
| `/sca` | Software-Kompositionsanalyse: Abhängigkeiten, Sicherheitshinweise, Lieferkettensignale, SBOMs und Fixes | Beta |
| `/exploit` | Proof-of-Concept-Exploitcode generieren | Beta |
| `/patch` | Sichere Patches für bestätigte Schwachstellen generieren | Beta |
| `/fuzz` | Binär-Fuzzing mit AFL++ und Absturzanalyse | Stable |
| `/crash-analysis` | Autonome Ursachenanalyse für C/C++-Abstürze | Stable |
| `/oss-forensics` | Evidenzgestützte forensische Untersuchung für GitHub-Repositories | Stable |
| `/project` | Benannte Arbeitsbereiche zum Organisieren von Läufen und Verfolgen von Funden über die Zeit | Stable |
| `/threat-model` | Projektspezifische Bedrohungsmodelle erstellen, prüfen und verwalten | Stable |
| `/sage` | Persistente Gedächtnisschicht (speichern, abrufen, verknüpfen, bestätigen) | Stable |
| `/frida` | Dynamische Instrumentierung mit Frida | Alpha |
| `/web` | Webanwendungsscanning | Alpha/stub |

## Wie die Pipeline funktioniert

Beginnen Sie mit der Erstellung eines Projekts, damit alle Ihre Läufe an einem Ort landen:```
/project create myapp --target /path/to/code   # create a project first
/project use myapp                             # set it as active
/understand --map                              # map the attack surface
/agentic --threat-model --validate             # map, model, scan, validate
/project findings                              # review everything in one place

`/understand` erstellt eine Kontextkarte von Einstiegspunkten, Vertrauensgrenzen und Senken, noch bevor eine Zeile gescannt wird. `/agentic` führt dann Semgrep und CodeQL aus, dedupliziert die Funde und leitet jeden einzelnen zur Validierung mittels der Exploitation-Validator-Methodik weiter:

Mit `--threat-model` erstellt RAPTOR zuerst die Karte, erzeugt `threat-model.json` und `THREAT_MODEL.md`, falls das Projekt diese noch nicht hat, und speist dann eine kompakte Version in `/understand`, die autonome Analyse und `/validate` ein. Existierende Projekt-Bedrohungsmodelle bleiben erhalten, es sei denn, Sie übergeben `--threat-model-refresh`; veraltete Fallback-Karten werden abgelehnt, es sei denn, Sie übergeben explizit `--threat-model-use-stale`. Außerdem werden kartierte, ungeprüfte Abläufe in Kandidaten-SARIF umgewandelt, sodass Scanner-Lücken den Durchlauf nicht abbrechen. Es handelt sich um einen vom Betreiber kontrollierten Kontext, keinen magischen Beweis: Funde benötigen weiterhin Code-Belege oder eine oraclegestützte Bestätigung. Siehe `docs/threat-model.md`.

- Stufe A: Ist das Muster tatsächlich eine Schwachstelle oder handelt es sich um Musterabgleichsrauschen des Tools?
- Stufe B: Was benötigt ein Angreifer, um es zu erreichen, und was steht im Weg?
- Stufe C: Existiert der Codepfad tatsächlich? Kann er von außen erreicht werden?
- Stufe D: Endgültige Entscheidung – handelt es sich um Testcode, sind unrealistische Vorbedingungen erforderlich, oder ist das Modell unsicher?
- Stufe E: Machbarkeit einer binären Exploit-Ausnutzung (sofern ein kompiliertes Artefakt verfügbar ist)
- Stufe F: Selbstüberprüfung – hat eine frühere Stufe Unentschlossenheit gezeigt oder sich widersprochen?

Funde, die die Validierung bestehen, erhalten Exploit-PoCs und Patches. Am Ende wird eine querschnittliche Analyse der Funde durchgeführt, um gemeinsame Ursachen und Angriffsketten zu finden.

`/validate` führt dieselbe Pipeline als eigenständigen Schritt aus, wenn Sie bereits Funde aus einem vorherigen Scan haben.

Bei einem kompilierten Artefakt führt `/binary <path>` nun eine evidenzgesteuerte Untersuchung durch, anstatt dem Betreiber einen Haufen roher Reverse-Engineering-Artefakte vorzulegen. Unter der Haube erstellt es weiterhin das SHA-256-gebundene Manifest, das Evidenzledger, die Kontextkarte, die Checkliste und die SQLite-Grafik aus Dateimetadaten, Importen und radare2-Xrefs. Mach-O-Apps erhalten zudem eine Slice-Inventarisierung, Bundle-Metadaten sowie Objective-C-/Swift-Klassen-Selektoren; hochwertiger Pseudocode wird dauerhaft gespeichert, anstatt im Durchlauf zu verschwinden. PE-DLL-Exporte, Windows-Treiber-Dispatcher und Linux-Kernelmodul-ioctl-Handler werden ebenfalls als eigene Einstiegskandidaten behandelt, wobei die PE-Architektur aus dem COFF-Header und nicht durch Raten gelesen wird. Die Untersuchungsebene fragt dann diese Grafik ab, bewertet externe Einstiegspunkte vor generischen Senken-Hinweisen, entdeckt deklarierte Helfer-/Geschwister-Binärdateien und erstellt einen kompakten Bericht, der in Fakten, strukturelle Schlussfolgerungen und unbewiesene Hypothesen unterteilt ist. Frida-Beobachtungen, Fuzz-Crash-Zeugen, explizite Z3-Prüfungen und Binärdateivergleiche können später stärkere Beweise hinzufügen. RAPTOR behält auch den internen Aufrufgraphen bei, der benötigt wird, um begrenzte Einstiegs-zu-Parser-Kandidaten wiederherzustellen, sodass ein App-Callback auf die interne Funktion eingegrenzt werden kann, die tatsächlich `XML_Parse`, `d2i_X509`, `jpeg_read_header` oder eine andere echte Parser-Oberfläche aufruft, ohne so zu tun, als sei dies ein Taint-Beweis. `/binary trace-parser <run-dir>` ist die explizite dynamische Folgemaßnahme: Es führt die enge Frida-Parser-Spur aus und aktualisiert dann dieselbe Kontextkarte, Übergabe, Grafik und Untersuchungsbericht an Ort und Stelle. `/binary investigate --active` erstellt zuerst eine Karte und startet nur dann eine echte Fuzz-Kampagne, wenn eine konkrete Harness-Grenze existiert; App-, DLL- und Treiberziele erhalten stattdessen einen Harness- oder Snapshot-Schritt. `/binary harness` schreibt eine evidenzgestützte Harness-Spezifikation für den gewählten Einstiegspunkt und gibt nur dann Quellkandidaten aus, wenn der ABI- oder IOCTL-Vertrag explizit ist. Es blufft sich nicht von „`memcpy` existiert“ zu „dies ist ausnutzbar“: Importe, Selektoren und Aufrufkanten bleiben Kandidaten, bis etwas Mechanisches mehr beweist. Siehe `docs/binary-analysis.md`.

---

## Software-Kompositionsanalyse

`/sca` analysiert die Abhängigkeits- und Lieferkettenseite eines Projekts. Es handelt sich nicht nur um eine CVE-Suche in der Requirements-Datei: RAPTOR entdeckt Manifeste, Lockfiles, Inline-Installationsbefehle, Workflow-Abhängigkeiten und Quellpakete von Containern/Base-Images und normalisiert sie dann zu einer einheitlichen Abhängigkeitsansicht.

Der Scan reichert Abhängigkeiten an mit OSV-Advisonies, CISA KEV, EPSS, CISA Vulnrichment/SSVC, Erreichbarkeit, Exploit-Evidenzsignalen, Hygiene-Checks, Supply-Chain-Heuristiken, Lizenzrichtlinien-Funden und optionaler LLM-Überprüfung/Triage. Er gibt RAPTOR-native Funde sowie SBOM- und CI-freundliche Ausgaben aus:

- `findings.json` – kanonische RAPTOR-Funde
- `report.md` – menschenlesbare Zusammenfassung
- `sbom.cdx.json` – CycloneDX-SBOM mit VEX-Daten
- `findings.sarif` – GitHub-/GitLab-Code-Scanning-Ausgabe

Häufige Befehle:```bash
python3 raptor.py sca --repo /path/to/project
python3 raptor.py sca --repo /path/to/project --no-llm
python3 raptor.py sca --repo /path/to/project --fail-on-severity high --fail-on-kev
python3 raptor.py sca --repo /path/to/project fix
python3 raptor.py sca check PyPI django 4.2.10

Sobald befüllt, löst der Scanner Paket-IDs in lokale Dateien auf, und es erfolgt kein Netzwerkaufruf. Ohne den Cache versucht RAPTOR, Registry-Pakete von semgrep.dev zum Scan-Zeitpunkt abzurufen; falls offline, verwirft es ungecachte Pakete anmutig und führt nur mit benutzerdefinierten Regeln aus.

CodeQL benötigt Netzwerkzugriff nur während der Ersteinrichtung, um das CLI und Abfragepakete herunterzuladen. Nach der Installation läuft es offline.

---

## Benutzerdefinierte Regeln

RAPTOR liefert 185 benutzerdefinierte statische Analyseregeln, die adversariell getestet wurden, um False Positives zu eliminieren:

- **Semgrep (123 Regeln)** — Taint-Tracking- und Pattern-Regeln für Python, Go, Java und JS/TS. Deckt SQLi, XSS, SSRF, SSTI, Command Injection, Deserialisierung, XXE, LDAP/NoSQL-Injection, Path Traversal, Open Redirect, Log-/Header-Injection, Eval-Injection, ReDoS, Prototype Pollution, JWT-Fehlkonfiguration, schwache Kryptografie, unsicheres TLS und hartcodierte Geheimnisse ab.
- **Coccinelle (54 Regeln)** — strukturelles Matching für C/C++. Speichersicherheit (Double Free, Use-after-Free, Free von Nicht-Base-Pointer, Free von Stack-Array, mmap'd-Speicher, Use-after-Close), Integer-Fehler (Überlauf, Vorzeichenerweiterung, doppeltes sizeof), Ressourcenlecks (popen/fclose-Fehlpaarung, fdopendir-Double-Close), Pufferbehandlung (strncpy ohne NUL, copy_user-Größenkonflikt, malloc/strlen-Off-by-One), Signal-Handler-Sicherheit, API-Missbrauch (fcntl-Flag-Domain, SIGKILL/SIGSTOP, doppeltes Byte-Swap, inet_ntoa-statischer Puffer), Compiler-Dead-Store-Eliminierung, Kernel-IS_ERR/PTR_ERR-Verwechslung, Format-String-Injection, TOCTOU-Races und mehr.
- **CodeQL (8 Abfragen)** — interprozedurales Taint-Tracking für C++ (Format-String-Injection, Integer-Truncation, Use-after-Move, Iterator-Invalidierung) und Java (XXE, unsichere Deserialisierung, Log-Injection, Spring SSRF).

Durchstöbern Sie die Regeln direkt: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Diese ergänzen die Registry-Pakete (`p/security-audit`, `p/owasp-top-ten`, `p/0xdea`, `p/trailofbits`), die ~950 zusätzliche Regeln bereitstellen – die Überschneidung ist minimal.

---

## Verwenden eines anderen LLM

RAPTOR verfügt über zwei separate Modellebenen, und es ist hilfreich zu wissen, wie beide funktionieren, bevor Sie etwas ändern.

Die **Orchestrierungsebene** ist immer Claude Code. Die CLAUDE.md, Skills und Befehle werden alle als Claude Code-Anweisungen ausgeführt. Um zu ändern, welches Claude-Modell RAPTOR orchestriert, verwenden Sie das `--model`-Flag von Claude Code oder den Befehl `/model` innerhalb einer Sitzung.

Die **Analyse-Dispatch-Ebene** ist das LLM, das einzelne Schwachstellenbefunde analysiert. Diese ist von der Orchestrierungsebene getrennt und kann jeder unterstützte Anbieter sein. Konfigurieren Sie sie in `~/.config/raptor/models.json`:```json
{
  "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"
    }
  ]
}

| Rolle | Aufgabe |
|------|---------|
| `analysis` | Validiert und analysiert jeden Befund (Schritte A-F) |
| `code` | Schreibt Exploit-PoCs und Patch-Code |
| `consensus` | Zweitmeinung über echte Positive |
| `aggregate` | Optional. Von LLM verfasste narrative Synthese auf Basis der deterministischen Multi-Modell-Korrelation, geschrieben in `aggregation.json` und den endgültigen `agentic-report.md` |
| `fallback` | Wird verwendet, wenn das primäre Modell fehlschlägt oder Ratenlimits erreicht |

Wenn keine Rollen festgelegt sind, übernimmt das erste Modell in der Liste alles. Für eine Multi-Modell-Quellcode-Analyse konfigurieren Sie zwei oder mehr `analysis`-Modelle – standardmäßig erhalten Sie die deterministische Korrelation. Die Rolle `aggregate` ist optional und fügt eine von einem LLM verfasste Zusammenfassung hinzu:```bash
python3 raptor.py agentic --repo /code \
  --model claude-opus-4-6 \
  --model gpt-5.4 \
  --aggregate claude-sonnet-4-6

Ollama funktioniert für die Analyse, erzeugt aber unzuverlässigen Exploit- und Patch-Code. Für Code-Generierungsaufgaben verwenden Sie ein Frontier-Modell.

### Fast-tier short-circuit + das model scorecard

Wenn Ihr Analyse-Stufen-Modell ein günstigeres Geschwistermodell desselben Anbieters hat (Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), verwendet RAPTOR es als Prefilter für Consumer, die in das Substrat eingebunden sind (derzeit codeql; SCA und andere folgen später). Das günstige Modell short-circuits nur bei **zuversichtlichen Falsch-Positiven**; mehrdeutige Fälle und zuversichtliche True Positives durchlaufen immer die vollständige Analyse. Das Vertrauen akkumuliert pro `(model, decision_class)`-Zelle – RAPTOR zeichnet die Übereinstimmung zwischen günstig und vollständig auf und short-circuits erst, wenn die Wilson-95%-Obergrenze der Fehlerrate der Zelle bei 5 % oder darunter liegt.

Um zu prüfen, worin Ihre Modelle gut sind, verwenden Sie `/scorecard` (oder direkt: `libexec/raptor-llm-scorecard list`). Die Scorecard ist global (Erkenntnisse werden projektübergreifend übernommen) und persistiert unter `out/llm_scorecard.json`.

---

## Projekte

Ohne Projekt erhält jeder Durchlauf sein eigenes, mit Zeitstempel versehenes Verzeichnis unter `out/`. Mit einem Projekt wird alles an einem Ort abgelegt, und Sie erhalten zusammengeführte Ergebnisse, Abdeckungsverfolgung und Diffs zwischen Durchläufen.```bash
/project create myapp --target /path/to/code -d "Short description"
/project use myapp

/scan
/understand --map
/validate

/project status                # all runs, pass/fail, timestamps
/project findings              # merged findings across all runs
/project findings --detailed   # per-finding detail
/project coverage --detailed   # which files were reviewed
/project diff myapp run1 run2  # compare two runs
/project report                # full merged report
/project clean --keep 3        # remove old runs, keep the last 3
/project export myapp /tmp/myapp.zip
/project none                  # clear active project

Die Aufteilung bedeutet, dass Sie die Python-Ebene aus einer CI-Pipeline ausführen können (`python3 raptor.py scan --repo …`) und strukturierte SARIF-Ausgabe ohne Claude Code erhalten, oder sie interaktiv mit dem vollständigen agentischen Workflow ausführen können.

---

## OSS-Forensik

`/oss-forensics` untersucht öffentliche GitHub-Repositories unter Verwendung von Beweisen aus mehreren Quellen: der GitHub-API, dem GH-Archiv (unveränderliche Ereignishistorie über BigQuery), der Wayback Machine und der lokalen Git-Historie. Es führt eine strukturierte Pipeline von der Beweiserhebung über die Hypothesenbildung bis hin zu einem abschließenden forensischen Bericht aus.

Erfordert `GOOGLE_APPLICATION_CREDENTIALS` für den BigQuery-Zugriff. Siehe `.claude/commands/oss-forensics.md` für Details.

---

## Experten-Personas

Sieben Experten-Personas sind auf Anfrage verfügbar. Laden Sie eine, wenn Sie eine andere Perspektive auf einen Befund oder eine bestimmte Technik wünschen:```
Exploit Developer (Mark Dowd)                  Exploit PoC generation
Crash Analyst (Charlie Miller / Halvar Flake)  Crash analysis and exploitability assessment
Security Researcher                            General adversarial code review
Patch Engineer                                 Secure fix generation
Penetration Tester                             Realistic attack scenario assessment
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption