PentestAgent

ИИ-тестирование на проникновение

https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975

Требования

• Python 3.10+
• Ключ API для OpenAI, Anthropic или другого провайдера, поддерживаемого LiteLLM

Установка

# Clone
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent

# Setup (creates venv, installs deps)
.\scripts\setup.ps1   # Windows
./scripts/setup.sh    # Linux/macOS

# Or manual
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate     # Linux/macOS
pip install -e ".[all]"
playwright install chromium  # Required for browser tool

Настройка

Создайте файл .env в корне проекта:

ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514

Или для OpenAI:

OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5

Подойдет любая модель, поддерживаемая LiteLLM.

Использование ретранслятора / собственного базового URL API

Направьте PentestAgent на любой OpenAI-совместимый эндпоинт с помощью OPENAI_API_BASE:

OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>

Для Anthropic-совместимых эндпоинтов используйте ANTHROPIC_API_BASE вместо этого. Полные примечания по провайдерам и опции эмбеддингов см. в .env.example.

Запуск

pentestagent                      # Launch TUI
pentestagent -t 192.168.1.1       # Launch with target
pentestagent tui --docker         # Run tools in Docker container

Docker

Запускайте инструменты внутри Docker-контейнера для изоляции и использования предустановленных инструментов пентеста.

Вариант 1: Загрузить готовый образ (самый быстрый)

# Base image with nmap, netcat, curl
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  -e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \
  ghcr.io/gh05tcrew/pentestagent:latest

# Kali image with metasploit, sqlmap, hydra, etc.
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  ghcr.io/gh05tcrew/pentestagent:kali

Вариант 2: Сборка локально

# Build
docker compose build

# Run
docker compose run --rm pentestagent

# Or with Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali

Контейнер запускает PentestAgent с доступом к Linux-инструментам пентеста. Агент может использовать nmap, msfconsole, sqlmap и т.д. напрямую через терминальный инструмент.

Требуется установленный и запущенный Docker.

Режимы

У PentestAgent есть три режима, доступных через команды в TUI:

Команды TUI

/assist <task>    One single-shot instruction.
/agent <task>     Run autonomous agent on task
/crew <task>      Run multi-agent crew on task
/interact <task>  Chat with the agent in guided mode
/target <host>    Set target
/tools            List available tools
/notes            Show saved notes
/report           Generate report from session
/memory           Show token/memory usage
/prompt           Show system prompt
/conversations    Browse and restore saved conversations
/mcp <list/add>   Visualizes or adds a new MCP server.
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
                  Manually spawn a child MCP agent from the TUI.
/despawn <server_name>
                  Terminate and remove a previously spawned child agent.
/clear            Clear chat and history
/quit             Exit (also /exit, /q)
/help             Show help (also /h, /?)

Нажмите Esc, чтобы остановить запущенного агента. Ctrl+Q для выхода.

Плейбуки

PentestAgent включает готовые атакующие плейбуки для тестирования безопасности методом черного ящика. Плейбуки задают структурированный подход к конкретным оценкам безопасности.

Запуск плейбука:

pentestagent run -t example.com --playbook thp3_web

Инструменты

PentestAgent включает встроенные инструменты и поддерживает MCP (Model Context Protocol) для расширения функциональности.

Встроенные инструменты: terminal, browser, notes, web_search (требуется TAVILY_API_KEY), spawn_mcp_agent

Самопорождение агента (spawn_mcp_agent)

spawn_mcp_agent — встроенный инструмент, который позволяет запущенному агенту породить собственную дочернюю копию в качестве подчиненного MCP-сервера, подключенного через stdio. Дочерний процесс полностью изолирован — у него собственный рантайм, LLM-клиент, история диалога и хранилище заметок, — а после порождения полный набор его инструментов внедряется в доступные инструменты родительского агента.

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

После возврата из spawn_mcp_agent инструменты дочернего агента (run_task, run_task_async, await_tasks и т.д.) становятся доступны при следующем вызове инструмента. Имя сервера дочернего агента назначается автоматически (например, child_agent_1) и возвращается в результате.

Пример — оркестратор делегирует параллельную разведку двум дочерним агентам:

