╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             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 der empfohlene Weg, um eine Sitzung zu starten, und er funktioniert aus jedem Verzeichnis -- er ermittelt die RAPTOR-Installation, 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 aus, lädt das Coverage-Tracking-Plugin 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, kein Coverage-Tracking, 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 daran zu hindern, auf Bereiche deines Dateisystems zuzugreifen, auf die sie nicht zugreifen sollen, sowie um den Schadensradius von bösartigem Code zu begrenzen, der ausgeführt werden könnte (z. B. über einen Supply-Chain-Angriff). Das Image ist groß (etwa 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 Repo) beim Start in `/workspaces/raptor` eingebunden wird. Optional können Sie einen Zielordner für die lokale Analyse einbinden.

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

Fügen Sie `--privileged` hinzu, wenn Sie den deterministischen Debugger `rr` benötigen.

VS Code Devcontainers werden ebenfalls unterstützt. Um einen Zielordner einzubinden, fügen Sie ihn zum Abschnitt `mounts` von `.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 dich im Container befindest, führe `raptor` aus, um zu starten.

---

## Was dich beim ersten Durchlauf erwartet

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

Dies führt die vollständige Pipeline aus: Scannen, Deduplizieren und dann jeden Fund durch die Validierungsstufen (A-F) schicken. Bei einer mittelgroßen Codebasis mit ~50 Funden sind 10-30 Minuten und 2-8 $ an LLM-Kosten der Analyseebene zu erwarten (je nach Modell). Die standardmäßige Kostengrenze liegt bei 10 $ pro Lauf; anpassbar mit `--max-cost-usd`.

**Kostenhinweis:** Die Orchestrierungsebene von Claude Code nutzt dein Claude-Abonnement. Die Dispatch-Ebene der Analyse führt separate LLM-API-Aufrufe durch, die pro Token abgerechnet werden. Wenn du Claude Code nur als Analysemodell verwendest (der Standard), entstehen keine zusätzlichen Kosten über dein Abonnement hinaus. Wenn du externe Modelle konfigurierst (OpenAI, Gemini usw.), werden diese API-Aufrufe den jeweiligen Anbietern in Rechnung gestellt.

---

## Sicherheitsmodell

RAPTOR führt LLM-generierten Code aus und analysiert nicht vertrauenswürdige Repositories. Subprozesse, die nicht vertrauenswürdige Inhalte verarbeiten, werden mit Linux-Namespaces, Landlock und seccomp in einer Sandbox isoliert. Die Sandbox blockiert Netzwerkzugriff, schränkt die Dateisystem-Sichtbarkeit 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 Subprozess-Aufrufe verwenden listenbasierte Argumente.

---

## Was RAPTOR kann

| Befehl | Was er tut | 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, nach Schwachstellenvarianten suchen | Stabil |
| `/binary` | Black-Box-Binäruntersuchung, Laufzeitnachweise, Graph-Abfragen und Übergabe | Beta |
| `/ghidra` | Ghidra-RE-Brücke: `.gpr`-Projekte anhängen/importieren, versionsübergreifender Diff, Export von Funden | Beta |
| `/audit` | Hypothesengetriebene, werkzeuggestützte systematische Code-Überprüfung | Beta |
| `/review` | Audit-Status abfragen: Funde, Lücken, Abdeckung, Betreibernotizen | Stabil |
| `/annotate` | Freiform-Prosa-Annotationen pro Funktion anhängen (Betreiber-Review-Notizen) | Stabil |
| `/validate` | Mehrstufige Pipeline zur Validierung der Ausnutzbarkeit (Stufen 0-F) | Stabil |
| `/diagram` | Visuelle Mermaid-Karten aus den JSON-Ausgaben von `/understand` und `/validate` | Beta |
| `/codeql` | CodeQL-exklusive Tiefenanalyse mit SMT-Datenfluss-Vorprüfung | Stabil |
| `/analyze` | Vorhandene SARIF-Funde mit LLM analysieren, ohne erneutes Scannen | Stabil |
| `/openant` | OpenAnt-LLM-Quellcode-Scan: AST-Analyse plus LLM-Reasoning pro Funktion | Beta |
| `/sca` | Software-Composition-Analyse: Abhängigkeiten, Advisories, Lieferketten-Signale, SBOMs und Fixes | Beta |
| `/cve-diff` | Den Fix-Commit für eine CVE über OSV, NVD, GitHub und GitLab finden und diffen | Beta |
| `/cve-env` | Eine 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` | Binäres Fuzzing mit AFL++ und Crash-Analyse | Stabil |
| `/crash-analysis` | Autonome Ursachenanalyse für C/C++-Abstürze | Stabil |
| `/oss-forensics` | Evidenzbasierte forensische Untersuchung für GitHub-Repositories | Stabil |
| `/project` | Benannte Arbeitsbereiche zum Organisieren von Läufen und Verfolgen von Funden über die Zeit | Stabil |
| `/describe` | Ein Ziel beschreiben: Sprachmix, Build-System, Werkzeuglücken, Kostenschätzung (schreibgeschützt) | Stabil |
| `/threat-model` | Bedrohungsmodelle pro Projekt erstellen, einsehen und pflegen | Stabil |
| `/sage` | Persistente Gedächtnisschicht (speichern, abrufen, verknüpfen, bestätigen) | Stabil |
| `/ask` | Einen Freiform-Prompt an ein beliebiges konfiguriertes LLM-Modell senden | Stabil |
| `/scorecard` | Zuverlässigkeit pro Modell über Entscheidungsklassen hinweg einsehen | Stabil |
| `/frida` | Dynamische Instrumentierung über Frida | Alpha |
| `/web` | Webanwendungs-Scanning: Crawling, ffuf/nuclei-Integration, oracle-verifizierte Injection, Blind-SSRF-Callbacks | Beta |

