Custom AI Agent

El puente entre Burp Suite y la IA moderna.

Nota sobre el nombre: esta extensión se publica como Custom AI Agent (anteriormente Burp AI Agent). Se renombró para cumplir con los requisitos de nombres de la BApp Store de PortSwigger y para evitar confusiones con el proveedor Burp AI integrado de Burp Suite. El repositorio de GitHub (github.com/six2dez/burp-ai-agent), el sitio de documentación (burp-ai-agent.six2dez.com) y el directorio de configuración (~/.burp-ai-agent/) conservan el identificador burp-ai-agent para mantener la continuidad.

Custom AI Agent es una extensión para Burp Suite que integra IA en tu flujo de trabajo de seguridad. Usa modelos locales o proveedores en la nube, conecta agentes de IA externos mediante MCP y deja que los escáneres pasivos/activos encuentren vulnerabilidades mientras te centras en las pruebas manuales.

Novedades en v0.9.0

• Backend nativo de Anthropic (CAP-01) — API directa de Anthropic Messages mediante el transporte HTTP de Burp; todo el tráfico aparece en el historial del Proxy.
• Secretos en reposo con AES-256-GCM (SEC-01) — todas las claves API y tokens almacenados se cifran con una clave por instalación usando javax.crypto. La clave maestra reside en las Preferencias de Burp junto al texto cifrado, por lo que esto protege contra la inspección casual de un archivo de preferencias, no contra un atacante local — consulta Notas de privacidad y seguridad.
• Anonimización real de hosts con HKDF (PRIV-01) — el modo STRICT ahora usa extract/expand genuinos de HMAC-SHA256 (no SHA-256 con sal) para la anonimización de hosts.
• Redacción del cuerpo de peticiones/respuestas + patrones personalizados (PRIV-02) — el flujo de redacción cubre los campos del cuerpo y los patrones regex configurables por el usuario validados contra ReDoS.
• Alerta de secretos antes del envío (PRIV-03) — advierte antes de que valores de alta entropía salgan de Burp; las acciones de la lista de permitidos se anotan en el registro de auditoría.
• Servidores MCP externos (CAP-02) — conéctate a servidores MCP externos o personalizados (SSE o stdio) para que los agentes de IA puedan llamar a sus herramientas junto con las herramientas integradas de Burp.
• Límites de presupuesto de tokens por sesión (CAP-04) — BudgetGuard limita el gasto del escáner pasivo con estados WARN/CAP/OFF; el escáner pasivo se pausa automáticamente al alcanzar el tope máximo.

Aspectos destacados

• 12 backends de IA — Burp AI (integrado), Anthropic, Ollama, LM Studio, NVIDIA NIM, Perplexity, compatible genérico con OpenAI, Gemini CLI, Claude CLI, Codex CLI, OpenCode CLI, Copilot CLI.
• 59 herramientas MCP — permite que Claude Desktop (o cualquier cliente MCP) controle Burp de forma autónoma (8 herramientas de IA nativas de la extensión en la compilación de la tienda, las 59 en la compilación completa).
• Acceso MCP restringido al alcance — confina opcionalmente cada herramienta MCP a tus hosts dentro del alcance, para que los clientes de IA externos no puedan alcanzar objetivos fuera del alcance a través de Burp.
• 62 clases de vulnerabilidades — escáneres de IA pasivos y activos entre inyección, autenticación, criptografía y más. El escáner pasivo se ejecuta como PassiveScanCheck de Burp (Burp Pro).
• Instalación desde Releases — descarga el JAR desde Releases. No está en la BApp Store: el envío está abierto desde enero de 2026.
• Interfaz sensible al tema — un sistema de diseño interno estiliza el panel de configuración y cambia de tema automáticamente con el interruptor claro/oscuro de Burp.
• Burp Scan Skill — usa tu asistente de codificación con IA preferido (Claude Code, Gemini CLI, Codex, etc.) como escáner a través de MCP.
• 3 modos de privacidad — STRICT / BALANCED / OFF. Redacta datos sensibles antes de que salgan de Burp.
• Biblioteca de prompts personalizados — guarda prompts de forma libre por contexto (petición HTTP o incidencia del escáner); ejecútalos desde el menú contextual o escribe unos ad hoc mediante Custom….
• Registro de auditoría — JSONL con hash de integridad SHA-256 para cumplimiento; cada lanzamiento se etiqueta con promptSource / contextKind para su reproducibilidad.

