**Cómo funciona:**

1. **Claude Code** lee `CLAUDE.md` para obtener la metodología completa de pentest y orquesta el flujo de trabajo de 7 fases
2. **Subagentes especializados por rol** (Scout, Analyzer, Exploiter, Reporter) ejecutan tareas enfocadas con plantillas de prompt dedicadas, guía de herramientas y antipatrones
3. **Servidor MCP WSTG** (más de 68 herramientas) proporciona procedimientos de prueba OWASP, 31 guías de técnicas de PortSwigger, árbol de tareas jerárquico, grafo de conocimiento, evasión de WAF, priorización de endpoints, verificación de resultados, compresión de contexto, puertas de calidad y generación de informes
4. **Contenedor Docker** ejecuta las 27 herramientas de seguridad — el tráfico puede enrutarse opcionalmente a través de Burp Suite para monitoreo pasivo
5. **Playwright MCP** maneja pruebas basadas en navegador (DOM XSS, clickjacking, páginas de inicio de sesión renderizadas con JS)

---

## Características

### Cobertura Integral OWASP
- **109 casos de prueba WSTG** en 12 categorías — desde recopilación de información hasta pruebas de API
- Cada prueba incluye procedimientos CLI paso a paso, payloads específicos del contexto, criterios de detección y rúbricas de severidad
- Las pruebas se priorizan (DEBE/DEBERÍA) con disparadores condicionales para que nada relevante se omita

