Custom AI Agent

Il ponte tra Burp Suite e l'IA moderna.

Nota sul nome: questa estensione è pubblicata come Custom AI Agent (in precedenza Burp AI Agent). È stata rinominata per conformarsi ai requisiti di denominazione del BApp Store di PortSwigger e per evitare confusione con il provider Burp AI integrato di Burp Suite. Il repository GitHub (github.com/six2dez/burp-ai-agent), il sito della documentazione (burp-ai-agent.six2dez.com) e la directory di configurazione (~/.burp-ai-agent/) mantengono l'identificativo burp-ai-agent per continuità.

Custom AI Agent è un'estensione per Burp Suite che integra l'IA nel tuo flusso di lavoro di sicurezza. Usa modelli locali o provider cloud, collega agenti IA esterni tramite MCP e lascia che gli scanner passivi/attivi trovino le vulnerabilità mentre ti concentri sui test manuali.

Novità nella v0.9.0

• Backend Anthropic nativo (CAP-01) — API Anthropic Messages diretta tramite il trasporto HTTP di Burp; tutto il traffico appare nella cronologia del Proxy.
• Segreti a riposo AES-256-GCM (SEC-01) — tutte le chiavi API e i token memorizzati sono crittografati con una chiave per installazione tramite javax.crypto. La chiave master risiede nelle Preferenze di Burp insieme al testo cifrato, quindi questa protezione difende dall'ispezione casuale di un file di preferenze, non da un attaccante locale — vedi Note su privacy e sicurezza.
• Anonimizzazione host HKDF reale (PRIV-01) — la modalità STRICT ora usa un vero HMAC-SHA256 extract/expand (non SHA-256 con sale) per l'anonimizzazione degli host.
• Oscuramento del corpo richiesta/risposta + pattern personalizzati (PRIV-02) — la pipeline di oscuramento copre i campi del corpo e i pattern regex configurabili dall'utente, validati contro ReDoS.
• Tripwire dei segreti pre-invio (PRIV-03) — avvisa prima che valori ad alta entropia lascino Burp; le azioni in allowlist vengono registrate nell'audit log.
• Server MCP esterni (CAP-02) — connessione a server MCP esterni/personalizzati (SSE o stdio) così gli agenti IA possono chiamare i loro strumenti insieme agli strumenti integrati di Burp.
• Limiti del budget di token per sessione (CAP-04) — BudgetGuard limita la spesa dello scanner passivo con gli stati WARN/CAP/OFF; lo scanner passivo si mette in pausa automaticamente al raggiungimento del limite massimo.

Caratteristiche principali

• 12 Backend IA — Burp AI (integrato), Anthropic, Ollama, LM Studio, NVIDIA NIM, Perplexity, OpenAI-compatibile generico, Gemini CLI, Claude CLI, Codex CLI, OpenCode CLI, Copilot CLI.
• 59 Strumenti MCP — Lascia che Claude Desktop (o qualsiasi client MCP) guidi Burp in autonomia (8 strumenti IA nativi dell'estensione nella build dello store, tutti e 59 nella build completa).
• Accesso MCP con scope — Confina facoltativamente ogni strumento MCP agli host in scope, così i client IA esterni non possono raggiungere target fuori scope tramite Burp.
• 62 Classi di vulnerabilità — Scanner IA passivi e attivi su injection, autenticazione, crittografia e altro. Lo scanner passivo viene eseguito come PassiveScanCheck di Burp (Burp Pro).
• Installazione dalle Release — Scarica il JAR dalle Release. Non è sul BApp Store: la richiesta di pubblicazione è aperta da gennaio 2026.
• UI sensibile al tema — Un sistema di design interno stilizza il pannello delle impostazioni e cambia tema automaticamente con l'interruttore chiaro/scuro di Burp.
• Burp Scan Skill — Usa il tuo assistente di codifica IA preferito (Claude Code, Gemini CLI, Codex, ecc.) come scanner tramite MCP.
• 3 Modalità di privacy — STRICT / BALANCED / OFF. Oscura i dati sensibili prima che lascino Burp.
• Libreria di prompt personalizzati — Salva prompt liberi per contesto (richiesta HTTP o issue dello scanner); avviali dal menu contestuale oppure scrivine di ad hoc tramite Custom….
• Registrazione audit — JSONL con hashing di integrità SHA-256 per la conformità; ogni avvio è marcato con promptSource / contextKind per la riproducibilità.

Avvio rapido

1. Installazione

Scarica l'ultimo JAR dalle Release, oppure compila dal sorgente (Java 21):

git clone https://github.com/six2dez/burp-ai-agent.git
cd burp-ai-agent

# Full build (default, GitHub releases) — all 59 MCP tools
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar
# Output: build/libs/Custom-AI-Agent-full-<version>.jar

# Store build (BApp Store submission) — 8 extension-native AI MCP tools only
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar -PstoreBuild=true
# Output: build/libs/Custom-AI-Agent-<version>.jar

2. Caricamento in Burp

1. Apri Burp Suite (Community o Professional).
2. Vai su Extensions > Installed > Add.
3. Seleziona Java come tipo di estensione e scegli il file .jar.

L'estensione si registra in Burp come Custom AI Agent (il nome nell'elenco delle estensioni e nella scheda Suite) per distinguerla dal provider Burp AI integrato di Burp.

