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

  python -m phantomrecon
  

• Esecuzione one-shot non interattiva:

  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):
   • Legge attack_plan dallo stato.
   • Esegue condizionalmente strumenti di exploit specifici (web_exploit_tool, sql_exploit_tool) in base al piano.
   • Stato: Gli strumenti di exploit aggiungono i risultati alla lista exploit_results nello stato della sessione.
5. Report (report_tool):
   • Legge tutti i dati rilevanti (ricognizione, piano, risultati) dallo stato della sessione.
   • Genera un file di report finale in Markdown.

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:

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

4. Installa le dipendenze:

   pip install -r requirements.txt
   

5. Configura le chiavi API (env):
   • Copia .env.example in .env (se l'esempio esiste) o modifica .env.
   • Aggiungi la tua chiave API Google (da AI Studio o dalla configurazione di Vertex AI) per la variabile GOOGLE_API_KEY.
   • Imposta GOOGLE_GENAI_USE_VERTEXAI su True o False e configura le variabili correlate (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION) se usi Vertex AI.
6. Esegui lo strumento:
   • CLI interattiva: python -m phantomrecon
   • CLI one-shot: python -m phantomrecon --target <target> --auto
   • ADK runner (opzionale): adk run phantomrecon

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)
• searchsploit (sudo apt install exploitdb oppure brew install exploitdb)
• Un progetto Google Cloud con l'API Gemini abilitata.
• Una chiave API per l'API Gemini.
• Librerie Python elencate in requirements.txt (installazione tramite pip install -r requirements.txt)

Caratteristiche principali