Custom AI Agent

A ponte entre o Burp Suite e a IA moderna.

Nota sobre o nome: Esta extensão é publicada como Custom AI Agent (anteriormente Burp AI Agent). Ela foi renomeada para cumprir os requisitos de nomenclatura da BApp Store da PortSwigger e para evitar confusão com o provedor Burp AI integrado do Burp Suite. O repositório GitHub (github.com/six2dez/burp-ai-agent), o site de documentação (burp-ai-agent.six2dez.com) e o diretório de configuração (~/.burp-ai-agent/) mantêm o identificador burp-ai-agent para continuidade.

Custom AI Agent é uma extensão para o Burp Suite que integra IA ao seu fluxo de trabalho de segurança. Use modelos locais ou provedores em nuvem, conecte agentes de IA externos via MCP e deixe os scanners passivos/ativos encontrarem vulnerabilidades enquanto você se concentra nos testes manuais.

Novidades na v0.9.0

• Backend nativo Anthropic (CAP-01) — API Messages direta do Anthropic via transporte HTTP do Burp; todo o tráfego aparece no histórico do Proxy.
• Segredos em repouso com AES-256-GCM (SEC-01) — todas as chaves de API e tokens armazenados são criptografados com uma chave por instalação usando javax.crypto. A chave mestra fica nas Preferências do Burp junto com o texto cifrado, portanto isso protege contra inspeção casual de um arquivo de preferências, e não contra um atacante local — consulte Notas de privacidade e segurança.
• Anonimização de host com HKDF real (PRIV-01) — o modo STRICT agora usa HMAC-SHA256 extract/expand genuíno (não SHA-256 com sal) para anonimização de hosts.
• Redação de corpo de solicitação/resposta + padrões personalizados (PRIV-02) — o pipeline de redação cobre campos do corpo e padrões regex configuráveis pelo usuário, validados contra ReDoS.
• Alarme de segredos pré-envio (PRIV-03) — avisa antes que valores de alta entropia saiam do Burp; ações na lista de permissões são registradas no log de auditoria.
• Servidores MCP externos (CAP-02) — conecte-se a servidores MCP externos/personalizados (SSE ou stdio) para que agentes de IA possam chamar suas ferramentas junto com as ferramentas integradas do Burp.
• Limites de orçamento de tokens por sessão (CAP-04) — o BudgetGuard limita os gastos do scanner passivo com estados WARN/CAP/OFF; o scanner passivo pausa automaticamente no limite rígido.

Destaques

• 12 backends de IA — Burp AI (integrado), Anthropic, Ollama, LM Studio, NVIDIA NIM, Perplexity, OpenAI-compatível genérico, Gemini CLI, Claude CLI, Codex CLI, OpenCode CLI, Copilot CLI.
• 59 ferramentas MCP — deixe o Claude Desktop (ou qualquer cliente MCP) controlar o Burp de forma autônoma (8 ferramentas de IA nativas da extensão na build da loja, todas as 59 na build completa).
• Acesso MCP com escopo — opcionalmente confina todas as ferramentas MCP aos seus hosts no escopo, para que clientes de IA externos não alcancem alvos fora do escopo através do Burp.
• 62 classes de vulnerabilidade — scanners de IA passivos e ativos cobrindo injeção, autenticação, criptografia e muito mais. O scanner passivo é executado como um PassiveScanCheck do Burp (Burp Pro).
• Instalação pelos Releases — baixe o JAR em Releases. Não está na BApp Store: a submissão está aberta desde janeiro de 2026.
• UI consciente do tema — um sistema de design interno estiliza o painel de configurações e reaplica o tema automaticamente com o alternador claro/escuro do Burp.
• Habilidade Burp Scan — use seu assistente de codificação de IA preferido (Claude Code, Gemini CLI, Codex, etc.) como scanner via MCP.
• 3 modos de privacidade — STRICT / BALANCED / OFF. Redija dados sensíveis antes que saiam do Burp.
• Biblioteca de prompts personalizados — salve prompts de forma livre por contexto (solicitação HTTP ou problema do scanner); execute-os pelo menu de contexto ou digite prompts ad-hoc via Custom….
• Log de auditoria — JSONL com hash de integridade SHA-256 para conformidade; cada execução é marcada com promptSource / contextKind para reprodutibilidade.

