Skip to content

Back to the catalog

GH05TCREW/pentestagent
github.comrepo

GH05TCREW/pentestagent

PentestAgent (GhostCrew) is an LLM-powered pentesting agent with a TUI that runs single-shot, autonomous-agent, or multi-agent "crew" modes against a target, backed by built-in terminal/browser/notes tools and prebuilt black-box attack playbooks. It supports Docker/Kali images preloaded with nmap, Metasploit, sqlmap and hydra, exposes itself as an MCP server for external clients, and can spawn hierarchical child agents over MCP (with RAG-based tool selection) to delegate recon subtasks in parallel.

TL;DR An LLM-driven autonomous pentesting agent (TUI + MCP server) that orchestrates nmap/Metasploit/sqlmap via Docker/Kali and can spawn child MCP sub-agents for parallel recon.
Open original ↗
Document

What it is

Concrete operational detail for PentestAgent (GhostCrew) beyond the catalog summary: the exact install path, the provider/relay configuration, the Docker image tags, and the mechanics of its self-spawning MCP child agents. Python 3.10+ and an OpenAI/Anthropic/LiteLLM key are required; the browser tool needs playwright install chromium.

How it works

Modes are driven by TUI slash-commands: /assist (single-shot), /agent (autonomous), /crew (multi-agent), /interact (guided). An agent can call the built-in spawn_mcp_agent tool to launch a child copy of itself as a subordinate MCP server over stdio — fully isolated runtime, LLM client, history, and notes. The child's entire tool set (run_task, run_task_async, await_tasks, get_task_result, etc.) is then injected back into the parent's available tools, enabling hierarchical delegation with no external orchestrator. When a spawned MCP server exposes more than 128 tools, PentestAgent auto-replaces the full catalogue with a single mcp_<server>_rag_optimizer meta-tool that selects by embedding similarity.

What to do

Run tools inside Docker for isolation and preinstalled tooling:

pentestagent tui --docker

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

Run a prebuilt playbook non-interactively:

pentestagent run -t example.com --playbook thp3_web

Manage child agents manually from the TUI:

/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/despawn child_agent_1
/mcp list

Caveats

  • The provider is arbitrary: setting OPENAI_API_BASE / ANTHROPIC_API_BASE points the agent — and therefore all target data, tool output, and notes — at any OpenAI-compatible relay you name. Treat the relay as a data-egress boundary.
  • Child agents auto-name (child_agent_1, …) and their tools appear on the next tool call, not immediately; collection is via explicit await_tasks with a timeout_seconds.
  • web_search requires TAVILY_API_KEY; the browser tool requires the Chromium install step above.

Technologies named here

Techniques named here

  • Autonomous agent task execution
  • Multi-agent crew execution
  • Hierarchical multi-agent delegation via spawn_mcp_agent
  • Playbook-driven black-box security testing
  • Async task recon pattern
  • RAG-based tool retrieval
  • Shadow Graph knowledge derivation

Related in Offensive Security