F --> G1[Passive scanners]
F --> G2[Active scanners]

I[template-tool] --> H[CVE templates]
H --> G2

G1 --> J[Findings]
G2 --> J
J --> K[Reporter]
K --> L[Auto Reports]
K --> M[CI/CD Controls]

## Perché ApiHunter?

### Vantaggi principali

- **Architettura API-First**: Progettato appositamente per API REST/GraphQL, non adattato da scanner per applicazioni web
- **Riduzione intelligente dei falsi positivi**:
  - Rilevamento catch-all per SPA con probing canary
  - Validazione dei segreti sensibile al contesto (frontend vs backend)
  - Validazione del contenuto del corpo e controllo del referer
  - Fingerprinting delle risposte per saltare risultati duplicati
- **Progettato per essere sicuro in produzione**:
  - Concorrenza adattiva (AIMD) che riduce la velocità in caso di errori
  - Rate limiting per host con ritardi configurabili
  - Controlli di cortesia (retry, timeout, evasione WAF)
  - Modalità dry-run per i controlli attivi
- **Stealth ed Evasione**:
  - Rotazione runtime dello User-Agent da un pool selezionato (assets/user_agents.txt)
  - Ritardi casuali con jitter
  - Applicazione del ritardo per host (evita schemi a raffica)
  - Logica di retry con backoff esponenziale
  - Iniezione di header personalizzati per mimetizzarsi nel traffico legittimo
  - Timing adattivo basato sulle risposte del server
  - Nessuna fingerprint di scanner hardcoded nella modalità predefinita

### Analisi approfondita delle tecniche stealth

ApiHunter utilizza diverse tecniche stealth per evitare il rilevamento da parte di WAF (Web Application Firewall) e sistemi anti-bot:

#### 1. Rotazione dello User-Agent
**Cosa fa:** Cicla casualmente oltre 100 stringhe User-Agent di browser reali da un file (`assets/user_agents.txt`)

**Perché funziona:** I bot in genere usano lo stesso User-Agent (come `curl/7.68.0`). Fingendoti Chrome, Firefox, Safari, ecc., ti confondi con il traffico legittimo

**Analogia semplice:** Come indossare travestimenti diversi invece di portare sempre la stessa uniforme

#### 2. Timing casuale e jitter
**Cosa fa:** Aggiunge ritardi casuali tra le richieste (controllati da `--delay-ms`) con jitter (piccole variazioni casuali)

**Perché funziona:** I bot inviano richieste a intervalli perfetti (esattamente 100ms di distanza). Gli esseri umani sono imprevedibili. Il timing casuale rende il traffico organico

**Analogia semplice:** Camminare con passi irregolari invece di marciare come un robot

#### 3. Applicazione del ritardo per host
**Cosa fa:** Tiene traccia del ritardo separatamente per ogni dominio, non a livello globale

**Perché funziona:** Previene schemi a raffica in cui colpisci un host 50 volte all'istante. Ogni host vede richieste educate e distanziate

**Analogia semplice:** Fare a turno in conversazioni diverse invece di gridare ripetutamente a una sola persona

#### 4. Concorrenza adattiva (AIMD)
**Cosa fa:** Rallenta automaticamente quando riceve errori 429 (rate limit) o 503 (server occupato), accelera quando ha successo

**Perché funziona:** Riduce la velocità quando viene scoperto, imita il modo in cui i browser riprovano. I WAF vedono "questo client rispetta i nostri limiti"

**Analogia semplice:** Rallentare quando il traffico è congestionato, accelerare su strade libere

#### 5. Retry con backoff esponenziale
**Cosa fa:** Quando una richiesta fallisce, attende 1s, poi 2s, poi 4s prima di riprovare

**Perché funziona:** I client legittimi riprovano con calma. I bot spesso colpiscono immediatamente o rinunciano

**Analogia semplice:** Bussare a una porta aspettando sempre più a lungo invece di martellare in continuazione

#### 6. Nessuna fingerprint di scanner
**Cosa fa:** Non invia header come `X-Scanner: ApiHunter` o schemi prevedibili

**Perché funziona:** Molti strumenti lasciano firme (modelli Nuclei, schemi di sqlmap). ApiHunter evita marcatori ovvi

**Analogia semplice:** Non indossare un cartellino con scritto "Tester di Sicurezza"

#### 7. Riuso delle connessioni e pooling
**Cosa fa:** Usa pool di client HTTP per host, mantiene le connessioni attive

**Perché funziona:** I browser riutilizzano le connessioni. Aprire/chiudere per ogni richiesta sembra sospetto

**Analogia semplice:** Tenere la porta aperta invece di sbatterla e suonare di nuovo il campanello

