╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             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.....⠀⠀⠀⠀⠀

Der `raptor`-Launcher ist die empfohlene Methode, um eine Sitzung zu starten, und er funktioniert von jedem Verzeichnis aus – er löst die RAPTOR-Installation auf, merkt sich das Verzeichnis, aus dem du gestartet hast (sodass Befehle wie `/scan` standardmäßig darauf zugreifen), führt die Pre-Flight-Vertrauens- und Projektprüfungen durch, lädt das Plugin zur Abdeckungsverfolgung und bereinigt die Umgebung, bevor er an Claude Code übergibt. Er akzeptiert außerdem einen optionalen Zielpfad und Flags wie `--project`, `--continue` und `--model` – siehe `raptor --help`.

Das Ausführen von einfachem `claude` aus dem Repo-Verzeichnis heraus funktioniert ebenfalls – Claude Code übernimmt RAPTORs Konfiguration aus dem Checkout –, aber du überspringst alles, was der Launcher oben tut: keine Pre-Flight-Prüfungen, keine Abdeckungsverfolgung, und Befehle, die standardmäßig auf „das Verzeichnis, aus dem du dies ausgeführt hast“ zugreifen, können es nicht sehen.

**Wichtig:** RAPTOR lädt seine Konfiguration aus dem Repo-Verzeichnis. Wenn du `claude` aus einem anderen Verzeichnis ausführst, erhältst du einfaches Claude Code, nicht RAPTOR. Der `raptor`-Launcher vermeidet diesen Fehlermodus vollständig.

### Option 2: In einem Container ausführen (empfohlen)

Die Verwendung von Containern ist eine gängige Sicherheitspraxis, um Agenten den Zugriff auf Bereiche deines Dateisystems zu verwehren, auf die du keinen Zugriff wünschst, sowie den Schadensradius von bösartigem Code zu begrenzen, der möglicherweise ausgeführt wird (z. B. durch einen Supply-Chain-Angriff). Das Image ist groß (ca. 6 GB). Es basiert auf dem Microsoft Python 3.12-Devcontainer und fügt statische Analyse-, Fuzzing- und Browser-Automatisierungswerkzeuge hinzu.

Du kannst ein vorgefertigtes Image herunterladen:```bash
docker pull danielcuthbert/raptor:latest

Das Image erwartet, dass das RAPTOR-Framework (dieses Repository) beim Start in `/workspaces/raptor` eingebunden wird. Optional können Sie einen Zielordner für die lokale Analyse einbinden.

So starten Sie den Container:```bash
docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

Füge `--privileged` hinzu, wenn du den deterministischen Debugger `rr` benötigst.