3. Profili agente

Al primo avvio, l'estensione installa automaticamente i profili inclusi in ~/.burp-ai-agent/AGENTS/. Aggiungi ulteriori file *.md in quella directory per avere profili personalizzati.

4. Configura un backend

Apri la scheda AI Agent e vai su Settings. Scegli un backend:

Per NVIDIA NIM, il backend prevede lo stesso flusso in stile chat-completions dell'endpoint ospitato da NVIDIA. Una configurazione funzionante è:

Backend: NVIDIA NIM
Base URL: https://integrate.api.nvidia.com
Model: moonshotai/kimi-k2.5
API Key: <your nvapi token>

Lascia vuoti gli header aggiuntivi a meno che il tuo gateway non li richieda. L'estensione invia richieste a /v1/chat/completions e usa automaticamente il bearer token configurato.

5. Esegui la tua prima analisi

1. Naviga un target attraverso il Proxy di Burp.
2. Fai clic con il tasto destro su una richiesta in Proxy > HTTP History.
3. Seleziona Extensions > Custom AI Agent > Analyze this request.
4. Si apre una sessione di chat con l'analisi dell'IA.

6. Connetti Claude Desktop tramite MCP (facoltativo)

Abilita il server MCP in Settings > MCP Server e aggiungi quanto segue alla configurazione di Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "burp-ai-agent": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "http://127.0.0.1:9876/sse"
      ]
    }
  }
}

Richiede Node.js 18+. Se abiliti External Access, il client MCP deve inviare Authorization: Bearer <token> a ogni richiesta.

Puoi anche registrare server MCP esterni o personalizzati in Settings > MCP > External Servers (trasporti SSE o stdio). I token di autenticazione dei server esterni sono memorizzati crittografati a riposo, con l'avvertenza descritta in Note su privacy e sicurezza. Vedi docs/external-mcp-servers.md per i dettagli di configurazione e le note di sicurezza.

Burp Scan Skill (Scansione IA da terminale)

La skill burp-scan ti consente di usare qualsiasi assistente di codifica IA (Claude Code, Gemini CLI, Codex, ecc.) come scanner di Burp dal tuo terminale. Al posto dell'IA integrata del plugin, l'IA del tuo terminale diventa il motore di ragionamento mentre Burp fornisce gli strumenti tramite MCP.

Cosa contiene

• Riferimento degli strumenti MCP (fino a tutti e 59 gli strumenti nella build completa) organizzati per azione di scansione
• Protocollo di analisi passiva (analisi del traffico senza inviare richieste)
• Libreria di payload per test attivi (200+ payload per 62 classi di vulnerabilità con pattern di rilevamento)
• Flusso di scansione end-to-end (scope -> passivo -> attivo -> OOB -> report)
• Protocollo di creazione issue con mappatura severità/confidenza

Installazione per Claude Code

Copia la skill nella directory delle skill di Claude Code:

# Global (available in all projects)
cp -r skills/burp-scan ~/.claude/skills/burp-scan

# Or project-specific
cp -r skills/burp-scan .claude/skills/burp-scan

Poi usa /burp-scan in Claude Code oppure lascia che si attivi automaticamente quando menzioni la scansione con Burp.

Installazione per altri assistenti IA

La skill è un file Markdown autonomo in skills/burp-scan/SKILL.md. Puoi usarla con qualsiasi assistente IA che supporti prompt di sistema o file di contesto:

• Gemini CLI / Codex / OpenCode: aggiungila come file di contesto oppure incollala nel prompt di sistema
• Client MCP personalizzati: includi il contenuto della skill come contesto di sistema insieme alla tua connessione MCP
• Qualsiasi LLM: il file è autonomo — forniscilo come contesto insieme alle definizioni dei tuoi strumenti MCP

Esempio di utilizzo

You: Connect to Burp MCP at localhost:9876 and scan the proxy history for IDOR vulnerabilities