Inicio rápido

1. Instalación

Descarga el JAR más reciente desde Releases, o compílalo desde el código fuente (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. Cargar en Burp

1. Abre Burp Suite (Community o Professional).
2. Ve a Extensions > Installed > Add.
3. Selecciona Java como tipo de extensión y elige el archivo .jar.

La extensión se registra en Burp como Custom AI Agent (el nombre en la lista de Extensiones y en la pestaña de Suite) para distinguirla del proveedor Burp AI integrado de Burp Suite.

3. Perfiles de agente

La extensión instala automáticamente los perfiles incluidos en ~/.burp-ai-agent/AGENTS/ en la primera ejecución. Coloca archivos *.md adicionales en ese directorio para añadir perfiles personalizados.

4. Configurar un backend

Abre la pestaña AI Agent y ve a Settings. Elige un backend:

Para NVIDIA NIM, el backend espera el mismo flujo de estilo chat-completions que el endpoint alojado de NVIDIA. Una configuración que funciona es:

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

Deja los encabezados adicionales vacíos a menos que tu puerta de enlace los requiera. La extensión envía peticiones a /v1/chat/completions y usa el token bearer configurado automáticamente.

5. Ejecuta tu primer análisis

1. Navega por un objetivo a través del Proxy de Burp.
2. Haz clic derecho en cualquier petición en Proxy > HTTP History.
3. Selecciona Extensions > Custom AI Agent > Analyze this request.
4. Se abre una sesión de chat con el análisis de IA.

6. Conectar Claude Desktop mediante MCP (opcional)

Habilita el servidor MCP en Settings > MCP Server y añade esto a la configuración de tu 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"
      ]
    }
  }
}

Requiere Node.js 18+. Si habilitas External Access, el cliente MCP debe enviar Authorization: Bearer <token> en cada petición.

También puedes registrar servidores MCP externos o personalizados en Settings > MCP > External Servers (transportes SSE o stdio). Los tokens de autenticación de los servidores externos se almacenan cifrados en reposo, con la salvedad descrita en Notas de privacidad y seguridad. Consulta docs/external-mcp-servers.md para obtener detalles de configuración y notas de seguridad.

Burp Scan Skill (escaneo con IA desde la terminal)

La skill burp-scan te permite usar cualquier asistente de codificación con IA (Claude Code, Gemini CLI, Codex, etc.) como escáner de Burp desde tu terminal. En lugar de la IA integrada del plugin, la IA de tu terminal se convierte en el motor de razonamiento mientras Burp proporciona las herramientas a través de MCP.

Qué incluye

• Referencia de herramientas MCP (hasta las 59 herramientas en la compilación completa) organizada por acción de escaneo
• Protocolo de análisis pasivo (análisis de tráfico sin enviar peticiones)
• Biblioteca de payloads para pruebas activas (más de 200 payloads para 62 clases de vulnerabilidades con patrones de detección)
• Flujo de trabajo de escaneo de extremo a extremo (scope -> passive -> active -> OOB -> report)
• Protocolo de creación de incidencias con mapeo de severidad/confianza

Instalación para Claude Code

Copia la skill a tu directorio de skills de 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

Luego usa /burp-scan en Claude Code o deja que se active automáticamente cuando menciones el escaneo de Burp.

Instalación para otros asistentes de IA

La skill es un archivo Markdown independiente en skills/burp-scan/SKILL.md. Puedes usarla con cualquier asistente de IA que admita prompts de sistema o archivos de contexto:

• Gemini CLI / Codex / OpenCode: añádela como archivo de contexto o pégala en tu prompt de sistema
• Clientes MCP personalizados: incluye el contenido de la skill como contexto de sistema junto con tu conexión MCP
• Cualquier LLM: el archivo es autónomo — úsalo como contexto junto con tus definiciones de herramientas MCP

Ejemplo 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]

La skill y el escáner integrado del plugin son complementarios: el plugin ejecuta escaneos automatizados en segundo plano, mientras que la skill permite un escaneo interactivo guiado por el analista desde tu terminal.

