╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║             ██████╗  █████╗ ██████╗ ████████╗ ██████╗ ██████╗             ║
║             ██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗            ║
║             ██████╔╝███████║██████╔╝   ██║   ██║   ██║██████╔╝            ║
║             ██╔══██╗██╔══██║██╔═══╝    ██║   ██║   ██║██╔══██╗            ║
║             ██║  ██║██║  ██║██║        ██║   ╚██████╔╝██║  ██║            ║
║             ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝    ╚═════╝ ╚═╝  ╚═╝            ║
║                                                                           ║
║             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 modo consigliato per avviare una sessione, e funziona da qualsiasi directory -- risolve l'installazione di RAPTOR, ricorda la directory da cui è stato avviato (così comandi come `/scan` la usano come predefinita), esegue i controlli pre-flight di trust e di progetto, carica il plugin di coverage-tracking e sanifica 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 il semplice `claude` dall'interno della directory del repo funziona comunque -- Claude Code rileva la configurazione di RAPTOR dal checkout -- ma si saltano tutte le operazioni che il launcher esegue sopra: nessun controllo pre-flight, nessun coverage tracking, e i comandi che usano come predefinita "la directory da cui è stato eseguito" non riescono a vederla.

**Importante:** RAPTOR carica la sua configurazione dalla directory del repo. 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: Eseguire in un container (consigliato)

Usare i container è una pratica di sicurezza comune per limitare l'accesso degli agenti alle aree del filesystem a cui non vuoi che accedano, oltre a limitare il raggio d'azione di qualsiasi codice malevolo che potrebbe essere eseguito (ad esempio tramite attacco 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 repo) sia montato in `/workspaces/raptor` all'avvio. È possibile montare opzionalmente 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`.