---

## Wie die Pipeline funktioniert

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 von Einstiegspunkten, Vertrauensgrenzen und Senken, bevor eine Zeile des Scannens stattfindet. `/agentic` führt dann Semgrep und CodeQL aus, dedupliziert Befunde und leitet jeden einzelnen zur Validierung mithilfe 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. Bestehende Bedrohungsmodelle des Projekts bleiben erhalten, es sei denn, du übergibst `--threat-model-refresh`; veraltete Fallback-Karten werden abgelehnt, es sei denn, du übergibst explizit `--threat-model-use-stale`. Außerdem wandelt es kartierte ungeprüfte Flüsse in Kandidaten-SARIF um, damit Scanner-Fehlschläge den Lauf nicht beenden. Es ist betreibereigener Kontext, kein magischer Beweis: Befunde benötigen weiterhin Code-Belege 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 muss ein Angreifer tun, 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, benötigt er unrealistische Vorbedingungen, weicht das Modell aus?
- Stufe E: Binäre Exploit-Machbarkeit (wenn ein kompiliertes Artefakt verfügbar ist)
- Stufe F: Selbstüberprüfung -- hat eine frühere Stufe ausgewichen oder sich selbst widersprochen?

Befunde, die die Validierung bestehen, erhalten Exploit-PoCs und generierte 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 du bereits Befunde aus einem vorherigen Scan hast.

