Preferisci l'HTTP raw? Usa l'API direttamente con curl:```bash
curl -X POST http://localhost:8080/api/v1/execute/async/sec-af.audit \
  -H "Content-Type: application/json" \
  -d '{"input": {"repo_url": "https://github.com/dolevf/Damn-Vulnerable-GraphQL-Application"}}'

Ogni finding include un **verdict** (`confirmed` / `likely` / `inconclusive` / `not_exploitable`), un **oggetto proof** con l'intera taint trace e la posizione esatta del codice. Non "potrebbe essere un problema". SEC-AF traccia i dati dalla source alla sink e dimostra se è realmente sfruttabile.

> Output completo del benchmark (30 findings): [`exampl/dvga-benchmark-result.json`](https://github.com/agent-field/sec-af/blob/HEAD/exampl/dvga-benchmark-result.json) | Analisi delle performance: [`exampl/benchmark-analysis.json`](https://github.com/agent-field/sec-af/blob/HEAD/exampl/benchmark-analysis.json)

## Benchmark: DVGA

Eseguiamo SEC-AF su [Damn Vulnerable GraphQL Application](https://github.com/dolevf/Damn-Vulnerable-GraphQL-Application), un'app deliberatamente vulnerabile con 21 scenari di sicurezza documentati.

| Metrica | Valore |
|---|---|
| Finding grezzi scoperti | 106 |
| Dopo deduplicazione AI | 61 |
| **Dopo verifica adversarial** | **28 confermati** |
| Inconcludenti (richiedono revisione manuale) | 1 |
| Non sfruttabili (correttamente respinti) | 1 |
| Riduzione del rumore | 94% |
| Nodi DAG (chiamate reasoner) | 82 |
| Chiamate agente | ~166–255 |
| Strategie eseguite | 11 |
| Tempo wall-clock | ~78 min |
| Costo stimato (Kimi K2.5) | ~$0.18–$0.90 |

<details>
<summary><strong>Dettaglio: 30 finding verificati per categoria</strong></summary>

| Categoria | Conteggio | Esempi |
|---|---|---|
| Autenticazione mancante | 8 | ImportPaste, delete_all_pastes, system_debug, CreateUser, file upload |
| Command Injection | 4 | `os.popen(cmd)` tramite ImportPaste, system_debug, system_diagnostics |
| SQL Injection | 3 | `filter` non sanificato in `resolve_pastes`, injection nel pattern LIKE, login |
| Bypass dell'autenticazione | 3 | Firma JWT disabilitata, bypass autorizzazione JWT, autenticazione password difettosa |
| Credenziali in chiaro | 3 | Archiviazione password in chiaro, confronto in chiaro, password nei diagnostici |
| SSRF | 2 | La mutation ImportPaste segue URL forniti dall'utente lato server |
| Logica di business / Sanificazione URL | 2 | Sanificazione URL inadeguata, cancellazione massiva non autenticata |
| DoS / Esaurimento risorse | 3 | Mancanza di paginazione sulle query users/audits, simulate_load non controllato |
| Config / Segreti | 2 | Segreti JWT/Flask hardcoded, modalità debug attiva in produzione |

</details>

<details>
<summary><strong>Pattern di design: come funziona l'analisi di sicurezza AI-native</strong></summary>

SEC-AF applica diversi pattern architetturali resi possibili componendo molti agenti AI focalizzati invece di eseguire un singolo scan monolitico. Questi pattern affrontano sfide fondamentali nell'analisi di sicurezza basata su IA.

**1. Tensione adversarial tra agenti (HUNT vs. PROVE)**

La maggior parte degli strumenti di sicurezza AI chiede a un singolo modello "questa cosa è vulnerabile?" e accetta la risposta. SEC-AF separa strutturalmente gli agenti di _finding_ dagli agenti di _confutazione_. I cacciatori sono incentivati a trovare vulnerabilità; i verificatori sono incentivati a confutarle. Ogni finding passa attraverso una catena di verifica a 4 agenti — un tracer ricostruisce il flusso dei dati, un analizzatore di sanificazione cerca mitigazioni che il cacciatore potrebbe aver mancato, un ipotizzatore di exploit costruisce uno scenario d'attacco concreto e un agente verdict valuta tutte le prove contrastanti. Questa tensione adversarial tra agenti è ciò che produce la riduzione del rumore del 94% — l'architettura stessa incorpora lo scetticismo.

**2. Cascata di segnale con restringimento progressivo**

Invece di scaricare tutti i finding sull'utente, la pipeline comprime il segnale in ogni fase: 106 finding grezzi → 61 dopo la deduplicazione AI → 30 dopo la verifica adversarial. Ogni fase è un filtro. Questo rispecchia il triage dei team di sicurezza umani: prima una scoperta ampia, poi un esame progressivamente più rigoroso. Il punto chiave è che ogni filtro è un _tipo diverso_ di ragionamento AI: similarità semantica per la deduplicazione, taint analysis per la verifica, costruzione di exploit per la conferma.

**3. Economia dell'informazione tramite pruning del contesto**

Gli LLM allucinano di più quando ricevono contesto irrilevante. SEC-AF instrada solo l'informazione di cui ogni agente ha bisogno: un cacciatore di injection riceve il contesto di recon potato sulle mappe del flusso dati e sui punti di ingresso, mentre un cacciatore di crittografia riceve alberi delle dipendenze e pattern di gestione delle chiavi. I verificatori ricevono viste proiettate dei finding con solo i campi necessari per il loro specifico metodo di verifica. Questo pruning del contesto per strategia riduce sia l'allucinazione sia i costi — gli agenti non possono confondersi con informazioni che non vedono mai.

**4. Overlap delle fasi in streaming**

Le pipeline tradizionali eseguono in sequenza: finisci la recon, poi inizi la caccia, poi inizi la verifica. SEC-AF sovrappone le fasi tramite `asyncio.Queue` — i cacciatori iniziano a consumare l'output della recon appena arriva e la deduplicazione processa i finding man mano che ogni cacciatore completa. I verificatori iniziano a verificare i primi finding deduplicati mentre i cacciatori successivi sono ancora in esecuzione. Questa architettura in streaming riduce il tempo wall-clock senza sacrificare la cascata di segnale — ogni finding passa comunque attraverso ogni filtro, solo prima.

**5. Routing dinamico tramite AI gate**

La pipeline si adatta a runtime in base a ciò che scopre. Un AI gate esamina l'output della recon e seleziona quali strategie di caccia attivare — un'app Flask con autenticazione JWT attiva cacciatori diversi rispetto a un microservizio Go con gRPC. Un gate separato per l'espansione CWE amplia dinamicamente l'elenco dei target di vulnerabilità in base allo stack tecnologico rilevato. Un gate di raggiungibilità valuta se le vulnerabilità delle dipendenze hanno percorsi di chiamata sfruttabili prima di sprecare risorse di verifica su codice non raggiungibile.

**6. Autonomia guidata per gli agenti di coding**

SEC-AF opera sopra agenti di coding (Claude Code, OpenCode, Codex) tramite l'harness AgentField. Invece di dare all'agente un singolo prompt enorme, ogni reasoner fornisce un'autonomia guidata consapevole della fase: l'agente riceve una definizione di task ristretta, uno schema di output piatto (2-4 campi) e un contesto specifico per la strategia. L'agente ha piena autonomia entro questi confini — può leggere file, tracciare codice e ragionare liberamente — ma l'harness vincola la _forma_ del suo output. Questo previene il modo di fallimento comune in cui gli agenti autonomi deviano dal compito o producono risultati non strutturati.

**7. DAG di reasoner componibili con osservabilità completa**

Ogni chiamata agente passa attraverso il control plane di AgentField, creando un grafo aciclico diretto completo dell'audit. Puoi vedere quale cacciatore ha trovato quale finding, quanto tempo ha richiesto ogni verifica, quali prove ha generato il verificatore e dove la pipeline ha speso il suo tempo. Aggiungere una nuova classe di vulnerabilità è un solo file — un nuovo cacciatore. L'orchestratore la scopre, instrada il contesto e integra i suoi finding nella pipeline esistente dedup → prove → remediation. Il DAG è l'architettura.

</details>

<details>
<summary><strong>Cosa non ha rilevato (e perché)</strong></summary>

I 9 scenari mancati sono principalmente **attacchi a livello di protocollo GraphQL**: query batch, ricorsione profonda, abuso di alias, duplicazione di campi, esposizione dell'introspection. Questi richiedono analisi runtime/DAST. SEC-AF è attualmente focalizzato su SAST. Il rilevamento a livello di protocollo è nella roadmap.

</details>

## Come Funziona

SEC-AF è costruito sulla filosofia [Composite Intelligence](https://github.com/Agent-Field/agentfield): invece di affidarsi a una singola chiamata LLM monolitica, compone molte chiamate LLM focalizzate e guidate in un **DAG di reasoner** in cui l'architettura stessa codifica l'intelligenza (per un approfondimento su questo pattern, vedi [The Atomic Unit of Intelligence](https://www.santoshkumarradha.com/writing/atomic-unit-of-intelligence)). Ogni chiamata LLM gestisce un compito piccolo e ben definito con uno schema Pydantic piatto (2-4 attributi). L'orchestratore gestisce il flusso del contesto, il parallelismo e il routing dinamico.

### Architettura: Grafo di chiamate reasoner (DAG)

Ogni fase è un `@reasoner` che chiama sub-reasoner attraverso il control plane di AgentField, per un totale di circa ~200-300 agenti che lavorano in modo sincrono per una data query:

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7491/d3e99c5c9b7067b17005f71ecb0f7c7abeb9d7fc8843d33938de9f755f416b7b.png" alt="Pipeline a cascata di segnale SEC-AF — RECON → HUNT → DEDUP → PROVE → OUTPUT" width="100%" />
</p>

### Pipeline a cascata di segnale

Ogni fase restringe il segnale. I finding grezzi vengono filtrati attraverso gate progressivamente più rigorosi:

| Fase | Scopo | Parallelismo |
|---|---|---|
| **RECON** | Mappare architettura, dipendenze, flussi di dati, contesto di sicurezza | Parallelo a 3 vie (arch + dipendenze + config), poi a 2 vie (flusso dati + sicurezza) |
| **HUNT** | Eseguire 10+ cacciatori di strategia specializzati | Parallelo limitato da semaforo (default 4 concorrenti) con deduplicazione incrementale |
| **PROVE** | Verifica adversarial: tentare di **confutare** ogni finding | Parallelo limitato da semaforo (default 3 concorrenti) |
| **REMEDIATION** | Generare suggerimenti di fix per i finding confermati/probabili | Parallelo limitato da semaforo (default 3 concorrenti) |

### Perché un'architettura multi-reasoner

La maggior parte degli strumenti di sicurezza AI esegue un unico grande prompt e spera che l'LLM faccia la cosa giusta. SEC-AF scompone il problema in ~258 chiamate agente focalizzate, ciascuna con uno schema piatto (2-4 campi) e un compito ristretto. L'architettura codifica la strategia di ragionamento, non il prompt (vedi [The Atomic Unit of Intelligence](https://www.santoshkumarradha.com/writing/atomic-unit-of-intelligence) per capire perché questo conta).

- **Molti agenti focalizzati > un singolo agente potente.** Una singola chiamata LLM non può mappare simultaneamente l'architettura, tracciare i flussi di dati, cercare injection, verificare la sfruttabilità e suggerire fix. SEC-AF assegna ciascuna di queste attività a un reasoner separato che fa bene una cosa sola. L'orchestratore gestisce composizione, parallelismo e routing del contesto.
- **Verifica adversarial, non bias di conferma.** La fase PROVE esegue 4 sotto-agenti per finding con obiettivi opposti: il tracer ricostruisce il flusso dei dati, l'analizzatore di sanificazione cerca blocchi, l'ipotizzatore di exploit costruisce un attacco e l'agente verdict valuta tutte le prove. Questa tensione tra agenti produce una confidenza maggiore rispetto a chiedere a un singolo modello "questo è sfruttabile?"
- **Routing dinamico tramite AI gate.** Il sistema si adatta a runtime. Un AI gate esamina l'output della recon e seleziona quali strategie di caccia attivare. Un gate separato espande l'elenco dei target CWE in base allo stack rilevato. Un'app Flask con autenticazione JWT riceve cacciatori diversi rispetto a un microservizio Go con gRPC.
- **Restringimento progressivo del segnale.** 106 finding grezzi diventano 61 dopo la deduplicazione, poi 30 dopo la verifica adversarial — riduzione del rumore del 94%. Ogni fase è un filtro. La pipeline comprime il rumore, non si limita a rilevare vulnerabilità e scaricarle sull'utente.
- **Economia dell'informazione.** Ogni agente vede solo ciò di cui ha bisogno. I cacciatori ricevono il contesto di recon potato per la loro strategia. I verificatori ricevono viste proiettate dei finding con un numero minimo di campi. Questo riduce l'allucinazione, riduce i costi e mantiene ogni chiamata LLM focalizzata.
- **Streaming incrementale.** La deduplicazione viene eseguita come consumer mentre i cacciatori sono ancora in produzione. I finding vengono deduplicati per impronta man mano che ogni cacciatore completa, poi un passaggio semantico finale cattura i duplicati tra strategie diverse. La pipeline opera in streaming, non in batch.

## Confronto

> Affermazioni provenienti da documentazione ufficiale e pagine di pricing. Se qualcosa è sbagliato, [apri un issue](https://github.com/Agent-Field/sec-af/issues).

| | SEC-AF | Nullify | Snyk Code | Semgrep | CodeQL |
|---|---|---|---|---|---|
| **Approccio** | **AI-native** | **AI-native** | **Assistito da AI** | **Basato su regole** | **Basato su regole** |
| | DAG multi-reasoner · l'LLM ragiona sul codice | Forza lavoro di sicurezza autonoma | Motore AI DeepCode | Pattern + taint matching | Analisi semantica + dataflow |
| **Open source** | ✅ Apache 2.0 | ❌ Proprietario | ❌ Proprietario | Motore: LGPL-2.1 · Regole Pro: proprietarie | Query: MIT · Motore: proprietario |
| **Finding verificati** | ✅ Fase PROVE adversarial · verdict + proof per finding | ✅ Generazione proof-of-exploit | ❌ Priority Score (opaco) · nessuna prova di exploit | ❌ Solo pattern match | ❌ Alert di analisi statica |
| **Evidenza per finding** | Traccia del flusso dati con propagazione taint | Percorso exploit + passaggi di riproduzione | Flusso source-to-sink mostrato | - | Query di percorso mostrano il flusso dati |
| **Architettura** | DAG di reasoner componibili con osservabilità completa | Agente monolitico | Motore a passaggio singolo | Motore a regole | Motore a query |
| **Parallelismo** | ✅ Cacciatori, verificatori e remediator paralleli con dedup incrementale | Non documentato | Non documentato | ✅ Parallelismo delle regole | ✅ Parallelismo delle query |
| **Scoring** | ✅ Formula composita pubblicata | Interno | Priority Score opaco | Interno | - |
| **SARIF** | ✅ Nativo 2.1.0 | Non documentato | ✅ | ✅ | ✅ Nativo |
| **Mappatura compliance** | PCI-DSS, SOC2, OWASP, HIPAA, ISO27001 | Non documentato | Solo compliance di piattaforma | Regole OWASP disponibili | - |
| **Linguaggi** | Qualsiasi linguaggio supportato da LLM | Non documentato | 14+ | 35+ (basato su parser) | 10 |
| **Prezzi** | **Gratuito · open source** (~$0.18–$0.90/audit in costi LLM) | **$6.000/mese** | $25-105/mese/sviluppatore | Motore OSS: uso gratuito · Pro: $30/mese/contributore | Gratuito per repo pubbliche · $49/mese/committer (GHAS) |

**Dove SEC-AF è più forte**: Finding verificati con oggetti proof, scoring trasparente, mappatura compliance, architettura multi-agente componibile con osservabilità completa del DAG e completamente open source.

**Dove gli altri sono più forti**: Semgrep e CodeQL hanno anni di copertura di regole battle-tested su 35+ linguaggi. Snyk ha un'integrazione profonda IDE/SCA. Nullify aggiunge contesto cloud runtime e campagne di auto-remediation. SEC-AF è più recente e attualmente più forte sull'analisi del codice guidata da IA.

> **Stessa architettura, dominio diverso:** [Contract-AF](https://github.com/Agent-Field/contract-af) applica HUNT→PROVE adversarial ai contratti legali — gli agenti generano agenti per trovare interazioni tra clausole che gli LLM singoli si perdono.

### Perché l'architettura multi-agente conta

Gli scanner di sicurezza tradizionali sono monolitici: un motore, un passaggio, un set di regole. L'architettura multi-reasoner di SEC-AF offre vantaggi strutturali:

- **Specializzazione**: Ogni cacciatore è uno specialista LLM guidato — un cacciatore di injection ragiona diversamente da un cacciatore di crittografia. L'architettura codifica la conoscenza di dominio nel routing, non solo nei prompt.
- **Componibilità**: Aggiungi una nuova classe di vulnerabilità aggiungendo un file hunter. L'orchestratore la scopre e la esegue automaticamente. Nessuna modifica alla pipeline.
- **Verifica adversarial**: La fase PROVE è strutturalmente separata da HUNT. I cacciatori cercano di trovare vulnerabilità; i verificatori cercano di confutarle. Questa tensione adversarial riduce i falsi positivi.
- **Osservabilità**: Ogni chiamata reasoner passa attraverso il control plane, creando un DAG completo. Puoi vedere esattamente quale cacciatore ha trovato quale finding, quanto tempo ha richiesto ogni fase e cosa ha ragionato l'LLM in ogni passaggio.
- **Efficienza dei costi**: Il pruning del contesto e le viste schema fanno sì che ogni chiamata LLM riceva solo il contesto di cui ha bisogno. Un audit completo a profondità standard con 30 finding verificati costa circa ~$0.18–$0.90 in chiamate LLM (Kimi K2.5 tramite OpenRouter).

## Avvio Rapido

### Installazione in AgentField (`af install`)

Stai già eseguendo un control plane [AgentField](https://github.com/Agent-Field/agentfield)? Installa SEC-AF direttamente da GitHub — nessun clone, nessuna configurazione locale:```bash
af install https://github.com/Agent-Field/sec-af
af run sec-af

