PhantomRecon

PhantomRecon est un outil d'automatisation Red Team modulaire, piloté par agents et basé sur CLI, conçu pour démontrer des workflows offensifs de sécurité autonomes propulsés par l'IA (Gemini de Google via Agent Development Kit - ADK).

Démarrage rapide (CLI)

• Lancez la console interactive (style Metasploit) :

  python -m phantomrecon
  

• Exécution one-shot non interactive :

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

Options CLI

• --target <domain|ip> : Cible à évaluer
• --auto : Exécute recon → plan → routage → rapport
• --nmap-timeout <seconds> : Remplace NMAP_TIMEOUT
• --nmap-top-ports <N> : Remplace NMAP_TOP_PORTS
• --nmap-args "..." : Ajoute aux arguments Nmap (NMAP_ARGS)
• --nmap-disable : Désactive Nmap (définit NMAP_DISABLE=1)

Les variables d'environnement sont également prises en charge directement : NMAP_TIMEOUT, NMAP_TOP_PORTS, NMAP_ARGS, NMAP_DISABLE.

Hygiène opérationnelle

• Les rapports ne sont pas versionnés. .gitignore exclut reports/* sauf reports/sample_report.md.
• Les rapports générés en HTML/MD se trouvent localement sous reports/ uniquement.
• Supprimez ou archivez les rapports selon les besoins ; ils ne sont jamais inclus dans les commits.

Conçu comme une preuve de concept, il simule l'identification d'une cible, l'exécution d'une reconnaissance étendue (Nmap, DNS, recherche web), la planification d'une stratégie d'attaque à l'aide d'un LLM, l'exécution conditionnelle d'exploits simulés et la génération d'un rapport.

Structure du projet

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

Workflow actuel

1. Reconnaissance parallèle (recon_workflow - Agent parallèle) :
   • Exécute un scan Nmap (nmap_tool)
   • Exécute des interrogations DNS/WHOIS (dns_tool)
   • Simule une recherche web (web_search_tool)
   • État : chaque outil écrit ses résultats dans l'état de session.
2. Agrégation (aggregation_tool) :
   • Combine les résultats du workflow parallèle.
   • État : écrit aggregated_recon_data dans l'état de session.
3. Planification LLM (planning_agent - LlmAgent) :
   • Reçoit les données agrégées.
   • Utilise Gemini et attack_planner_prompt.txt pour générer un plan d'attaque JSON.
   • État : écrit attack_plan dans l'état de session.
4. Routage des exploits (exploit_router - RouterAgent) :
   • Lit attack_plan depuis l'état.
   • Exécute conditionnellement des outils d'exploit spécifiques (web_exploit_tool, sql_exploit_tool) en fonction du plan.
   • État : les outils d'exploit ajoutent leurs résultats à la liste exploit_results dans l'état de session.
5. Reporting (report_tool) :
   • Lit toutes les données pertinentes (recon, plan, résultats) depuis l'état de session.
   • Génère un fichier de rapport final en Markdown.

Installation

1. Clonez le dépôt.
2. Assurez-vous que les prérequis sont installés : python3, pip, nmap, dig, whois, sqlmap, wapiti, wpscan, searchsploit.
3. Créez un environnement virtuel :

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

4. Installez les dépendances :

   pip install -r requirements.txt
   

5. Configurez les clés API (env) :
   • Copiez .env.example vers .env (si l'exemple existe) ou modifiez .env.
   • Ajoutez votre clé API Google (depuis AI Studio ou la configuration Vertex AI) pour la variable GOOGLE_API_KEY.
   • Définissez GOOGLE_GENAI_USE_VERTEXAI sur True ou False et configurez les variables associées (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION) si vous utilisez Vertex AI.
6. Exécutez l'outil :
   • CLI interactive : python -m phantomrecon
   • CLI one-shot : python -m phantomrecon --target <target> --auto
   • Exécuteur ADK (optionnel) : adk run phantomrecon

Avis de sécurité

Cet outil est destiné uniquement aux tests de sécurité autorisés et à des fins éducatives. Ne l'utilisez pas contre des systèmes sans autorisation explicite.

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

Prérequis

• Python 3.9+
• pip (installateur de paquets Python)
• Nmap (sudo apt install nmap ou brew install nmap)
• dig (sudo apt install dnsutils ou brew install bind)
• whois (sudo apt install whois ou brew install whois)
• sqlmap (sudo apt install sqlmap ou brew install sqlmap)
• wapiti (sudo apt install wapiti ou brew install wapiti)
• wpscan (sudo apt install ruby-full puis gem install wpscan ou brew install wpscan)
• searchsploit (sudo apt install exploitdb ou brew install exploitdb)
• Un projet Google Cloud avec l'API Gemini activée.
• Une clé API pour l'API Gemini.
• Les bibliothèques Python listées dans requirements.txt (installation via pip install -r requirements.txt)

Fonctionnalités clés