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

  python -m phantomrecon
  

• Ejecución única no interactiva:

  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):
   • Lee attack_plan del estado.
   • Ejecuta condicionalmente herramientas de exploit específicas (web_exploit_tool, sql_exploit_tool) según el plan.
   • Estado: Las herramientas de exploit añaden resultados a la lista exploit_results en el estado de la sesión.
5. Generación de informes (report_tool):
   • Lee todos los datos relevantes (reconocimiento, plan, resultados) del estado de la sesión.
   • Genera un archivo de informe final en Markdown.

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:

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

4. Instala las dependencias:

   pip install -r requirements.txt
   

5. Configura las claves de API (env):
   • Copia .env.example a .env (si el ejemplo existe) o edita .env.
   • Añade tu clave de API de Google (desde AI Studio o la configuración de Vertex AI) para la variable GOOGLE_API_KEY.
   • Establece GOOGLE_GENAI_USE_VERTEXAI como True o False y configura las variables relacionadas (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION) si usas Vertex AI.
6. Ejecuta la herramienta:
   • CLI interactivo: python -m phantomrecon
   • CLI de una sola ejecución: python -m phantomrecon --target <target> --auto
   • Ejecutor ADK (opcional): adk run phantomrecon

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)
• searchsploit (sudo apt install exploitdb o brew install exploitdb)
• Un proyecto de Google Cloud con la API de Gemini habilitada.
• Una clave de API para la API de Gemini.
• Librerías de Python listadas en requirements.txt (instálalas con pip install -r requirements.txt)

Características principales