Documentación

La documentación completa está disponible en burp-ai-agent.six2dez.com.

• Instalación
• Inicio rápido
• Recorrido por la interfaz
• Perfiles de agente
• Escáner pasivo
• Escáner activo
• Descripción general de MCP
• Modos de privacidad
• Referencia de ajustes
• Solución de problemas
• Burp Scan Skill

Guías del operador

• Endurecimiento de MCP
• Guía de seguridad de la interfaz
• Solución de problemas de backend
• Configuración del backend de Anthropic
• Servidores MCP externos

Notas de privacidad y seguridad

• Secretos en reposo: qué hace y qué no hace el cifrado. Todas las claves API y tokens almacenados (Anthropic, token bearer MCP, contraseña del almacén de claves TLS, etc.) se cifran con AES-256-GCM usando una clave maestra aleatoria por instalación (SecretCipher). Esa clave maestra se almacena en las Preferencias de Burp, codificada en Base64, junto al texto cifrado que protege (preferencia secret.master.key.v1). Por lo tanto, cualquiera que pueda leer tus Preferencias de Burp también puede leer la clave y descifrar los secretos. No protege contra un atacante local ni contra un proceso malicioso que se ejecute con tu usuario; trátalo como ofuscación contra la inspección casual de un archivo de preferencias o de un proyecto exportado. Si una credencial debe sobrevivir a ese modelo de amenazas, guárdala en un almacén de secretos dedicado y pégala en cada sesión.
• Las llamadas a herramientas emitidas por el modelo requieren tu aprobación. Una llamada a herramienta que la extensión extrae de la salida del modelo no se ejecuta contra Burp hasta que tú decidas. Cada herramienta lleva un nivel de seguridad obligatorio: ejecutar automáticamente (solo lectura y salida limitada), confirmar con una opción Approve for session, o confirmar en cada llamada individual. Un nombre de herramienta que el catálogo no reconoce se resuelve como confirmar siempre, nunca como automático, y las herramientas externas con espacio de nombres ext: siempre confirman cada llamada. La decisión aparece como una tarjeta en línea en la transcripción del chat en lugar de un diálogo modal, y cada decisión se registra — un evento de auditoría más una línea en la pestaña Output de Burp, ya que el registro de auditoría está desactivado por defecto. Denegar devuelve al modelo un resultado neutral de "no autorizado, no reintentar" en lugar de un error. Este nivel es independiente del interruptor Unsafe Mode: Unsafe Mode determina si una herramienta puede alguna vez ejecutarse; el nivel determina si el modelo puede ejecutarla sin preguntar. Justificación del diseño: DECISIONS.md ADR-15. Manual del operador: docs/ui-safety-guide.md.
• El modo de privacidad STRICT anonimiza los hosts usando HKDF real (extract/expand HMAC-SHA256). El modo BALANCED redacta cookies, tokens y encabezados de autenticación. El modo OFF envía el tráfico tal cual.
• Las salidas de los servidores MCP externos se envuelven en un marcador de límite de confianza antes de entrar en el prompt de IA, lo que previene la inyección de prompts desde respuestas de servidores no confiables.

La configuración tiene versiones de esquema internas (settings.schema.version) y se migra de forma aditiva al cargar para realizar actualizaciones seguras.

Requisitos

• Burp Suite Community o Professional (2023.12+)
• Java 21 (incluido con Burp moderno para el tiempo de ejecución; se requiere por separado para compilar desde el código fuente)
• Al menos un backend de IA configurado (consulta la tabla anterior)

Licencia

Este proyecto se distribuye bajo la Licencia MIT.

Aviso legal

El uso de Custom AI Agent para atacar objetivos sin consentimiento previo es ilegal. Es responsabilidad del usuario cumplir todas las leyes aplicables. Los desarrolladores no asumen ninguna responsabilidad por el mal uso o los daños causados por esta herramienta. Úsala de forma responsable.

Contribuciones

Las issues y las pull requests son bienvenidas. Consulta CONTRIBUTING.md para la configuración de desarrollo y las directrices, o los Documentos para desarrolladores para conocer los detalles de la arquitectura.