PhantomRecon is a CLI-based, modular, agent-driven red team automation tool designed to demonstrate autonomous offensive security workflows powered by AI (Google's Gemini via Agent Development Kit - ADK).

PhantomRecon

PhantomRecon is a CLI-based, modular, agent-driven red team automation tool designed to demonstrate autonomous offensive security workflows powered by AI (Google's Gemini via Agent Development Kit - ADK).

Quick Start (CLI)

• Run interactive console (metasploit-style):

  python -m phantomrecon
  

• One-shot non-interactive run:

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

CLI options

• --target <domain|ip>: Target to assess
• --auto: Run recon → plan → route → report
• --nmap-timeout <seconds>: Overrides NMAP_TIMEOUT
• --nmap-top-ports <N>: Overrides NMAP_TOP_PORTS
• --nmap-args "...": Appends to Nmap args (NMAP_ARGS)
• --nmap-disable: Disable Nmap (sets NMAP_DISABLE=1)

Environment variables are also supported directly: NMAP_TIMEOUT, NMAP_TOP_PORTS, NMAP_ARGS, NMAP_DISABLE.

Operational hygiene

• Reports are not versioned. .gitignore excludes reports/* except reports/sample_report.md.
• Generated HTML/MD reports live under reports/ locally only.
• Remove or rotate reports as needed; they are never uploaded in commits.

Built as a proof-of-concept, it simulates identifying a target, performing broad reconnaissance (Nmap, DNS, Web Search), planning an attack strategy using an LLM, executing simulated exploits conditionally, and generating a report.

Project Structure

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_