PhantomRecon

PhantomRecon es una herramienta CLI de automatización de red team, modular y basada en agentes, diseñada para demostrar flujos de trabajo autónomos de seguridad ofensiva impulsados por IA (Google Gemini mediante Agent Development Kit - ADK).

Inicio rápido (CLI)

• Ejecutar consola interactiva (estilo metasploit):
  root@kitploit:~

  python -m phantomrecon
  

• Ejecución única no interactiva:
  root@kitploit:~

  python -m phantomrecon --target example.com --auto \
    --nmap-timeout 30 --nmap-top-ports 100 --nmap-args "-sV -Pn"
  

Opciones de CLI

• --target <domain|ip>: Objetivo a evaluar
• --auto: Ejecutar reconocimiento → plan → ruta → informe
• --nmap-timeout <seconds>: Sobrescribe NMAP_TIMEOUT
• --nmap-top-ports <N>: Sobrescribe NMAP_TOP_PORTS
• --nmap-args "...": Añade a los argumentos de Nmap (NMAP_ARGS)
• --nmap-disable: Deshabilita Nmap (establece NMAP_DISABLE=1)

Las variables de entorno también se admiten directamente: NMAP_TIMEOUT, NMAP_TOP_PORTS, NMAP_ARGS, NMAP_DISABLE.

Higiene operativa