VS-Code-Devcontainer werden ebenfalls unterstützt. Um einen Zielordner einzubinden, füge ihn dem Abschnitt `mounts` in `.devcontainer/devcontainer.json` hinzu:```jsonc
"mounts": [
  // ...existing entries...
  "source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]

So oder so: Sobald du im Container bist, führe `raptor` aus, um loszulegen.

---

## 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 und anschließendes Senden jedes Befunds durch die Validierungsstufen (A-F). Bei einer mittelgroßen Codebasis mit etwa 50 Befunden ist mit 10-30 Minuten und 2-8 $ an LLM-Kosten für die Analyseebene zu rechnen (abhängig vom Modell). Das standardmäßige Kostenlimit beträgt 10 $ pro Lauf; anpassbar mit `--max-cost-usd`.

**Hinweis zu den Kosten:** Die Orchestrierungsebene von Claude Code nutzt dein Claude-Abonnement. Die Analyse-Dispatch-Ebene tätigt separate LLM-API-Aufrufe, die pro Token abgerechnet werden. Wenn du nur Claude Code als Analysemodell verwendest (die Standardeinstellung), entstehen keine zusätzlichen Kosten über dein Abonnement hinaus. Wenn du externe Modelle konfigurierst (OpenAI, Gemini usw.), werden diese API-Aufrufe von den jeweiligen Anbietern abgerechnet.

---

## Sicherheitsmodell

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

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 Subprozessaufrufe verwenden listenbasierte Argumente.

---

## Was RAPTOR kann

| Befehl | Funktion | Status |
|---------|-------------|--------|
| `/agentic` | Vollständiger autonomer Workflow: Scannen, Validieren, Ausnutzen, Patchen | Stabil |
| `/scan` | Statische Analyse mit Semgrep und CodeQL | Stabil |
| `/understand` | Angriffsfläche kartieren, Datenflüsse verfolgen, Schwachstellenvarianten aufspüren | Stabil |
| `/binary` | Black-Box-Untersuchung von Binärdateien, Laufzeitnachweise, Graph-Abfragen und Übergabe | Beta |
| `/ghidra` | Ghidra-RE-Brücke: `.gpr`-Projekte anhängen/importieren, versionsübergreifender Diff, Export von Befunden | Beta |
| `/audit` | Hypothesengetriebene, toolgestützte systematische Code-Überprüfung | Beta |
| `/review` | Audit-Status abfragen: Befunde, Lücken, Abdeckung, Operator-Notizen | Stabil |
| `/annotate` | Freiform-Prosa-Anmerkungen pro Funktion anhängen (Operator-Überprüfungsnotizen) | Stabil |
| `/validate` | Mehrstufige Ausnutzbarkeits-Validierungspipeline (Stufen 0-F) | Stabil |
| `/diagram` | Mermaid-Visualisierungen aus `/understand`- und `/validate`-JSON-Ausgaben | Beta |
| `/codeql` | CodeQL-only Tiefenanalyse mit SMT-Dataflow-Vorprüfung | Stabil |
| `/analyze` | Vorhandene SARIF-Befunde mit LLM analysieren, ohne erneut zu scannen | Stabil |
| `/sca` | Software-Composition-Analyse: Abhängigkeiten, Advisories, Supply-Chain-Signale, SBOMs und Fixes | Beta |
| `/cve-diff` | Fix-Commit für eine CVE über OSV, NVD, GitHub und GitLab entdecken und diffen | Beta |
| `/cve-env` | Docker-Umgebung erstellen und verifizieren, die die betroffene Anwendung einer CVE in ihrer Vor-Patch-Version ausführt | Experimentell |
| `/exploit` | Proof-of-Concept-Exploit-Code generieren | Beta |
| `/patch` | Sichere Patches für bestätigte Schwachstellen generieren | Beta |
| `/fuzz` | Binary-Fuzzing mit AFL++ und Absturzanalyse | Stabil |
| `/crash-analysis` | Autonome Root-Cause-Analyse für C/C++-Abstürze | Stabil |
| `/oss-forensics` | Evidenzgestützte forensische Untersuchung für GitHub-Repositories | Stabil |
| `/project` | Benannte Arbeitsbereiche zur Organisation von Läufen und zur Verfolgung von Befunden über die Zeit | Stabil |
| `/describe` | Ein Ziel beschreiben: Sprachmix, Build-System, Tool-Lücken, Kostenschätzung (nur lesend) | Stabil |
| `/threat-model` | Projektbezogene Bedrohungsmodelle erstellen, einsehen und pflegen | Stabil |
| `/sage` | Persistente Speicherebene (speichern, abrufen, verknüpfen, untermauern) | Stabil |
| `/ask` | Freiform-Prompt an jedes konfigurierte LLM-Modell senden | Stabil |
| `/scorecard` | Zuverlässigkeit pro Modell über Entscheidungsklassen hinweg prüfen | Stabil |
| `/frida` | Dynamische Instrumentierung über Frida | Alpha |
| `/web` | Webanwendungs-Scanning: Crawlen, ffuf/nuclei-Integration, oracle-verifizierte Injection, blinde SSRF-Callbacks | Beta |

---

## So funktioniert die Pipeline

Beginne damit, ein Projekt zu erstellen, damit alle deine 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 der Einstiegspunkte, Vertrauensgrenzen und Senken, bevor eine Zeile gescannt wird. `/agentic` führt dann Semgrep und CodeQL aus, dedupliziert Befunde und leitet jeden zur Validierung anhand der Exploitation-Validator-Methodik weiter:

Mit `--threat-model` führt RAPTOR zuerst die Karte aus, erstellt `threat-model.json` und `THREAT_MODEL.md`, falls das Projekt diese noch nicht besitzt, und speist dann eine kompakte Version in `/understand`, die autonome Analyse und `/validate` ein. Vorhandene Projekt-Threat-Modelle 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`. Es wandelt außerdem kartierte ungeprüfte Flows in Kandidaten-SARIF um, sodass Scanner-Lücken den Lauf nicht beenden. Es handelt sich um vom Operator verwalteten Kontext, nicht um magischen Beweis: Befunde benötigen weiterhin Code-Evidenz oder oracle-gestützte Bestätigung. Siehe `docs/threat-model.md`.

