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

Il launcher `raptor` è il metodo consigliato per avviare una sessione e funziona da qualsiasi directory: risolve l'installazione di RAPTOR, ricorda la directory da cui hai lanciato (così comandi come `/scan` la usano come predefinita), esegue i controlli pre-flight di trust e progetto, carica il plugin di tracciamento della copertura e igienizza l'ambiente prima di passare il controllo a Claude Code. Accetta anche un percorso target opzionale e flag come `--project`, `--continue` e `--model` — vedi `raptor --help`.

Eseguire semplicemente `claude` dall'interno della directory del repository funziona comunque — Claude Code rileva la configurazione di RAPTOR dal checkout — ma salti tutto ciò che fa il launcher sopra: niente controlli pre-flight, niente tracciamento della copertura, e i comandi che usano come predefinita "la directory da cui hai eseguito" non riescono a vederla.

**Importante:** RAPTOR carica la sua configurazione dalla directory del repository. Se esegui `claude` da qualsiasi altra directory, ottieni il semplice Claude Code, non RAPTOR. Il launcher `raptor` evita del tutto questa modalità di errore.

### Opzione 2: Esegui in un container (consigliato)

L'uso dei container è una pratica di sicurezza comune per impedire agli agenti di accedere ad aree del tuo filesystem a cui non vuoi che accedano, oltre a limitare il raggio d'esplosione di qualsiasi codice dannoso che possa essere eseguito (ad esempio tramite attacco alla supply chain). L'immagine è grande (circa 6 GB). Parte dal devcontainer Microsoft Python 3.12 e aggiunge strumenti di analisi statica, fuzzing e automazione del browser.

Puoi scaricare un'immagine pre-costruita:```bash
docker pull danielcuthbert/raptor:latest

L'immagine prevede che il framework RAPTOR (questo repository) venga montato in `/workspaces/raptor` all'avvio. Puoi opzionalmente montare una cartella di destinazione per l'analisi locale.

