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):
  root@kitploit:~

  python -m phantomrecon
  

• One-shot non-interactive run:
  root@kitploit:~

  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_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

Current Workflow

1. Parallel Reconnaissance (recon_workflow - Parallel Agent):
   • Runs Nmap Scan (nmap_tool)
   • Runs DNS/WHOIS lookups (dns_tool)
   • Simulates Web Search (web_search_tool)
   • State: Each tool writes its results to the session state.
2. Aggregation (aggregation_tool):
   • Combines results from the parallel workflow.
   • State: Writes aggregated_recon_data to session state.
3. LLM Planning (planning_agent - LlmAgent):
   • Receives aggregated data.
   • Uses Gemini and attack_planner_prompt.txt to generate a JSON attack plan.
   • State: Writes attack_plan to session state.
4. Exploit Routing (exploit_router - RouterAgent):
   • Reads attack_plan from state.

Setup

1. Clone the repository.
2. Ensure prerequisites are installed: python3, pip, nmap, dig, whois, sqlmap, wapiti, wpscan, searchsploit.
3. Create a virtual environment:
   root@kitploit:~

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

4. Install dependencies:
   root@kitploit:~

   pip install -r requirements.txt
   

5. Configure API Keys (env):
   • Copy .env.example to .env (if example exists) or edit .

Security Notice

This tool is for authorized security testing and educational purposes only. Do not use against systems without explicit permission.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Prerequisites

• Python 3.9+
• pip (Python package installer)
• Nmap (sudo apt install nmap or brew install nmap)
• dig (sudo apt install dnsutils or brew install bind)
• whois (sudo apt install whois or brew install whois)
• sqlmap (sudo apt install sqlmap or brew install sqlmap)
• wapiti (sudo apt install wapiti or brew install wapiti)
• wpscan (sudo apt install ruby-full then gem install wpscan or brew install wpscan)

Key Features

• Agent-Based Workflow: Utilizes Google's Agent Development Kit (ADK) for a modular structure.
• Interactive Target Input: Uses adk web interface to ask the user for the target IP/domain.
• Multi-Stage Assessment:
  • Reconnaissance:
    • Nmap port scanning (Real)
    • Enhanced DNS/WHOIS lookups (Real: dig, nslookup, dig +trace, AXFR attempt, whois)
    • Web Search (Real, using Google Search)
    • Enhanced Web Content Analysis (Real: links, forms, comments, scripts, headers, emails, basic tech detection)
    • Data Aggregation
  • Planning: LLM (Gemini) analyzes recon data to generate a prioritized attack plan (with validation).
  • Exploitation (Conditional Routing): Executes tests based on the plan:
    • Web: Default files, Misconfigurations (Dir Listing), SQL Injection (via sqlmap with refined options), Wapiti scan (parsed results), WPScan (parsed results, conditional), Basic Reflected XSS, Basic Command Injection - (Real Checks)
    • SQL: Default Credentials (MySQL/PostgreSQL), Version Vulnerabilities (via searchsploit with refined query), Post-Auth Enumeration (via sqlmap direct connect) - (Real Checks)
    • Weak Credentials, Version Vulnerabilities (via with refined query), Configuration Audit (via , parsed results) - (Real Checks)

Architecture (Autonomous Multi-Agent System)

PhantomRecon uses a fully autonomous multi-agent architecture powered by Google's Agent Development Kit (ADK).

Core Components

Senior Orchestrator Agent (gemini-1.5-pro-latest)

• Autonomous decision-making and strategic planning
• Dynamically selects which specialist agents to invoke
• Iterates based on findings (no fixed sequence)
• Conducts comprehensive security audits with full autonomy

Specialized Security Agents

• Reconnaissance Agent: Port scanning, DNS enumeration, service detection
• Web Security Specialist: XSS, CSRF, SSRF, Path Traversal, Open Redirect
• SQL Injection Specialist: All SQL injection techniques across major databases
• SSH/Network Specialist: SSH security auditing, network service testing
• Authentication Specialist: Auth bypass, session security, privilege escalation
• Planning Agent: Strategic attack planning based on findings
• Reporting Agent: Comprehensive security report generation

Autonomous Operation

The orchestrator operates like a senior penetration tester:

1. Accepts a target domain/IP
2. Plans reconnaissance strategy
3. Analyzes findings and identifies attack surfaces
4. Dynamically invokes specialist agents based on discoveries
5. Iterates and adapts approach as new information emerges
6. Generates comprehensive security audit report

Key Features:

• No fixed workflow - orchestrator decides strategy
• Parallel agent execution for efficiency
• Iterative deep-dive on discovered vulnerabilities
• Adaptive approach based on target characteristics
• Complete autonomy from target input to final report

Technical Details

• State management via context.session.state (ADK sessions)
• Parallel reconnaissance with real-time progress visualization (Rich library)
• Async command execution with timeouts (executor_fix.py)
• Configurable scanning parameters (env vars for Nmap, etc.)

Usage

Run via CLI (recommended):

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

Interactive console:

python -m phantomrecon

Optional ADK runner:

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