Nuovo su AgentField? Installa il control plane prima con `curl -fsSL https://agentfield.ai/install.sh | bash`, oppure usa le opzioni Docker / Railway qui sotto.

### Deploy in un clic (Railway)

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/sec-af)

Distribuisce il control plane di AgentField + l'agente SEC-AF. Avrai bisogno di una `OPENROUTER_API_KEY`.

### In locale (Docker Compose)```bash
git clone https://github.com/Agent-Field/sec-af.git && cd sec-af
cp .env.example .env          # Add OPENROUTER_API_KEY
docker compose up --build

Interroga per i risultati:```bash
curl http://localhost:8080/api/v1/executions/<execution_id>

**Passaggio 2 — Creare e attivare un ambiente virtuale**```bash
python3 -m venv .venv
source .venv/bin/activate

**Passaggio 4 — Configurare le variabili d'ambiente**```bash
cp .env.example .env

Opzionale — imposta una directory di lavoro personalizzata per evitare problemi di permessi:```
SEC_AF_WORKSPACES_DIR=~/.sec-af/workspaces

Questo gira su `http://localhost:8080` di default.

**Passaggio 6 — Avvia l'agente SEC-AF** (in un altro terminale, con il venv attivo)```bash
python3 main.py

## API

<details>
<summary><strong>Opzioni di richiesta complete</strong></summary>```bash
curl -X POST http://localhost:8080/api/v1/execute/async/sec-af.audit \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "repo_url": "https://github.com/org/repo",
      "branch": "main",
      "depth": "thorough",
      "severity_threshold": "high",
      "scan_types": ["sast", "sca", "secrets", "config"],
      "output_formats": ["sarif", "json", "markdown"],
      "compliance_frameworks": ["pci-dss", "soc2", "owasp", "hipaa"],
      "max_cost_usd": 15.0,
      "max_provers": 30,
      "max_duration_seconds": 1800,
      "include_paths": ["src/"],
      "exclude_paths": ["tests/", "vendor/"]
    }
  }'