### 31 Guías de Técnicas de Ataque de PortSwigger
- Obtenidas de [PortSwigger Web Security Academy](https://portswigger.net/web-security) — métodos de detección, técnicas de explotación, payloads, chuletas y patrones de evasión de WAF
- Organizadas por clase de vulnerabilidad (SQLi, XSS, SSRF, JWT, OAuth, etc.) para uso directo durante las pruebas
- Integradas en cada fase de prueba — los agentes cargan automáticamente la guía de técnica relevante antes de probar cada clase de vulnerabilidad
- Tablas de payloads específicos de base de datos/plataforma (Oracle vs MySQL vs PostgreSQL vs MSSQL para SQLi, Jinja2 vs Twig vs Freemarker para SSTI, etc.)
- Patrones de evasión de WAF organizados por nivel de evasión (básico → intermedio → avanzado)

### 27 Herramientas de Seguridad Preconfiguradas
- Todas las herramientas preinstaladas en una sola imagen Docker — `make setup` y ya estás listo
- Herramientas organizadas por fase: descubrimiento, pruebas de inyección, autenticación, criptografía, pruebas de API
- Integración automática con proxy Burp Suite para monitoreo pasivo de tráfico

### Flujo de Trabajo Estructurado de 7 Fases
- **Fase 0:** Descubrimiento y Mapeo de la Aplicación
- **Fase 1:** Recopilación de Información y Reconocimiento
- **Fase 2:** Pruebas de Configuración y Despliegue
- **Fase 3:** Gestión de Identidad, Autenticación, Autorización y Sesión
- **Fase 4:** Pruebas de Validación de Entrada (pipelines de XSS/SQLi/SSRF)
- **Fase 5:** Pruebas de Manejo de Errores, Criptografía, Lógica de Negocio, Lado del Cliente y API
- **Fase 6:** Verificación de Cobertura y Reporte
- **Fase 7:** Revisión Final del Juez y Remediación

### Sistema de Aseguramiento de Calidad
- **Puertas de fase automatizadas** — cada fase debe pasar controles de calidad antes de continuar
- **Subagente Revisor de Calidad** en cada transición de fase identifica brechas y sugiere mejoras
- **Juez Final** — un agente sin contexto revisa todo el engagement en frío, como un revisor QA externo
- **Puertas de agotamiento** — "no vulnerable" requiere prueba de esfuerzo de prueba suficiente (técnicas mínimas e intentos de evasión)

### Hallazgos Basados en Evidencia
- Cada hallazgo requiere comandos curl reproducibles y evidencia completa de solicitud/respuesta
- **Clasificación de tres niveles:** EXPLOTADO (impacto probado), POTENCIAL (bloqueado por control), FALSO_POSITIVO (el control se mantiene)
- **Marco anti-alucinación** — "sin exploit = sin hallazgo" aplicado en todos los niveles
- Listas de verificación de evidencia por clase de vulnerabilidad verificadas antes de registrar cualquier hallazgo

### Subagentes Especializados por Rol
- **4 roles dedicados** con plantillas de prompt enfocadas, guía de herramientas y antipatrones:
  - **Scout** — solo reconocimiento, mapea la superficie de ataque sin enviar payloads (Fase 0-1)
  - **Analyzer** — identifica sinks potenciales con payloads canarios/testigo, construye colas de explotación (análisis Fase 2-5)
  - **Exploiter** — consume la salida del Analyzer, prueba la explotación con evidencia, registra hallazgos confirmados (explotación Fase 4)
  - **Reporter** — revisión de calidad y Juez Final, revisa datos sin enviar solicitudes (QA + post-reporte)
- Punto de control de validación entre análisis y explotación evita esfuerzo desperdiciado
- Cada rol tiene listas explícitas de herramientas permitidas/restringidas y contratos de entrada/salida

### Explotación en Pipeline (Fase 4)
- **3 pipelines independientes de dos etapas** se ejecutan en paralelo: XSS, Inyección (SQLi/CMDi), SSRF/SSTI
- Cada pipeline: Analyzer (descubrir → analizar → encolar) → punto de control de validación → Exploiter (explotar → registrar)
- Cada pipeline carga su guía de técnica de PortSwigger para métodos de detección, chuletas y patrones de evasión de WAF
- Inteligencia de WAF compartida entre todos los pipelines
- Payloads testigo conscientes del contexto para 13 tipos de sink

### Evasión Adaptativa de WAF
- **Huella digital automática de WAF** a partir de encabezados de respuesta, cuerpo y códigos de estado — identifica 12 proveedores de WAF (Cloudflare, AWS WAF, Akamai, Imperva, ModSecurity, F5, FortiWeb, Sucuri, Barracuda, Wordfence, NAXSI, Citrix)
- **Payloads de evasión específicos del proveedor** organizados por nivel de complejidad (básico → intermedio → avanzado)
- Inteligencia de WAF compartida entre todos los agentes a través del sistema de entregables
- Los agentes identifican automáticamente el WAF ante la primera respuesta de bloqueo y cambian a payloads de evasión adaptados

### Grafo de Conocimiento Transversal entre Fases
- **Grafo entidad-relación** rastrea endpoints, parámetros, tecnologías, hallazgos, cookies, dominios y roles de usuario
- **Encadenamiento automatizado de vulnerabilidades** mediante búsqueda de caminos BFS con 7 patrones de cadena predefinidos:
  - XSS + falta de CSP, XSS + cookie débil (sin HttpOnly), Open redirect + callback OAuth
  - IDOR + rol admin, SSRF + metadatos en la nube, Sin bloqueo + sin MFA, CORS + endpoint sensible
- Mejora de severidad cuando el encadenamiento aumenta materialmente el impacto
- Se completa durante las pruebas, se consulta después de la Fase 4 para el descubrimiento de cadenas

### Árbol de Tareas Jerárquico
- Estructura de árbol persistente (fases como ramas, pruebas como hojas) evita el sesgo de profundidad primero de los LLM y la pérdida de contexto
- El agente principal mantiene una visión macro estratégica; los subagentes actualizan solo sus nodos hoja asignados
- Auto-propagación: cuando todos los hijos se completan, el padre se completa automáticamente
- Porcentajes de finalización por fase para la toma de decisiones informada

### Priorización de Riesgo de Endpoint
- Puntuar y ordenar endpoints por riesgo para pruebas priorizadas — el de mayor riesgo se prueba primero
- Factores de puntuación: cantidad de parámetros, indicadores de riesgo tecnológico, confianza en la cadena de contaminación, convergencia de herramientas, requisitos de autenticación, nombres de parámetros inyectables
- Integrado en la generación del mapa de endpoints de la Fase 0

### Análisis de Salida de Herramientas
- **13 analizadores integrados** para herramientas CLI comunes (nmap, nuclei, sqlmap, ffuf, httpx, whatweb, testssl, nikto, dalfox, katana, gau, wapiti, commix)
- Condensa la salida bruta de la herramienta 3-5 veces mientras preserva hallazgos clave, endpoints y errores
- Verbosidad configurable: resumen (~15 líneas), detallado (~50 líneas), completo (salida analizada completa)

### Verificación de Resultados de Herramientas CLI
- Validación automática de la calidad de la salida de herramientas CLI — detecta salida vacía, errores de proxy, problemas de permisos y resultados sospechosos
- **10 validadores por herramienta** (nmap, nuclei, sqlmap, ffuf, feroxbuster, testssl, dalfox, wapiti, katana, httpx) con sugerencias de comandos corregidos
- Cuando una herramienta produce salida vacía o sospechosa, el validador sugiere correcciones (ej., agregar `-Pn` para nmap, eliminar variables de entorno de proxy, probar diferentes banderas)
- Integrado en el flujo de trabajo de ejecución de herramientas — los agentes llaman a `verify_tool_result()` después de cada ejecución de herramienta CLI

### Compresión Progresiva de Contexto
- **Resúmenes de fase** (~500-800 palabras) se generan automáticamente cuando se superan las puertas de fase — capturando hallazgos, cobertura, resultados de herramientas y superficie de ataque en forma comprimida
- Previene la degradación del contexto en compromisos de larga duración reemplazando datos históricos sin procesar con resúmenes estructurados
- `get_engagement_summary()` combina todos los resúmenes de fase en una sola visión general para inyectar en nuevas indicaciones de subagentes
- Los resúmenes se almacenan como entregables — accesibles por cualquier agente downstream sin requerir el historial completo del engagement

### Análisis Contrafactual (Descubrimiento de Segunda Pasada)
- Después de que un Analyzer completa con vulnerabilidades encontradas, se genera un **segundo Analyzer** con instrucciones de "asumir que esas vulnerabilidades están parcheadas"
- El Analyzer contrafactual busca vulnerabilidades **adicionales**: diferentes endpoints, diferentes parámetros, diferentes contextos de inyección, fallos de lógica
- Los resultados se añaden a la cola de explotación existente (fusión automática con deduplicación por endpoint+parámetro e IDs de incremento automático)
- Basado en la investigación de ablación PenHeal que muestra un +71% de cobertura de vulnerabilidades con indicaciones contrafactuales

### Soporte Multi-Dominio
- Detección y manejo automático de SSO/OAuth/OIDC/SAML
- Registro, rastreo y pruebas de alcance por dominio
- Gestión de frascos de cookies para persistencia de sesión entre dominios
- Escalada de fallos de autenticación de 6 niveles (concesiones alternativas → PKCE → navegador headless → extracción de tokens → aprovisionamiento de usuario → no autenticado)

### Gestión de Engagement a Prueba de Caídas
- `findings.md` y `progress.log` de solo añadidura sobreviven a caídas
- Puntos de control de Git workspace con capacidad de reversión
- **Reanudación automática en interrupción** — `resume-prompt.md` se genera automáticamente en cada punto de control con contexto completo (objetivo, credenciales, fase actual, pruebas restantes, alcance). Pega en una nueva sesión para continuar exactamente donde lo dejaste
- Granularidad de punto de control a mitad de fase — rastrea qué pruebas dentro de una fase están completadas, no solo el estado a nivel de fase
- Registro de auditoría completo de cada llamada a herramienta MCP con marcas de tiempo

### Informes Profesionales
- Informes en Markdown con resumen ejecutivo, hallazgos por severidad, matriz de cobertura de pruebas y cobertura de herramientas
- Porcentajes de cobertura por categoría y análisis de brechas
- Análisis de encadenamiento de vulnerabilidades documentado
- Observaciones del Juez Final y notas de calidad incluidas

---

## Sistema de Roles de Agente

AutoPentest usa 4 roles de agente especializados en lugar de subagentes genéricos. Cada rol tiene una plantilla de prompt dedicada con guía de herramientas enfocada, contratos de entrada/salida y antipatrones.

| Rol | Plantilla | Propósito | Fases |
|------|----------|---------|--------|
| **Scout** | `templates/agent-roles/scout.md` | Reconocimiento y mapeo de superficie de ataque | Fase 0-1, descubrimiento de código fuente |
| **Analyzer** | `templates/agent-roles/analyzer.md` | Descubrimiento de vulnerabilidades con payloads canarios/testigo | Análisis Fase 2-5 |
| **Exploiter** | `templates/agent-roles/exploiter.md` | Prueba de explotación con evidencia | Explotación Fase 4 |
| **Reporter** | `templates/agent-roles/reporter.md` | Revisión de calidad y Juez Final | Transiciones de fase, post-reporte |

### Cómo Funciona el Pipeline

La Fase 4 (pruebas de mayor impacto) utiliza un pipeline de dos etapas por clase de vulnerabilidad:```
┌──────────────────────────────────────────────────────────────┐
│                    Pipeline 1: XSS                           │
│                                                              │
│  Analyzer (75 turns)          Exploiter (75 turns)           │
│  ┌─────────────────────┐      ┌─────────────────────┐        │
│  │ Discover endpoints  │      │ Load Analyzer queue │        │
│  │ Send canary payloads│─────▶│ Attempt exploitation│        │
│  │ Build exploit queue │ gate │ Prove impact        │        │
│  │ Save deliverable    │      │ Log findings        │        │
│  └─────────────────────┘      └─────────────────────┘        │
│                          ▲                                   │
│               validate_exploitation_queue()                  │
└──────────────────────────────────────────────────────────────┘

Eso es todo. Las 27 herramientas de seguridad están ahora instaladas y listas dentro del contenedor Docker.

### Verificar la instalación```bash
# Check all tools are installed
make verify-tools

# Expected output:
# [+] nuclei: installed
# [+] httpx: installed
# [+] katana: installed
# ... (27 tools total)

Entonces dile a Claude qué probar:```
Run a full WSTG assessment against https://target.example.com

Claude preguntará por cualquier información faltante (como credenciales) e iniciará el flujo de trabajo de 7 fases.

### Opción B: Modo basado en configuración (Recomendado)

Cree un archivo de configuración YAML para evaluaciones repetibles y consistentes:```yaml
# configs/my-target.yaml
target:
  url: https://app.example.com
  scope:
    - app.example.com
    - api.example.com
  exclude:
    - cdn.example.com

authentication:
  login_type: form
  login_url: https://app.example.com/login
  credentials:
    username: [email protected]
    password: secret123
  login_flow:
    - "Type $username into the email field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"
  success_condition:
    type: url_contains
    value: "/dashboard"

rules:
  avoid:
    - description: "Do not test logout"
      type: path
      url_path: "/logout"
  focus:
    - description: "Prioritize API endpoints"
      type: path
      url_path: "/api"

reporting:
  tester_name: "Security Team"

### Opción C: Pruebas dirigidas

Ejecute pruebas WSTG específicas contra endpoints específicos:```
Run WSTG-INPV-05 (SQL Injection) against https://app.example.com/search?q=

*   [Nmap](https://nmap.org/) escáner de redes
*   [OpenVAS](https://www.openvas.org/) escáner de vulnerabilidades
*   [OWASP ZAP](https://www.zaproxy.org/) escáner de aplicaciones web
*   [sqlmap](http://sqlmap.org/) herramienta de inyección SQL
*   [Metasploit Framework](https://www.metasploit.com/) framework de pruebas de penetración
*   [Aircrack-ng](https://www.aircrack-ng.org/) herramientas de seguridad inalámbrica
*   [Burp Suite Community Edition](https://portswigger.net/burp/communitydownload) escáner de vulnerabilidades web
*   [John the Ripper](https://www.openwall.com/john/) cracker de contraseñas
*   [Hydra](https://github.com/vanhauser-thc/thc-hydra) cracker de inicio de sesión en red
*   [Wireshark](https://www.wireshark.org/) analizador de protocolos de red
*   [Nikto](https://cirt.net/Nikto2) escáner de servidores web
*   [Kismet](https://www.kismetwireless.net/) detector de redes inalámbricas
*   [Ettercap](https://www.ettercap-project.org/) sniffer/interceptor de red
*   [Maltego](https://www.maltego.com/) herramienta de análisis de enlaces
*   [Recon-ng](https://github.com/lanmaster53/recon-ng) framework de reconocimiento web
*   [theHarvester](https://github.com/laramies/theHarvester) recolector de correos, subdominios y nombres
*   [dirb](https://dirb.sourceforge.net/) escáner de contenido web
*   [Gobuster](https://github.com/OJ/gobuster) herramienta de fuerza bruta de directorios/archivos y DNS
*   [CeWL](https://github.com/digininja/CeWL) generador personalizado de listas de palabras
*   [Searchsploit](https://www.exploit-db.com/searchsploit) herramienta de búsqueda en la base de datos de exploits```
Run all authentication tests (WSTG-ATHN) against https://app.example.com

---

## Fases de Prueba

### Fase 0: Descubrimiento y Mapeo de la Aplicación

La fase base crítica. Claude de forma autónoma:

1. **Verificaciones previas al vuelo** — verifica la accesibilidad del objetivo, detecta redirecciones y autenticación entre dominios
2. **Lanza 10+ herramientas en segundo plano** en paralelo (katana, ffuf, nuclei, whatweb, gau, nmap, feroxbuster, wapiti, httpx)
3. **Rastreo recursivo** — sigue enlaces hasta profundidad 2-3, analiza HTML/JS en busca de endpoints
4. **Fuerza bruta de directorios** — rutas comunes + listas de palabras específicas de tecnologías
5. **Ingesta de resultados de herramientas** — lee todas las salidas de herramientas en segundo plano y las fusiona en un mapa unificado de endpoints
6. **Construye un inventario estructurado de endpoints** con parámetros, requisitos de autenticación y prioridades

**Salida:** Un mapa completo de endpoints organizado por dominio, listo para pruebas sistemáticas.

### Fase 1-2: Reconocimiento y Configuración

- Huella del servidor, detección de tecnologías, revisión de metadatos
- Análisis de encabezados de seguridad (HSTS, CSP, CORS, X-Frame-Options)
- Pruebas de configuración TLS, descubrimiento de interfaces de administración
- Pruebas de métodos HTTP, manejo de extensiones de archivo

### Fase 3: Autenticación, Autorización y Gestión de Sesiones

- **Entramado de roles/privilegios** construido antes de las pruebas (mapea guardias, middleware y pruebas de omisión)
- Pruebas de IDOR con múltiples IDs alternativos por endpoint
- Pruebas de CSRF en cada endpoint que cambia el estado
- Fijación de sesión, secuestro y análisis de tokens
- Pruebas de vulnerabilidades JWT (si aplica)
- Pruebas de debilidades OAuth/OIDC (si aplica)

### Fase 4: Validación de Entrada (Mayor Impacto)

Tres pipelines independientes de dos etapas se ejecutan en paralelo, cada uno usando la división de roles Analizador→Explotador:

| Pipeline | Clases de Vulnerabilidad | Herramientas | Guías de Técnicas |
|----------|--------------------------|--------------|-------------------|
| Pipeline XSS | XSS Reflejado, XSS Almacenado, XSS DOM | dalfox, Playwright | XSS, DOM |
| Pipeline Inyección | Inyección SQL, Inyección de Comandos, Inyección NoSQL | sqlmap, commix, nosqli | SQLI, CMDI, NOSQLI |
| Pipeline SSRF/SSTI | SSRF, SSTI, Path Traversal | sstimap, ssrfmap | SSRF, SSTI, PTRAV |

Cada pipeline: **Analizador** (descubrir → analizar → construir cola de explotación) → punto de control de validación → **Explotador** (intentar explotación → probar impacto → registrar hallazgos). La inteligencia de evasión de WAF se comparte entre todos los pipelines.

### Fase 5: Manejo de Errores, Criptografía, Lógica de Negocio, Cliente y APIs

- Divulgación de trazas de pila y mensajes de error
- Pruebas de TLS/SSL mediante testssl.sh
- Omisión de lógica de negocio (circunvención de flujo de trabajo, falsificación de solicitudes)
- Pruebas del lado del cliente (clickjacking, redirecciones abiertas, manipulación del DOM)
- Pruebas de GraphQL y API REST
- Análisis de encadenamiento de vulnerabilidades en todos los hallazgos

### Fase 6: Informes

- Verificación de cobertura (cobertura de pruebas + cobertura de herramientas)
- Deduplicación de hallazgos y calibración de severidad
- Generación de informes en Markdown con resumen ejecutivo, hallazgos, matrices de cobertura

### Fase 7: Revisión Final del Juez

Un agente sin contexto revisa todo el compromiso en frío — sin conocimiento de decisiones o dificultades de la prueba. Examina:

- **Integridad de cobertura** — pruebas aprobadas automáticamente, endpoints faltantes
- **Detección de cascada N/A** — categorías con marcas excesivas de "no aplica"
- **Calidad de hallazgos** — integridad de evidencia, consistencia de severidad, oportunidades de encadenamiento
- **Utilización de herramientas** — herramientas ejecutadas pero salida nunca revisada, razones de omisión perezosa
- **Superficie de ataque perdida** — endpoints no probados, parámetros no probados, dominios no probados

El veredicto (PASS/CONDITIONAL_PASS/FAIL) desencadena acciones de remediación específicas antes de que se entregue el informe.

---

## Herramientas de Seguridad

### Descubrimiento y Reconocimiento (Fase 0)

| Herramienta | Propósito | Flags Clave |
|-------------|-----------|-------------|
| **katana** | Rastreador web con renderizado JS | `-jc` para rastreo JavaScript |
| **httpx** | Sondeo HTTP, detección de tecnologías | `-tech-detect -status-code -title` |
| **ffuf** | Fuzzing de directorios/parámetros | `-w wordlist -mc all -fc 404` |
| **feroxbuster** | Enumeración recursiva de directorios | `--smart --auto-tune` |
| **nuclei** | Escáner de vulnerabilidades basado en plantillas | `-t cves/ -t misconfigurations/` |
| **nikto** | Mala configuración del servidor web | `-Tuning 1234567890` |
| **whatweb** | Huella digital de tecnologías | `--aggression 3` |
| **nmap** | Escaneo de puertos y servicios | `-sV -sC --top-ports 1000` |
| **gau** | Descubrimiento de URLs históricas | `--blacklist png,jpg,gif` |
| **subfinder** | Enumeración de subdominios | `-silent -all` |

### Pruebas de Inyección (Fase 4)

| Herramienta | Propósito | Flags Clave |
|-------------|-----------|-------------|
| **sqlmap** | Inyección SQL (todas las técnicas) | `--batch --risk 3 --level 5` |
| **dalfox** | Escaneo y explotación XSS | `--skip-bav --deep-domxss` |
| **commix** | Inyección de comandos | `--batch --all` |
| **sstimap** | Inyección de Plantillas del Lado del Servidor | `-u <url>` |
| **ssrfmap** | Explotación de SSRF | `-r request.txt` |
| **nosqli** | Inyección NoSQL | `-u <url>` |
| **crlfuzz** | Inyección CRLF / Separación HTTP | `-u <url>` |
| **smuggler** | Contrabando de solicitudes HTTP | `-u <url>` |

### Autenticación y Sesión (Fase 3)

| Herramienta | Propósito | Flags Clave |
|-------------|-----------|-------------|
| **hydra** | Fuerza bruta de credenciales | `-L users.txt -P pass.txt` |
| **jwt_tool** | Análisis y explotación de tokens JWT | `-t <token> -M at` |

### Criptografía y APIs (Fase 5)

| Herramienta | Propósito | Flags Clave |
|-------------|-----------|-------------|
| **testssl.sh** | Pruebas de configuración TLS/SSL | `--severity HIGH --sneaky` |
| **graphql-cop** | Pruebas de seguridad GraphQL | `-t <url>` |
| **websocat** | Pruebas de WebSocket | `ws://<url>` |

### Infraestructura (Fase 2)

| Herramienta | Propósito |
|-------------|-----------|
| **corscanner** | Escaneo de mala configuración CORS |
| **dnsreaper** | Detección de toma de control de subdominios |

### Automatización del Navegador

| Herramienta | Propósito |
|-------------|-----------|
| **Playwright** | Prueba de XSS DOM, clickjacking, inicio de sesión renderizado con JS, inspección de almacenamiento del lado del cliente |

---

## Base de Conocimiento WSTG

109 casos de prueba en 12 categorías OWASP, cada uno con procedimientos específicos de CLI:

| Código | Categoría | Pruebas | Ejemplos |
|--------|-----------|:-------:|----------|
| **INFO** | Recopilación de Información | 10 | Descubrimiento en motores de búsqueda, huella del servidor, revisión de metadatos |
| **CONF** | Configuración y Despliegue | 14 | Encabezados de seguridad, CORS, CSP, HSTS, interfaces de administración |
| **IDNT** | Gestión de Identidad | 5 | Definiciones de roles, registro, enumeración de cuentas |
| **ATHN** | Autenticación | 11 | Credenciales por defecto, bloqueo, omisión de autenticación, MFA, política de contraseñas |
| **ATHZ** | Autorización | 5 | Path traversal, omisión de autenticación, escalada de privilegios, IDOR |
| **SESS** | Gestión de Sesiones | 11 | Atributos de cookies, CSRF, fijación/secuestro de sesión, JWT |
| **INPV** | Validación de Entrada | 20 | XSS, SQLi, CMDi, SSTI, SSRF, path traversal, XXE, LDAP |
| **ERRH** | Manejo de Errores | 2 | Mensajes de error, trazas de pila |
| **CRYP** | Criptografía | 4 | Configuración TLS, padding oracle, cifrado débil |
| **BUSL** | Lógica de Negocio | 10 | Omisión de flujo de trabajo, falsificación de solicitudes, carga de archivos, límites de tasa |
| **CLNT** | Lado del Cliente | 14 | XSS DOM, clickjacking, redirecciones abiertas, WebSockets, almacenamiento |
| **APIT** | Pruebas de API | 3 | GraphQL, REST, SOAP |

Cada archivo de prueba incluye:
- Procedimientos CLI paso a paso (comandos curl, invocaciones de herramientas)
- Payloads organizados por nivel de omisión (básico, intermedio, avanzado)
- Criterios de detección con rúbricas de evaluación de severidad
- Guía de remediación con referencias

---

## Guías de Técnicas de PortSwigger

31 guías de referencia de técnicas de ataque obtenidas de [PortSwigger Web Security Academy](https://portswigger.net/web-security), organizadas por clase de vulnerabilidad para uso directo durante compromisos reales de pentesting.

### Qué Incluye

| Código | Categoría | Mapeo WSTG | Contenido Clave |
|--------|-----------|------------|-----------------|
| **SQLI** | Inyección SQL | INPV-05 | Técnicas UNION/cegas/de error/basadas en tiempo/OOB, hojas de referencia específicas de bases de datos (Oracle, MySQL, PostgreSQL, MSSQL), evasión de WAF |
| **XSS** | Cross-Site Scripting | INPV-01, INPV-02, CLNT-01 | Contextos reflejado/almacenado/DOM, payloads de etiquetas y manejadores de eventos, omisión de CSP, evasión de filtros |
| **CMDI** | Inyección de Comandos del SO | INPV-12 | Caracteres separadores, técnicas ciegas (retardo de tiempo, OOB), payloads específicos del SO |
| **SSTI** | Inyección de Plantillas del Lado del Servidor | INPV-18 | Detección y explotación de Jinja2/Twig/Freemarker/Velocity/ERB, escapes de sandbox |
| **SSRF** | Server-Side Request Forgery | INPV-19 | Trucos de esquemas URL, ofuscación de IP, reenlace DNS, metadatos de la nube, omisión de filtros |
| **PTRAV** | Path Traversal | INPV-04 | Variaciones de codificación, inyección de byte nulo, omisión de wrappers |
| **XXE** | XML External Entities | INPV-07 | Recuperación de archivos, SSRF mediante XXE, XXE ciego con OOB, entidades de parámetros |
| **AUTHN** | Autenticación | ATHN-01 a ATHN-07 | Fuerza bruta, omisión de 2FA, envenenamiento de restablecimiento de contraseña, relleno de credenciales |
| **AUTHZ** | Control de Acceso | ATHZ-01 a ATHZ-04 | IDOR, escalada de privilegios, omisión horizontal/vertical, controles basados en referer |
| **JWT** | JSON Web Tokens | SESS-10 | Confusión de algoritmos (none/HS256→RS256), inyección kid, explotación de JWK/JKU |
| **OAUTH** | OAuth 2.0 | ATHZ-05 | Robo de código de autorización, redirección abierta, actualización de ámbito, CSRF en flujos OAuth |
| **CSRF** | Cross-Site Request Forgery | SESS-05 | Omisión de token, omisión de SameSite, omisión de validación de referer |
| **SMUGGLE** | Contrabando de Solicitudes HTTP | INPV-15 | CL.TE, TE.CL, TE.TE, degradación HTTP/2, tunelización de solicitudes |
| **DOM** | Vulnerabilidades Basadas en DOM | CLNT-01 | Fuentes/sumideros, DOM clobbering, gadgets de contaminación de prototipos |
| **CORS** | Intercambio de Recursos de Origen Cruzado | CONF-13, CLNT-07 | Reflexión de origen, origen nulo, explotación de confianza en subdominios |
| **NOSQLI** | Inyección NoSQL | INPV-05 | Inyección de operadores MongoDB, inyección JavaScript, extracción ciega |
| **GRAPHQL** | GraphQL | APIT-01 | Introspección, sugerencia de campos, ataques por lotes, omisión de autorización |
| **RACE** | Condiciones de Carrera | BUSL-04 | Exceso de límite, TOCTOU, carreras de un solo endpoint, sincronización de último fotograma |
| **UPLOAD** | Carga de Archivos | BUSL-08, BUSL-09 | Omisión de extensión, manipulación de tipo de contenido, web shells, archivos políglotas |
| **HOST** | Inyección de Encabezado Host | INPV-17 | Envenenamiento de restablecimiento de contraseña, envenenamiento de caché, SSRF basado en enrutamiento |

Más 11: CLICK, WS, CACHEPOIS, CACHEDEC, DESER, INFO, BUSL, PROTO, API, LLM, SKILLS.

### Cómo Se Utilizan

Las guías de técnicas se integran en cada fase de prueba a través de la herramienta MCP `get_technique_guide()`:```
Phase 2 → CORS guide for CONF-13 testing
Phase 3 → AUTHN, AUTHZ, CSRF, JWT, OAUTH guides for auth/session testing
Phase 4 → SQLI, XSS, CMDI, SSTI, SSRF, PTRAV, XXE guides for input validation
Phase 5 → DOM, CLICK, GRAPHQL, RACE, UPLOAD guides for client-side & business logic

El solucionador tiene dos modos:
- **autopentest** (predeterminado): Ejecuta Claude Code desde la raíz del proyecto, cargando `.mcp.json` (servidor MCP con más de 68 herramientas) y `CLAUDE.md` (metodología de pentest). Mide la capacidad completa de AutoPentest.
- **raw** (`RAW=1`): Ejecuta Claude Code sin servidor MCP ni metodología. Línea base para medir el valor añadido de AutoPentest sobre la capacidad LLM sin procesar.

Cada desafío es una aplicación Docker Compose con una flag inyectada en el momento de la compilación. La extracción de la flag de la salida de Claude determina aprobado/reprobado. Los resultados se puntúan por desafío, por etiqueta y por nivel de dificultad.

### Modo CTF

Para desafíos CTF y aplicaciones pequeñas, habilite el modo CTF para puertas de calidad relajadas:```yaml
mode: ctf
target:
  url: https://target.com

### Hallazgo de ejemplo (Inyección SQL)

Del informe — un hallazgo crítico de inyección SQL con evidencia completa de explotación:```
FINDING-017: SQL Injection in /catalog category parameter — Full Data Extraction

Severity: Critical
WSTG Reference: WSTG-INPV-05

The category parameter is vulnerable to UNION-based SQL injection.
The attacker can:
  1. Inject a single quote to cause a 500 error (confirming injection)
  2. Use UNION SELECT with 8 columns to extract arbitrary data
  3. Enumerate tables: PRODUCTS, TRACKING, USERS
  4. Extract credentials from the USERS table

Evidence (reproducible curl command):
  curl -sk "https://ginandjuice.shop/catalog?category='+UNION+SELECT+1,USERNAME,PASSWORD,
  1,1,USERNAME,1,USERNAME+FROM+USERS+LIMIT+10--"

### Configuración del servidor MCP

El archivo `.mcp.json` registra dos servidores MCP:```json
{
  "mcpServers": {
    "wstg-pentest": {
      "command": "uv",
      "args": ["--directory", "./server", "run", "server.py"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Todos los dominios se registran automáticamente en el alcance con su tipo (app, auth_provider, api, cdn).

### Pruebas por Dominio

Cada prueba WSTG se evalúa por dominio, no solo el principal:

- Las herramientas de descubrimiento (katana, ffuf, nuclei) se ejecutan contra **todos** los dominios
- Las herramientas de validación de entrada (sqlmap, dalfox) apuntan a endpoints en **cada** dominio con procesamiento del lado del servidor
- Una prueba es "no aplicable" solo cuando **ningún** dominio tiene la característica probada

### Autenticación entre Dominios

Protocolos SSO compatibles:
- **OAuth 2.0 / OIDC** (Authorization Code, PKCE, Password Grant, Client Credentials)
- **SAML** (flujo iniciado por SP)
- **Keycloak**, **Auth0**, **Okta**, **Azure AD**
- **SSO Personalizado** (seguimiento de cadena de redirección con cookie jar)

El procedimiento de escalado de autenticación (6 niveles) asegura que las pruebas puedan continuar incluso con flujos de autenticación complejos.

---

## Recuperación ante Fallos

AutoPentest está diseñado para sobrevivir a interrupciones:

### Puntos de Control Automáticos
- Las compuertas de fase guardan automáticamente puntos de control en PASS
- `git_checkpoint()` crea instantáneas git del espacio de trabajo de la evaluación
- Los registros de solo anexión (`findings.md`, `progress.log`) sobreviven a fallos

### Reanudación Automática mediante resume-prompt.md (Recomendado)

Cada punto de control y compuerta de fase genera automáticamente `engagements/<eid>/resume-prompt.md` — un prompt completo y autocontenido con todo lo que una sesión nueva necesita:

- URL objetivo, credenciales de autenticación y dominios del alcance
- Fase actual y qué pruebas específicas quedan (precisión a mitad de fase)
- Estado del cookie jar e instrucciones de reautenticación
- Reglas de evitar/enfocar y referencias del mapa de endpoints

**Para reanudar después de una interrupción:**
1. Abre una nueva sesión de Claude Code
2. Pega el contenido de `engagements/<eid>/resume-prompt.md`
3. Claude retoma exactamente donde se quedó — no se necesita contexto manual

### Reanudar desde Punto de Control (Alternativo)```
Resume engagement pentest-2026-02-11-myapp

### Reversión en caso de fallo

Si una fase produce malos resultados, revierte al punto de control anterior:```
Roll back the engagement to the last checkpoint

---

## Requisitos

| Requisito | Versión | Notas |
|-------------|---------|-------|
| Docker | 20.10+ | Docker Desktop en macOS/Windows |
| Claude Code | Última | `npm install -g @anthropic-ai/claude-code` |
| uv | 0.1+ | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Node.js | 18+ | Para el servidor MCP de Playwright |
| Python | 3.10+ | Gestionado por uv (no requiere instalación manual) |
| Burp Suite Pro | Última | **Opcional** — para monitoreo pasivo de tráfico |

**Plataformas compatibles:** macOS (Apple Silicon e Intel), Linux (x86_64 y ARM64)

---

## FAQ

**P: ¿Esto reemplaza a un probador de penetración humano?**

No. AutoPentest automatiza las partes sistemáticas y basadas en metodología de un pentest. Destaca en cobertura (asegurando que no se omita nada) y consistencia (cada prueba sigue el mismo procedimiento). Sin embargo, la lógica de negocio compleja, las cadenas de explotación creativas y la evaluación de riesgos dependiente del contexto aún se benefician de la experiencia humana. Piense en ello como un multiplicador de fuerza.

**P: ¿Cuánto tiempo lleva una evaluación completa?**

Depende del tamaño y la complejidad de la aplicación. Una aplicación web típica de tamaño mediano (50-100 endpoints) toma unas pocas horas. Las aplicaciones multidominio con SSO llevan más tiempo. La arquitectura canalizada de la Fase 4 paraleliza las pruebas que más tiempo consumen.

**P: ¿Puedo ejecutar esto sin Burp Suite?**

Sí. Burp Suite es opcional y se usa solo para monitoreo pasivo de tráfico. Todas las solicitudes HTTP pasan a través de `docker exec curl` y todas las herramientas de seguridad se ejecutan dentro del contenedor Docker. Sin Burp, pierde la capacidad de revisar el tráfico en el historial del proxy de Burp, pero toda la funcionalidad de prueba funciona.

**P: ¿Qué son las guías de técnica de PortSwigger?**

31 guías de referencia de ataque que cubren detección, técnicas de explotación, payloads, hojas de trucos y patrones de evasión de WAF — obtenidas de PortSwigger Web Security Academy. Durante las pruebas, los agentes cargan automáticamente la guía relevante (por ejemplo, la guía de SQLi al probar inyección SQL) para obtener una referencia completa de técnicas y payloads. Consulte [`docs/adding-knowledge-base-resources.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/docs/adding-knowledge-base-resources.md) para agregar sus propias guías.

**P: ¿Cómo agrego wordlists o payloads personalizados?**

Coloque las wordlists en `templates/wordlists/` y estarán disponibles dentro del contenedor Docker a través del montaje de volumen. Los archivos de prueba WSTG en `knowledge-base/` también se pueden personalizar con payloads adicionales. Para agregar nuevas guías de técnicas de ataque, siga las instrucciones en [`docs/adding-knowledge-base-resources.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/docs/adding-knowledge-base-resources.md).

**P: ¿Puedo probar aplicaciones detrás de una VPN?**

Sí. El contenedor Docker hereda la red de su host (en Linux con `--network host`) o llega al host a través de `host.docker.internal` (en macOS/Windows). Si su VPN se está ejecutando en el host, el contenedor puede alcanzar los objetivos protegidos por VPN.

**P: ¿Qué sucede si se interrumpe un pentest (fallo, límite de uso, tiempo de espera)?**

AutoPentest genera automáticamente un archivo `resume-prompt.md` en cada punto de control con todo lo necesario para continuar. Abra una nueva sesión de Claude Code, pegue el contenido de `engagements/<eid>/resume-prompt.md`, y las pruebas se reanudan exactamente donde se dejaron, incluido el progreso a mitad de fase, credenciales, alcance y pruebas restantes.

**P: ¿Qué pasa con la limitación de velocidad?**

AutoPentest incluye clasificación de errores de tres niveles (Transitorio/Límite de velocidad/Permanente) con retroceso automático. Si el objetivo limita la velocidad de las solicitudes, las herramientas se ralentizan automáticamente. También puede configurar reglas de omisión en la configuración para saltar endpoints específicos.

**P: ¿Cuáles son los roles de los agentes?**

AutoPentest utiliza 4 roles especializados (Scout, Analyzer, Exploiter, Reporter) en lugar de subagentes genéricos. Cada rol tiene una plantilla de instrucciones dedicada con guía de herramientas enfocada, listas de herramientas restringidas y antipatrones. Esto evita que los agentes confundan reconocimiento, análisis, explotación e informes, mejorando el enfoque y el aislamiento de fallos. Consulte [`templates/agent-roles/README.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/templates/agent-roles/README.md) para el índice completo de roles.

**P: ¿Cómo funciona la evasión de WAF?**

Cuando un payload es bloqueado (403, página de bloqueo), AutoPentest identifica automáticamente el proveedor de WAF a partir de las características de la respuesta, luego carga payloads de evasión específicos del proveedor organizados por nivel de complejidad. Se admiten 12 proveedores de WAF (Cloudflare, AWS WAF, Akamai, Imperva, ModSecurity, F5 y más). La inteligencia de WAF se comparte entre todos los agentes a través del sistema de entregables.

**P: ¿Qué es el análisis contrafactual?**

Después del primer pase de análisis que encuentra vulnerabilidades, AutoPentest puede generar un segundo Analyzer que asume que todas las vulnerabilidades conocidas están parcheadas. Esto obliga al agente a buscar vectores de ataque diferentes: diferentes endpoints, parámetros, contextos de inyección y fallos lógicos. Los resultados se fusionan en la cola de explotación existente con deduplicación automática. Esta técnica se basa en investigación académica (estudio de ablación PenHeal) que muestra una mejora del +71% en la cobertura de vulnerabilidades.

**P: ¿Cómo funciona la verificación de resultados?**

Cuando las herramientas CLI (nmap, nuclei, sqlmap, etc.) producen resultados vacíos o sospechosos, la herramienta `verify_tool_result()` detecta problemas comunes (errores de proxy, permiso denegado, banderas incorrectas) y sugiere comandos corregidos. Esto evita que los agentes cuenten silenciosamente ejecuciones de herramientas rotas como "completadas", un modo de fallo común en pentesting automatizado.

**P: ¿Cómo funciona el encadenamiento de vulnerabilidades?**

El grafo de conocimiento rastrea entidades (endpoints, parámetros, hallazgos, cookies, dominios) y relaciones descubiertas durante las pruebas. Después de la Fase 4, `find_chains()` utiliza BFS para descubrir rutas de ataque de múltiples saltos y verifica 7 patrones de cadena predefinidos (por ejemplo, XSS + falta de CSP, SSRF + metadatos de nube, IDOR + rol de administrador). Las cadenas que aumentan el impacto desencadenan actualizaciones automáticas de severidad.

---

## Descargo de responsabilidad

**Esta herramienta está destinada únicamente para pruebas de seguridad autorizadas.** Utilice AutoPentest solo contra aplicaciones para las que tenga permiso explícito para probar. El acceso no autorizado a sistemas informáticos es ilegal. Los autores no son responsables del mal uso de esta herramienta.

Siempre asegúrese de tener:
- Autorización por escrito del propietario de la aplicación
- Un alcance claramente definido de lo que se puede y no se puede probar
- Una comprensión del entorno de prueba (producción vs. staging)
- Reglas de omisión apropiadas configuradas para endpoints destructivos o sensibles

---

<p align="center">
  Construido con <a href="https://modelcontextprotocol.io">Model Context Protocol</a>
</p>