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 nomenclatura 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/) mantienen el identificador burp-ai-agent por 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 tú te concentras en las pruebas manuales.

Novedades en v0.9.0

• Backend nativo de Anthropic (CAP-01) — API Messages de Anthropic directa a través del 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; sin texto plano en las preferencias.
• Anonimización real de hosts con HKDF (PRIV-01) — el modo STRICT ahora usa extracción/expansión HMAC-SHA256 genuina (no SHA-256 con sal) para la anonimización de hosts.
• Redacción de cuerpo de solicitud/respuesta + patrones personalizados (PRIV-02) — el pipeline de redacción cubre campos del cuerpo y patrones regex configurables, validados contra ReDoS.
• Tripwire de secretos previo al envío (PRIV-03) — advierte antes de que valores de alta entropía salgan de Burp; las acciones en lista blanca se registran en el registro de auditoría.
• Servidores MCP externos (CAP-02) — conéctate a servidores MCP externos/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 límite máximo.

Características destacadas

• 11 Backends de IA — Burp AI (integrado), Ollama, LM Studio, NVIDIA NIM, Perplexity, Genérico compatible con OpenAI, Gemini CLI, Claude CLI, Codex CLI, OpenCode CLI, Copilot CLI.
• 59 Herramientas MCP — Deja que Claude Desktop (o cualquier cliente MCP) maneje Burp de forma autónoma (8 herramientas de IA nativas de la extensión en la compilación de BApp Store, las 59 en la compilación completa).
• Acceso MCP con ámbito — Opcionalmente, confina cada herramienta MCP a tus hosts dentro del alcance, evitando que los clientes de IA externos lleguen a objetivos fuera del alcance a través de Burp.
• 62 Clases de Vulnerabilidad — Escáneres de IA Pasivos y Activos en inyección, autenticación, criptografía y más. El escáner pasivo se ejecuta como un PassiveScanCheck de Burp (Burp Pro).
• Disponible en la BApp Store — Instala Custom AI Agent directamente desde la BApp Store de Burp, o descarga la compilación completa desde Releases.
• UI adaptable al tema — Un sistema de diseño interno estiliza el panel de configuración y se re-tematiza automáticamente con el interruptor claro/oscuro de Burp.
• Burp Scan Skill — Usa tu asistente de codificación de 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 (solicitud HTTP o problema del escáner); ejecútalos desde el menú contextual o escribe prompts ad-hoc mediante Custom….
• Registro de Auditoría — JSONL con hash de integridad SHA-256 para cumplimiento; cada lanzamiento incluye promptSource / contextKind para reproducibilidad.

Inicio Rápido

1. Instalar

Instala Custom AI Agent desde la BApp Store de Burp, descarga el JAR más reciente desde Releases, o compila desde el código fuente (Java 21):

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

# Compilación completa (predeterminada, releases de GitHub) — las 59 herramientas MCP
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar
# Salida: build/libs/Custom-AI-Agent-full-<version>.jar

# Compilación para la tienda (BApp Store) — solo 8 herramientas MCP nativas de la extensión
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar -PstoreBuild=true
# Salida: 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 la pestaña de Suite) para distinguirlo del proveedor Burp AI integrado de Burp.

3. Perfiles de Agente

La extensión instala automáticamente los perfiles incluidos en ~/.burp-ai-agent/AGENTS/ en el primer inicio. Agrega 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 funcional es:

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

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

5. Ejecutar tu Primer Análisis

1. Navega a un objetivo a través del Proxy de Burp.
2. Haz clic derecho en cualquier solicitud 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 agrega esto a tu configuración de 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 Acceso Externo, el cliente MCP debe enviar Authorization: Bearer <token> en cada solicitud.

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

Burp Scan Skill (Escaneo con IA desde Terminal)

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

Qué Contiene

• Referencia de herramientas MCP (hasta las 59 herramientas en la compilación completa) organizadas por acción de escaneo
• Protocolo de análisis pasivo (análisis de tráfico sin enviar solicitudes)
• Biblioteca de payloads para pruebas activas (más de 200 payloads para 62 clases de vulnerabilidad con patrones de detección)
• Flujo de trabajo de escaneo completo (alcance -> pasivo -> activo -> OOB -> informe)
• Protocolo de creación de incidencias con mapeo de severidad/confianza

Instalar para Claude Code

Copia la habilidad en tu directorio de habilidades de Claude Code:

# Global (disponible en todos los proyectos)
cp -r skills/burp-scan ~/.claude/skills/burp-scan

# O específico de proyecto
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 escaneo con Burp.

Instalar para Otros Asistentes de IA

La habilidad 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: Agrega como archivo de contexto o pégalo en tu prompt de sistema
• Clientes MCP personalizados: Incluye el contenido de la habilidad como contexto de sistema junto con tus definiciones de herramientas MCP
• Cualquier LLM: El archivo es autocontenido — pásalo como contexto junto con tus definiciones de herramientas MCP

Ejemplo de Uso

Tú: Conéctate a Burp MCP en localhost:9876 y escanea el historial del proxy en busca de vulnerabilidades IDOR

IA: [Usa proxy_http_history para obtener tráfico]
    [Identifica endpoints con IDs numéricos]
    [Envía http1_request con payloads ID+1, ID-1]
    [Compara respuestas en busca de datos de diferentes usuarios]
    [Crea issue_create para IDOR confirmado]

La habilidad y el escáner integrado del plugin son complementarios: el plugin ejecuta escaneo automatizado en segundo plano, mientras que la habilidad 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
• Tour de la UI
• Perfiles de Agente
• Escáner Pasivo
• Escáner Activo
• Visión General de MCP
• Modos de Privacidad
• Referencia de Configuración
• Solución de Problemas
• Burp Scan Skill

Guías de Operador

• Endurecimiento de MCP
• Guía de Seguridad de la UI
• Solución de Problemas de Backend
• Configuración del Backend Anthropic
• Servidores MCP Externos

Notas de Privacidad y Seguridad

• Todas las claves API y tokens almacenados (Anthropic, token de portador de MCP, contraseña del almacén de claves TLS, etc.) se cifran en reposo con AES-256-GCM usando una clave maestra por instalación.
• El modo de privacidad STRICT anonimiza los hosts usando HKDF real (extracción/expansión 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 servidores MCP externos se envuelven en un marcador de límite de confianza antes de entrar en el prompt de IA, evitando la inyección de prompts desde respuestas de servidores no confiables.

Los ajustes tienen versiones de esquema internamente (settings.schema.version) y se migran de forma aditiva al cargar para actualizaciones seguras.

Requisitos

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

Licencia

Este proyecto está licenciado 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 con todas las leyes aplicables. Los desarrolladores no asumen ninguna responsabilidad por el uso indebido o los daños causados por esta herramienta. Úsala de forma responsable.

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Consulta CONTRIBUTING.md para la configuración de desarrollo y las directrices, o la Documentación para desarrolladores para detalles de arquitectura.