- Stufe A: Ist das Muster tatsächlich eine Schwachstelle, oder ist das Tool nur Musterabgleich-Rauschen?
- Stufe B: Was braucht 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 – ist dies Testcode, erfordert es unrealistische Vorbedingungen, weicht das Modell aus?
- Stufe E: Machbarkeit eines Binär-Exploits (wenn ein kompiliertes Artefakt verfügbar ist)
- Stufe F: Selbstprüfung – hat eine frühere Stufe ausgewichen oder sich widersprochen?

Befunde, die die Validierung bestehen, erhalten generierte Exploit-PoCs und Patches. Am Ende läuft eine übergreifende Befundanalyse, um gemeinsame Grundursachen und Angriffsketten zu finden.

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

Für ein kompiliertes Artefakt führt `/binary <path>` nun eine evidenzorientierte
Untersuchung durch, anstatt dem Operator einen Haufen roher Reverse-Engineering-Artefakte
vorzulegen. Darunter baut es weiterhin das SHA-256-gebundene Manifest,
Evidenz-Ledger, die Kontextkarte, Checkliste und SQLite-Graph aus Dateimetadaten,
Imports und radare2-Xrefs auf. Mach-O-Apps erhalten außerdem eine Slice-Inventur, Bundle-
Metadaten und Objective-C-/Swift-Klassen-Selektoren; hochwertiger Pseudocode wird
persistiert, statt innerhalb des Laufs zu verschwinden. PE-DLL-Exports, Windows-
Treiber-Dispatcher und Linux-Kernel-Modul-ioctl-Handler werden ebenfalls als eigene
Ingress-Kandidaten behandelt, wobei die PE-Architektur aus dem COFF-Header gelesen
statt geraten wird. Die Untersuchungsebene fragt dann diesen Graphen ab,
reiht externen Ingress vor generischen Senken-Hinweisen ein, entdeckt deklarierte
Hilfs-/Begleit-Binaries und schreibt einen kompakten Bericht, aufgeteilt in Fakten,
strukturelle Schlussfolgerungen und unbewiesene Hypothesen. Frida-Beobachtungen, Fuzz-Crash-
Zeugen, explizite Z3-Prüfungen und Binärdiffs können später stärkere Evidenz
hinzufügen. RAPTOR behält außerdem den internen Call-Graph bei, der benötigt wird, um
begrenzte Ingress-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 vorzutäuschen, dass dies
Taint-Beweis sei. `/binary trace-parser <run-dir>` ist das explizite dynamische Folgewerkzeug:
Es führt die schmale Frida-Parser-Trace aus und aktualisiert dann dieselbe Kontextkarte,
Übergabe, Graph und Untersuchungsbericht an Ort und Stelle. `/binary investigate --active` kartiert zuerst und startet nur dann eine echte
Fuzz-Kampagne, wenn eine konkrete Harness-Grenze existiert; App-, DLL- und Treiber-
Ziele erhalten stattdessen einen Harness- oder Snapshot-Schritt. `/binary harness` schreibt eine
evidenzgestützte Harness-Spezifikation für den gewählten Ingress und gibt nur dann Kandidaten-
Quellcode aus, wenn der ABI- oder IOCTL-Vertrag explizit ist. Es täuscht sich nicht von „`memcpy` existiert“ zu „dies ist
exploitbar“ durch: Imports, Selektoren und Call-Kanten bleiben Kandidaten, bis
etwas Mechanisches mehr beweist. Siehe `docs/binary-analysis.md`.

---

## Software-Zusammensetzungsanalyse

`/sca` analysiert die Abhängigkeits- und Lieferketten-Seite eines Projekts. Es ist nicht nur ein CVE-Lookup für Requirements-Dateien: RAPTOR entdeckt Manifeste, Lockfiles, Inline-Installationsbefehle, Workflow-Abhängigkeiten und Paketquellen von Containern/Base-Images und normalisiert sie dann in eine einzige Abhängigkeitsansicht.

Der Scan reichert Abhängigkeiten mit OSV-Advisories, CISA KEV, EPSS, CISA Vulnrichment/SSVC, Erreichbarkeit, Exploit-Evidenz-Signalen, Hygiene-Checks, Lieferketten-Heuristiken, Lizenzrichtlinien-Befunden und optionaler LLM-Prüfung/Triage an. Es gibt RAPTOR-native Befunde sowie SBOM- und CI-freundliche Ausgaben aus:

- `findings.json` – kanonische RAPTOR-Befunde
- `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 der Cache befüllt ist, löst der Scanner Paket-IDs in lokale Dateien auf und es findet kein Netzwerkaufruf statt. Ohne den Cache versucht RAPTOR, Registry-Pakete zur Scan-Zeit von semgrep.dev abzurufen; wenn offline, verwirft es ungecachte Pakete elegant und läuft nur mit benutzerdefinierten Regeln.

CodeQL benötigt Netzwerkzugriff nur während der anfänglichen Einrichtung, um die CLI und Query-Pakete herunterzuladen. Einmal installiert, läuft es offline.

---

## Benutzerdefinierte Regeln

RAPTOR enthält über 200 benutzerdefinierte statische Analyse-Regeln, die adversarially getestet wurden, um False Positives zu eliminieren:

- **Semgrep (145 Regeln)** — Taint-Tracking- und Pattern-Regeln für Python, Go, Java und JS/TS. Abdeckung von 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, schwacher Kryptografie, unsicherem TLS und hartcodierten Secrets.
- **Coccinelle (63 Regeln)** — strukturelles Matching für C/C++. Speichersicherheit (Double Free, Use-after-Free, Free von Nicht-Basis-Pointern, Free von Stack-Arrays, mmap'd Speicher, Use-after-Close), Integer-Bugs (Overflow, Sign Extension, Double sizeof), Ressourcenlecks (popen/fclose-Mismatch, fdopendir Double Close), Pufferbehandlung (strncpy ohne NUL, copy_user-Größenmismatch, malloc/strlen Off-by-One), Signal-Handler-Sicherheit, API-Missbrauch (fcntl-Flag-Domain, SIGKILL/SIGSTOP, Double 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 Queries)** — 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).

Durchsuchen Sie die Regeln direkt: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Diese ergänzen die Semgrep-Registry-Pakete, die RAPTOR einzieht (`p/security-audit`, `p/owasp-top-ten`, `p/secrets` immer; pro Policy-Gruppe zusätzliche Pakete wie `p/command-injection`, `p/jwt`, `p/xss`) — die Überschneidung ist minimal.

---

## Wie RAPTOR sich selbst prüft

RAPTOR nutzt einen guten Teil seiner eigenen Sicherheitswerkzeuge selbst (Dogfooding), aber es ist wichtig, ehrlich zu sein, was tatsächlich einen PR blockiert und was nur im Hintergrund läuft, um uns ehrlich zu halten. Einiges davon ist ein harter Gate, einiges ist ein geplanter Check, und einiges ist nur ein Benchmark, den wir behalten, um zu erkennen, wann wir Dinge verschlechtert haben. Die ausführlichere Aufschlüsselung, einschließlich der tatsächlichen Parameter und wie die Checks reproduziert werden, finden Sie in `docs/ci-controls.md`.

| Kontrolle | Was geprüft wird | Auslöser | Konfiguration / Nachweis |
|---|---|---|---|
| Ruff | Python-Korrektheits-Linting (`F401`, `F811`, `F821`, `F841`) | PR-Diff-Gate, plus wöchentlicher Full-Tree-Audit | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | Schnelle Unit-/Integrationsgrenzen, subsystem-spezifische Stufen (über Import-Graph-Dispatch), Prompt-Envelope-Audit | PRs, Pushes auf `main`, Merge-Queue, geplante vollständige Suite | `pytest.ini`, `.github/workflows/tests.yml`, `.github/workflows/nightly.yml` |
| CodeQL Advanced | Python-, C/C++- und GitHub-Actions-Code-Scanning mit Import-Graph-Scope-Verengung | PRs, Pushes auf `main`, Merge-Queue, wöchentlicher Zeitplan | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| Workflow-Härtung | SHA-gepinnte Drittanbieter-Actions, Least-Privilege-Berechtigungen, Command-Metadaten-Linting | Jede Workflow-Änderung und jeder Lint-Lauf | `.github/workflows/`, `.github/scripts/check_command_metadata.py` |
| Corpus-Label-Lint | Audit-Corpus-Label-Schema-Validierung und Upstream-Pin-Verifizierung | PRs (geänderte Labels), wöchentlicher Voll-Sweep | `.github/workflows/corpus-labels.yml` |
| RAPTOR SCA PR-Gate | Abhängigkeits- und Supply-Chain-Regressionen, die durch einen PR eingeführt werden | Manifest-/Lockfile-/Workflow-Änderungen | `.github/workflows/sca-pr-gate.yml` |
| RAPTOR SCA Self-Bump | Mechanische Abhängigkeits-Härtung und sichere Upgrade-Vorschläge | Wöchentlicher Zeitplan, manueller Lauf | `.github/workflows/sca-self-bump.yml` |
| SCA-Kompromiss-Corpus | Ob bekannte Abhängigkeits-Kompromittierungen weiterhin das erwartete Signal auslösen | Wöchentlicher Zeitplan, relevante PR-Änderungen | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| Miswiring-Scan | Dead-Code-/Falsch-Aufruf-Erkennung, Env-Var-Dokumentationsdrift, Vokabellisten-Guardrails, Optional-Dep-Import-Lint | Täglicher Zeitplan | `.github/workflows/miswiring-scan.yml`, `.github/scripts/*_baseline.json` |
| SCA-Kalibrierung + Stress-Corpus | Ob Risiko-Scoring und Parser-Abdeckung im Laufe der Zeit driften | Wöchentliche / monatliche geplante Jobs | `packages/sca/data/calibration/`, `.github/workflows/refresh-sca-calibration.yml`, `.github/workflows/sca-stress-sweep.yml` |
| Dataflow-Corpus | Precision-/Recall-/FP-Kategorie-Tracking für Validator-Verhalten | Entwickler-ausgeführter Benchmark und Corpus-Tests | `core/dataflow/corpus/`, `core/dataflow/scripts/corpus-metrics` |
| CI-Controls-Doc-Guard | Dokumentierte Pfade existieren, Ruff-Konfiguration stimmt überein, README verlinkt auf das Doc | PRs | `.github/tests/test_ci_controls_docs.py` |

Derzeit nicht erzwungen: `mypy` ist in `requirements-dev.txt` installiert, blockiert aber nichts; Ruff-Formatierung wird nicht erzwungen; Semgrep ist Teil der Scanner-Oberfläche von RAPTOR, aber wir haben noch keinen dedizierten „RAPTOR mit RAPTOR scannen"-Semgrep-Workflow.

---

## Verwendung eines anderen LLM

RAPTOR hat zwei getrennte Modell-Ebenen, und es ist wichtig zu wissen, wie beide funktionieren, bevor Sie etwas ändern.

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

Die **Analyse-Dispatch-Ebene** ist das LLM, das einzelne Schwachstellen-Befunde analysiert. Diese ist getrennt von der Orchestrierungs-Ebene und kann jeder unterstützte Provider 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 | Funktion |
|------|-------------|
| `analysis` | Validiert und analysiert jeden Befund (Stufen A-F) |
| `code` | Schreibt Exploit-PoCs und Patch-Code |
| `consensus` | Zweitmeinungs-Abstimmung über echte Positivbefunde |
| `aggregate` | Optional. LLM-geschriebene narrative Synthese zusätzlich zur deterministischen Multi-Modell-Korrelation, geschrieben in `aggregation.json` und den finalen `agentic-report.md` |
| `fallback` | Wird verwendet, wenn das primäre Modell ausfällt oder Ratenlimits erreicht |

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

Ollama eignet sich für Analysen, erzeugt aber unzuverlässigen Exploit- und Patch-Code. Verwenden Sie für Codegenerierungsaufgaben ein Frontier-Modell.

### Fast-Tier-Short-Circuit + die Modell-Bewertungstabelle

Wenn Ihr Analyse-Tier-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 Vorfilter für Consumer, die in das Substrat eingebunden sind (derzeit CodeQL; SCA und weitere folgen später). Das günstige Modell greift nur bei **sicheren False Positives** ein; mehrdeutige Fälle und sichere True Positives durchlaufen immer die vollständige Analyse. Vertrauen akkumuliert pro `(Modell, Entscheidungsklasse)`-Zelle — RAPTOR zeichnet die Übereinstimmung zwischen günstigem und vollem Modell auf und greift erst ein, wenn die obere Wilson-95%-Grenze für die Fehlerquote 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 Bewertungstabelle ist global (Erkenntnisse übertragen sich über Projekte hinweg) und wird unter `out/llm_scorecard.json` gespeichert.

---

## Projekte

Ohne ein Projekt erhält jeder Lauf sein eigenes, mit Zeitstempel versehenes Verzeichnis unter `out/`. Mit einem Projekt geht alles an einen Ort, und Sie erhalten zusammengeführte Ergebnisse, Abdeckungsverfolgung sowie Diffs zwischen Lä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 du die Python-Ebene aus einer CI-Pipeline ausführen kannst (`python3 raptor.py scan --repo ...`) und strukturierte SARIF-Ausgabe ohne Claude Code erhältst, oder sie interaktiv mit dem vollständigen agentischen Workflow ausführen kannst.

---

## OSS-Forensik

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

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

---

## Experten-Personas

Sieben Experten-Personas sind auf Abruf verfügbar. Lade eine, wenn du eine andere Perspektive auf einen Befund oder eine bestimmte Technik möchtest:```
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