Framework de agentes de IA para pruebas de seguridad de caja negra con orquestación autónoma multiagente, herramientas de pentesting integradas e integración con MCP para flujos de trabajo de bug bounty, red team y pruebas de penetración.
<div align="center">
<img src="https://raw.githubusercontent.com/gh05tcrew/pentestagent/HEAD/assets/pentestagent-logo.png" alt="Logotipo de PentestAgent" width="220" style="margin-bottom: 20px;"/>
# PentestAgent
### Pruebas de Penetración con IA
[](https://www.python.org/) [](LICENSE.txt) [](https://github.com/GH05TCREW/pentestagent/releases) [](https://github.com/GH05TCREW/pentestagent) [](https://github.com/GH05TCREW/pentestagent)
</div>
https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975
## Requisitos
- Python 3.10+
- Clave de API para OpenAI, Anthropic u otro proveedor compatible con LiteLLM
## Instalación
```bash
# Clone
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent
# Setup (creates venv, installs deps)
.\scripts\setup.ps1 # Windows
./scripts/setup.sh # Linux/macOS
# Or manual
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
source venv/bin/activate # Linux/macOS
pip install -e ".[all]"
playwright install chromium # Required for browser tool
```
## Configuración
Crea un archivo `.env` en la raíz del proyecto:
```
ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514
```
O para OpenAI:
```
OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5
```
Cualquier [modelo compatible con LiteLLM](https://docs.litellm.ai/docs/providers) funciona.
### Uso de un relay / base de API personalizada
Apunta PentestAgent a cualquier endpoint compatible con OpenAI mediante `OPENAI_API_BASE`:
```bash
OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>
```
Para endpoints compatibles con Anthropic usa `ANTHROPIC_API_BASE` en su lugar.
Consulta `.env.example` para las notas completas sobre proveedores y opciones de embeddings.
## Ejecución
```bash
pentestagent # Launch TUI
pentestagent -t 192.168.1.1 # Launch with target
pentestagent tui --docker # Run tools in Docker container
```
## Docker
Ejecuta las herramientas dentro de un contenedor Docker para aislamiento y herramientas de pentesting preinstaladas.
### Opción 1: Obtener la imagen preconstruida (más rápido)
```bash
# Base image with nmap, netcat, curl
docker run -it --rm \
-e ANTHROPIC_API_KEY=your-key \
-e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \
ghcr.io/gh05tcrew/pentestagent:latest
# Kali image with metasploit, sqlmap, hydra, etc.
docker run -it --rm \
-e ANTHROPIC_API_KEY=your-key \
ghcr.io/gh05tcrew/pentestagent:kali
```
### Opción 2: Compilar localmente
```bash
# Build
docker compose build
# Run
docker compose run --rm pentestagent
# Or with Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali
```
El contenedor ejecuta PentestAgent con acceso a herramientas de pentesting de Linux. El agente puede usar `nmap`, `msfconsole`, `sqlmap`, etc. directamente mediante la herramienta de terminal.
Requiere que Docker esté instalado y en ejecución.
## Modos
PentestAgent tiene tres modos, accesibles mediante comandos en la TUI:
| Modo | Comando | Descripción |
|------|---------|-------------|
| Assist | `/assist <task>` | Una instrucción de un solo disparo, con ejecución de herramientas |
| Agent | `/agent <task>` | Ejecución autónoma de una sola tarea |
| Crew | `/crew <task>` | Modo multiagente. El orquestador genera agentes especializados |
| Interact | `/interact <task>` | Modo interactivo. Chatea con el agente; te ayudará y guiará durante el procedimiento de pentesting |
### Comandos de la TUI
```
/assist <task> One single-shot instruction.
/agent <task> Run autonomous agent on task
/crew <task> Run multi-agent crew on task
/interact <task> Chat with the agent in guided mode
/target <host> Set target
/tools List available tools
/notes Show saved notes
/report Generate report from session
/memory Show token/memory usage
/prompt Show system prompt
/conversations Browse and restore saved conversations
/mcp <list/add> Visualizes or adds a new MCP server.
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
Manually spawn a child MCP agent from the TUI.
/despawn <server_name>
Terminate and remove a previously spawned child agent.
/clear Clear chat and history
/quit Exit (also /exit, /q)
/help Show help (also /h, /?)
```
Pulsa `Esc` para detener un agente en ejecución. `Ctrl+Q` para salir.
## Playbooks
PentestAgent incluye **playbooks de ataque** preconstruidos para pruebas de seguridad de caja negra. Los playbooks definen un enfoque estructurado para evaluaciones de seguridad específicas.
**Ejecutar un playbook:**
```bash
pentestagent run -t example.com --playbook thp3_web
```
## Herramientas
PentestAgent incluye herramientas integradas y soporta MCP (Model Context Protocol) para extensibilidad.
**Herramientas integradas:** `terminal`, `browser`, `notes`, `web_search` (requiere `TAVILY_API_KEY`), `spawn_mcp_agent`
### Autogeneración de agentes (`spawn_mcp_agent`)
`spawn_mcp_agent` es una herramienta integrada que permite a un agente en ejecución generar una copia hija de sí mismo como servidor MCP subordinado conectado a través de stdio. El proceso hijo está completamente aislado — su propio runtime, cliente LLM, historial de conversación y almacén de notas — y su conjunto completo de herramientas se inyecta de nuevo en las herramientas disponibles del agente padre después de la generación.
Esto permite flujos de trabajo jerárquicos y multiagente sin orquestación externa: el agente se autoorganiza delegando subtareas acotadas a hijos que genera bajo demanda.
| Argumento | Tipo | Por defecto | Descripción |
|----------|------|---------|-------------|
| `target` | string | — | Objetivo de pentesting para pasar al hijo |
| `scope` | string[] | — | Objetivos/CIDR dentro del alcance para el hijo |
| `model` | string | variable de entorno | Identificador del modelo; sobrescribe `PENTESTAGENT_MODEL` en el hijo |
| `no_rag` | boolean | `false` | Omitir la inicialización del motor RAG en el hijo |
| `no_mcp` | boolean | `true` | Omitir las conexiones a servidores MCP externos en el hijo (recomendado) |
Después de que `spawn_mcp_agent` regrese, las herramientas del hijo (`run_task`, `run_task_async`, `await_tasks`, etc.) están disponibles en la **siguiente** llamada de herramienta. El nombre del servidor del hijo se asigna automáticamente (p. ej., `child_agent_1`) y se devuelve en el resultado.
**Ejemplo — orquestador delegando reconocimiento paralelo a dos hijos:**
```
# Turn 1: spawn two isolated child agents
spawn_mcp_agent target="10.0.1.0/24" scope=["10.0.1.0/24"]
spawn_mcp_agent target="10.0.2.0/24" scope=["10.0.2.0/24"]
# Turn 2: children's tools are now available — delegate work asynchronously
child_agent_1__run_task_async task="Full port scan and service enumeration"
child_agent_2__run_task_async task="Full port scan and service enumeration"
# Turn 3: wait and collect
child_agent_1__await_tasks task_ids=["<id1>"] timeout_seconds=600
child_agent_2__await_tasks task_ids=["<id2>"] timeout_seconds=600
child_agent_1__get_task_result task_id="<id1>"
child_agent_2__get_task_result task_id="<id2>"
```
### Control manual de agentes hijo (`/spawn` y `/despawn`)
Además de la herramienta automática `spawn_mcp_agent`, la TUI expone dos comandos que te permiten generar y terminar agentes hijo **manualmente**, independientemente de un bucle de agente en ejecución.
#### `/spawn`
```
/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]
```
Genera un nuevo agente MCP hijo a través de stdio y lo adjunta a la sesión actual. El hijo aparece como un panel de terminal plegable en la barra lateral de la TUI y sus herramientas quedan disponibles para el agente padre en la siguiente llamada de herramienta.
| Argumento | Descripción |
|----------|-------------|
| `target` | Objetivo de pentesting para pasar al hijo (posicional o `--target`) |
| `--scope CIDR` | Uno o más CIDR dentro del alcance (repetible) |
| `--model MODEL` | Sobrescribe el modelo para el agente hijo |
| `--no-rag` | Omitir la inicialización del motor RAG en el hijo |
| `--no-mcp` | Omitir las conexiones a servidores MCP externos en el hijo |
**Ejemplos:**
```
/spawn 10.0.1.1
/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag
```
#### `/despawn`
```
/despawn <server_name>
```
Termina el agente hijo identificado por `server_name` (p. ej., `child_agent_1`), elimina su panel de terminal de la TUI y desconecta sus herramientas de la sesión padre. Usa `/mcp list` para ver los nombres de todos los agentes hijo actualmente activos.
**Ejemplo:**
```
/despawn child_agent_1
```
### Optimizador de herramientas RAG para MCP
Cuando un servidor MCP expone más de 128 herramientas, PentestAgent reemplaza automáticamente el catálogo completo con una única herramienta `mcp_<server>_rag_optimizer`. Esta metaherramienta utiliza similitud de embeddings (a través de LiteLLM, por defecto `text-embedding-3-small`) para recuperar las herramientas más relevantes para la tarea en cuestión e inyectarlas en el siguiente turno del agente — manteniendo la ventana de contexto manejable sin perder acceso al conjunto completo de herramientas.
El optimizador es transparente para el agente: llama a la herramienta RAG con consultas enfocadas en lenguaje natural que describen lo que necesita, y las herramientas coincidentes quedan disponibles en el siguiente turno para llamarlas directamente.
**Guía de uso para el agente:**
| Argumento | Tipo | Por defecto | Descripción |
|----------|------|---------|-------------|
| `queries` | string[] | *(requerido)* | Una consulta enfocada por capacidad necesaria. Cuanto más específica, mayor precisión |
| `top_k` | integer | `20` | Herramientas a recuperar por consulta (máx. 128). Los resultados se combinan y deduplican |
Los embeddings se calculan una vez al inicio y se almacenan en caché, por lo que las consultas repetidas son rápidas. El optimizador se construye por servidor, de modo que cada servidor MCP con un catálogo grande obtiene su propio índice independiente.
> **Consejo:** Pasa una consulta por capacidad distinta en lugar de combinar todo en una sola consulta. `["list open ports on a host", "get process memory usage"]` obtiene mejores resultados que `["list ports and memory and CPU"]`.
### Integración con MCP
PentestAgent soporta MCP (Model Context Protocol) en dos direcciones: **consumir** servidores MCP externos como fuentes de herramientas y **exponerse a sí mismo** como servidor MCP para que clientes externos (Claude Desktop, Cursor, etc.) puedan controlar PentestAgent programáticamente.
---
#### Consumo de servidores MCP externos (modo cliente)
Configura `mcp_servers.json` para conectar PentestAgent a cualquier servidor MCP externo. Ejemplo de configuración:
```json
{
"mcpServers": {
"nmap": {
"command": "npx",
"args": ["-y", "gc-nmap-mcp"],
"env": {
"NMAP_PATH": "/usr/bin/nmap"
}
}
}
}
```
---
#### Exponer PentestAgent como servidor MCP (modo servidor)
PentestAgent puede ejecutarse como servidor MCP, lo que permite a cualquier cliente compatible con MCP enviar tareas, inspeccionar resultados y controlar el agente de forma remota. Se admiten dos transportes:
**STDIO** — para clientes locales (p. ej., Claude Desktop, Cursor):
```bash
pentestagent mcp_server --type stdio
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24
pentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker
```
**SSE (HTTP)** — para clientes remotos o en red:
```bash
pentestagent mcp_server --type sse
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080
pentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0/24 --docker
```
El transporte SSE expone un único endpoint `/mcp` que soporta `POST` (solicitudes), `GET` (flujo SSE persistente para push iniciado por el servidor) y `DELETE` (cierre de sesión). Las sesiones se rastrean mediante la cabecera `Mcp-Session-Id`.
**Todas las banderas de `mcp_server`:**
| Bandera | Por defecto | Descripción |
|------|---------|-------------|
| `--type` | *(requerido)* | Transporte: `stdio` o `sse` |
| `--host` | `0.0.0.0` | Host de enlace SSE |
| `--port` | `8080` | Puerto de enlace SSE |
| `--target` | ninguno | Objetivo principal de pentesting (IP / nombre de host) |
| `--scope` | `[]` | Objetivos/CIDR dentro del alcance (separados por espacios) |
| `--model` | variable de entorno | Identificador del modelo; sobrescribe `PENTESTAGENT_MODEL` |
| `--docker` | false | Usa DockerRuntime en lugar de LocalRuntime |
| `--no-rag` | false | Omitir la inicialización del motor RAG |
| `--no-mcp` | false | Omitir las conexiones a servidores MCP externos |
##### Ejemplo: configuración de Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"pentestagent": {
"command": "pentestagent",
"args": ["mcp_server", "--type", "stdio"]
}
}
}
```
---
#### Referencia de herramientas del servidor MCP
Cuando actúa como servidor MCP, PentestAgent expone las siguientes herramientas:
**Estado y configuración del servidor**
| Herramienta | Descripción |
|------|-------------|
| `get_server_status` | Estado en vivo del servidor: disponibilidad, recuento de tareas por estado, objetivo/alcance principal, tamaño del almacén de memoria |
| `get_config` | Configuración principal del agente: objetivo, alcance, iteraciones máximas, lista de herramientas |
| `update_config` | Actualiza el objetivo, el alcance o las iteraciones máximas para todas las tareas posteriores |
**Ejecución de tareas**
| Herramienta | Descripción |
|------|-------------|
| `run_task` | Envía una tarea y **bloquea** hasta que se complete. Devuelve el resultado completo, las herramientas usadas y una instantánea de notas |
| `run_task_async` | Envía una tarea y **regresa inmediatamente** con un `task_id`. Consulta con `get_task_status` |
**Inspección de tareas**
| Herramienta | Descripción |
|------|-------------|
| `list_tasks` | Lista todas las tareas con estado, objetivo y resumen. Filtrable por estado |
| `get_task_status` | Consulta el estado actual y la vista previa del resultado de una tarea |
| `get_task_result` | Resultado completo de la tarea: salida final, pasos de razonamiento, todas las llamadas a herramientas y resultados, instantánea de notas |
| `await_tasks` | Bloquea hasta que un conjunto de IDs de tareas asíncronas hayan terminado (consulta cada 500 ms, tiempo de espera configurable) |
**Control de tareas**
| Herramienta | Descripción |
|------|-------------|
| `cancel_task` | Cancela una tarea en ejecución o pendiente por su ID |
**Gestión de herramientas**
| Herramienta | Descripción |
|------|-------------|
| `list_tools` | Lista todas las herramientas disponibles para el agente |
| `enable_tool` | Habilita una herramienta con nombre en el agente principal |
| `disable_tool` | Deshabilita una herramienta con nombre en el agente principal |
**Historial de conversación**
| Herramienta | Descripción |
|------|-------------|
| `get_conversation_history` | Devuelve el historial de mensajes de una tarea o del agente principal. Admite un parámetro `limit` |
| `reset_conversation` | Limpia el historial de conversación de una tarea o del agente principal |
**Memoria**
| Herramienta | Descripción |
|------|-------------|
| `store_memory` | Persiste un par clave-valor en el almacén de memoria del proceso |
| `retrieve_memory` | Recupera por clave exacta, busca por subcadena o lista todas las claves |
| `clear_memory` | Elimina una clave específica o borra toda la memoria con `scope='all'` |
**Observabilidad**
| Herramienta | Descripción |
|------|-------------|
| `get_logs` | Devuelve los registros de ejecución recientes, opcionalmente filtrados por nivel (`info` / `warning` / `error`) |
| `get_metrics` | Métricas de ejecución: recuento de tareas, tasa de éxito, total de llamadas a herramientas, tamaños de memoria y registros |
---
#### Ejemplo de flujo de trabajo con tareas asíncronas
Para tareas de reconocimiento de larga duración, usa el patrón asíncrono:
```
# 1. Submit tasks without blocking
run_task_async task="Enumerate subdomains of example.com" target="example.com"
run_task_async task="Run nmap SYN scan on example.com" target="example.com"
# 2. Block until both finish (up to 5 minutes)
await_tasks task_ids=["<id1>", "<id2>"] timeout_seconds=300
# 3. Retrieve full results
get_task_result task_id="<id1>"
get_task_result task_id="<id2>"
```
---
### Gestión de herramientas CLI
```bash
pentestagent tools list # List all tools
pentestagent tools info <name> # Show tool details
pentestagent mcp list # List MCP servers
pentestagent mcp add <name> <command> [args...] # Add MCP server
pentestagent mcp test <name> # Test MCP connection
```
## Controles del historial de conversación
Cada mensaje de usuario en la TUI expone dos botones de acción en línea: **rewind** y **fork**.
### Rewind
Haz clic en **rewind** en cualquier mensaje de usuario para truncar la conversación hasta justo antes de ese mensaje, tanto en la interfaz como en el historial en memoria del agente. Úsalo para reintentar una consulta desde cero sin guardar la ruta descartada.
### Fork
Haz clic en **>> fork** en cualquier mensaje de usuario para ramificar la conversación desde ese punto:
1. La conversación completa actual se **guarda** en el almacén de conversaciones y se muestra un ID corto de instantánea.
2. Luego, la conversación se **trunca** hasta justo antes del mensaje seleccionado (igual que rewind).
Esto te permite probar un enfoque alternativo desde cualquier punto mientras mantienes el hilo original recuperable mediante `/conversations`.
---
## Historial de conversación
PentestAgent conserva automáticamente cada conversación para que puedas revisar, comparar y restaurar sesiones pasadas.
El **guardado automático** se activa después de cada tarea `/assist`, `/agent`, `/crew` e `/interact`, y antes de `/clear`. Se conservan hasta 20 conversaciones; las más antiguas se eliminan automáticamente.
**Ubicación de almacenamiento:** `workspaces/<active>/memory/conversations/` cuando hay un workspace activo, o `conversations/` en la raíz del proyecto en caso contrario. Cada conversación es un archivo JSON.
**Explora y restaura con `/conversations`:**
El comando `/conversations` abre un modal de panel dividido dentro de la TUI:
- **Panel izquierdo** — lista de conversaciones guardadas con título y fecha.
- **Panel derecho** — vista previa de metadatos más los primeros 5 mensajes (mensajes de usuario en azul, respuestas del agente en verde, llamadas a herramientas en amarillo, resultados de herramientas en gris). Un contador muestra cuántos mensajes adicionales existen.
<img width="1657" height="662" alt="imagen" src="https://github.com/user-attachments/assets/da42f083-9b7f-445e-8c59-2402ac8e5ddc" />
Selecciona una conversación y pulsa **Restore** para recargarla en la sesión actual, o **Close** para cerrar el modal.
## Conocimiento
- **RAG:** Coloca metodologías, CVE o listas de palabras en `pentestagent/knowledge/sources/` para la inyección automática de contexto.
- **Notas:** Los agentes guardan hallazgos en `loot/notes.json` con categorías (`credential`, `vulnerability`, `finding`, `artifact`). Las notas persisten entre sesiones y se inyectan en el contexto del agente.
- **Shadow Graph:** En el modo Crew, el orquestador construye un grafo de conocimiento a partir de las notas para derivar perspectivas estratégicas (p. ej., "Tenemos credenciales para el host X").
## Estructura del proyecto
```
pentestagent/
agents/ # Agent implementations
config/ # Settings and constants
interface/ # TUI and CLI
knowledge/ # RAG system and shadow graph
llm/ # LiteLLM wrapper
mcp/ # MCP client and server configs
playbooks/ # Attack playbooks
runtime/ # Execution environment
tools/ # Built-in tools
```
## Desarrollo
```bash
pip install -e ".[dev]"
pytest # Run tests
pytest --cov=pentestagent # With coverage
black pentestagent # Format
ruff check pentestagent # Lint
```
## Legal
Úsalo solo contra sistemas en los que tengas autorización explícita para realizar pruebas. El acceso no autorizado es ilegal.
## Licencia
MIT