Início rápido

1. Instalação

Baixe o JAR mais recente em Releases, ou compile a partir do código-fonte (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. Carregar no Burp

1. Abra o Burp Suite (Community ou Professional).
2. Vá em Extensions > Installed > Add.
3. Selecione Java como tipo de extensão e escolha o arquivo .jar.

A extensão é registrada no Burp como Custom AI Agent (o nome na lista de Extensions e na aba do Suite) para diferenciá-la do provedor Burp AI integrado do Burp.

3. Perfis de agente

A extensão instala automaticamente os perfis incluídos em ~/.burp-ai-agent/AGENTS/ na primeira execução. Adicione outros arquivos *.md nesse diretório para criar perfis personalizados.

4. Configurar um backend

Abra a aba AI Agent e vá em Settings. Escolha um backend:

Para NVIDIA NIM, o backend espera o mesmo fluxo no estilo chat-completions do endpoint hospedado pela NVIDIA. Uma configuração funcional é:

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

Deixe os cabeçalhos extras vazios, a menos que seu gateway os exija. A extensão envia solicitações para /v1/chat/completions e usa o token bearer configurado automaticamente.

5. Executar sua primeira análise

1. Navegue por um alvo pelo Proxy do Burp.
2. Clique com o botão direito em qualquer solicitação em Proxy > HTTP History.
3. Selecione Extensions > Custom AI Agent > Analyze this request.
4. Uma sessão de chat abre com a análise da IA.

6. Conectar o Claude Desktop via MCP (Opcional)

Ative o servidor MCP em Settings > MCP Server e adicione isto à configuração do seu 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"
      ]
    }
  }
}

Requer Node.js 18+. Se você ativar o External Access, o cliente MCP deve enviar Authorization: Bearer <token> em todas as solicitações.

Você também pode registrar servidores MCP externos ou personalizados em Settings > MCP > External Servers (transportes SSE ou stdio). Os tokens de autenticação de servidores externos são armazenados criptografados em repouso, com a ressalva descrita em Notas de privacidade e segurança. Consulte docs/external-mcp-servers.md para detalhes de configuração e notas de segurança.

Habilidade Burp Scan (Varredura de IA no terminal)

A habilidade burp-scan permite que você use qualquer assistente de codificação de IA (Claude Code, Gemini CLI, Codex, etc.) como um scanner do Burp a partir do seu terminal. Em vez da IA integrada do plugin, a IA do seu terminal se torna o mecanismo de raciocínio enquanto o Burp fornece as ferramentas via MCP.

O que ela contém

• Referência de ferramentas MCP (até 59 ferramentas na build completa) organizada por ação de scanner
• Protocolo de análise passiva (análise de tráfego sem enviar solicitações)
• Biblioteca de payloads para teste ativo (mais de 200 payloads para 62 classes de vulnerabilidade com padrões de detecção)
• Fluxo de trabalho de scanner ponta a ponta (escopo -> passivo -> ativo -> OOB -> relatório)
• Protocolo de criação de problemas com mapeamento de severidade/confiança

Instalação para Claude Code

Copie a habilidade para o diretório de habilidades do 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

Depois use /burp-scan no Claude Code ou deixe-o disparar automaticamente quando você mencionar o scanner do Burp.

Instalação para outros assistentes de IA

A habilidade é um arquivo Markdown independente em skills/burp-scan/SKILL.md. Você pode usá-la com qualquer assistente de IA que suporte prompts de sistema ou arquivos de contexto:

• Gemini CLI / Codex / OpenCode: adicione como arquivo de contexto ou cole no seu prompt de sistema
• Clientes MCP personalizados: inclua o conteúdo da habilidade como contexto de sistema junto com sua conexão MCP
• Qualquer LLM: o arquivo é autocontido — forneça-o como contexto junto com as definições de suas ferramentas MCP

Exemplo de uso

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]

