PhantomRecon

PhantomRecon ist ein CLI-basiertes, modulares, agentengesteuertes Red-Team-Automatisierungstool, das dazu dient, autonome offensive Sicherheits-Workflows zu demonstrieren, die von KI unterstützt werden (Googles Gemini über das Agent Development Kit - ADK).

Schnellstart (CLI)

• Interaktive Konsole ausführen (Metasploit-Stil):

  python -m phantomrecon
  

• Einmaliger nicht-interaktiver Lauf:

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

CLI-Optionen

• --target <domain|ip>: Ziel, das bewertet werden soll
• --auto: Recon → Plan → Route → Report ausführen
• --nmap-timeout <seconds>: Überschreibt NMAP_TIMEOUT
• --nmap-top-ports <N>: Überschreibt NMAP_TOP_PORTS
• --nmap-args "...": Hängt an Nmap-Argumente an (NMAP_ARGS)
• --nmap-disable: Nmap deaktivieren (setzt NMAP_DISABLE=1)

Umgebungsvariablen werden ebenfalls direkt unterstützt: NMAP_TIMEOUT, NMAP_TOP_PORTS, NMAP_ARGS, NMAP_DISABLE.

Betriebshinweise

• Berichte werden nicht versioniert. .gitignore schließt reports/* aus, außer reports/sample_report.md.
• Generierte HTML/MD-Berichte liegen nur lokal unter reports/.
• Entfernen oder rotieren Sie Berichte nach Bedarf; sie werden niemals in Commits hochgeladen.

Als Proof-of-Concept konzipiert, simuliert es die Identifizierung eines Ziels, die Durchführung breiter Aufklärung (Nmap, DNS, Websuche), die Planung einer Angriffsstrategie mithilfe eines LLM, die bedingte Ausführung simulierter Exploits und die Erstellung eines Berichts.

Projektstruktur

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

Aktueller Workflow

1. Parallele Aufklärung (recon_workflow - Parallel-Agent):
   • Führt Nmap-Scan aus (nmap_tool)
   • Führt DNS/WHOIS-Abfragen durch (dns_tool)
   • Simuliert Websuche (web_search_tool)
   • Zustand: Jedes Tool schreibt seine Ergebnisse in den Sitzungszustand.
2. Aggregation (aggregation_tool):
   • Kombiniert Ergebnisse aus dem parallelen Workflow.
   • Zustand: Schreibt aggregated_recon_data in den Sitzungszustand.
3. LLM-Planung (planning_agent - LlmAgent):
   • Empfängt aggregierte Daten.
   • Verwendet Gemini und attack_planner_prompt.txt, um einen JSON-Angriffsplan zu generieren.
   • Zustand: Schreibt attack_plan in den Sitzungszustand.
4. Exploit-Routing (exploit_router - RouterAgent):
   • Liest attack_plan aus dem Zustand.
   • Führt basierend auf dem Plan bedingt bestimmte Exploit-Tools aus (web_exploit_tool, sql_exploit_tool).
   • Zustand: Exploit-Tools fügen Ergebnisse zur Liste exploit_results im Sitzungszustand hinzu.
5. Berichterstattung (report_tool):
   • Liest alle relevanten Daten (Aufklärung, Plan, Ergebnisse) aus dem Sitzungszustand.
   • Generiert eine abschließende Markdown-Berichtsdatei.

Einrichtung

1. Klonen Sie das Repository.
2. Stellen Sie sicher, dass die Voraussetzungen installiert sind: python3, pip, nmap, dig, whois, sqlmap, wapiti, wpscan, searchsploit.
3. Erstellen Sie eine virtuelle Umgebung:

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

4. Installieren Sie Abhängigkeiten:

   pip install -r requirements.txt
   

5. Konfigurieren Sie API-Schlüssel (env):
   • Kopieren Sie .env.example in .env (falls ein Beispiel existiert) oder bearbeiten Sie .env.
   • Fügen Sie Ihren Google-API-Schlüssel (von AI Studio oder Vertex AI-Setup) für die Variable GOOGLE_API_KEY hinzu.
   • Setzen Sie GOOGLE_GENAI_USE_VERTEXAI auf True oder False und konfigurieren Sie zugehörige Variablen (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION), falls Sie Vertex AI verwenden.
6. Führen Sie das Tool aus:
   • CLI-interaktiv: python -m phantomrecon
   • CLI-Einmalausführung: python -m phantomrecon --target <target> --auto
   • ADK-Runner (optional): adk run phantomrecon

Sicherheitshinweis

Dieses Tool ist ausschließlich für autorisierte Sicherheitstests und Bildungszwecke bestimmt. Verwenden Sie es nicht gegen Systeme ohne ausdrückliche Genehmigung.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die Datei LICENSE für Details.

Voraussetzungen

• Python 3.9+
• pip (Python-Paketinstallationsprogramm)
• Nmap (sudo apt install nmap oder brew install nmap)
• dig (sudo apt install dnsutils oder brew install bind)
• whois (sudo apt install whois oder brew install whois)
• sqlmap (sudo apt install sqlmap oder brew install sqlmap)
• wapiti (sudo apt install wapiti oder brew install wapiti)
• wpscan (sudo apt install ruby-full und dann gem install wpscan oder brew install wpscan)
• searchsploit (sudo apt install exploitdb oder brew install exploitdb)
• Ein Google Cloud-Projekt mit aktivierter Gemini-API.
• Ein API-Schlüssel für die Gemini-API.
• Python-Bibliotheken, die in requirements.txt aufgeführt sind (Installation über pip install -r requirements.txt)

Hauptfunktionen