Custom AI Agent

Il ponte tra Burp Suite e l'IA moderna.

Nota sul nome: Questa estensione è pubblicata come Custom AI Agent (precedentemente Burp AI Agent). È stata rinominata per rispettare i 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 di documentazione (burp-ai-agent.six2dez.com) e la directory di configurazione (~/.burp-ai-agent/) mantengono l'identificatore burp-ai-agent per continuità.

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

Novità nella v0.9.0

• Backend Anthropic nativo (CAP-01) — API Messages di Anthropic direttamente tramite il trasporto HTTP di Burp; tutto il traffico appare nella cronologia del Proxy.
• Segreti crittografati a riposo con AES-256-GCM (SEC-01) — tutte le chiavi API e i token salvati sono crittografati con una chiave per installazione usando javax.crypto; nessun testo in chiaro nelle preferenze.
• Anonimizzazione host reali con HKDF (PRIV-01) — la modalità STRICT ora utilizza una vera estrazione/espansione HMAC-SHA256 (non SHA-256 con sale) per l'anonimizzazione degli host.
• Oscuramento corpo richiesta/risposta + pattern personalizzati (PRIV-02) — la pipeline di oscuramento copre i campi del corpo e pattern regex configurabili dall'utente, validati contro ReDoS.
• Sentinella segreto pre-invio (PRIV-03) — avvisa prima che valori ad alta entropia lascino Burp; le azioni in whitelist sono registrate nell'audit log.
• Server MCP esterni (CAP-02) — connetti server MCP esterni/personalizzati (SSE o stdio) in modo che gli agenti AI possano chiamare i loro strumenti insieme a quelli integrati di Burp.
• Guardrail budget token per sessione (CAP-04) — BudgetGuard limita la spesa dello scanner passivo con stati WARN/CAP/OFF; lo scanner passivo si mette in pausa automaticamente al limite massimo.

Punti salienti

• 11 Backend IA — Burp AI (integrato), Ollama, LM Studio, NVIDIA NIM, Perplexity, Generic OpenAI-compatible, Gemini CLI, Claude CLI, Codex CLI, OpenCode CLI, Copilot CLI.
• 59 Strumenti MCP — Lascia che Claude Desktop (o qualsiasi client MCP) guidi Burp autonomamente (8 strumenti IA nativi dell'estensione nella build del BApp Store, tutti e 59 nella build completa).
• Accesso MCP con ambito — Opzionalmente confina ogni strumento MCP ai tuoi host in-scope, così i client AI esterni non possono raggiungere target fuori scope tramite Burp.
• 62 Classi di vulnerabilità — Scanner IA passivi e attivi su injection, auth, crittografia e altro. Lo scanner passivo funziona come un PassiveScanCheck di Burp (Burp Pro).
• Disponibile sul BApp Store — Installa Custom AI Agent direttamente dal BApp Store di Burp, oppure scarica la build completa dalle Release.
• Interfaccia adattabile al tema — Un sistema di design interno stilizza il pannello delle impostazioni e si riadatta automaticamente al tema 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à Privacy — STRICT / BALANCED / OFF. Oscura i dati sensibili prima che lascino Burp.
• Libreria Prompt Personalizzati — Salva prompt liberi per contesto (richiesta HTTP o problema scanner); avviali dal menu contestuale o scrivine di ad-hoc tramite Custom….
• Audit Logging — JSONL con hashing di integrità SHA-256 per conformità; ogni avvio è marcato con promptSource / contextKind per riproducibilità.

Avvio Rapido

1. Installazione

Installa Custom AI Agent dal BApp Store di Burp, scarica l'ultimo JAR dalle Release, oppure compila dai sorgenti (Java 21):

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

# Build completa (default, release GitHub) — tutti e 59 gli strumenti MCP
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar
# Output: build/libs/Custom-AI-Agent-full-<version>.jar

# Build per Store (BApp Store) — solo 8 strumenti MCP IA nativi dell'estensione
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar -PstoreBuild=true
# Output: build/libs/Custom-AI-Agent-<version>.jar

2. Caricare 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.

3. Profili Agente

L'estensione installa automaticamente i profili inclusi in ~/.burp-ai-agent/AGENTS/ al primo avvio. Aggiungi altri file *.md in quella directory per inserire profili personalizzati.

4. Configurare un Backend

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

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

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

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

5. Esegui la tua prima analisi

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

6. Collegare Claude Desktop tramite MCP (Opzionale)

Abilita il server MCP in Settings > MCP Server e aggiungi questo 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> su 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. Vedi docs/external-mcp-servers.md per dettagli di configurazione e note sulla sicurezza.

Burp Scan Skill (Scansione AI da Terminale)

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

Cosa Contiene

• Riferimento agli strumenti MCP (fino a tutti e 59 nella build completa) organizzati per azione di scansione
• Protocollo di analisi passiva (analisi del traffico senza inviare richieste)
• Libreria di payload per test attivi (oltre 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 gravità/fiducia

Installazione per Claude Code

Copia la skill nella directory delle skills di Claude Code:

# Globale (disponibile in tutti i progetti)
cp -r skills/burp-scan ~/.claude/skills/burp-scan

# Oppure specifica per progetto
cp -r skills/burp-scan .claude/skills/burp-scan

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

Installazione per Altri Assistenti AI

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

• Gemini CLI / Codex / OpenCode: Aggiungi come file di contesto o incolla nel tuo 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 — fornisci come contesto insieme alle definizioni dei tuoi strumenti MCP

Esempio di Utilizzo

Tu: Connettiti a Burp MCP su localhost:9876 e scansiona la cronologia del proxy per vulnerabilità IDOR

AI: [Usa proxy_http_history per ottenere il traffico]
    [Identifica endpoint con ID numerici]
    [Invia http1_request con payload ID+1, ID-1]
    [Confronta le risposte per dati utente differenti]
    [Crea issue_create per IDOR confermato]

La skill e lo scanner integrato del plugin sono complementari: il plugin esegue scansioni di fondo automatiche, mentre la skill permette scansioni interattive 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à Privacy
• Riferimento Impostazioni
• Risoluzione Problemi
• Burp Scan Skill

Playbook per Operatori

• MCP Hardening
• Guida alla Sicurezza dell'Interfaccia
• Risoluzione Problemi Backend
• Configurazione Backend Anthropic
• Server MCP Esterni

Note sulla Privacy e Sicurezza

• Tutte le chiavi API e i token salvati (Anthropic, bearer token MCP, password keystore TLS, ecc.) sono crittografati a riposo con AES-256-GCM usando una chiave master per installazione.
• La modalità privacy STRICT anonimizza gli host usando un vero HKDF (estrazione/espansione HMAC-SHA256). 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 AI, prevenendo l'iniezione di prompt da risposte di server non affidabili.

Le impostazioni sono versionate internamente tramite schema (settings.schema.version) e migrate in modo additivo al caricamento per aggiornamenti sicuri.

Requisiti

• Burp Suite Community o Professional (2023.12+)
• Java 21 (incluso con Burp moderno per l'esecuzione; richiesto separatamente per la compilazione dai sorgenti)
• Almeno un backend AI configurato (vedi tabella sopra)

Licenza

Questo progetto è concesso in licenza con 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. Utilizza responsabilmente.

Contributi

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