PhantomRecon

PhantomRecon è uno strumento di automazione red team basato su CLI, modulare e guidato da agenti, progettato per dimostrare flussi di lavoro di sicurezza offensiva autonomi alimentati dall'IA (Gemini di Google tramite Agent Development Kit - ADK).

Avvio rapido (CLI)

• Esegui la console interattiva (stile metasploit):
  root@kitploit:~

  python -m phantomrecon
  

• Esecuzione one-shot non interattiva:
  root@kitploit:~

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

Opzioni CLI

• --target <domain|ip>: Target da valutare
• --auto: Esegui ricognizione → piano → routing → report
• --nmap-timeout <seconds>: Sostituisce NMAP_TIMEOUT
• --nmap-top-ports <N>: Sostituisce NMAP_TOP_PORTS
• --nmap-args "...": Aggiunge agli argomenti di Nmap (NMAP_ARGS)
• --nmap-disable: Disabilita Nmap (imposta NMAP_DISABLE=1)

Le variabili d'ambiente sono supportate anche direttamente: NMAP_TIMEOUT, NMAP_TOP_PORTS, NMAP_ARGS, NMAP_DISABLE.

Igiene operativa

• I report non sono versionati. .gitignore esclude reports/* tranne reports/sample_report.md.
• I report HTML/MD generati risiedono solo localmente in reports/.
• Rimuovi o ruota i report secondo necessità; non vengono mai caricati nei commit.

Costruito come proof-of-concept, simula l'identificazione di un target, l'esecuzione di un'ampia ricognizione (Nmap, DNS, Web Search), la pianificazione di una strategia di attacco tramite un LLM, l'esecuzione condizionata di exploit simulati e la generazione di un report.

Struttura del progetto

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

Flusso di lavoro attuale

1. Ricognizione Parallela (recon_workflow - Agente Parallelo):
   • Esegue la scansione Nmap (nmap_tool)
   • Esegue lookup DNS/WHOIS (dns_tool)
   • Simula la ricerca web (web_search_tool)
   • Stato: Ogni strumento scrive i propri risultati nello stato della sessione.
2. Aggregazione (aggregation_tool):
   • Combina i risultati del flusso di lavoro parallelo.
   • Stato: Scrive aggregated_recon_data nello stato della sessione.
3. Pianificazione LLM (planning_agent - LlmAgent):
   • Riceve i dati aggregati.
   • Usa Gemini e attack_planner_prompt.txt per generare un piano di attacco JSON.
   • Stato: Scrive attack_plan nello stato della sessione.
4. Routing degli Exploit (exploit_router - RouterAgent):

Setup

1. Clona il repository.
2. Assicurati che i prerequisiti siano installati: python3, pip, nmap, dig, whois, sqlmap, wapiti, wpscan, searchsploit.
3. Crea un ambiente virtuale:
   root@kitploit:~

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

4. Installa le dipendenze:
   root@kitploit:~

   pip install -r requirements.txt
   

5. Configura le chiavi API (env):
   • Copia .env.example in .env (se l'esempio esiste) o modifica .

Avviso di sicurezza

Questo strumento è destinato esclusivamente a test di sicurezza autorizzati e a fini educativi. Non utilizzarlo contro sistemi senza esplicita autorizzazione.

Licenza

Questo progetto è concesso in licenza MIT - vedi il file LICENSE per i dettagli.

Prerequisiti

• Python 3.9+
• pip (installer di pacchetti Python)
• Nmap (sudo apt install nmap oppure brew install nmap)
• dig (sudo apt install dnsutils oppure brew install bind)
• whois (sudo apt install whois oppure brew install whois)
• sqlmap (sudo apt install sqlmap oppure brew install sqlmap)
• wapiti (sudo apt install wapiti oppure brew install wapiti)
• wpscan (sudo apt install ruby-full poi gem install wpscan oppure brew install wpscan)

Caratteristiche principali

• Flusso di lavoro basato su agenti: Utilizza l'Agent Development Kit (ADK) di Google per una struttura modulare.
• Input del target interattivo: Usa l'interfaccia adk web per chiedere all'utente l'IP/dominio del target.
• Valutazione a più stadi:
  • Ricognizione:
    • Scansione delle porte Nmap (Reale)
    • Lookup DNS/WHOIS potenziati (Reali: dig, nslookup, dig +trace, tentativo AXFR, whois)
    • Ricerca web (Reale, tramite Google Search)
    • Analisi avanzata dei contenuti web (Reale: link, moduli, commenti, script, header, email, rilevamento tecnologico di base)
    • Aggregazione dei dati
  • Pianificazione: L'LLM (Gemini) analizza i dati di ricognizione per generare un piano di attacco prioritizzato (con validazione).
  • Sfruttamento (Routing condizionale): Esegue test in base al piano:
    • Web: File predefiniti, Configurazioni errate (Directory Listing), SQL Injection (tramite sqlmap con opzioni raffinate), scansione Wapiti (risultati analizzati), WPScan (risultati analizzati, condizionale), XSS riflesso di base, Command Injection di base - (Controlli reali)
    • SQL: Credenziali predefinite (MySQL/PostgreSQL), Vulnerabilità di versione (tramite searchsploit con query raffinata), Enumerazione post-autenticazione (tramite connessione diretta di sqlmap) - (Controlli reali)

Architettura (Sistema Autonomo Multi-Agente)

PhantomRecon usa un'architettura multi-agente completamente autonoma basata sull'Agent Development Kit (ADK) di Google.

Componenti principali

Agente Orchestratore Senior (gemini-1.5-pro-latest)

• Processo decisionale autonomo e pianificazione strategica
• Seleziona dinamicamente quali agenti specialistici invocare
• Itera in base ai risultati (nessuna sequenza fissa)
• Conduce audit di sicurezza completi con piena autonomia

Agenti di sicurezza specializzati

• Agente di ricognizione: scansione delle porte, enumerazione DNS, rilevamento dei servizi
• Specialista sicurezza web: XSS, CSRF, SSRF, Path Traversal, Open Redirect
• Specialista SQL Injection: tutte le tecniche di SQL injection sui principali database
• Specialista SSH/Reti: audit di sicurezza SSH, test dei servizi di rete
• Specialista autenticazione: bypass dell'autenticazione, sicurezza delle sessioni, escalation dei privilegi
• Agente di pianificazione: pianificazione strategica degli attacchi basata sui risultati
• Agente di report: generazione di report di sicurezza completi

Operazione autonoma

L'orchestratore opera come un penetration tester senior:

1. Accetta un dominio/IP target
2. Pianifica la strategia di ricognizione
3. Analizza i risultati e identifica le superfici di attacco
4. Invoca dinamicamente gli agenti specialistici in base alle scoperte
5. Itera e adatta l'approccio man mano che emergono nuove informazioni
6. Genera un report completo di audit di sicurezza

Caratteristiche principali:

• Nessun flusso di lavoro fisso - l'orchestratore decide la strategia
• Esecuzione parallela degli agenti per efficienza
• Approfondimento iterativo delle vulnerabilità scoperte
• Approccio adattivo in base alle caratteristiche del target
• Autonomia completa dall'input del target al report finale

Dettagli tecnici

• Gestione dello stato tramite context.session.state (sessioni ADK)
• Ricognizione parallela con visualizzazione dell'avanzamento in tempo reale (libreria Rich)
• Esecuzione asincrona dei comandi con timeout (executor_fix.py)
• Parametri di scansione configurabili (variabili d'ambiente per Nmap, ecc.)

Utilizzo

Esegui tramite CLI (consigliato):

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

Console interattiva:

python -m phantomrecon

ADK runner opzionale:

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