pentestagent

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

Requirements

• Python 3.10+
• API key for OpenAI, Anthropic, or other LiteLLM-supported provider

Install

# 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

Configure

Create .env in the project root:

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

Or for OpenAI:

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

Any LiteLLM-supported model works.

Using a relay / custom API base

Point PentestAgent at any OpenAI-compatible endpoint via OPENAI_API_BASE:

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

For Anthropic-compatible endpoints use ANTHROPIC_API_BASE instead. See .env.example for full provider notes and embedding options.

Run

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

Docker

Run tools inside a Docker container for isolation and pre-installed pentesting tools.

Option 1: Pull pre-built image (fastest)

# 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

Option 2: Build locally

# 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

The container runs PentestAgent with access to Linux pentesting tools. The agent can use nmap, msfconsole, sqlmap, etc. directly via the terminal tool.

Requires Docker to be installed and running.

Modes

PentestAgent has three modes, accessible via commands in the TUI:

Mode	Command	Description
Assist	/assist <task>	One single-shot instruction, with tool execution
Agent	/agent <task>	Autonomous execution of a single task
Crew	/crew <task>	Multi-agent mode. Orchestrator spawns specialized workers
Interact	/interact <task>	Interactive mode. Chat with the agent, it will help you and guide during the pentesting procedure

TUI Commands

…

Press Esc to stop a running agent. Ctrl+Q to quit.

Playbooks

PentestAgent includes prebuilt attack playbooks for black-box security testing. Playbooks define a structured approach to specific security assessments.

Run a playbook:

pentestagent run -t example.com --playbook thp3_web

Tools

PentestAgent includes built-in tools and supports MCP (Model Context Protocol) for extensibility.

Built-in tools: terminal, browser, notes, web_search (requires TAVILY_API_KEY), spawn_mcp_agent

Agent Self-Spawning (spawn_mcp_agent)

spawn_mcp_agent is a built-in tool that allows a running agent to spawn a child copy of itself as a subordinate MCP server connected over stdio. The child process is fully isolated — its own runtime, LLM client, conversation history, and notes store — and its complete tool set is injected back into the parent agent's available tools after spawning.

This enables hierarchical, multi-agent workflows without any external orchestration: the agent self-organises by delegating scoped subtasks to children it spawns on demand.

Argument	Type	Default	Description
target	string	—	Pentest target to pass to the child
scope	string[]	—	In-scope targets/CIDRs for the child
model	string	env var	Model identifier, overrides PENTESTAGENT_MODEL on the child
no_rag	boolean	false	Skip RAG engine initialisation on the child
no_mcp	boolean	true	Skip external MCP server connections on the child (recommended)

After spawn_mcp_agent returns, the child's tools (run_task, run_task_async, await_tasks, etc.) are available on the next tool call. The child's server name is assigned automatically (e.g. child_agent_1) and returned in the result.

Example — orchestrator delegating parallel recon to two children:

…

Manual Child Agent Control (/spawn and /despawn)

Beyond the automatic spawn_mcp_agent tool, the TUI exposes two commands that let you spawn and terminate child agents manually, independently of a running agent loop.

/spawn

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

Spawns a new child MCP agent over stdio and attaches it to the current session. The child appears as a collapsible terminal panel in the TUI sidebar and its tools become available to the parent agent on the next tool call.

Argument	Description
target	Pentest target to pass to the child (positional or --target)
--scope CIDR	One or more in-scope CIDRs (repeatable)
--model MODEL	Override the model for the child agent
--no-rag	Skip RAG engine initialisation on the child
--no-mcp	Skip external MCP server connections on the child

Examples:

/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>

Terminates the child agent identified by server_name (e.g. child_agent_1), removes its terminal panel from the TUI, and disconnects its tools from the parent session. Use /mcp list to see the names of all currently active child agents.

Example:

/despawn child_agent_1

MCP RAG Tool Optimizer

When an MCP server exposes more than 128 tools, PentestAgent automatically replaces the full catalogue with a single mcp_<server>_rag_optimizer tool. This meta-tool uses embedding similarity (via LiteLLM, default text-embedding-3-small) to retrieve the most relevant tools for the task at hand and injects them into the agent's next turn — keeping the context window manageable without losing access to the full tool set.

The optimizer is transparent to the agent: it calls the RAG tool with focused natural-language queries describing what it needs, and the matching tools become available on the next turn to call directly.

Usage guidance for the agent:

Argument	Type	Default	Description
queries	string[]	(required)	One focused query per capability needed. More specific = higher accuracy
top_k	integer	20	Tools to retrieve per query (max 128). Results are merged and deduplicated

Embeddings are computed once at startup and cached, so repeated queries are fast. The optimizer is built per-server, so each MCP server with a large catalogue gets its own independent index.

Tip: Pass one query per distinct capability rather than combining everything into one query. ["list open ports on a host", "get process memory usage"] retrieves better results than ["list ports and memory and CPU"].

MCP Integration

PentestAgent supports MCP (Model Context Protocol) in two directions: consuming external MCP servers as tool sources, and exposing itself as an MCP server so external clients (Claude Desktop, Cursor, etc.) can drive PentestAgent programmatically.

---

Consuming External MCP Servers (Client Mode)

Configure mcp_servers.json to connect PentestAgent to any external MCP servers. Example config:

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

---

Exposing PentestAgent as an MCP Server (Server Mode)

PentestAgent can run as an MCP server, allowing any MCP-compatible client to submit tasks, inspect results, and control the agent remotely. Two transports are supported:

STDIO — for local clients (e.g. 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) — for remote or networked clients:

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

The SSE transport exposes a single /mcp endpoint supporting POST (requests), GET (persistent SSE stream for server-initiated push), and DELETE (session teardown). Sessions are tracked via the Mcp-Session-Id header.

All mcp_server flags:

Flag	Default	Description
--type	(required)	Transport: stdio or sse
--host	0.0.0.0	SSE bind host
--port	8080	SSE bind port
--target	none	Primary pentest target (IP / hostname)
--scope	[]	In-scope targets/CIDRs (space-separated)
--model	env var	Model identifier, overrides PENTESTAGENT_MODEL
--docker	false	Use DockerRuntime instead of LocalRuntime
--no-rag	false	Skip RAG engine initialisation
--no-mcp	false	Skip external MCP server connections

Example: Claude Desktop config (claude_desktop_config.json)

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

---

MCP Server Tools Reference

When acting as an MCP server, PentestAgent exposes the following tools:

Server Status & Config

Tool	Description
get_server_status	Live server status: readiness, task counts by state, primary target/scope, memory store size
get_config	Primary agent configuration: target, scope, max iterations, tool list
update_config	Update target, scope, or max iterations for all subsequent tasks

Task Execution

Tool	Description
run_task	Submit a task and block until it completes. Returns full result, tools used, and notes snapshot
run_task_async	Submit a task and return immediately with a task_id. Poll with get_task_status

Task Inspection

Tool	Description
list_tasks	List all tasks with status, target, and summary. Filterable by status
get_task_status	Poll the current status and result preview of a task
get_task_result	Full task result: final output, thinking steps, all tool calls and results, notes snapshot
await_tasks	Block until a set of async task IDs have all finished (polls every 500 ms, configurable timeout)

Task Control

Tool	Description
cancel_task	Cancel a running or pending task by ID

Tool Management

Tool	Description
list_tools	List all tools available to the agent
enable_tool	Enable a named tool on the primary agent
disable_tool	Disable a named tool on the primary agent

Conversation History

Tool	Description
get_conversation_history	Return message history for a task or the primary agent. Supports a limit parameter
reset_conversation	Clear conversation history for a task or the prim