AI: [Uses proxy_http_history to pull traffic]
    [Identifies endpoints with numeric IDs]
    [Sends http1_request with ID+1, ID-1 payloads]
    [Compares responses for different user data]
    [Creates issue_create for confirmed IDOR]

La skill e lo scanner integrato del plugin sono complementari: il plugin esegue scansioni automatiche in background, mentre la skill consente scansioni interattive e guidate dall'analista dal tuo terminale.

Documentazione

La documentazione completa è disponibile su burp-ai-agent.six2dez.com.

• Installazione
• Avvio rapido
• Tour dell'interfaccia
• Profili agente
• Scanner passivo
• Scanner attivo
• Panoramica MCP
• Modalità di privacy
• Riferimento impostazioni
• Risoluzione dei problemi
• Burp Scan Skill

Playbook per operatori

• Hardening MCP
• Guida alla sicurezza dell'interfaccia
• Risoluzione dei problemi del backend
• Configurazione del backend Anthropic
• Server MCP esterni

Note su privacy e sicurezza

• Segreti a riposo — cosa fa e cosa non fa la crittografia. Tutte le chiavi API e i token memorizzati (Anthropic, bearer token MCP, password del keystore TLS, ecc.) sono crittografati con AES-256-GCM usando una chiave master casuale per installazione (SecretCipher). Quella chiave master è a sua volta memorizzata nelle Preferenze di Burp, codificata in Base64, accanto al testo cifrato che protegge (preferenza secret.master.key.v1). Chiunque possa leggere le tue Preferenze di Burp può quindi leggere anche la chiave e decrittare i segreti. Non protegge contro un attaccante locale o un processo dannoso eseguito con il tuo utente; considerala come un'offuscamento contro l'ispezione casuale di un file di preferenze o di un progetto esportato. Se una credenziale deve sopravvivere a quel modello di minaccia, conservala in un archivio di segreti dedicato e incollala a ogni sessione.
• Le chiamate agli strumenti emesse dal modello richiedono la tua approvazione. Una chiamata a uno strumento che l'estensione estrae dall'output del modello non viene eseguita su Burp finché non decidi tu. Ogni strumento ha un livello di sicurezza obbligatorio: esecuzione automatica (sola lettura e output limitato), conferma con l'opzione Approve for session, oppure conferma a ogni singola chiamata. Un nome di strumento non riconosciuto dal catalogo viene risolto in conferma-a-ogni-chiamata, mai in automatico, e gli strumenti esterni con namespace ext: richiedono sempre la conferma a ogni chiamata. La decisione appare come una scheda inline nella trascrizione della chat invece che come finestra modale, e ogni decisione viene registrata — un evento di audit più una riga nella scheda Output di Burp, poiché la registrazione audit è disattivata per impostazione predefinita. Il rifiuto restituisce al modello un risultato neutro "non autorizzato, non riprovare" invece di un errore. Questo livello è indipendente dall'interruttore Unsafe Mode: Unsafe Mode stabilisce se uno strumento può mai essere eseguito, il livello stabilisce se il modello può eseguirlo senza chiedere. Razionale di progettazione: DECISIONS.md ADR-15. Runbook per operatori: docs/ui-safety-guide.md.
• La modalità di privacy STRICT anonimizza gli host usando un HKDF reale (HMAC-SHA256 extract/expand). La modalità BALANCED oscura cookie, token e header di autenticazione. La modalità OFF invia il traffico così com'è.
• Gli output dei server MCP esterni sono avvolti in un marcatore di confine di fiducia prima di entrare nel prompt dell'IA, prevenendo l'iniezione di prompt da risposte non affidabili dei server.

Le impostazioni hanno una versione di schema interna (settings.schema.version) e vengono migrate in modo additivo al caricamento per aggiornamenti sicuri.

Requisiti

• Burp Suite Community o Professional (2023.12+)
• Java 21 (incluso con le versioni moderne di Burp per l'esecuzione; richiesto separatamente per la compilazione dal codice sorgente)
• Almeno un backend IA configurato (vedi la tabella sopra)

Licenza

Questo progetto è rilasciato sotto la MIT License.

Disclaimer

L'utilizzo di Custom AI Agent per attaccare target senza previo consenso è illegale. È responsabilità dell'utente rispettare tutte le leggi applicabili. Gli sviluppatori non si assumono alcuna responsabilità per uso improprio o danni causati da questo strumento. Usalo in modo responsabile.

Contributi

Issue e pull request sono benvenuti. Vedi CONTRIBUTING.md per la configurazione dello sviluppo e le linee guida, oppure la Documentazione per sviluppatori per i dettagli sull'architettura.