Sono supportati anche i devcontainer di VS Code. 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, quindi invia ogni risultato attraverso le fasi di validazione (A-F). Su una codebase di medie dimensioni con ~50 risultati, prevedere 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 di 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 (l'impostazione predefinita), non ci sono costi aggiuntivi oltre al tuo abbonamento. Se configuri modelli esterni (OpenAI, Gemini, ecc.), tali chiamate API vengono fatturate a quei fornitori.

---

## Modello di sicurezza

RAPTOR esegue codice generato da LLM e analizza repository non attendibili. I sottoprocessi che gestiscono contenuti non attendibili sono isolati tramite 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 avvio vengono rimosse all'avvio (`core/security/_dangerous_env_strip.sh`). I percorsi dei file dai repository scansionati non vengono mai interpolati nelle stringhe di shell — tutte le chiamate ai sottoprocessi utilizzano argomenti basati su liste.

---

## Cosa può fare RAPTOR

| Comando | Cosa fa | Stato |
|---------|-------------|--------|
| `/agentic` | Flusso di lavoro autonomo completo: scansione, validazione, exploit, patch | Stabile |
| `/scan` | Analisi statica con Semgrep e CodeQL | Stabile |
| `/understand` | Mappa la superficie di attacco, traccia i flussi di dati, cerca varianti di vulnerabilità | Stabile |
| `/binary` | Indagine black-box su binari, evidenze runtime, query su grafi e handoff | Beta |
| `/ghidra` | Ponte RE Ghidra: collega/importa progetti `.gpr`, diff tra versioni, esportazione risultati | Beta |
| `/audit` | Revisione sistematica del codice guidata da ipotesi e basata su strumenti | Beta |
| `/review` | Interroga lo stato dell'audit: risultati, lacune, copertura, note dell'operatore | Stabile |
| `/annotate` | Allega annotazioni testuali libere per funzione (note di revisione dell'operatore) | Stabile |
| `/validate` | Pipeline di validazione multi-fase della sfruttabilità (Fasi 0-F) | Stabile |
| `/diagram` | Mappe visuali Mermaid dagli output JSON di `/understand` e `/validate` | Beta |
| `/codeql` | Analisi approfondita solo CodeQL con pre-screening del dataflow SMT | Stabile |
| `/analyze` | Analizza i risultati SARIF esistenti con LLM, senza ri-scansionare | Stabile |
| `/openant` | Scansione del codice sorgente con LLM OpenAnt: analisi AST più ragionamento LLM per funzione | Beta |
| `/sca` | Analisi della composizione software: dipendenze, advisory, segnali di supply-chain, SBOM e correzioni | Beta |
| `/cve-diff` | Scopri ed effettua il diff del commit di correzione per una CVE su OSV, NVD, GitHub e GitLab | Beta |
| `/cve-env` | Crea e verifica un ambiente Docker che esegue l'applicazione affetta da una CVE nella sua versione pre-patch | Sperimentale |
| `/exploit` | Genera codice exploit proof-of-concept | Beta |
| `/patch` | Genera patch sicure per vulnerabilità confermate | Beta |
| `/fuzz` | Fuzzing di binari con AFL++ e analisi dei crash | Stabile |
| `/crash-analysis` | Analisi autonoma della causa radice per crash C/C++ | Stabile |
| `/oss-forensics` | Indagine forense basata su evidenze per repository GitHub | Stabile |
| `/project` | Workspace denominati per organizzare le esecuzioni e tracciare i risultati nel tempo | Stabile |
| `/describe` | Descrive un target: mix di linguaggi, sistema di build, lacune negli strumenti, stima dei costi (sola lettura) | Stabile |
| `/threat-model` | Crea, ispeziona e mantiene modelli di minaccia per progetto | Stabile |
| `/sage` | Livello di memoria persistente (memorizza, richiama, collega, corrobora) | Stabile |
| `/ask` | Invia un prompt libero a qualsiasi modello LLM configurato | Stabile |
| `/scorecard` | Ispeziona l'affidabilità per modello attraverso le classi di decisione | Stabile |
| `/frida` | Strumentazione dinamica tramite Frida | Alpha |
| `/web` | Scansione di applicazioni web: crawling, integrazione ffuf/nuclei, injection verificata tramite oracle, callback SSRF cieche | Beta |

---

## Come funziona la pipeline

Inizia creando un progetto in modo che tutte le tue esecuzioni finiscano 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 entry point, trust boundary e sink prima che venga eseguita una sola riga di scansione. `/agentic` esegue poi Semgrep e CodeQL, deduplica i risultati e ne invia ciascuno per la validazione usando 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 ha già, quindi alimenta una versione compatta in `/understand`, nell'analisi autonoma e in `/validate`. I threat model esistenti del progetto vengono preservati a meno che tu non passi `--threat-model-refresh`; le mappe di fallback obsolete vengono rifiutate a meno che tu non passi esplicitamente `--threat-model-use-stale`. Inoltre trasforma i flussi non controllati mappati in SARIF candidato, così le mancanze degli scanner non uccidono l'esecuzione. È contesto di proprietà dell'operatore, non una prova magica: i risultati necessitano comunque di evidenza nel codice o di conferma supportata da oracle. Vedi `docs/threat-model.md`.

- Stage A: il pattern è davvero una vulnerabilità, o lo strumento sta facendo pattern-matching su rumore?
- Stage B: cosa serve a un attaccante per raggiungerlo, e cosa si frappone?
- Stage C: il percorso del codice esiste davvero? può essere raggiunto dall'esterno?
- Stage D: verdetto finale -- è codice di test, richiede precondizioni irrealistiche, il modello sta tergiversando?
- Stage E: fattibilità di exploit binario (quando è disponibile un artefatto compilato)
- Stage F: auto-verifica -- qualche stage precedente ha tergiversato o si è contraddetto?

I risultati che superano la validazione ottengono 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 step autonomo se hai già risultati da una scansione precedente.

Per un artefatto compilato, `/binary <path>` ora esegue un'indagine
evidence-first invece di scaricare un mucchio di artefatti grezzi di
reverse-engineering sull'operatore. Sotto il cofano costruisce comunque il manifest
vincolato a SHA-256, l'evidence ledger, la mappa di contesto, la checklist e il grafo SQLite
dai metadati del file, dagli import e dagli xref di radare2. Le app Mach-O ottengono anche
l'inventario degli slice, i metadati del bundle e i selettori di classe Objective-C / Swift;
il pseudocodice di alto valore viene persistito invece di sparire dentro l'esecuzione. Gli export
di DLL PE, i dispatcher dei driver Windows e gli handler ioctl dei moduli del kernel Linux sono
gestiti come candidati di ingresso a sé stanti, con l'architettura PE letta dall'header
COFF invece che indovinata. Il livello di indagine interroga poi quel grafo,
classifica gli ingressi esterni prima dei lead generici sui sink, scopre i binari
helper/sibling dichiarati e scrive un report compatto suddiviso in fatti,
inferenze strutturali e ipotesi non dimostrate. Le osservazioni Frida, i testimoni di crash
da fuzzing, i controlli Z3 espliciti e i diff binari possono poi aggiungere evidenze più forti
in seguito. RAPTOR conserva anche il call graph interno necessario per recuperare candidati
limitati da ingresso a parser, così una callback dell'app può essere ristretta alla
funzione interna che chiama effettivamente `XML_Parse`, `d2i_X509`,
`jpeg_read_header` o un'altra vera superficie di parser senza pretendere che sia
una prova di taint. `/binary trace-parser <run-dir>` è il seguito dinamico esplicito:
esegue il trace ristretto del parser Frida, poi aggiorna sul posto la stessa mappa di contesto,
il handoff, il grafo e il report di indagine. `/binary investigate --active` mappa prima e lancia una vera
campagna di fuzzing solo quando esiste un confine di harness concreto; i target app, DLL e driver
ottengono invece uno step di harness o snapshot. `/binary harness` scrive una
specifica di harness supportata da evidenze per l'ingresso scelto ed emette codice sorgente candidato
solo quando il contratto ABI o IOCTL è esplicito. Non si arrampica da "`memcpy` esiste" a "questo è
exploitabile": 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 di CVE nei 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 un'unica vista delle dipendenze.

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

- `findings.json` - risultati canonici RAPTOR
- `report.md` - riepilogo leggibile dall'uomo
- `sbom.cdx.json` - SBOM CycloneDX con dati VEX
- `findings.sarif` - output per il code-scanning di 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, lo scanner risolve gli ID dei pacchetti in file locali e non avviene alcuna chiamata di rete. Senza la cache, RAPTOR tenterà di recuperare i pacchetti del registry da semgrep.dev al momento della scansione; se offline, scarta i pacchetti non in cache in modo controllato e viene eseguito solo con le regole personalizzate.

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

---

## Regole personalizzate

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

- **Semgrep (~150 regole)** — regole di taint-tracking e pattern per Python, Go, Java e JS/TS. Coprono SQLi, XSS, SSRF, SSTI, command injection, deserializzazione, XXE, LDAP/NoSQL injection, path traversal, open redirect, log/header injection, eval injection, ReDoS, prototype pollution, misconfigurazione JWT, crittografia debole, TLS insicuro e segreti hardcoded.
- **Coccinelle (68 regole)** — matching strutturale per C/C++. Sicurezza della memoria (double free, use-after-free, free di puntatore non base, free di array su stack, memoria mmap'd, use-after-close), bug sugli interi (overflow, sign extension, double sizeof), leak di risorse (mismatch popen/fclose, doppia chiusura fdopendir), gestione dei buffer (strncpy senza NUL, mismatch di dimensione copy_user, off-by-one malloc/strlen), sicurezza dei signal handler, uso improprio delle API (dominio dei flag fcntl, SIGKILL/SIGSTOP, doppio byte-swap, buffer statico inet_ntoa), dead-store elimination del compilatore, confusione kernel IS_ERR/PTR_ERR, format string injection, race TOCTOU e altro ancora.
- **CodeQL (8 query)** — taint tracking interprocedurale per C++ (format string injection, integer truncation, use-after-move, iterator invalidation) e Java (XXE, deserializzazione insicura, log injection, Spring SSRF).

Sfoglia direttamente le regole: `engine/semgrep/rules/`, `engine/coccinelle/rules/`, `engine/codeql/queries/`. Queste integrano i pacchetti del registry 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 gran parte del proprio tooling di sicurezza su se stesso, ma vale la pena essere onesti su cosa effettivamente blocca una PR e cosa viene semplicemente eseguito in background per tenerci onesti. Parte di questo è un gate rigido, parte è un controllo pianificato, e parte è solo un benchmark che teniamo in giro per poter capire quando abbiamo peggiorato le cose. La ripartizione più 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 sul diff delle PR, più audit settimanale dell'intero albero | `pyproject.toml`, `.github/workflows/lint.yml` |
| Pytest | Confini rapidi unit/integration, tier specifici per sottosistema (tramite dispatch dell'import-graph), audit del prompt-envelope | PR, push su `main`, merge queue, suite completa pianificata | `pytest.ini`, `.github/workflows/tests.yml`, `.github/workflows/nightly.yml` |
| CodeQL Advanced | Code scanning per Python, C/C++ e GitHub Actions con restringimento dello scope tramite import-graph | PR, push su `main`, merge queue, pianificazione settimanale | `.github/workflows/codeql.yml`, `.github/codeql/codeql-config.yml` |
| Hardening dei workflow | Actions di terze parti con SHA pinnato, permessi di minimo privilegio, linting dei metadati dei comandi | Ogni modifica ai workflow e ogni esecuzione di lint | `.github/workflows/`, `.github/scripts/check_command_metadata.py` |
| Lint delle label del corpus | Validazione dello schema delle label del corpus di audit e verifica del pin upstream | PR (label modificate), sweep completo settimanale | `.github/workflows/corpus-labels.yml` |
| Gate SCA PR di RAPTOR | Regressioni nelle dipendenze e nella 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 sicuro | 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 rilevanti nelle PR | `test/data/sca-e2e/compromise-corpus/`, `.github/workflows/sca-compromise-check.yml` |
| Rilevatori di invarianti del repo | Rilevamento di dead-code / chiamate errate, drift della documentazione delle variabili d'ambiente, guardrail sulle liste di vocabolario, forme canoniche dei byte JSON, lint degli import di dipendenze opzionali | Gate PR (job `repo-invariants` di `lint.yml`), più sweep giornaliero | `.github/workflows/lint.yml`, `.github/workflows/miswiring-scan.yml`, `.github/scripts/*_baseline.json` |
| Calibrazione SCA + corpus di stress | Se il risk scoring 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 di dataflow | Tracciamento di precisione / recall / categoria di FP per il comportamento del validator | Benchmark eseguito dagli sviluppatori e test sul corpus | `core/dataflow/corpus/`, `core/dataflow/scripts/corpus-metrics` |
| Guardia del documento sui controlli CI | I percorsi documentati esistono, la config di ruff corrisponde, il README rimanda al documento | PR | `.github/tests/test_ci_controls_docs.py` |

Attualmente non applicati: `mypy` è pinnato in `pyproject.toml` ma non blocca nulla; la formattazione di Ruff non è applicata; Semgrep fa parte della superficie di scansione di RAPTOR, ma non abbiamo ancora un workflow Semgrep dedicato a "scansionare RAPTOR con RAPTOR".

---

## Usare un LLM diverso

RAPTOR ha due livelli di modello separati, e vale la pena sapere come funzionano entrambi prima di modificare qualcosa.

Il **livello di orchestrazione** è Claude Code -- ma solo per la shell interattiva `raptor` (questo livello conversazionale, con slash-command). Il CLAUDE.md, le skill e i comandi vengono tutti eseguiti come istruzioni di Claude Code lì. Per cambiare quale modello Claude orchestra quel livello, usa il flag `--model` di Claude Code o il comando `/model` all'interno di una sessione. Se non vuoi affatto questo livello, vedi [Esecuzione completamente standalone](#running-fully-standalone-no-claude-code) qui sotto.

Il **livello di dispatch dell'analisi** è l'LLM che analizza i singoli findings 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"
    }
  ]
}

I ruoli dei modelli ti permettono di assegnare modelli diversi a compiti diversi:

| Ruolo | Cosa fa |
|------|-------------|
| `analysis` | Convalida 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 dall'LLM sopra la correlazione deterministica multi-modello, scritta 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 viene impostato alcun ruolo, il primo modello nella lista gestisce tutto. Per l'analisi multi-modello del codice sorgente, configura due o più modelli `analysis` — otterrai la correlazione deterministica per impostazione predefinita. Il ruolo `aggregate` è opzionale e aggiunge un riepilogo scritto dall'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 bene per l'analisi; l'affidabilità per la generazione di codice di exploit/patch dipende dalla scala del modello e dalla quantizzazione piuttosto che essere una proprietà fissa dei modelli locali — vedi [Quality Tradeoffs](https://github.com/gadievron/raptor/blob/main/llm.md#quality-tradeoffs) nella guida LLM, e controlla `/scorecard` per ciò che il tuo modello specifico sta effettivamente misurando.

### Esecuzione completamente standalone (senza Claude Code)

`bin/raptor` -- la shell interattiva con il banner e i comandi slash, ovvero questo livello conversazionale -- esegue direttamente la CLI di Claude Code e necessita sempre di un proprio login. I meccanismi effettivi sottostanti no: `python3 raptor.py <mode>` è una semplice CLI Python senza alcuna dipendenza da Claude Code.```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

Punta `models.json` / `OLLAMA_HOST` a un'istanza Ollama locale (vedi sopra) e l'intero percorso non comunica mai con Anthropic -- utile per macchine airgapped o hardware solo locale. Perdi il livello conversazionale dei comandi slash (questa chat); la pipeline di scansione/analisi/exploit stessa non è influenzata.

### Short-circuit del tier veloce + il modello scorecard

Quando il tuo modello del tier di analisi ha un fratello più economico dello stesso provider (Anthropic Opus → Haiku, OpenAI 5.x → 4o-mini, Gemini Pro → Flash-Lite, Mistral Large → Small), RAPTOR lo userà come prefilter sui consumer che si collegano al substrate (codeql oggi; SCA e altri man mano che arrivano i follow-up). Il modello economico esegue il short-circuit solo su **falsi positivi sicuri**; i casi ambigui e i TP sicuri eseguono sempre l'analisi completa. La fiducia si accumula per cella `(model, decision_class)` — RAPTOR registra l'accordo tra economico e completo e esegue il short-circuit solo quando il limite superiore di Wilson al 95% sul miss-rate della cella scende a o sotto il 5%.

Per ispezionare ciò in cui i tuoi modelli sono bravi, usa `/scorecard` (o direttamente: `libexec/raptor-llm-scorecard list`). Lo 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 va in un unico posto e ottieni findings uniti, tracciamento della copertura e diff tra 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 separazione significa che puoi eseguire il livello Python da una pipeline CI (`python3 raptor.py scan --repo ...`) e ottenere un output SARIF strutturato senza Claude Code, oppure eseguirlo in modo interattivo con il flusso di lavoro agentico completo.

---

## OSS forensics

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

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

---

## Expert personas

Otto expert personas 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
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

Mantenere `/web`, Z3, SAGE e gli SDK dei provider cloud come extra opzionali evita
di rendere l'installazione predefinita di RAPTOR più pesante e fragile di quanto debba essere.