• Los informes no están versionados. .gitignore excluye reports/* excepto reports/sample_report.md.
• Los informes HTML/MD generados viven bajo reports/ solo localmente.
• Elimina o rota los informes según sea necesario; nunca se suben en los commits.

Construida como prueba de concepto, simula identificar un objetivo, realizar un reconocimiento amplio (Nmap, DNS, búsqueda web), planificar una estrategia de ataque usando un LLM, ejecutar exploits simulados de forma condicional y generar un informe.

Estructura del Proyecto

phantomrecon/
├── phantomrecon/             # Main package (exported orchestrator agent)
│   ├── __init__.py
│   ├── __main__.py           # CLI entrypoint (interactive and non-interactive)
│   └── agent/                # Agent graph and tools
├── agents/                   # Python modules containing agent/tool logic
│   ├── recon_logic.py        # Nmap, DNS (dig), seeded web analysis; ADK search enabled
│   ├── routing_logic.py      # Logic for the Exploit Router agent
│   ├── exploit_web_logic.py  # Functions for web exploits (currently simulated)
│   ├── exploit_sql_logic.py  # Functions for SQL exploits (currently simulated)
│   └── report_logic.py       # Functions for report generation using session state
├── configs/
│   └── targets.json          # (Optional) Target configuration
├── data/
│   └── dummy_scan_output.json # Example Nmap data if no target specified
├── demos/
│   └── walkthrough.md        # Demo steps
├── prompts/                  # Prompt templates for LLM agents
├── reports/
│   └── sample_report.md      # Example output report
├── requirements.txt          # Python dependencies (includes google-adk)
├── .gitignore                # Files excluded from version control
└── LICENSE                   # MIT License

Flujo de trabajo actual

1. Reconocimiento paralelo (recon_workflow - Agente paralelo):
   • Ejecuta escaneo Nmap (nmap_tool)
   • Ejecuta consultas DNS/WHOIS (dns_tool)
   • Simula búsqueda web (web_search_tool)
   • Estado: Cada herramienta escribe sus resultados en el estado de la sesión.
2. Agregación (aggregation_tool):
   • Combina los resultados del flujo de trabajo paralelo.
   • Estado: Escribe aggregated_recon_data en el estado de la sesión.
3. Planificación con LLM (planning_agent - LlmAgent):
   • Recibe los datos agregados.
   • Usa Gemini y attack_planner_prompt.txt para generar un plan de ataque JSON.
   • Estado: Escribe attack_plan en el estado de la sesión.
4. Enrutamiento de exploits (exploit_router - RouterAgent):

Configuración

1. Clona el repositorio.
2. Asegúrate de tener los requisitos previos instalados: python3, pip, nmap, dig, whois, sqlmap, wapiti, wpscan, searchsploit.
3. Crea un entorno virtual:
   root@kitploit:~

   python3 -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   

4. Instala las dependencias:
   root@kitploit:~

   pip install -r requirements.txt
   

5. Configura las claves de API (env):
   • Copia .env.example a .env (si el ejemplo existe) o edita .

Aviso de seguridad

Esta herramienta es para pruebas de seguridad autorizadas y fines educativos únicamente. No la uses contra sistemas sin permiso explícito.

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Requisitos previos

• Python 3.9+
• pip (instalador de paquetes de Python)
• Nmap (sudo apt install nmap o brew install nmap)
• dig (sudo apt install dnsutils o brew install bind)
• whois (sudo apt install whois o brew install whois)
• sqlmap (sudo apt install sqlmap o brew install sqlmap)
• wapiti (sudo apt install wapiti o brew install wapiti)
• wpscan (sudo apt install ruby-full y luego gem install wpscan o brew install wpscan)

Características principales

• Flujo de trabajo basado en agentes: Utiliza el Agent Development Kit (ADK) de Google para una estructura modular.
• Entrada interactiva del objetivo: Usa la interfaz adk web para pedir al usuario la IP/dominio objetivo.
• Evaluación multi-etapa:
  • Reconocimiento:
    • Escaneo de puertos con Nmap (Real)
    • Consultas DNS/WHOIS mejoradas (Real: dig, nslookup, dig +trace, intento AXFR, whois)
    • Búsqueda web (Real, usando Google Search)
    • Análisis mejorado de contenido web (Real: enlaces, formularios, comentarios, scripts, cabeceras, correos electrónicos, detección básica de tecnología)
    • Agregación de datos
  • Planificación: El LLM (Gemini) analiza los datos de reconocimiento para generar un plan de ataque priorizado (con validación).
  • Explotación (Enrutamiento condicional): Ejecuta pruebas según el plan:
    • Web: Archivos por defecto, configuraciones incorrectas (listado de directorios), inyección SQL (mediante sqlmap con opciones refinadas), escaneo de Wapiti (resultados analizados), WPScan (resultados analizados, condicional), XSS reflejado básico, inyección de comandos básica - (Comprobaciones reales)
    • SQL: Credenciales por defecto (MySQL/PostgreSQL), vulnerabilidades de versión (mediante searchsploit con consulta refinada), enumeración post-autenticación (mediante conexión directa con ) - (Comprobaciones reales)

Arquitectura (Sistema autónomo multi-agente)

PhantomRecon utiliza una arquitectura multi-agente completamente autónoma impulsada por el Agent Development Kit (ADK) de Google.

Componentes principales

Agente orquestador senior (gemini-1.5-pro-latest)

• Toma de decisiones autónoma y planificación estratégica
• Selecciona dinámicamente qué agentes especialistas invocar
• Itera según los hallazgos (sin secuencia fija)
• Realiza auditorías de seguridad exhaustivas con total autonomía

Agentes de seguridad especializados

• Agente de reconocimiento: Escaneo de puertos, enumeración DNS, detección de servicios
• Especialista en seguridad web: XSS, CSRF, SSRF, Path Traversal, Open Redirect
• Especialista en inyección SQL: Todas las técnicas de inyección SQL en las principales bases de datos
• Especialista en SSH/Red: Auditoría de seguridad SSH, pruebas de servicios de red
• Especialista en autenticación: Bypass de autenticación, seguridad de sesiones, escalada de privilegios
• Agente de planificación: Planificación estratégica de ataques basada en hallazgos
• Agente de informes: Generación de informes de seguridad exhaustivos

Operación autónoma

El orquestador opera como un pentester senior:

1. Acepta un dominio/IP objetivo
2. Planifica la estrategia de reconocimiento
3. Analiza los hallazgos e identifica superficies de ataque
4. Invoca dinámicamente agentes especialistas según los descubrimientos
5. Itera y adapta el enfoque a medida que surge nueva información
6. Genera un informe exhaustivo de auditoría de seguridad

Características principales:

• Sin flujo de trabajo fijo - el orquestador decide la estrategia
• Ejecución paralela de agentes para mayor eficiencia
• Análisis profundo iterativo de las vulnerabilidades descubiertas
• Enfoque adaptativo basado en las características del objetivo
• Autonomía completa desde la entrada del objetivo hasta el informe final

Detalles técnicos

• Gestión de estado mediante context.session.state (sesiones de ADK)
• Reconocimiento paralelo con visualización de progreso en tiempo real (librería Rich)
• Ejecución asíncrona de comandos con timeouts (executor_fix.py)
• Parámetros de escaneo configurables (variables de entorno para Nmap, etc.)

Uso

Ejecuta vía CLI (recomendado):

python -m phantomrecon --target <domain|ip> --auto

Consola interactiva:

python -m phantomrecon

Ejecutor ADK opcional:

adk run phantomrecon -- --target <domain|ip> --auto