#### 8. Iniezione di header personalizzati
**Cosa fa:** Può aggiungere header come `Referer`, `X-Forwarded-For`, cookie personalizzati

**Perché funziona:** Rende le richieste simili a un flusso applicativo legittimo (clic su un link, cookie di sessione presenti)

**Analogia semplice:** Mostrare un biglietto all'ingresso di un locale invece di saltare la recinzione

#### Confronto del rilevamento

| Tecnica | Senza evasione | Con evasione |
|-----------|----------------|-------------|
| **User-Agent** | `python-requests/2.28.0` (bot ovvio) | `Mozilla/5.0 (Windows NT 10.0; Win64; x64)...` (sembra Chrome) |
| **Timing** | Intervalli perfetti di 100ms → il WAF blocca | 120ms, 95ms, 180ms → sembra umano |
| **Retry** | Retry istantaneo → ban | Attendi 1s→2s→4s → "client paziente" |
| **Concorrenza** | 100 hit paralleli → allarme | Adattivo 5→10→3 in base alla risposta → "browser educato" |

#### Quando usare `--waf-evasion`

- Test di API in produzione con Cloudflare/Akamai/AWS WAF
- Evitare ban IP durante scan di grandi dimensioni
- Test di penetrazione in cui devi rimanere sotto il radar

- **Nativo CI/CD**:
  - Diffing della baseline (segnala solo nuovi risultati)
  - Output NDJSON in streaming per monitoraggio in tempo reale
  - SARIF 2.1.0 per GitHub/GitLab Code Scanning
  - Bitmask del codice di uscita per il controllo della pipeline
  - Filtri per severità e soglie di fallimento
- **Prestazioni su larga scala**:
  - Runtime async Rust (tokio) con astrazioni a costo zero
  - Scansione concorrente con parallelismo limitato da semaforo
  - Pool di client HTTP per host per evitare colli di bottiglia nelle connessioni
  - Uso efficiente della memoria (nessuna pausa GC)
- **Supporto completo per l'autenticazione**:
  - Flussi di autenticazione basati su JSON con estrazione di cookie/header
  - Test IDOR/BOLA a doppia identità
  - Import di file di sessione (integrazione Excalibur)
  - Autenticazione Bearer, Basic e con header personalizzati
  - Client non autenticato automatico per controlli di escalation dei privilegi

## Moduli scanner

