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.

Использование ретранслятора / пользовательской базы API

Направьте PentestAgent на любой совместимый с OpenAI endpoint через 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 endpoint используйте 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, история разговоров и хранилище заметок — и его полный набор инструментов внедряется обратно в доступные инструменты родительского агента после создания.

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

Пример — оркестратор делегирует параллельный сбор информации двум дочерним агентам:

# 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

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

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

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

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

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

Совет: Передавайте один запрос на каждую отдельную возможность, а не объединяйте всё в один запрос. ["получить список открытых портов на хосте", "получить использование памяти процессом"] даст лучшие результаты, чем ["получить порты, память и 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:

| --docker | false | Использовать DockerRuntime вместо LocalRuntime | | --no-rag | false | Пропустить инициализацию движка RAG | | --no-mcp | false | Пропустить подключения к внешним MCP-серверам |

Пример: Конфигурация 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 содержит две встроенные кнопки действий: откатить и ветвление.

Откат

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

Ветвление

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

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

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

История переписки

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

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

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

Просмотр и восстановление с помощью /conversations:

Команда /conversations открывает модальное окно с разделённым экраном внутри TUI: - Левая панель — список сохранённых переписок с заголовком и датой.

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

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

База знаний

• 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