# Turn 1: spawn two isolated child agents
spawn_mcp_agent  target="10.0.1.0/24"  scope=["10.0.1.0/24"]
spawn_mcp_agent  target="10.0.2.0/24"  scope=["10.0.2.0/24"]

# Turn 2: children's tools are now available — delegate work asynchronously
child_agent_1__run_task_async  task="Full port scan and service enumeration"
child_agent_2__run_task_async  task="Full port scan and service enumeration"

# Turn 3: wait and collect
child_agent_1__await_tasks  task_ids=["<id1>"]  timeout_seconds=600
child_agent_2__await_tasks  task_ids=["<id2>"]  timeout_seconds=600
child_agent_1__get_task_result  task_id="<id1>"
child_agent_2__get_task_result  task_id="<id2>"

Ручное управление дочерними агентами (/spawn и /despawn)

Помимо автоматического инструмента spawn_mcp_agent, TUI предоставляет две команды, которые позволяют вручную запускать и завершать дочерних агентов, независимо от выполняющегося цикла агента.

/spawn

/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]

Порождает нового дочернего MCP-агента через stdio и подключает его к текущей сессии. Дочерний агент появляется в виде сворачиваемой терминальной панели на боковой панели TUI, а его инструменты становятся доступны родительскому агенту при следующем вызове инструмента.

Примеры:

/spawn 10.0.1.1
/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag

/despawn

/despawn <server_name>

Завершает дочернего агента, идентифицируемого по server_name (например, child_agent_1), удаляет его терминальную панель из TUI и отключает его инструменты от родительской сессии. Используйте /mcp list, чтобы увидеть имена всех активных на данный момент дочерних агентов.

Пример:

/despawn child_agent_1

RAG-оптимизатор MCP-инструментов

Когда MCP-сервер предоставляет более 128 инструментов, PentestAgent автоматически заменяет весь каталог одним инструментом mcp_<server>_rag_optimizer. Этот мета-инструмент использует схожесть эмбеддингов (через LiteLLM, по умолчанию text-embedding-3-small) для поиска наиболее релевантных инструментов для текущей задачи и внедряет их в следующий ход агента — сохраняя контекстное окно управляемым без потери доступа к полному набору инструментов.

Оптимизатор прозрачен для агента: он вызывает RAG-инструмент с точечными запросами на естественном языке, описывающими то, что ему нужно, и подходящие инструменты становятся доступны на следующем ходу для прямого вызова.

Рекомендации по использованию для агента:

Эмбеддинги вычисляются один раз при запуске и кэшируются, поэтому повторные запросы выполняются быстро. Оптимизатор создается для каждого сервера отдельно, поэтому каждый MCP-сервер с большим каталогом получает собственный независимый индекс.

Совет: Передавайте по одному запросу на отдельную возможность, а не объединяйте всё в один запрос. ["list open ports on a host", "get process memory usage"] даёт лучшие результаты, чем ["list ports and memory and CPU"].

Интеграция с MCP

PentestAgent поддерживает MCP (Model Context Protocol) в двух направлениях: потребление внешних MCP-серверов в качестве источников инструментов и предоставление себя в качестве MCP-сервера, чтобы внешние клиенты (Claude Desktop, Cursor и т.д.) могли управлять PentestAgent программно.

Потребление внешних MCP-серверов (режим клиента)

Настройте mcp_servers.json, чтобы подключить PentestAgent к любым внешним MCP-серверам. Пример конфигурации:

{
  "mcpServers": {
    "nmap": {
      "command": "npx",
      "args": ["-y", "gc-nmap-mcp"],
      "env": {
        "NMAP_PATH": "/usr/bin/nmap"
      }
    }
  }
}

Предоставление PentestAgent в роли MCP-сервера (режим сервера)

PentestAgent может работать как MCP-сервер, позволяя любому MCP-совместимому клиенту отправлять задачи, просматривать результаты и удаленно управлять агентом. Поддерживаются два транспорта:

STDIO — для локальных клиентов (например, Claude Desktop, Cursor):

pentestagent mcp_server --type stdio
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24
pentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker

SSE (HTTP) — для удаленных или сетевых клиентов:

pentestagent mcp_server --type sse
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080
pentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0/24 --docker

