PentestAgent

Pruebas de Penetración con IA

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

# 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 funciona.

Uso de un relay / base de API personalizada

Apunta PentestAgent a cualquier endpoint compatible con OpenAI mediante OPENAI_API_BASE:

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

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)

# 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

# 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:

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:

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.

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.

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:

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:

{
  "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):

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:

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:

Ejemplo: configuración de Claude Desktop (claude_desktop_config.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

Ejecución de tareas

Inspección de tareas

Control de tareas

Gestión de herramientas

Historial de conversación

Memoria

Observabilidad

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

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.

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

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