PhantomRecon

PhantomRecon — это CLI-инструмент автоматизации red team с модульной архитектурой и управлением через агентов, предназначенный для демонстрации автономных рабочих процессов наступательной безопасности на базе ИИ (Google Gemini через Agent Development Kit — ADK).

Быстрый старт (CLI)

• Запуск интерактивной консоли (в стиле metasploit):

  python -m phantomrecon
  

• Одноразовый неинтерактивный запуск:

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

Параметры CLI

• --target <domain|ip>: Цель для оценки
• --auto: Выполнить: разведка → планирование → маршрутизация → отчёт
• --nmap-timeout <seconds>: Переопределяет NMAP_TIMEOUT
• --nmap-top-ports <N>: Переопределяет NMAP_TOP_PORTS
• --nmap-args "...": Дополняет аргументы Nmap (NMAP_ARGS)
• --nmap-disable: Отключить Nmap (устанавливает NMAP_DISABLE=1)

Переменные окружения также поддерживаются напрямую: NMAP_TIMEOUT, NMAP_TOP_PORTS, NMAP_ARGS, NMAP_DISABLE.

Эксплуатационная гигиена

• Отчёты не версионируются. .gitignore исключает reports/*, кроме reports/sample_report.md.
• Сгенерированные HTML/MD-отчёты хранятся только локально в каталоге reports/.
• Удаляйте или ротируйте отчёты по мере необходимости; они никогда не загружаются в коммитах.

Созданный как proof-of-concept, инструмент имитирует идентификацию цели, проведение широкой разведки (Nmap, DNS, веб-поиск), планирование стратегии атаки с помощью LLM, условное выполнение имитируемых эксплойтов и формирование отчёта.

Структура проекта

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

Текущий рабочий процесс

1. Параллельная разведка (recon_workflow — параллельный агент):
   • Выполняет Nmap-сканирование (nmap_tool)
   • Выполняет DNS/WHOIS-запросы (dns_tool)
   • Имитирует веб-поиск (web_search_tool)
   • Состояние: каждый инструмент записывает свои результаты в состояние сессии.
2. Агрегация (aggregation_tool):
   • Объединяет результаты параллельного рабочего процесса.
   • Состояние: записывает aggregated_recon_data в состояние сессии.
3. Планирование LLM (planning_agent — LlmAgent):
   • Получает агрегированные данные.
   • Использует Gemini и attack_planner_prompt.txt для генерации JSON-плана атаки.
   • Состояние: записывает attack_plan в состояние сессии.
4. Маршрутизация эксплойтов (exploit_router — RouterAgent):
   • Читает attack_plan из состояния.
   • Условно выполняет определённые инструменты эксплойтов (web_exploit_tool, sql_exploit_tool) на основе плана.
   • Состояние: инструменты эксплойтов добавляют результаты в список exploit_results в состоянии сессии.
5. Формирование отчёта (report_tool):
   • Читает все соответствующие данные (разведка, план, результаты) из состояния сессии.
   • Генерирует итоговый файл отчёта в формате Markdown.

Установка

1. Клонируйте репозиторий.
2. Убедитесь, что установлены необходимые зависимости: python3, pip, nmap, dig, whois, sqlmap, wapiti, wpscan, searchsploit.
3. Создайте виртуальное окружение:

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

4. Установите зависимости:

   pip install -r requirements.txt
   

5. Настройте API-ключи (env):
   • Скопируйте .env.example в .env (если пример существует) или отредактируйте .env.
   • Добавьте ваш Google API-ключ (из AI Studio или настройки Vertex AI) для переменной GOOGLE_API_KEY.
   • Установите GOOGLE_GENAI_USE_VERTEXAI в True или False и настройте связанные переменные (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION), если используете Vertex AI.
6. Запустите инструмент:
   • CLI интерактивно: python -m phantomrecon
   • CLI одноразово: python -m phantomrecon --target <target> --auto
   • ADK runner (необязательно): adk run phantomrecon

Уведомление о безопасности

Этот инструмент предназначен только для авторизованного тестирования безопасности и образовательных целей. Не используйте его против систем без явного разрешения.

Лицензия

Этот проект лицензирован в соответствии с MIT License — подробности см. в файле LICENSE.

Предварительные требования

• Python 3.9+
• pip (установщик пакетов Python)
• Nmap (sudo apt install nmap или brew install nmap)
• dig (sudo apt install dnsutils или brew install bind)
• whois (sudo apt install whois или brew install whois)
• sqlmap (sudo apt install sqlmap или brew install sqlmap)
• wapiti (sudo apt install wapiti или brew install wapiti)
• wpscan (sudo apt install ruby-full, затем gem install wpscan или brew install wpscan)
• searchsploit (sudo apt install exploitdb или brew install exploitdb)
• Проект Google Cloud с включённым Gemini API.
• API-ключ для Gemini API.
• Библиотеки Python, перечисленные в requirements.txt (установка через pip install -r requirements.txt)

Ключевые особенности