Транспорт SSE предоставляет единый эндпоинт /mcp, поддерживающий POST (запросы), GET (постоянный SSE-поток для push-уведомлений, инициируемых сервером) и DELETE (завершение сессии). Сессии отслеживаются через заголовок Mcp-Session-Id.

Все флаги mcp_server:

Пример: конфигурация Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pentestagent": {
      "command": "pentestagent",
      "args": ["mcp_server", "--type", "stdio"]
    }
  }
}

Справочник инструментов MCP-сервера

В роли MCP-сервера PentestAgent предоставляет следующие инструменты:

Статус сервера и конфигурация

Выполнение задач

Просмотр задач

Управление задачами

Управление инструментами

История диалога

Память

Наблюдаемость

Пример асинхронного рабочего процесса с задачами

Для длительных задач разведки используйте асинхронный паттерн:

# 1. Submit tasks without blocking
run_task_async  task="Enumerate subdomains of example.com"  target="example.com"
run_task_async  task="Run nmap SYN scan on example.com"     target="example.com"

# 2. Block until both finish (up to 5 minutes)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. Retrieve full results
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

Управление инструментами через CLI

pentestagent tools list         # List all tools
pentestagent tools info <name>  # Show tool details
pentestagent mcp list           # List MCP servers
pentestagent mcp add <name> <command> [args...]  # Add MCP server
pentestagent mcp test <name>    # Test MCP connection

Управление историей диалога

Каждое пользовательское сообщение в TUI содержит две встроенные кнопки действий: rewind и fork.

Rewind

Нажмите rewind на любом пользовательском сообщении, чтобы обрезать диалог до точки непосредственно перед этим сообщением — как в интерфейсе, так и в оперативной истории агента. Используйте эту функцию, чтобы повторить запрос с нуля, не сохраняя отброшенную ветку.

Fork

Нажмите >> fork на любом пользовательском сообщении, чтобы создать ответвление диалога от этой точки:

1. Текущий полный диалог сохраняется в хранилище диалогов, и показывается короткий ID снимка.
2. Затем диалог обрезается до точки непосредственно перед выбранным сообщением (так же, как и при rewind).

Это позволяет опробовать альтернативный подход с любой точки, сохраняя исходную ветку доступной через /conversations.

История диалогов

PentestAgent автоматически сохраняет каждый диалог, чтобы вы могли просматривать, сравнивать и восстанавливать прошлые сессии.

Автосохранение срабатывает после каждой задачи /assist, /agent, /crew и /interact, а также перед /clear. Хранится до 20 диалогов; более старые автоматически удаляются.

Место хранения: workspaces/<active>/memory/conversations/ при активной рабочей области, либо conversations/ в корне проекта в противном случае. Каждый диалог — это JSON-файл.

Просмотр и восстановление через /conversations:

Команда /conversations открывает модальное окно с двумя панелями внутри TUI:

• Левая панель — список сохраненных диалогов с заголовком и датой.
• Правая панель — предпросмотр метаданных и первые 5 сообщений (сообщения пользователя — синим, ответы агента — зеленым, вызовы инструментов — желтым, результаты инструментов — серым). Счетчик показывает, сколько дополнительных сообщений имеется.

Выберите диалог и нажмите Restore, чтобы загрузить его в текущую сессию, или Close, чтобы закрыть модальное окно.

База знаний

• RAG: Помещайте методологии, CVE или словари в pentestagent/knowledge/sources/ для автоматического внедрения в контекст.
• Заметки: Агенты сохраняют находки в loot/notes.json с категориями (credential, vulnerability, finding, artifact). Заметки сохраняются между сессиями и внедряются в контекст агента.
• Теневой граф: В режиме Crew оркестратор строит граф знаний из заметок для получения стратегических выводов (например, «У нас есть учетные данные для хоста X»).

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

pentestagent/
  agents/         # Agent implementations
  config/         # Settings and constants
  interface/      # TUI and CLI
  knowledge/      # RAG system and shadow graph
  llm/            # LiteLLM wrapper
  mcp/            # MCP client and server configs
  playbooks/      # Attack playbooks
  runtime/        # Execution environment
  tools/          # Built-in tools

Разработка

pip install -e ".[dev]"
pytest                       # Run tests
pytest --cov=pentestagent    # With coverage
black pentestagent           # Format
ruff check pentestagent      # Lint

Правовая информация

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

Лицензия

MIT