Pentest Lab - Orquestador AI Autónomo

Este proyecto es un sistema de pentesting automatizado, impulsado por Inteligencia Artificial y orquestado mediante CrewAI. Utiliza modelos LLM locales (como Llama 3.1 8B a través de Ollama) para coordinar a un equipo de agentes especializados en ciberseguridad ofensiva, auditoría y reporte.

El sistema ejecuta el código generado de manera segura dentro de un entorno Docker (pentest-kali) y provee observabilidad detallada mediante Arize Phoenix. Todo esto puede integrarse fácilmente a flujos de automatización externos (como n8n) y se puede controlar mediante una API en FastAPI.

---

Índice

1. Arquitectura del Sistema
2. Flujo de Trabajo (Workflow)
3. Descripción de los Agentes
4. Herramientas (Tools)
5. Instalación y Configuración
6. Uso y Ejecución
7. Observabilidad y Logging
8. Consideraciones de Seguridad

---

Arquitectura del Sistema

La solución tiene un enfoque modular y "Local-First".

• Orquestador Principal (hacker_agente.py): Coordina la ejecución secuencial de las tareas utilizando CrewAI. Carga toda la configuración (.env, agentes, tareas y whitelist).
• Controlador API (api.py): Brinda un servidor FastAPI (puerto 8080) para facilitar la activación de escaneos y la consulta asíncrona de resultados a través de peticiones HTTP.
• Entorno de Ejecución Seguro (Docker Sandbox): Todas las interacciones con la línea de comandos o ejecución de scripts se aisla dentro del contenedor pentest-kali (basado en Kali Linux).
• Telemetría e Interfaz Gráfica (docker-compose.yml): Usa Arize Phoenix para graficar todo el razonamiento del LLM, el uso de herramientas y las salidas (STDOUT).
• Integrador Node.js (bridge.js): Ofrece una vía amigable u opcional si se requiere integrar con entornos basados en Node.js de forma directa.

Diagrama General

graph TD;
    A[Usuario / n8n / API] -->|Inicia Escaneo| B(api.py o hacker_agente.py)
    B -->|Instancia Crew| E[CrewAI Orquestador]
    E -->|Tarea 1| F(Pentester Agent: Reconnaissance)
    F -->|Usa| G[TerminalTool]
    G -->|Resultados de Nmap/Whatweb| E
    E -->|Tarea 2| H(Coder Agent: Exploit Dev)
    H -->|Programa Python Exploit| I[ScriptTool]
    I -->|Ejecuta en Docker Kali| J((Container\n'pentest-kali'))
    J -->|Devuelve STDOUT| H
    E -->|Tarea 3| K(Documenter Agent: Report)
    K -->|Genera| L[Reporte Final MD]
    L --> M[Carpeta logs/]

Loading

---

Flujo de Trabajo

El orquestador trabaja de forma secuencial en una cadena de 3 tareas interdependientes (tasks.yaml):

1. Reconocimiento (Reconnaissance): El agente evalúa el objetivo e inicia enumeraciones de puertos, recolección de versiones (SCA) y búsqueda de puntos de entrada. Se genera evidencia de qué puertos/servicios están accesibles.
2. Desarrollo y Validación de Exploit: A partir de la información anterior, el modelo genera un script o comando de comprobación y lo prueba obligatoriamente contra el entorno (usando el sandbox). El resultado es interceptado por un bucle iterativo: si hay un fallo de sintaxis interactúa y lo corrige. Al final emite un veredicto de "Vulnerable" solo ante el éxito del script.
3. Reporte (Reporting): Recopila la evidencia cruda y determina cuáles vulnerabilidades tienen prueba fehaciente de terminal. Escribe un resumen en formato de reporte técnico (en los archivos logs/reporte_final_YYYY-MM-DD...).

---

Descripción de los Agentes

La parametrización de sus personalidades y misiones están en agents.yaml:

• pentester (Lead Penetration Tester): Encargado de la etapa inicial e identificación de versiones/SCA. Emite comandos estrictamente en la whitelist configurada.
• coder (Exploit Developer): Ingeniero de Exploits. Su orden prioritaria es iterar herramientas o scripts Python hasta validar la debilidad y arrojar el resultado real del STDOUT al "consorcio".
• documenter (Report Auditor Assistant): El perfil escéptico. Audita la coherencia entre el "dicho" del Pentester/Coder y la evidencia real provista por las herramientas antes de elaborar la documentación final en un archivo Markdown markdown.

---

Herramientas (Tools)

Las "Tools" se encuentran en el directorio tools/ y son componentes cruciales que otorgan "manos" a los agentes, permitiéndoles accionar el mundo real:

1. TerminalTool (tools/terminal_tool.py):

   • Diseñada para lanzar comandos simples como de CLI (ej: nmap, curl, whatweb).
   • Bloqueada de forma predeterminada mediante una whitelist definida en config.py para prevenir que el modelo de lenguaje pueda borrar archivos rm o afectar el sistema base con intenciones negativas (o alucinaciones accidentales).
   • Levanta el comando envolviéndolo en: docker run --rm -i pentest-kali bash -c "comando".

2. ScriptTool (tools/script_tool.py):

   • Pensada para que el agente proporcione un listado de código de múltiples líneas en Python (creación de exploits).
   • Genera el archivo dentro del Docker temporal usando heredoc y ejecuta python3 /tmp/script.py. Devuelve los códigos de salida y errores crudos al LLM para que este entienda qué le faltó importar o por qué explotó su código.

---

Instalación y Configuración

Prerrequisitos

• Docker Engine instalado en el sistema.
• Python 3.12+
• Ollama instalado localmente o accesible por red, con el modelo hermes3:8b-llama3.1-q8_0 (o el necesario) ya cargado en memoria.

1. Clonar e Instalar Entorno

# Crear el entorno e instalar dependencias
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt # (Asegúrate de tener un requirerets u omite si todo está en el venv)
pip install crewai openinference-instrumentation-crewai opentelemetry-sdk fastapi uvicorn

2. Variables de Entorno (.env)

Modifica/crea el archivo .env basado en la plantilla:

OPENAI_API_BASE=http://localhost:11434/v1
OPENAI_API_KEY=ollama
OLLAMA_BASE_URL=http://localhost:11434
CREWAI_TRACING_ENABLED=true
PHOENIX_ENDPOINT=127.0.0.1:4317

3. Preparación de Docker (Kali Sandbox)

Dado que las herramientas corren contra un sandbox, primero debes asegurarte de generar/taguear la imagen local pentest-kali:

# Construir imagen a partir del dockerfile proporcionado 
docker build -t pentest-kali -f kali.Dockerfile .

4. Lanzar Tracer de Arize Phoenix

Levanta el ecosistema de trazabilidad para auditar a los agentes:

docker-compose up -d phoenix

---

Uso y Ejecución

Vas a encontrar 3 métodos de disparo de pruebas. Elije el que mejor se adapte a tu etapa (Testing directo, Sistema Rest/API o Flujo N8N).

Modo 1: Directo por Consola (CLI)

Activa tu Python e invoca al hacker_agente.py:

source venv/bin/activate
python hacker_agente.py "192.168.1.50" "Verificar vulnerabilidades en puerto 80"

Revisa las tareas interactivas en tu CLI, y finalmente la respuesta se guardará en logs/.

Modo 2: Interfaz API con FastAPI

Levanta la API que envuelve al sistema y utilízala desde Postman o una App Web.

source venv/bin/activate
# Se puede levantar corriendo uvicorn o a través del bash
python api.py

(Luego prueba enviar un POST a http://localhost:8080/api/scan con { "target": "demo.com", "details": "solo sql injections" })

Modo 3: Interfaz NodeJS y Automatizadores

Un script utilitario en NodeJS para ambientes integrados o de n8n.

node bridge.js "demo.com" "revisar wp-admin"

---

Observabilidad y Logging

Para evitar problemas de seguridad o no saber qué hizo exactamente la "caja negra" del IA:

1. Dashboard de Phoenix: Abre http://127.0.0.1:6006 Acá vas a ver un árbol detallado (Trace) donde por cada agente se listan el Tense, Uso de "Tools" (y sus atributos) y la salida explícita del servidor local (Prompt Completo enviado y Compleción total recibida de Ollama).
2. Carpeta de Logs: Todas las pruebas ejecutadas generarán salidas segregadas por fecha en formato logs/[tarea]_[fechayhora].md.

---

Consideraciones de Seguridad

Caution

El LLM es capaz de "Alucinar" ataques o inventarse comandos. Hemos establecido mitigaciones, preste atención:

• Lista Blanca (Whitelist): Validamos en config.py los binarios iniciales usados. NUNCA introduzcas al listado comandos puramente destructivos sin parámetros como rm en modo genérico en ambiente productivo sin aislar del host.
• Dockerización Estricta: No configures compartición de volúmenes en caliente -v /:/host dentro de los scripts de los Tools (en terminal_tool.py y script_tool.py). Los contenedores deben ser Efímeros y limitados.
• Acciones y Scope: Debes ser cuidadoso del target (Objetivo) a enviar. El sistema va a intentar accionar un hacking de manera automatizada. No lo uses en infraestructuras fuera del entorno de test en donde no poseas contratos/Bounty permitidos legalmente.