ApiHunter include 13 moduli scanner integrati. Vedi [docs/scanners.md](https://github.com/teycir/apihunter/blob/main/docs/scanners.md) per la logica di rilevamento dettagliata.

| Scanner | Tipo | Cosa rileva |
|---------|------|----------------|
| **CORS** | Passivo | Origin wildcard, origin riflessi con credenziali, accettazione di origin null, vulnerabilità di bypass regex (attacchi suffisso/prefisso), Vary: Origin mancante, metodi preflight non sicuri |
| **CSP** | Passivo | Content-Security-Policy mancante, direttive unsafe-inline/unsafe-eval, sorgenti wildcard, host CDN bypassabili (gadget JSONP), frame-ancestors mancante |
| **GraphQL** | Passivo | Introspection abilitata, campi di schema sensibili (tipi user/password/token), suggerimenti sui campi (fuoriuscita dello schema), query batching, amplificazione alias (DoS), esposizione GraphiQL/Playground |
| **JWT** | Passivo | Token con alg=none, segreti HS256 deboli (basati su wordlist), scadenza mancante/eccessiva, claim sensibili nel payload, vulnerabilità di confusione algoritmica |
| **OpenAPI** | Passivo | Schemi di sicurezza mancanti, operazioni senza requisiti di autenticazione, endpoint di upload file, operazioni deprecate ancora presenti, endpoint sensibili non protetti |
| **API Versioning** | Passivo | Divulgazione dell'header di versione, versioni legacy/nuove dell'API concorrenti, header di deprecazione e deriva delle risposte tra varianti benigne di query/versione (più modalità profonda tramite `--response-diff-deep`) |
| **gRPC/Protobuf** | Passivo + Attivo | Segnali di trasporto/content-type gRPC, indizi di superficie protobuf e segnali opzionali di probe reflection/health |
| **API Security** | Passivo + Attivo | Header di sicurezza mancanti (X-Content-Type-Options, X-Frame-Options), divulgazione della versione del server, accesso non autenticato a percorsi sensibili, enumerazione dei metodi HTTP, endpoint di debug, schemi di esposizione di segreti, controlli IDOR/BOLA attivi (corpo + confronto di header selezionati), probe callback SSRF cieco e segnali di probe gateway/bypass |
| **Mass Assignment** | Attivo | Campi sensibili riflessi (is_admin, role, permissions), modifiche di stato persistenti, escalation dei privilegi tramite iniezione di campi |
| **OAuth/OIDC** | Attivo | Bypass della validazione dell'URI di redirect, parametro state mancante, problemi di supporto PKCE (S256 mancante, plain consentito), flusso implicito abilitato, password grant abilitato |
| **Rate Limit** | Attivo | Rate limiting mancante (probe a raffica), header Retry-After mancanti, bypass tramite spoofing di header IP (X-Forwarded-For) |
| **WebSocket** | Attivo | Accettazione dell'upgrade WebSocket su percorsi comuni, validazione dell'origin mancante, connessioni WebSocket non autenticate |
| **CVE Templates** | Attivo | Rilevamento CVE basato su template da `assets/cve_templates/*.toml` (168 template attuali), corrispondenza differenziale baseline vs bypass |

**Gli scanner passivi** vengono eseguiti di default e analizzano le risposte senza inviare richieste costruite.  
**Gli scanner/controlli attivi** richiedono `--active-checks` e inviano probe potenzialmente invasivi (IDOR/BOLA, mutazione, test di bypass).  
IDOR/BOLA risiede nello scanner `API Security` (non esiste un flag dedicato `--no-idor`; usa `--no-api-security` per disabilitarlo).

### Note su output e segnali dei moduli

Queste note riassumono come vengono emessi i risultati e cosa causa tipicamente rumore:

| Modulo | Prefisso / Forma dei risultati | Falsi positivi comuni | Falsi negativi comuni |
|---------|-------------------------|-------------------------|-------------------------|
| CORS | `cors/*` con campi origin/evidence | Riflessione su route non sensibili | Controlli sull'origin applicati solo su route autenticate |
| CSP | `csp/*` con evidenza delle direttive | CSP legacy applicata intenzionalmente durante la migrazione | CSP consegnata solo sul percorso CDN di produzione |
| GraphQL | `graphql/*` con endpoint + segnale di capacità | Playground pubblico destinato a tenant interni/di test | Controlli dello schema abilitati solo dopo l'autenticazione |
| JWT | `jwt/*` con evidenza di claim/header del token | Token di test/demo in risposte sintetiche | Il token non appare mai nelle risposte scandite |
| OpenAPI | `openapi/*` con contesto di operazione/sicurezza | La spec include intenzionalmente endpoint deprecati ma bloccati | Spec non disponibile o suddivisa in documenti privati |
| API Versioning | `api_versioning/*` + `response_diff/*` | Versioni multiple supportate durante migrazioni controllate | Percorsi versionati non rilevabili dal set di seed corrente |
| gRPC/Protobuf | `grpc_protobuf/*` con evidenza di trasporto/reflection | Metadati simili a gRPC su proxy perimetrali senza superficie RPC esposta | Endpoint gRPC dietro host/percorso separato non raggiunti dal set di seed |
| API Security | `api_security/*` con evidenza di header/percorso/metodo | Endpoint di debug/test esposti intenzionalmente in non-prod | Controlli applicati dietro contesto di autenticazione/sessione |
| Mass Assignment | `mass_assignment/*` con delta riflessi/persistiti | Comportamento echo che non persiste lo stato backend | Mutazioni rifiutate da regole di validazione nascoste |
| OAuth/OIDC | `oauth/*` con evidenza di redirect/metadata | Configurazione IdP non di produzione con policy permissive | Applicazione dinamica delle policy non visibile nei metadata |
| Rate Limit | `rate_limit/*` con comportamento burst/429 | Il traffic shaping globale maschera il comportamento del limiter a livello applicativo | Limiter con finestre lunghe non attivati da brevi finestre di probe |
| WebSocket | `websocket/*` con controlli upgrade/origin | Endpoint WS pubblici intenzionalmente anonimi | Autenticazione richiesta tramite header di handshake non forniti nel probe |
| CVE Templates | `cve/<id>/<check>` con evidenza del template | Collisione di fingerprint su endpoint generici | Percorso/contesto vulnerabile non raggiunto dagli URL seed |

Per il dettaglio check-by-check e le indicazioni di remediation, vedi [docs/scanners.md](https://github.com/teycir/apihunter/blob/main/docs/scanners.md) e [docs/findings.md](https://github.com/teycir/apihunter/blob/main/docs/findings.md).
La documentazione degli scanner ora include un [Catalogo dei controlli dei moduli](https://github.com/teycir/apihunter/blob/main/docs/scanners.md#module-check-catalog) allineato alle sorgenti e un [Modello delle aspettative sui falsi positivi](https://github.com/teycir/apihunter/blob/main/docs/scanners.md#false-positive-expectation-model).

## Funzionalità

### Analisi di sicurezza passiva
- **Rilevamento di configurazioni errate CORS**:
  - Generazione dinamica dell'origin in base al dominio target
  - Test di bypass regex (attacchi suffisso/prefisso)
  - Punteggio di severità sensibile alle credenziali
  - Rilevamento di origin wildcard e null
- **Analisi delle policy CSP**:
  - Rilevamento di Content Security Policy mancante/debole
  - Direttive unsafe inline/eval
  - Rilevamento di sorgenti wildcard
  - Schemi di bypass delle policy
- **Sicurezza GraphQL**:
  - Rilevamento di query di introspection
  - Analisi di nomi di tipi/campi sensibili
  - Rilevamento del supporto al query batching
  - Probe di amplificazione alias (DoS)
  - Fuzzing attivo delle mutazioni (`--active-checks`, supporta `--dry-run`)
  - Esposizione GraphiQL/Playground
- **Analisi dei token JWT**:
  - Confusione algoritmica (alg=none, HS256→RS256)
  - Rilevamento di segreti deboli (wordlist selezionata)
  - Rilevamento di token longevi (exp mancante/eccessivo)
  - Esposizione di claim sensibili
  - Estrazione del token da header e cookie
- **Analisi OpenAPI/Swagger**:
  - Validazione degli schemi di sicurezza
  - Rilevamento di endpoint di upload file
  - Segnalazione di operazioni deprecate
  - Definizioni di sicurezza mancanti
  - Cache della spec per prestazioni
- **Copertura gRPC/Protobuf**:
  - Rilevamento di metadata/content-type di risposta gRPC
  - Rilevazione di indizi di superficie protobuf da metadata/forma del percorso degli endpoint
  - Segnali opzionali di probe attivo reflection/health su percorsi gRPC noti
- **Rilevamento di esposizione di segreti**:
  - Chiavi AWS (AKIA*, secret key)
  - Chiavi API Google (AIza*)
  - Token GitHub (ghp_*, github_pat_*)
  - Token Slack (xox*)
  - Chiavi Stripe (sk_live_*, pk_live_*)
  - URL di database, chiavi private, bearer token
  - Validazione sensibile al contesto (riduce i falsi positivi)
- **Controlli di sicurezza API**:
  - Enumerazione dei metodi HTTP
  - Rilevamento di endpoint di debug
  - Esposizione del listing delle directory
  - Presenza di security.txt
  - Analisi degli header di risposta (HSTS, X-Frame-Options, ecc.)
  - Divulgazione di messaggi di errore

### Test di sicurezza attiva (--active-checks)
- **Controlli IDOR/BOLA di API Security** (approccio a 3 livelli):
  - Test di accesso non autenticato
  - Confronto delle risposte tramite fingerprint del corpo più snapshot stabili degli header
  - Enumerazione degli ID (walk range ±2)
  - Bypass dell'autorizzazione tra utenti (doppia identità)
  - Probe callback SSRF cieco tramite query param in stile callback (`APIHUNTER_OAST_BASE`, supporta `--dry-run`)
  - Probe di fingerprint e bypass gateway (`api_security/gateway-*`)
- **Vulnerabilità Mass Assignment**:
  - Iniezione di campi sensibili riflessi
  - Rilevamento di modifiche di stato persistenti
  - Verifica Baseline→Mutate→Confirm
  - Escalation dei privilegi tramite iniezione di campi
- **Sicurezza OAuth/OIDC**:
  - Bypass della validazione dell'URI di redirect
  - Gestione del parametro state
  - Rilevamento del supporto PKCE
  - Hardening della configurazione dei metadata
  - Rilevamento di flusso implicito e password grant
- **Rate Limiting**:
  - Probe di richieste a raffica
  - Rilevamento di rate limit mancante
  - Validazione dell'header Retry-After
  - Test di bypass tramite spoofing di header IP
- **Sicurezza WebSocket**:
  - Accettazione dell'upgrade su percorsi comuni
  - Test di validazione dell'origin
  - Controlli di autenticazione mancanti
- **Motore template CVE**:
  - Catalogo template basato su TOML
  - Supporto all'import YAML Nuclei
  - Corrispondenza differenziale baseline vs bypass
  - Deduplicazione host+template
  - Gate di qualità del loader che saltano template di richiesta non validi/non sicuri (ad esempio segnaposto di richiesta non risolti)
  - Corrispondenza di contesto segment-aware che riduce l'eccesso di attivazione per sottostringhe di percorso generiche
  - Catalogo locale attuale: 168 template (include controlli hardened selezionati come CVE-2022-22947, CVE-2021-29442, CVE-2021-29441, CVE-2020-13945, CVE-2021-45232, CVE-2022-24288)

### Scoperta ed enumerazione
- **Scoperta degli endpoint**:
  - Parsing di robots.txt
  - Parsing di sitemap.xml
  - Import di spec OpenAPI/Swagger
  - Import di file HAR (integrazione Excalibur)
  - Import di collection Postman/Insomnia (`--collection`)
  - Estrazione di endpoint da JavaScript
  - Filtro stesso-host
- **Pre-filtro di accessibilità degli URL**:
  - Pre-controllo rapido per saltare endpoint non funzionanti
  - Timeout configurabile
  - Bypass opzionale con --no-filter

### Prestazioni e affidabilità
- **Concorrenza adattiva (AIMD)**:
  - Regolazione automatica della velocità in base agli errori
  - Incremento additivo (ogni 5s)
  - Decremento moltiplicativo su 429/503/timeout
- **Stealth ed evasione WAF**:
  - Rotazione dello User-Agent da pool runtime (assets/user_agents.txt con oltre 100 UA reali)
  - UA di fallback incorporati se il file non è disponibile
  - Jitter di ritardo casuale per evitare schemi di rilevamento
  - Applicazione del timing per host (non globale)
  - Logica di retry con backoff esponenziale
  - Iniezione di header personalizzati (X-Forwarded-For, Referer, ecc.)
  - Timing adattivo basato su risposte 429/503
  - Modalità cortesia per test collaborativi
  - Nessuna fingerprint di scanner nello User-Agent o negli header di default
- **Gestione delle risorse**:
  - Parallelismo limitato da semaforo
  - Pool di client HTTP per host
  - Riuso e pooling delle connessioni
  - Timeout e retry configurabili
- **Gestione degli errori**:
  - Recupero da panic tramite JoinSet
  - Errori catturati riportati separatamente
  - Degrado graduale in caso di errori dello scanner

### Output e reporting
- **Formati di output multipli**:
  - JSON leggibile (pretty JSON)
  - NDJSON (streaming, parsabile)
  - SARIF 2.1.0 (GitHub/GitLab Code Scanning)
- **Diffing della baseline**:
  - Genera snapshot di baseline
  - Confronta le scansioni per riportare solo nuovi risultati
  - Perfetto per test di regressione
- **Report con salvataggio automatico** (abilitato di default, disabilitabile con `--no-auto-report`):
  - Salvati in ~/Documents/ApiHunterReports/<timestamp>/
  - findings.json (risultati strutturati)
  - summary.md (report markdown)
  - scan.log (log di esecuzione)
- **Streaming in tempo reale**:
  - Stream dei risultati man mano che vengono scoperti
  - Formato NDJSON per parsing live
  - Tracciamento dell'avanzamento
- **Filtro per severità**:
  - Filtra per severità minima (info/low/medium/high/critical)
  - Soglia fail-on per CI/CD
  - Bitmask del codice di uscita (0x01 risultati, 0x02 errori)

### Integrazione ed estensibilità
- **Architettura scanner pluggabile**:
  - Implementa il trait Scanner per aggiungere moduli
  - Design async-first
  - Esecuzione indipendente degli scanner
  - Isolamento dei panic per scanner
- **Estensibilità basata su TOML**:
  - Catalogo template CVE in assets/cve_templates/*.toml
  - Nessuna modifica al codice necessaria per aggiungere nuovi controlli
  - Rilevamento di vulnerabilità guidato da template
  - Formato template condivisibile dalla community
- **Import template Nuclei**:
  - Binario template-tool per conversione YAML → TOML
  - Traduzione automatica dei matcher (status, word, regex, dsl)
  - Estrazione sicura delle catene di richieste preflight
  - Preserva la logica di rilevamento dei template originali
- **Modello di estensione duale**:
  - **Basato su codice**: Scrivi scanner Rust che implementano il trait Scanner per logica complessa
  - **Basato su template**: Scrivi template TOML per controlli basati su firma (CVE, misconfig)
  - Il meglio di entrambi i mondi: prestazioni + flessibilità
- **Strumenti complementari**:
  - Estensione browser Excalibur (cattura HAR)
  - BurpAPIsecuritysuite (test manuali)
  - Workflow: Cattura → Automatizza → Test approfondito

### Configurazione e controllo
- **Input flessibile**:
  - Elenchi di URL da file
  - stdin (pipe da altri strumenti)
  - Import di file HAR
  - Import di collection Postman/Insomnia
  - Import di spec OpenAPI
- **Controllo granulare degli scanner**:
  - Abilita/disabilita singoli scanner
  - Modalità attiva vs passiva
  - Dry-run per i controlli attivi
  - Configurazione per scanner
- **Configurazione di rete**:
  - Supporto proxy HTTP/HTTPS
  - Controllo della validazione dei certificati TLS
  - Header e cookie personalizzati
  - Timeout e retry configurabili
- **Profilo di scansione**:
  - quickscan.sh (veloce, a basso impatto)
  - deepscan.sh (completo, controlli attivi)
  - inaccessiblescan.sh (ricontrolla target precedentemente inaccessibili con impostazioni più lente)
  - baselinescan.sh (genera baseline)
  - diffscan.sh (confronta con la baseline)
  - authscan.sh (scansione autenticata)
  - sarifscan.sh (integrazione CI/CD)
  - scan-and-report.sh (esegue la scansione + stampa il percorso dell'ultimo report)
  - split-by-host.sh (divide i target per host e opzionalmente distribuisce le scansioni)

## Confronto con altri strumenti| Funzionalità | ApiHunter | Nuclei | ZAP | Burp Suite | ffuf |
|---------|-----------|--------|-----|------------|------|
| **Linguaggio** | Rust | Go | Java | Java | Go |
| **Prestazioni** | ⚡⚡⚡ Asincrono, concorrenza adattiva | ⚡⚡ Parallelo veloce | ⚡ Moderato | ⚡ Moderato | ⚡⚡⚡ Molto veloce |
| **Progettazione API-first** | ✅ Pensato per le API | ❌ Web generale | ⚠️ Ibrido | ⚠️ Ibrido | ❌ Focalizzato sul fuzzing |
| **Filtraggio falsi positivi** | ✅ Rilevamento SPA, validazione del corpo, controlli referer | ⚠️ Dipendente dai template | ⚠️ Molti FP | ✅ Buono | N/A |
| **Analisi CORS/CSP** | ✅ Parsing approfondito delle policy | ⚠️ Template di base | ✅ Buona | ✅ Buona | ❌ |
| **Introspection GraphQL** | ✅ Esposizione dello schema + controlli dei campi sensibili | ⚠️ Rilevamento di base | ⚠️ Limitata | ✅ Tramite estensioni | ❌ |
| **OpenAPI/Swagger** | ✅ Analisi degli schemi di sicurezza | ❌ | ✅ Solo importazione | ✅ Importazione + scansione | ❌ |
| **Analisi JWT** | ✅ alg=none, segreti deboli, scadenza | ⚠️ Tramite template | ⚠️ Limitata | ✅ Tramite estensioni | ❌ |
| **Rilevamento IDOR/BOLA** | ✅ A 3 livelli (non autenticato/intervallo/cross-user) | ⚠️ Template manuali | ⚠️ Limitato | ✅ Test manuali | ❌ |
| **Rilevamento segreti** | ✅ Context-aware (frontend vs backend) | ⚠️ Basato su regex | ⚠️ Base | ⚠️ Base | ❌ |
| **Controlli attivi** | ✅ Opt-in (IDOR, mass-assignment, OAuth/OIDC, websocket, rate-limit, template CVE) | ✅ Basati su template | ✅ Scansione attiva | ✅ Scansione attiva | ✅ Fuzzing |
| **Evasione WAF** | ✅ Rotazione UA, ritardi, nuovi tentativi, temporizzazione adattiva | ⚠️ Base | ⚠️ Limitata | ✅ Buona | ⚠️ Base |
| **Integrazione CI/CD** | ✅ NDJSON, SARIF, codici di uscita | ✅ JSON, SARIF | ⚠️ Report XML | ⚠️ XML/JSON | ✅ JSON |
| **Diffing della baseline** | ✅ Integrato | ❌ Strumenti esterni | ❌ | ❌ | ❌ |
| **Flussi di autenticazione** | ✅ Login pre-scansione basato su JSON | ⚠️ Iniezione header | ✅ Gestione sessione | ✅ Gestione sessione | ⚠️ Iniezione header |
| **Output in streaming** | ✅ NDJSON in tempo reale | ❌ Solo batch | ❌ | ❌ | ✅ |
| **Utilizzo risorse** | 🟢 Basso (Rust) | 🟢 Basso (Go) | 🟡 Alto (Java) | 🟡 Alto (Java) | 🟢 Basso (Go) |
| **Curva di apprendimento** | 🟢 CLI semplice | 🟢 Sintassi template | 🟡 Complessità GUI | 🔴 Ripida | 🟢 Semplice |
| **Estendibilità** | ✅ Sistema di trait Rust | ✅ Template YAML | ✅ Componenti aggiuntivi | ✅ Estensioni | ⚠️ Limitata |
| **Licenza** | MIT (Gratuita) | MIT (Gratuita) | Apache 2.0 (Gratuita) | Commerciale | MIT (Gratuita) |
| **Ideale per** | Sicurezza API in CI/CD, test di regressione, analisi CORS/GraphQL/JWT | Scansione vulnerabilità generali, rilevamento CVE | Penetration testing completo di app web | Penetration testing manuale, workflow complessi | Fuzzing di directory/parametri |

### Differenziatori chiave

**ApiHunter:** progettazione API-first, rilevamento SPA, diffing della baseline, IDOR/BOLA a 3 livelli, segreti context-aware, concorrenza AIMD, **evasione stealth/WAF (rotazione UA, jitter, temporizzazione adattiva)**, **doppia estendibilità (template TOML + moduli Rust)**  
**Nuclei:** copertura CVE più ampia, solo template YAML, evasione di base  
**ZAP/Burp:** test manuali, workflow proxy, estensioni basate su GUI, stealth limitato  
**ffuf:** fuzzing puro, scoperta di contenuti, estendibilità limitata, evasione di base

## Avvio rapido```bash
cargo build --release

# Scan URLs from a file (newline-delimited)
./target/release/apihunter --urls ./targets/cve-regression-real-public.txt --format ndjson --output ./results.ndjson

# Or scan URLs from stdin
cat ./targets/cve-regression-real-public.txt | ./target/release/apihunter --stdin --min-severity medium

L'input della scansione desktop supporta:
- Inserimento manuale di più target (un URL per riga o separato da virgole)
- Importazione CSV tramite `Load CSV` (max 307.200 byte / 300 KiB)
- Preset di scansione guidata: `Quick Passive` e `Deep Active`
- Limite massimo: fino a 3.000 target per esecuzione (deduplicati + validati come URL assoluti `http/https`)
- Controlli di scope: discovery on/off, filtro dell'accessibilità + timeout, numero massimo di endpoint per sito
- Controlli di versionamento API: toggle opzionale per il probing approfondito delle differenze di risposta
- Controlli avanzati: proxy, header, cookie, autenticazione bearer/basic, toggle TLS per certificati non validi
- Input di correlazione callback SSRF cieca (`OAST callback base`) per i controlli attivi
- Controlli delle prestazioni: client per host, concorrenza adattiva, bypass WAF con pool di user-agent personalizzato
- Copertura completa dei toggle dello scanner, inclusi `API Versioning` e `gRPC/Protobuf`
- Sezioni di scansione comprimibili con indicatori allineati a destra; `Safety and Scan Behavior`, `Runtime Limits` e `Scanner toggles` sono compresse per impostazione predefinita
- Schede di avanzamento per esecuzioni parallele con snapshot di completamento/risultati per target
- Dashboard di analisi dei risultati: mappa di calore della gravità, scheda del target peggiore, efficienza della scansione, copertura dello scanner, percorsi vulnerabili principali, ripartizione della gravità dei controlli
- Persistenza della sessione: gli ultimi risultati della scansione vengono ripristinati automaticamente al successivo avvio
- Pannello Enrich Mode: caricare i risultati NDJSON, eseguire l'arricchimento con threat-intel, promuovere gli host con punteggio elevato direttamente a Full Scan con preset Deep Active
- UX di esportazione: etichette di dimensione + `Save All Reports` + nomi file con timestamp per esecuzione; le esportazioni includono bundle JSON per target, NDJSON, SARIF, collection Insomnia e dati Insomnia Runner

Consulta [HOWTO.md](https://github.com/teycir/apihunter/blob/main/HOWTO.md) per l'uso dettagliato, [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/main/docs/lab-setup.md) per i laboratori di validazione CVE basati su Vulhub, e [docs/](https://github.com/teycir/apihunter/blob/main/docs) per i dettagli interni.

Se desideri un binario desktop per la release:```bash
cd apps/desktop
npm run tauri build
./src-tauri/target/release/apihunter-desktop

Nota: ora l'avvio dell'app desktop in modalità sviluppo usa direttamente gli asset frontend compilati e non richiede un server `localhost:1420` separato.

Vedi [HOWTO.md](https://github.com/teycir/apihunter/blob/main/HOWTO.md) per l'uso dettagliato, [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/main/docs/lab-setup.md) per i lab di validazione CVE basati su Vulhub e [docs/](https://github.com/teycir/apihunter/blob/main/docs) per i dettagli interni.

### Esempio di risultato NDJSON```json
{
  "url": "https://api.example.com/graphql",
  "check": "graphql/introspection-enabled",
  "title": "GraphQL introspection is enabled",
  "severity": "MEDIUM",
  "detail": "Introspection query returned schema metadata from a public endpoint.",
  "evidence": "POST /graphql -> HTTP 200 with __schema fields in response body",
  "scanner": "graphql",
  "timestamp": "2026-03-19T14:02:11.824Z"
}

**Flusso:** argomenti CLI → Config → Runner orchestra Discovery + Scanners → Client HTTP (con Auth/WAF) → Report

## Strumenti per Template

ApiHunter supporta **doppia estensibilità**: aggiungi controlli tramite **template TOML** (senza codice) oppure **moduli Rust** (controllo completo).

### Formato del template TOML
Crea controlli personalizzati in `assets/cve_templates/*.toml`:```toml
id = "custom-api-check"
name = "Custom API Vulnerability"
severity = "high"

[[requests]]
method = "GET"
path = "/api/vulnerable"

[[requests.matchers]]
type = "status"
values = [200]

[[requests.matchers]]
type = "word"
part = "body"
words = ["sensitive_data", "exposed"]

### Aggiungi Scanner Rust Personalizzati
Implementa il trait `Scanner` per logiche complesse:```rust
#[async_trait]
impl Scanner for MyCustomScanner {
    async fn scan(
        &self,
        url: &str,
        client: &HttpClient,
        config: &Config,
    ) -> (Vec<Finding>, Vec<CapturedError>) {
        // Your custom scanning logic
    }
}

Tutti gli script wrapper tranne `split-by-host.sh` supportano `--stdin` e flag ApiHunter finali.

## Strategia di test

I test di ApiHunter sono suddivisi per intenzione:

- **Unit test** (`tests/*_scanner.rs`, test di parser/config): logica dello scanner e casi limite.
- **Test di integrazione** (`tests/integration_runner.rs`, comportamento di avvio/CLI): orchestrazione e collegamento runtime.
- **Test di regressione su fixture** (`tests/cve_templates_real_data.rs`, `tests/cve_templates_upstream_parity.rs`): riproducono payload reali e li confrontano con i template upstream fissati.
- **Test con server mock** (diverse suite di scanner): verifiche di comportamento deterministico senza dipendere da target internet.
- **Controlli su target live**: solo facoltativi/manuali (non fanno parte del `cargo test` predefinito).

Consulta la dedicata [Guida ai test](https://github.com/teycir/apihunter/blob/main/docs/testing.md) per la matrice completa dei test e la mappa di copertura.

Esegui suite mirate:```bash
cargo test --test cors_scanner
cargo test --test graphql_scanner
cargo test --test cve_templates_runtime_ext
cargo test --test integration_runner

Esegui il gate di integrazione con dati reali (fixture + suite live ignorate):```bash
# Fixture-backed real payload regression suites
cargo test --test cve_templates_real_data --test cve_templates_upstream_parity --test cve_templates_runtime_ext

# Manual live internet integration suites (ignored by default)
cargo test --test live_vulnerable_apis --test live_real_world_targets -- --ignored

### Artefatti di rilascio precompilati

Le release con tag (`v*`) pubblicano binari `apihunter` precompilati per:

- Linux (`x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`)
- macOS (`x86_64-apple-darwin`)
- Windows (`x86_64-pc-windows-msvc`)

Ogni release pubblica anche artefatti della supply chain:

- File di checksum SHA256 (`*.sha256`)
- Materiali di firma keyless Sigstore (`*.sig`, `*.pem`, `*.sigstore.json`)
- SBOM JSON SPDX (`apihunter-release-assets-sbom.spdx.json`)
- Attestazioni di artefatti GitHub (provenienza e metadati di attestazione SBOM)

Scarica da [GitHub Releases](https://github.com/Teycir/ApiHunter/releases).

### Installazione desktop (Tauri + React)

Il codice sorgente dell'app desktop si trova in `apps/desktop`.

Compila ed esegui un binario desktop di produzione:```bash
cd apps/desktop
npm install
npm run tauri build
./src-tauri/target/release/apihunter-desktop

Installa un'icona del launcher Linux cliccabile:```bash
cd apps/desktop
npm run desktop:install-icon

Esegui una scansione dai file nella tua directory corrente:```bash
docker run --rm -v "$PWD:/work" apihunter:local \
  --urls /work/targets/cve-regression-real-public.txt \
  --format ndjson \
  --output /work/results.ndjson

**D: Diffing della baseline?**```bash
./target/release/apihunter --urls targets/cve-regression-real-public.txt --format ndjson --output baseline.ndjson
./target/release/apihunter --urls targets/cve-regression-real-public.txt --baseline baseline.ndjson --format ndjson