pentestagent

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

Usar 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 obtener 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: Descargar la imagen preconstruida (la más rápida)

# 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 a través de 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 única 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 trabajadores 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:

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

Auto-generació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 un 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 vuelta en las herramientas disponibles del agente padre después de la generación.

Esto permite flujos de trabajo multiagente jerárquicos sin orquestación externa: el agente se autoorganiza delegando subtareas con alcance definido a hijos que genera bajo demanda.

Argumento	Tipo	Predeterminado	Descripción
target	string	—	Objetivo de pentesting para pasar al hijo
scope	string[]	—	Objetivos/CIDRs dentro del alcance para el hijo
model	string	variable de entorno	Identificador del modelo, anula PENTESTAGENT_MODEL en el hijo
no_rag	boolean	false	Omitir la inicialización del motor RAG en el hijo
no_mcp	boolean	true	Omitir 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 Hijos (/spawn y /despawn)

Más allá de la herramienta automática spawn_mcp_agent, la TUI expone dos comandos que te permiten generar y terminar agentes hijos 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 están 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 CIDRs dentro del alcance (repetible)
--model MODEL	Anular el modelo para el agente hijo
--no-rag	Omitir la inicialización del motor RAG en el hijo
--no-mcp	Omitir 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 hijos 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 meta-herramienta 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 de lenguaje natural enfocadas que describen lo que necesita, y las herramientas coincidentes están disponibles en el siguiente turno para llamarlas directamente.

Guía de uso para el agente:

Argumento	Tipo	Predeterminado	Descripción
queries	string[]	(requerido)	Una consulta enfocada por capacidad necesaria. Más específica = mayor precisión
top_k	integer	20	Herramientas a recuperar por consulta (máx. 128). Los resultados se fusionan 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, por lo 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"] recupera mejores resultados que ["list ports and memory and CPU"].

Integración MCP

PentestAgent soporta MCP (Model Context Protocol) en dos direcciones: consumiendo servidores MCP externos como fuentes de herramientas, y exponiéndose como servidor MCP para que clientes externos (Claude Desktop, Cursor, etc.) puedan controlar PentestAgent programáticamente.

---

Consumir 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, permitiendo que cualquier cliente compatible con MCP envíe tareas, inspeccione resultados y controle el agente de forma remota. Se soportan 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 el encabezado Mcp-Session-Id.

Todos los indicadores de mcp_server:

Indicador	Predeterminado	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/CIDRs dentro del alcance (separados por espacios)
--model	variable de entorno	Identificador del modelo, anula PENTESTAGENT_MODEL
--docker	false	Usar DockerRuntime en lugar de LocalRuntime
--no-rag	false	Omitir la inicialización del motor RAG
--no-mcp	false	Omitir conexiones a servidores MCP externos

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

Herramienta	Descripción
get_server_status	Estado del servidor en vivo: preparación, recuentos 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	Actualizar objetivo, alcance o iteraciones máximas para todas las tareas posteriores

Ejecución de Tareas

Herramienta	Descripción
run_task	Enviar una tarea y bloquear hasta que se complete. Devuelve el resultado completo, las herramientas utilizadas y una instantánea de notas
run_task_async	Enviar una tarea y regresar inmediatamente con un task_id. Consulta con get_task_status

Inspección de Tareas

Herramienta	Descripción
list_tasks	Listar todas las tareas con estado, objetivo y resumen. Filtrable por estado
get_task_status	Consultar 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 de herramientas y resultados, instantánea de notas
await_tasks	Bloquear 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	Cancelar una tarea en ejecución o pendiente por ID

Gestión de Herramientas

Herramienta	Descripción
list_tools	Listar todas las herramientas disponibles para el agente
enable_tool	Habilitar una herramienta con nombre en el agente principal
disable_tool	Deshabilitar una herramienta con nombre en el agente principal

Historial de Conversación

Herramienta	Descripción
get_conversation_history	Devolver el historial de mensajes de una tarea o del agente principal. Soporta un parámetro limit
reset_conversation	Borrar el historial de conversación de una tarea o del agente principal

Memoria

Herramienta	Descripción
store_memory	Persistir un par clave-valor en el almacén de memoria del proceso
retrieve_memory	Recuperar por clave exacta, buscar por subcadena o listar todas las claves
clear_memory	Eliminar una clave específica o borrar toda la memoria con scope='all'

Observabilidad

Herramienta	Descripción
get_logs	Devolver registros de ejecución recientes, opcionalmente filtrados por nivel (info / warning / error)
get_metrics	Métricas del runtime: recuentos de tareas, tasa de éxito, total de llamadas de herramientas, tamaños de memoria y registros

---

Ejemplo de Flujo de Trabajo de 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 por 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 de Historial de Conversación

Cada mensaje de usuario en la TUI expone dos botones de acción en línea: rebobinar y bifurcar.

Rebobinar

Haz clic en rebobinar en cualquier mensaje de usuario para truncar la conversación de vuelta a 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.

Bifurcar

Haz clic en >> bifurcar 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 de instantánea corto.
2. La conversación se trunca a justo antes del mensaje seleccionado (igual que rebobinar). Esto te permite probar un enfoque alternativo desde cualquier punto mientras mantienes el hilo original recuperable mediante /conversations.

---

Historial de Conversaciones

PentestAgent persiste automáticamente cada conversación para que puedas revisar, comparar y restaurar sesiones pasadas.

Guardado automático se activa después de cada tarea de /assist, /agent, /crew y /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 espacio de trabajo activo, o conversations/ en la raíz del proyecto en caso contrario. Cada conversación es un archivo JSON.

Explorar y restaurar 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 presiona Restaurar para recargarla en la sesión actual, o Cerrar para descartar el modal.

Conocimiento

• RAG: Coloca metodologías, CVEs 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 modo Crew, el orquestador construye un grafo de conocimiento a partir de las notas para derivar conocimientos estratégicos (por ejemplo, "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 únicamente contra sistemas para los que tengas autorización explícita de prueba. El acceso no autorizado es ilegal.

Licencia

MIT