Für ein kompiliertes Artefakt führt `/binary <path>` nun eine evidenzbasierte Untersuchung durch, anstatt einen Haufen roher Reverse-Engineering-Artefakte auf den Operator zu werfen. Darunter erstellt es weiterhin das SHA-256-gebundene Manifest, das Evidenz-Ledger, die Kontextkarte, die Checkliste und den SQLite-Graphen aus Dateimetadaten, Imports und radare2-Xrefs. Mach-O-Apps erhalten außerdem ein Slice-Inventar, Bundle-Metadaten und Objective-C-/Swift-Klassenselektoren; hochwertiger Pseudocode wird persistiert, anstatt während des Laufs zu verschwinden. PE-DLL-Exporte, Windows-Treiber-Dispatcher und Linux-Kernelmodul-ioctl-Handler werden ebenfalls als eigene Ingress-Kandidaten behandelt, wobei die PE-Architektur aus dem COFF-Header gelesen und nicht geraten wird. Die Untersuchungsschicht fragt dann diesen Graphen ab, priorisiert externen Ingress vor generischen Senken-Hinweisen, entdeckt deklarierte Helfer-/Geschwister-Binärdateien und schreibt einen kompakten Bericht, der in Fakten, strukturelle Schlussfolgerungen und unbewiesene Hypothesen unterteilt ist. 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 Aufrufgraphen 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 vorzugeben, dass dies ein Taint-Beweis ist. `/binary trace-parser <run-dir>` ist die explizite dynamische Fortsetzung: Es führt den engen Frida-Parser-Trace aus und aktualisiert dann dieselbe Kontextkarte, den Handoff, den Graphen und den 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 Kandidatenquellcode aus, wenn der ABI- oder IOCTL-Vertrag explizit ist. Es schwindelt sich nicht von „`memcpy` existiert" zu „dies ist ausnutzbar": Imports, Selektoren und Aufrufkanten bleiben Kandidaten, bis etwas Mechanisches mehr beweist. Siehe `docs/binary-analysis.md`.

---

## Software Composition Analysis

`/sca` analysiert die Abhängigkeits- und Lieferkettenseite eines Projekts. Es ist nicht nur ein CVE-Lookup in einer Requirements-Datei: RAPTOR entdeckt Manifeste, Lockfiles, Inline-Installationsbefehle, Workflow-Abhängigkeiten und Paketquellen von Containern/Basis-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-Evidenzsignalen, Hygiene-Prüfungen, Lieferketten-Heuristiken, Lizenzrichtlinien-Befunden und optionaler LLM-Überprüfung/-Triage an. Er 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 Pack-IDs in lokale Dateien auf und es findet kein Netzwerkaufruf statt. Ohne den Cache versucht RAPTOR, Registry-Packs zur Scan-Zeit von semgrep.dev abzurufen; wenn offline, werden nicht gecachte Packs ordnungsgemäß verworfen und nur mit benutzerdefinierten Regeln ausgeführt.

CodeQL benötigt Netzwerkzugriff nur während der Ersteinrichtung, um die CLI und Query-Packs herunterzuladen. Nach der Installation läuft es offline.

---

## Benutzerdefinierte Regeln

RAPTOR liefert über 200 benutzerdefinierte Regeln zur statischen Analyse mit, die adversarial getestet wurden, um False Positives zu eliminieren:

- **Semgrep (~150 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 Secrets ab.
- **Coccinelle (68 Regeln)** — strukturelles Matching für C/C++. Memory Safety (Double Free, Use-after-Free, Free eines Nicht-Basis-Zeigers, Free eines Stack-Arrays, mmap'd Memory, Use-after-Close), Integer-Bugs (Overflow, Sign Extension, doppeltes sizeof), Ressourcenlecks (popen/fclose-Mismatch, fdopendir Double Close), Buffer-Handling (strncpy ohne NUL, copy_user Size-Mismatch, malloc/strlen Off-by-One), Signal-Handler-Sicherheit, API-Missbrauch (fcntl-Flag-Domain, SIGKILL/SIGSTOP, doppelter Byte-Swap, inet_ntoa statischer Buffer), Compiler Dead-Store-Elimination, 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).

Die Regeln direkt durchsuchen: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Diese ergänzen die Semgrep-Registry-Packs, die RAPTOR einbindet (`p/security-audit`, `p/owasp-top-ten`, `p/secrets` immer; zusätzlich policy-gruppenspezifische Packs wie `p/command-injection`, `p/jwt`, `p/xss`) — die Überschneidung ist minimal.

---

## Wie RAPTOR sich selbst prüft

RAPTOR verwendet einen guten Teil seines eigenen Security-Toolings für sich selbst, aber es lohnt sich, ehrlich zu sein darüber, was tatsächlich einen PR blockiert und was nur im Hintergrund läuft, um uns ehrlich zu halten. Einiges davon ist ein hartes Gate, einiges ist ein geplanter Check, und einiges ist nur ein Benchmark, den wir beibehalten, damit wir erkennen können, wann wir etwas verschlechtert haben. Die ausführlichere Aufschlüsselung, einschließlich der tatsächlichen Parameter und wie man die Checks reproduziert, findet sich in `docs/ci-controls.md`.

| Control | Was geprüft wird | Auslöser | Konfiguration / Nachweis |
|---|---|---|---|
| Ruff | Python-Korrektheits-Linting (`F401`, `F811`, `F821`, `F841`) | PR-Diff-Gate, plus wöchentliches Full-Tree-Audit | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | Schnelle Unit-/Integration-Grenzen, subsystem-spezifische Tiers (via 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-Narrowing | PRs, Pushes auf `main`, Merge Queue, wöchentlicher Zeitplan | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| Workflow-Härtung | SHA-gepinnte Third-Party-Actions, Least-Privilege-Berechtigungen, Command-Metadata-Linting | Jede Workflow-Änderung und jeder Lint-Lauf | `.github/workflows/`, `.github/scripts/check_command_metadata.py` |
| Corpus-Label-Lint | Validierung des Audit-Corpus-Label-Schemas und Verifikation der Upstream-Pins | PRs (geänderte Labels), wöchentlicher vollständiger Sweep | `.github/workflows/corpus-labels.yml` |
| RAPTOR SCA PR Gate | Durch einen PR eingeführte Dependency- und Supply-Chain-Regressionen | Manifest- / Lockfile- / Workflow-Änderungen | `.github/workflows/sca-pr-gate.yml` |
| RAPTOR SCA Self-Bump | Mechanische Dependency-Härtung und Vorschläge für sichere Upgrades | Wöchentlicher Zeitplan, manueller Lauf | `.github/workflows/sca-self-bump.yml` |
| SCA Compromise Corpus | Ob bekannte Dependency-Kompromittierungen noch das erwartete Signal auslösen | Wöchentlicher Zeitplan, relevante PR-Änderungen | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| Repo-Invariant-Detektoren | Dead-Code- / Wrong-Call-Erkennung, Drift der Env-Var-Dokumentation, Guardrails für Vokabular-Listen, kanonische JSON-Byte-Formen, Optional-Dep-Import-Lint | PR-Gate (`lint.yml` `repo-invariants`-Job), plus täglicher Sweep | `.github/workflows/lint.yml`, `.github/workflows/miswiring-scan.yml`, `.github/scripts/*_baseline.json` |
| SCA-Kalibrierung + Stress-Corpus | Ob Risk-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 | Von Entwicklern 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 das Dokument | PRs | `.github/tests/test_ci_controls_docs.py` |

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

---

## Verwendung eines anderen LLM

RAPTOR hat zwei separate Modellschichten, und es lohnt sich zu wissen, wie beide funktionieren, bevor man etwas ändert.

Die **Orchestrierungsschicht** ist Claude Code -- aber nur für die interaktive `raptor`-Shell (diese konversationelle Slash-Command-Schicht). Die CLAUDE.md, Skills und Commands laufen dort alle als Claude-Code-Anweisungen. Um zu ändern, welches Claude-Modell diese Schicht orchestriert, verwende das `--model`-Flag von Claude Code oder den `/model`-Befehl innerhalb einer Session. Wenn du diese Schicht überhaupt nicht willst, siehe [Vollständig eigenständig ausführen](#running-fully-standalone-no-claude-code) unten.

Die **Analyse-Dispatch-Schicht** ist das LLM, das einzelne Vulnerability-Findings analysiert. Diese ist von der Orchestrierungsschicht getrennt und kann ein beliebiger unterstützter Provider sein. Konfiguriere 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"
    }
  ]
}

Modellrollen ermöglichen es dir, verschiedene Modelle verschiedenen Aufgaben zuzuweisen:

| Rolle | Was sie tut |
|------|-------------|
| `analysis` | Validiert und analysiert jeden Fund (Stufen A-F) |
| `code` | Schreibt Exploit-PoCs und Patch-Code |
| `consensus` | Zweitmeinungs-Abstimmung über echte Positive |
| `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 fehlschlägt oder Rate-Limits erreicht |

Wenn keine Rollen festgelegt sind, übernimmt das erste Modell in der Liste alles. Für Multi-Modell-
Quellcode-Analyse konfiguriere zwei oder mehr `analysis`-Modelle — du erhältst
standardmäßig die deterministische Korrelation. Die `aggregate`-Rolle ist optional und fügt eine
LLM-geschriebene Zusammenfassung obendrauf 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 gut für die Analyse; die Zuverlässigkeit bei der Generierung von Exploit-/Patch-Code hängt eher von Modellgröße und Quantisierung ab als von einer festen Eigenschaft lokaler Modelle — siehe [Quality Tradeoffs](https://github.com/gadievron/raptor/blob/main/llm.md#quality-tradeoffs) im LLM-Leitfaden und prüfe `/scorecard`, um zu sehen, was dein spezifisches Modell tatsächlich misst.

### Vollständig eigenständig ausführen (ohne Claude Code)

`bin/raptor` -- die interaktive Shell mit Banner und Slash-Befehlen, also diese konversationelle Ebene -- führt direkt in die Claude Code CLI aus und benötigt immer einen eigenen Login. Die eigentliche Mechanik darunter nicht: `python3 raptor.py <mode>` ist eine reine Python-CLI ohne jegliche Claude-Code-Abhängigkeit.```bash
# No `claude` process involved at any point
python3 raptor.py doctor                        # status check -- explicitly "no claude needed"
python3 raptor.py agentic --repo /path/to/code   # scan -> dedup -> analysis
python3 raptor.py scan --repo /path/to/code

Richte `models.json` / `OLLAMA_HOST` auf eine lokale Ollama-Instanz aus (siehe oben), und dieser gesamte Pfad spricht nie mit Anthropic -- nützlich für airgapped Boxen oder rein lokale Hardware. Du verlierst die konversationelle Slash-Command-Ebene (dieser Chat); die Scan-/Analyse-/Exploit-Pipeline selbst ist davon nicht betroffen.

### Fast-Tier-Kurzschluss + das Modell-Scorecard

Wenn dein 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 (heute codeql; SCA und andere, sobald Follow-ups landen). Das günstige Modell schließt nur bei **sicheren False Positives** kurz; mehrdeutige Fälle und sichere TPs durchlaufen immer die vollständige Analyse. Vertrauen akkumuliert sich pro `(model, decision_class)`-Zelle — RAPTOR zeichnet die Übereinstimmung zwischen günstig und vollständig auf und schließt erst dann kurz, wenn die Wilson-95%-Obergrenze der Fehlerrate der Zelle bei oder unter 5% liegt.

Um zu prüfen, worin deine Modelle gut sind, verwende `/scorecard` (oder direkt: `libexec/raptor-llm-scorecard list`). Die Scorecard ist global (Lektionen werden über Projekte hinweg übernommen) und wird unter `out/llm_scorecard.json` persistiert.

---

## Projekte

Ohne ein Projekt erhält jeder Lauf sein eigenes zeitgestempeltes Verzeichnis unter `out/`. Mit einem Projekt geht alles an einen Ort, und du erhältst zusammengeführte Findings, Coverage-Tracking und 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 Sie die Python-Schicht aus einer CI-Pipeline heraus 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 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. Siehe `.claude/commands/oss-forensics.md` für Details.

---

## Experten-Personas

Acht Experten-Personas sind auf Abruf 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
Web Researcher (James Kettle)                  Web endpoint research (smuggling, cache poisoning, SSRF)
Fuzzing Strategist                             Corpus design and triage
Binary Exploitation Specialist                 ROP, heap, and memory corruption

Wenn `/web`, Z3, SAGE und Cloud-Provider-SDKs als optionale Extras beibehalten werden, wird verhindert, dass die Standardinstallation von RAPTOR schwerer und fehleranfälliger wird als nötig.