Per avviare il container:```bash
docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

Aggiungi `--privileged` se hai bisogno del debugger deterministico `rr`.

Anche i devcontainer di VS Code sono supportati. Per montare una cartella di destinazione, aggiungila alla sezione `mounts` di `.devcontainer/devcontainer.json`:```jsonc
"mounts": [
  // ...existing entries...
  "source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]

In ogni caso, una volta dentro il container, esegui `raptor` per iniziare.

---

## Cosa aspettarsi al primo avvio

La cosa più semplice che puoi fare:```
/scan /path/to/code

Questo esegue l'intera pipeline: scansione, deduplicazione, poi invio di ogni risultato attraverso le fasi di validazione (A-F). Su una codebase di medie dimensioni con circa 50 risultati, aspettati 10-30 minuti e $2-8 di costi LLM del livello di analisi (a seconda del modello). Il limite di costo predefinito è $10 per esecuzione; regolalo con `--max-cost-usd`.

**Nota sui costi:** Il livello di orchestrazione Claude Code utilizza il tuo abbonamento Claude. Il livello di dispatch dell'analisi effettua chiamate API LLM separate che vengono fatturate per token. Se utilizzi solo Claude Code come modello di analisi (il default), non ci sono costi aggiuntivi oltre al tuo abbonamento. Se configuri modelli esterni (OpenAI, Gemini, ecc.), quelle chiamate API vengono fatturate a quei provider.

---

## Modello di sicurezza

RAPTOR esegue codice generato da LLM e analizza repository non attendibili. I sottoprocessi che gestiscono contenuti non attendibili sono isolati in sandbox utilizzando namespace Linux, Landlock e seccomp. La sandbox blocca l'accesso alla rete, limita la visibilità del filesystem e limita il consumo di risorse. Consulta `docs/sandbox.md` per il modello di minaccia completo e la configurazione.

Le variabili d'ambiente che potrebbero iniettare codice nella catena di lancio vengono rimosse all'avvio (`core/security/_dangerous_env_strip.sh`). I percorsi dei file provenienti dai repository scansionati non vengono mai interpolati in stringhe di shell — tutte le chiamate ai sottoprocessi utilizzano argomenti basati su liste.

---

## Cosa può fare RAPTOR

| Comando | Cosa fa | Stato |
|---------|-------------|--------|
| `/agentic` | Workflow autonomo completo: scansione, validazione, exploit, patch | Stabile |
| `/scan` | Analisi statica con Semgrep e CodeQL | Stabile |
| `/understand` | Mappatura della superficie d'attacco, tracciamento dei flussi di dati, ricerca di varianti di vulnerabilità | Stabile |
| `/binary` | Indagine binaria black-box, prove runtime, query sui grafi e handoff | Beta |
| `/ghidra` | Bridge RE Ghidra: allegazione/importazione di progetti `.gpr`, diff tra versioni, esportazione dei risultati | Beta |
| `/audit` | Revisione sistematica del codice guidata da ipotesi e basata su strumenti | Beta |
| `/review` | Query sullo stato dell'audit: risultati, lacune, copertura, note dell'operatore | Stabile |
| `/annotate` | Allegazione di annotazioni prosaiche libere per funzione (note di revisione dell'operatore) | Stabile |
| `/validate` | Pipeline di validazione dell'exploitabilità multi-fase (Fasi 0-F) | Stabile |
| `/diagram` | Mappe visive Mermaid dagli output JSON di `/understand` e `/validate` | Beta |
| `/codeql` | Analisi approfondita solo CodeQL con pre-screening del dataflow SMT | Stabile |
| `/analyze` | Analisi dei risultati SARIF esistenti con LLM, senza riscansione | Stabile |
| `/sca` | Analisi della composizione software: dipendenze, advisory, segnali di supply-chain, SBOM e fix | Beta |
| `/cve-diff` | Scoperta e diff del commit di fix per una CVE su OSV, NVD, GitHub e GitLab | Beta |
| `/cve-env` | Creazione e verifica di un ambiente Docker che esegue l'applicazione affetta da una CVE alla sua versione pre-patch | Sperimentale |
| `/exploit` | Generazione di codice proof-of-concept per exploit | Beta |
| `/patch` | Generazione di patch sicure per vulnerabilità confermate | Beta |
| `/fuzz` | Fuzzing binario con AFL++ e analisi dei crash | Stabile |
| `/crash-analysis` | Analisi autonoma della causa principale per crash C/C++ | Stabile |
| `/oss-forensics` | Indagine forense basata su prove per repository GitHub | Stabile |
| `/project` | Workspace nominati per organizzare le esecuzioni e tracciare i risultati nel tempo | Stabile |
| `/describe` | Descrizione di un target: mix di linguaggi, sistema di build, lacune degli strumenti, stima dei costi (sola lettura) | Stabile |
| `/threat-model` | Creazione, ispezione e manutenzione di modelli di minaccia per progetto | Stabile |
| `/sage` | Livello di memoria persistente (archivia, richiama, collega, corrobora) | Stabile |
| `/ask` | Invio di un prompt libero a qualsiasi modello LLM configurato | Stabile |
| `/scorecard` | Ispezione dell'affidabilità per modello nelle classi decisionali | Stabile |
| `/frida` | Strumentazione dinamica tramite Frida | Alpha |
| `/web` | Scansione di applicazioni web: crawling, integrazione ffuf/nuclei, iniezione verificata da oracle, callback SSRF ciechi | Beta |

---

## Come funziona la pipeline

Inizia creando un progetto così tutte le tue esecuzioni finiscono in un unico posto:```
/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` costruisce una mappa di contesto di punti di ingresso, confini di fiducia e sink prima che inizi una riga di scansione. `/agentic` esegue poi Semgrep e CodeQL, deduplica i risultati e li inoltra singolarmente per la validazione utilizzando la metodologia exploitation-validator:

Con `--threat-model`, RAPTOR esegue prima la mappa, crea `threat-model.json` e `THREAT_MODEL.md` se il progetto non li possiede già, quindi alimenta una versione compatta in `/understand`, analisi autonoma e `/validate`. I modelli di minaccia esistenti del progetto vengono preservati a meno che non si passi `--threat-model-refresh`; le mappe di fallback obsolete vengono rifiutate a meno che non si passi esplicitamente `--threat-model-use-stale`. Converte inoltre i flussi non controllati mappati in SARIF candidati, così le mancanze dello scanner non interrompono l'esecuzione. È contesto di proprietà dell'operatore, non una prova magica: i risultati richiedono comunque evidenza nel codice o conferma basata su oracolo. Vedi `docs/threat-model.md`.

- Fase A: il pattern è effettivamente una vulnerabilità, o il tool sta facendo pattern-matching su rumore?
- Fase B: di cosa ha bisogno un attaccante per raggiungerlo, e cosa si frappone?
- Fase C: il percorso di codice esiste davvero? può essere raggiunto dall'esterno?
- Fase D: decisione finale -- è codice di test, richiede precondizioni irrealistiche, il modello sta facendo hedging?
- Fase E: fattibilità dello sfruttamento binario (quando è disponibile un artefatto compilato)
- Fase F: auto-revisione -- una fase precedente ha fatto hedging o si è contraddetta?

I risultati che superano la validazione ricevono PoC di exploit e patch generati. Alla fine viene eseguita un'analisi trasversale dei risultati per trovare cause radice condivise e catene di attacco.

`/validate` esegue questa stessa pipeline come passaggio autonomo se hai già risultati da una scansione precedente.

Per un artefatto compilato, `/binary <path>` ora esegue un'indagine
evidence-first piuttosto che scaricare un mucchio di artefatti grezzi di
reverse-engineering sull'operatore. Sotto il cofano costruisce comunque il manifest vincolato a SHA-256,
il registro delle evidenze, la mappa di contesto, la checklist e il grafo SQLite da metadati di file,
import e xref di radare2. Le app Mach-O ricevono anche l'inventario delle slice, i metadati
del bundle e i selettori di classi Objective-C / Swift; il pseudocodice ad alto valore viene
persistito piuttosto che sparire all'interno dell'esecuzione. Le esportazioni di DLL PE, i dispatcher
di driver Windows e i gestori ioctl di moduli kernel Linux vengono gestiti come
candidati di ingresso propri, con l'architettura PE letta dall'header COFF
piuttosto che ipotizzata. Il livello di indagine interroga poi quel grafo,
classifica l'ingresso esterno prima dei lead generici di sink, scopre binari
helper/sibling dichiarati e scrive un report compatto suddiviso in fatti,
inferenze strutturali e ipotesi non provate. Osservazioni Frida, testimoni di crash da fuzz,
controlli Z3 espliciti e diff binari possono poi aggiungere evidenze più forti
in seguito. RAPTOR mantiene inoltre il grafo di chiamate interno necessario per recuperare
candidati limitati da ingresso a parser, così una callback di un'app può essere ristretta alla
funzione interna che effettivamente chiama `XML_Parse`, `d2i_X509`,
`jpeg_read_header` o un'altra superficie di parser reale senza fingere che sia
una prova di taint. `/binary trace-parser <run-dir>` è il follow-on dinamico esplicito:
esegue la traccia Frida ristretta del parser, poi aggiorna sul posto la stessa mappa di contesto,
l'handoff, il grafo e il report di indagine. `/binary investigate --active` mappa prima e lancia una vera
campagna di fuzz solo quando esiste un confine di harness concreto; i target app, DLL e
driver ricevono invece un passo di harness o snapshot. `/binary harness` scrive una
spec di harness basata su evidenze per l'ingresso scelto ed emette solo sorgente
candidata quando il contratto ABI o IOCTL è esplicito. Non tira a indovinare dal fatto che “`memcpy` esiste” a “questo è
sfruttabile”: import, selettori e archi di chiamata restano candidati finché
qualcosa di meccanico non prova di più. Vedi `docs/binary-analysis.md`.

---

## Software Composition Analysis

`/sca` analizza il lato dipendenze e supply-chain di un progetto. Non è solo una ricerca CVE sul file dei requisiti: RAPTOR scopre manifest, lockfile, comandi di installazione inline, dipendenze dei workflow e sorgenti di pacchetti di container/immagini base, poi li normalizza in una singola vista delle dipendenze.

La scansione arricchisce le dipendenze con advisory OSV, CISA KEV, EPSS, CISA Vulnrichment/SSVC, raggiungibilità, segnali di evidenza di exploit, controlli di igiene, euristiche di supply-chain, risultati delle policy di licenza e revisione/triage LLM opzionale. Emette risultati nativi RAPTOR più SBOM e output compatibile con CI:

- `findings.json` - risultati canonici RAPTOR
- `report.md` - riepilogo leggibile dall'uomo
- `sbom.cdx.json` - SBOM CycloneDX con dati VEX
- `findings.sarif` - output per code-scanning GitHub/GitLab

Comandi comuni:```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

Una volta popolata, la cache consente allo scanner di risolvere gli ID dei pacchetti in file locali e non viene effettuata alcuna chiamata di rete. Senza la cache, RAPTOR tenterà di recuperare i pacchetti del registro da semgrep.dev al momento della scansione; se è offline, elimina con garbo i pacchetti non memorizzati nella cache ed esegue solo con regole personalizzate.

CodeQL richiede accesso alla rete solo durante la configurazione iniziale per scaricare la CLI e i pacchetti di query. Una volta installato, funziona offline.

---

## Regole personalizzate

RAPTOR include oltre 200 regole personalizzate di analisi statica, testate in modo avversario per eliminare i falsi positivi:

- **Semgrep (145 regole)** — regole di taint-tracking e pattern per Python, Go, Java e JS/TS. Coprono SQLi, XSS, SSRF, SSTI, command injection, deserializzazione, XXE, iniezione LDAP/NoSQL, path traversal, open redirect, log/header injection, eval injection, ReDoS, prototype pollution, configurazione errata di JWT, crittografia debole, TLS insicuro e segreti hardcoded.
- **Coccinelle (63 regole)** — corrispondenza strutturale per C/C++. Sicurezza della memoria (double free, use-after-free, free di puntatore non-base, free di array sullo stack, memoria mmap, use-after-close), bug di interi (overflow, estensione del segno, doppio sizeof), perdite di risorse (mancata corrispondenza popen/fclose, doppia chiusura fdopendir), gestione dei buffer (strncpy senza NUL, mancata corrispondenza delle dimensioni in copy_user, off-by-one in malloc/strlen), sicurezza dei gestori di segnale, uso improprio delle API (dominio flag fcntl, SIGKILL/SIGSTOP, doppio byte-swap, buffer statico inet_ntoa), eliminazione di dead-store da parte del compilatore, confusione IS_ERR/PTR_ERR nel kernel, injection di stringhe di formato, race TOCTOU e altro.
- **CodeQL (8 query)** — taint-tracking interprocedurale per C++ (injection di stringhe di formato, troncamento di interi, use-after-move, invalidazione di iteratori) e Java (XXE, deserializzazione insicura, log injection, SSRF in Spring).

Sfoglia le regole direttamente: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Queste completano i pacchetti del registro Semgrep che RAPTOR recupera (`p/security-audit`, `p/owasp-top-ten`, `p/secrets` sempre; pacchetti per gruppo di policy come `p/command-injection`, `p/jwt`, `p/xss` in aggiunta) — la sovrapposizione è minima.

---

## Come RAPTOR verifica se stesso

RAPTOR utilizza internamente una buona parte dei propri strumenti di sicurezza, ma vale la pena essere onesti su cosa blocca effettivamente una PR e cosa viene eseguito solo in background per tenerci onesti. Parte di questo è un gate rigido, parte è un controllo pianificato e parte è solo un benchmark che manteniamo per capire quando abbiamo peggiorato le cose. La ripartizione completa, inclusi i parametri effettivi e come riprodurre i controlli, è in `docs/ci-controls.md`.

| Controllo | Cosa verifica | Trigger | Config / evidenza |
|---|---|---|---|
| Ruff | Linting di correttezza Python (`F401`, `F811`, `F821`, `F841`) | Gate sulle diff delle PR, più audit settimanale dell'intero albero | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | Confini rapidi di unit/integrazione, livelli specifici per sottosistema (tramite dispatch basato su import-graph), audit dell'envelope dei prompt | PR, push su `main`, merge queue, suite completa pianificata | `pytest.ini`, `.github/workflows/tests.yml`, `.github/workflows/nightly.yml` |
| CodeQL Advanced | Scansione del codice per Python, C/C++ e GitHub Actions con restrizione dell'ambito tramite import-graph | PR, push su `main`, merge queue, pianificazione settimanale | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| Hardening dei workflow | Action di terze parti con pin SHA, permessi con privilegio minimo, linting dei metadati dei comandi | Ogni modifica ai workflow e ogni esecuzione di lint | `.github/workflows/`, `.github/scripts/check_command_metadata.py` |
| Lint delle etichette del corpus | Validazione dello schema delle etichette del corpus di audit e verifica dei pin upstream | PR (etichette modificate), sweep completo settimanale | `.github/workflows/corpus-labels.yml` |
| Gate SCA sulle PR di RAPTOR | Regressioni di dipendenze e supply chain introdotte da una PR | Modifiche a manifest / lockfile / workflow | `.github/workflows/sca-pr-gate.yml` |
| Self-bump SCA di RAPTOR | Hardening meccanico delle dipendenze e proposte di upgrade sicure | Pianificazione settimanale, esecuzione manuale | `.github/workflows/sca-self-bump.yml` |
| Corpus di compromissione SCA | Se le compromissioni note delle dipendenze attivano ancora il segnale atteso | Pianificazione settimanale, modifiche PR pertinenti | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| Scansione miswiring | Rilevamento di dead-code / chiamate errate, deriva della documentazione delle variabili d'ambiente, guardrail dell'elenco di vocabolario, lint delle import opzionali dei pacchetti | Pianificazione giornaliera | `.github/workflows/miswiring-scan.yml`, `.github/scripts/*_baseline.json` |
| Calibrazione SCA + corpus di stress | Se il punteggio del rischio e la copertura del parser derivano nel tempo | Job pianificati settimanali / mensili | `packages/sca/data/calibration/`, `.github/workflows/refresh-sca-calibration.yml`, `.github/workflows/sca-stress-sweep.yml` |
| Corpus dataflow | Tracciamento di precision / recall / categoria FP per il comportamento del validator | Benchmark eseguito dagli sviluppatori e test del corpus | `core/dataflow/corpus/`, `core/dataflow/scripts/corpus-metrics` |
| Guardia del documento dei controlli CI | I percorsi documentati esistono, la configurazione di ruff corrisponde, il README collega al documento | PR | `.github/tests/test_ci_controls_docs.py` |

Attualmente non applicati: `mypy` è installato in `requirements-dev.txt` ma non blocca nulla; la formattazione Ruff non è applicata; Semgrep fa parte della superficie di scansione di RAPTOR, ma non abbiamo ancora un workflow dedicato "scansiona RAPTOR con RAPTOR" basato su Semgrep.

---

## Utilizzo di un LLM diverso

RAPTOR ha due livelli di modello separati, ed è utile sapere come funzionano entrambi prima di modificare qualsiasi cosa.

Il **livello di orchestrazione** è sempre Claude Code. CLAUDE.md, le skill e i comandi vengono tutti eseguiti come istruzioni di Claude Code. Per cambiare quale modello Claude orchestra RAPTOR, usa il flag `--model` di Claude Code o il comando `/model` all'interno di una sessione.

Il **livello di dispatch dell'analisi** è l'LLM che analizza i singoli risultati di vulnerabilità. Questo è separato dal livello di orchestrazione e può essere qualsiasi provider supportato. Configuralo 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"
    }
  ]
}