A habilidade e o scanner integrado do plugin são complementares: o plugin executa varredura automatizada em segundo plano, enquanto a habilidade permite varredura interativa guiada por analistas a partir do seu terminal.

Documentação

A documentação completa está disponível em burp-ai-agent.six2dez.com.

• Instalação
• Início rápido
• Tour da UI
• Perfis de agente
• Scanner passivo
• Scanner ativo
• Visão geral do MCP
• Modos de privacidade
• Referência de configurações
• Solução de problemas
• Habilidade Burp Scan

Playbooks de operador

• Endurecimento do MCP
• Guia de segurança da UI
• Solução de problemas de backend
• Configuração do backend Anthropic
• Servidores MCP externos

Notas de privacidade e segurança

• Segredos em repouso — o que a criptografia faz e o que não faz. Todas as chaves de API e tokens armazenados (Anthropic, token bearer do MCP, senha do keystore TLS, etc.) são criptografados com AES-256-GCM usando uma chave mestra aleatória por instalação (SecretCipher). Essa chave mestra é armazenada nas Preferências do Burp, codificada em Base64, ao lado do texto cifrado que ela protege (preferência secret.master.key.v1). Qualquer pessoa que possa ler suas Preferências do Burp também pode ler a chave e descriptografar os segredos. Isso não protege contra um atacante local ou um processo malicioso executado com seu usuário; trate como ofuscação contra inspeção casual de um arquivo de preferências ou de um projeto exportado. Se uma credencial precisar sobreviver a esse modelo de ameaça, mantenha-a em um cofre de segredos dedicado e cole-a a cada sessão.
• Chamadas de ferramentas emitidas pelo modelo precisam da sua aprovação. Uma chamada de ferramenta que a extensão extrai da saída do modelo não é executada no Burp até que você decida. Cada ferramenta possui um nível de segurança obrigatório: executar automaticamente (somente leitura e saída limitada), confirmar com uma opção Approve for session, ou confirmar em cada chamada individual. Um nome de ferramenta que o catálogo não reconhece é resolvido para confirmar-sempre, nunca para automático, e ferramentas externas com namespace ext: sempre confirmam em cada chamada. A decisão aparece como um cartão inline no histórico do chat, em vez de uma janela modal, e cada decisão é registrada — um evento de auditoria além de uma linha na aba Output do Burp, já que o log de auditoria fica desativado por padrão. Negar retorna ao modelo um resultado neutro de "não autorizado, não tente novamente" em vez de um erro. Esse nível é independente do alternador Unsafe Mode: o Unsafe Mode determina se uma ferramenta pode alguma vez ser executada; o nível determina se o modelo pode executá-la sem perguntar. Fundamentação do design: DECISIONS.md ADR-15. Runbook do operador: docs/ui-safety-guide.md.
• O modo de privacidade STRICT anonimiza hosts usando HKDF real (HMAC-SHA256 extract/expand). O modo BALANCED remove cookies, tokens e cabeçalhos de autenticação. O modo OFF envia o tráfego como está.
• As saídas de servidores MCP externos são envolvidas em um marcador de limite de confiança antes de entrar no prompt da IA, prevenindo injeção de prompt a partir de respostas não confiáveis de servidores.

As configurações são versionadas internamente por esquema (settings.schema.version) e migradas de forma aditiva no carregamento para atualizações seguras.

Requisitos

• Burp Suite Community ou Professional (2023.12+)
• Java 21 (incluído com o Burp moderno para execução; necessário separadamente para compilar a partir do código-fonte)
• Pelo menos um backend de IA configurado (consulte a tabela acima)

Licença

Este projeto está licenciado sob a Licença MIT.

Aviso legal

O uso do Custom AI Agent para atacar alvos sem consentimento prévio é ilegal. É responsabilidade do usuário obedecer a todas as leis aplicáveis. Os desenvolvedores não assumem responsabilidade por uso indevido ou danos causados por esta ferramenta. Use com responsabilidade.

Contribuição

Issues e pull requests são bem-vindos. Consulte CONTRIBUTING.md para configuração de desenvolvimento e diretrizes, ou a Documentação do desenvolvedor para detalhes de arquitetura.