PhantomRecon

PhantomRecon é uma ferramenta de automação de red team modular, baseada em CLI e orientada a agentes, projetada para demonstrar fluxos de trabalho ofensivos de segurança autônomos alimentados por IA (Gemini do Google via Agent Development Kit - ADK).

Início Rápido (CLI)

• Execute o console interativo (estilo metasploit):

  python -m phantomrecon
  

• Execução única não interativa:

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

Opções de CLI

• --target <domínio|ip>: Alvo a ser avaliado
• --auto: Executa reconhecimento → planejamento → roteamento → relatório
• --nmap-timeout <segundos>: Substitui NMAP_TIMEOUT
• --nmap-top-ports <N>: Substitui NMAP_TOP_PORTS
• --nmap-args "...": Acrescenta argumentos ao Nmap (NMAP_ARGS)
• --nmap-disable: Desabilita o Nmap (define NMAP_DISABLE=1)

Variáveis de ambiente também são suportadas diretamente: NMAP_TIMEOUT, NMAP_TOP_PORTS, NMAP_ARGS, NMAP_DISABLE.

Higiene operacional

• Os relatórios não são versionados. O .gitignore exclui reports/* exceto reports/sample_report.md.
• Os relatórios HTML/MD gerados ficam em reports/ apenas localmente.
• Remova ou rotacione os relatórios conforme necessário; eles nunca são enviados em commits.

Construída como uma prova de conceito, ela simula a identificação de um alvo, a realização de reconhecimento amplo (Nmap, DNS, Pesquisa Web), o planejamento de uma estratégia de ataque usando um LLM, a execução condicional de exploits simulados e a geração de um relatório.

Estrutura do Projeto

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

Fluxo de Trabalho Atual

1. Reconhecimento em Paralelo (recon_workflow - Agente Paralelo):
   • Executa varredura Nmap (nmap_tool)
   • Executa consultas DNS/WHOIS (dns_tool)
   • Simula pesquisa web (web_search_tool)
   • Estado: Cada ferramenta grava seus resultados no estado da sessão.
2. Agregação (aggregation_tool):
   • Combina os resultados do fluxo de trabalho paralelo.
   • Estado: Grava aggregated_recon_data no estado da sessão.
3. Planejamento com LLM (planning_agent - LlmAgent):
   • Recebe os dados agregados.
   • Usa o Gemini e attack_planner_prompt.txt para gerar um plano de ataque em JSON.
   • Estado: Grava attack_plan no estado da sessão.
4. Roteamento de Exploits (exploit_router - RouterAgent):
   • Lê attack_plan do estado.
   • Executa condicionalmente ferramentas de exploit específicas (web_exploit_tool, sql_exploit_tool) com base no plano.
   • Estado: As ferramentas de exploit adicionam resultados à lista exploit_results no estado da sessão.
5. Relatório (report_tool):
   • Lê todos os dados relevantes (reconhecimento, plano, resultados) do estado da sessão.
   • Gera um arquivo de relatório final em Markdown.

Configuração

1. Clone o repositório.
2. Garanta que os pré-requisitos estejam instalados: python3, pip, nmap, dig, whois, sqlmap, wapiti, wpscan, searchsploit.
3. Crie um ambiente virtual:

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

4. Instale as dependências:

   pip install -r requirements.txt
   

5. Configure as Chaves de API (env):
   • Copie .env.example para .env (se o exemplo existir) ou edite .env.
   • Adicione sua Google API Key (da configuração do AI Studio ou do Vertex AI) para a variável GOOGLE_API_KEY.
   • Defina GOOGLE_GENAI_USE_VERTEXAI como True ou False e configure as variáveis relacionadas (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION) se estiver usando Vertex AI.
6. Execute a ferramenta:
   • CLI interativo: python -m phantomrecon
   • CLI de execução única: python -m phantomrecon --target <target> --auto
   • Runner ADK (opcional): adk run phantomrecon

Aviso de Segurança

Esta ferramenta é apenas para testes de segurança autorizados e fins educacionais. Não use contra sistemas sem permissão explícita.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Pré-requisitos

• Python 3.9+
• pip (instalador de pacotes 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 e em seguida gem install wpscan ou brew install wpscan)
• searchsploit (sudo apt install exploitdb ou brew install exploitdb)
• Um Google Cloud Project com a API Gemini habilitada.
• Uma chave de API para a API Gemini.
• Bibliotecas Python listadas em requirements.txt (instale via pip install -r requirements.txt)

Principais Recursos