| Ruolo | Cosa fa |
|------|-------------|
| `analysis` | Valida e analizza ogni risultato (Fasi A-F) |
| `code` | Scrive PoC di exploit e codice di patch |
| `consensus` | Voto di seconda opinione sui veri positivi |
| `aggregate` | Opzionale. Sintesi narrativa scritta da LLM sopra la correlazione deterministica multi-modello, salvata in `aggregation.json` e nel report finale `agentic-report.md` |
| `fallback` | Usato se il modello primario fallisce o raggiunge i limiti di frequenza |

Se non vengono impostati ruoli, il primo modello nell'elenco gestisce tutto. Per l'analisi
del codice sorgente multi-modello, configura due o più modelli `analysis` — otterrai la
correlazione deterministica per impostazione predefinita. Il ruolo `aggregate` è opzionale e aggiunge
un riepilogo scritto da LLM sopra:```bash
python3 raptor.py agentic --repo /code \
  --model claude-opus-4-6 \
  --model gpt-5.4 \
  --aggregate claude-sonnet-4-6

Ollama funziona per l'analisi ma produce codice di exploit e patch inaffidabile. Per le attività di generazione di codice, usa un modello di frontiera.

### Short-circuit del livello veloce + la scorecard dei modelli

Quando il tuo modello del livello di analisi ha un fratello più economico dello stesso fornitore (Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), RAPTOR lo userà come pre-filtro sui consumer che si collegano al substrato (codeql oggi; SCA e altri come follow-up in arrivo). Il modello economico fa short-circuit solo su **falsi positivi con alta confidenza**; i casi ambigui e i veri positivi con alta confidenza eseguono sempre l'analisi completa. La fiducia si accumula per cella `(modello, classe_di_decisione)` — RAPTOR registra l'accordo economico-vs-completo e fa short-circuit solo quando il limite superiore di Wilson al 95% sul tasso di mancati rilevamenti della cella scende al 5% o sotto.

Per ispezionare in cosa sono bravi i tuoi modelli, usa `/scorecard` (o direttamente: `libexec/raptor-llm-scorecard list`). La scorecard è globale (le lezioni si trasferiscono tra progetti) e persiste in `out/llm_scorecard.json`.

---

## Progetti

Senza un progetto, ogni esecuzione ottiene la propria directory con timestamp sotto `out/`. Con un progetto, tutto finisce in un unico posto e ottieni risultati unificati, tracciamento della copertura e diff tra le esecuzioni.```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

La suddivisione consente di eseguire il livello Python da una pipeline CI (`python3 raptor.py scan --repo ...`) e ottenere output SARIF strutturato senza Claude Code, oppure eseguirlo in modo interattivo con il flusso di lavoro agentico completo.

---

## Analisi forense OSS

`/oss-forensics` indaga su repository GitHub pubblici utilizzando prove provenienti da più fonti: l'API GitHub, GH Archive (cronologia degli eventi immutabile tramite BigQuery), la Wayback Machine e la cronologia git locale. Esegue una pipeline strutturata dalla raccolta delle prove alla formulazione di ipotesi fino a un rapporto forense finale.

Richiede `GOOGLE_APPLICATION_CREDENTIALS` per l'accesso a BigQuery. Consulta `.claude/commands/oss-forensics.md` per i dettagli.

---

## Persona esperte

Sette persona esperte sono disponibili su richiesta. Caricane una quando desideri una prospettiva diversa su un risultato o una tecnica specifica:```
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