phantomrecon

# PhantomRecon

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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):
  ```bash
  python -m phantomrecon
  ```
- One-shot non-interactive run:
  ```bash
  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_