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.
https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975
# 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
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.
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.
pentestagent # Launch TUI
pentestagent -t 192.168.1.1 # Launch with target
pentestagent tui --docker # Run tools in Docker container
Ejecuta las herramientas dentro de un contenedor Docker para aislamiento y herramientas de pentesting preinstaladas.
# 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
# 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.
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 |
/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.
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
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
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>"
/spawn y /despawn)