GH05TCREW/PentestAgent: AI-Driven Black-Box Security Testing

GH05TCREW/PentestAgent: AI-Driven Black-Box Security Testing

Black-box security testing remains one of the most time-intensive disciplines in cybersecurity. Reconnaissance, vulnerability enumeration, and exploitation each demand hours of manual work across disparate tools—nmap, sqlmap, Metasploit, and countless custom scripts. For bug bounty hunters, red-team operators, and penetration testers, the cognitive overhead of context-switching between tools and maintaining coherent notes across long engagements creates friction that slows findings and increases error rates.

PentestAgent, developed by GH05TCREW, addresses this directly. It is an open-source AI agent framework that orchestrates black-box security testing workflows through a unified terminal interface, with support for autonomous single-agent execution, multi-agent crew delegation, and interactive guided sessions. Built in Python^{↗ Bright Coding Blog} and released under the MIT License, it has accumulated 2,791 GitHub stars and 557 forks as of its last commit on July 7, 2026. This article examines what PentestAgent offers, how it works, and where it fits in a modern offensive security toolchain.

What is GH05TCREW/PentestAgent?

PentestAgent is a Python 3.10+ application that wraps large language model (LLM) reasoning around a suite of built-in security tools and external integrations. It is maintained by GH05TCREW as an open-source project with no commercial licensing restrictions. The framework sits at the intersection of three technical categories: AI agent orchestration, penetration testing automation, and MCP (Model Context Protocol) infrastructure.

The project's relevance stems from a specific architectural bet: rather than building yet another vulnerability scanner, PentestAgent treats the LLM as a planning and execution layer that can invoke real security tools, manage state across long-running tasks, and delegate work to child agents when parallelism is beneficial. This distinguishes it from static scan-and-report tools or simple LLM chatbots that lack tool-use capabilities.

PentestAgent supports any LiteLLM-compatible provider, including OpenAI and Anthropic, with explicit configuration paths for custom API bases and relay endpoints. It ships with a terminal-based user interface (TUI), Docker^{↗ Bright Coding Blog} runtime options for tool isolation, and pre-built attack playbooks for structured assessments. The MCP compatibility badge in its README signals broader ecosystem ambitions—PentestAgent can consume external MCP servers as tools and expose itself as an MCP server for integration with clients like Claude Desktop or Cursor.

The project is actively maintained, with version 0.2.0 as its current release. Its MIT License permits commercial and private use with minimal friction, a meaningful consideration for security consultants who need to deploy tooling in client environments without license audit overhead.

Key Features

Four Execution Modes PentestAgent provides four distinct interaction patterns through its TUI: /assist for single-shot instructions with tool execution; /agent for autonomous task execution; /crew for multi-agent orchestration where a parent spawns specialized workers; and /interact for guided conversational support during manual testing. This granularity lets operators match automation level to task risk—autonomous modes for well-scoped recon, interactive mode for sensitive exploitation.

Hierarchical Multi-Agent Spawning The spawn_mcp_agent tool enables a running agent to create fully isolated child copies of itself as subordinate MCP servers. Each child maintains independent runtime, LLM client, conversation history, and notes store. After spawning, the child's tools (including run_task, run_task_async, and await_tasks) become available to the parent. This enables parallel reconnaissance across network segments without external orchestration infrastructure.

MCP Bidirectional Integration PentestAgent functions as both MCP client and server. As client, it connects to external MCP servers via mcp_servers.json configuration. As server, it exposes tools for task submission, status inspection, and memory management over STDIO or SSE transports. The SSE transport implements session tracking via Mcp-Session-Id headers with POST, GET, and DELETE verb support.

RAG Tool Optimizer for Large MCP Catalogues When an MCP server exposes more than 128 tools, PentestAgent automatically substitutes the full catalogue with an embedding-based retrieval tool. Using LiteLLM's embedding capabilities (defaulting to text-embedding-3-small), it retrieves relevant tools per-query and injects them into the agent's context window. Embeddings are computed once at startup and cached.

Docker Isolation with Pre-Built Images The project distributes two container variants: a base image with nmap, netcat, and curl; and a Kali image with Metasploit, sqlmap, and hydra. This eliminates host environment contamination and provides predictable tool availability.

Conversation History with Rewind and Fork Every user message in the TUI offers inline rewind (truncate to before this message) and fork (save current branch, then truncate) operations. Conversations auto-save after task completion and are browsable via /conversations with split-pane preview and restore.

Use Cases

Bug Bounty Reconnaissance at Scale A researcher targeting a wide scope can use /crew mode to spawn child agents per subdomain or IP range. Each child performs independent port scanning and service enumeration, with results aggregating into the parent's notes store. The shadow graph in Crew mode derives strategic insights—such as credential reuse across hosts—from accumulated findings.

Red-Team Infrastructure Assessment For authorized red-team engagements, the Kali Docker image provides immediate access to Metasploit and sqlmap without host installation. The /interact mode guides operators through complex multi-step exploitation while maintaining searchable notes categorized as credential, vulnerability, finding, or artifact.

Continuous Security Validation in CI/CD PentestAgent's MCP server mode enables programmatic integration. A CI pipeline can submit tasks via run_task_async, poll with get_task_status, and retrieve structured results. The SSE transport supports remote orchestration across segmented networks.

Security Tooling as MCP Infrastructure Organizations standardizing on MCP can expose PentestAgent as a server, allowing analysts using Claude Desktop or Cursor to dispatch security tasks without leaving their development environment. The update_config tool permits dynamic target and scope adjustment without process restart.

Knowledge Management for Distributed Teams The RAG system ingests methodologies, CVEs, and wordlists from pentestagent/knowledge/sources/, while notes persist to loot/notes.json across sessions. Teams can share knowledge bases and note repositories to maintain organizational memory across testers.

Installation & Setup

PentestAgent requires Python 3.10 or later and an API key for an LLM provider. The installation process is straightforward, with automated setup scripts for Windows and Unix-like systems.

Clone the repository and enter the project directory:

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

Run the automated setup for your platform:

# Windows
.\scripts\setup.ps1

# Linux/macOS
./scripts/setup.sh

Alternatively, perform manual installation:

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

Create a .env file in the project root for your chosen provider. For Anthropic:

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

For OpenAI:

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

Any LiteLLM-supported model works. For custom API bases—such as internal relays or proxy endpoints—use:

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, substitute ANTHROPIC_API_BASE. The .env.example file contains full provider notes and embedding configuration options.

Real Code Examples

Launching with a Target

The simplest entry point specifies a target at invocation:

pentestagent -t 192.168.1.1

This launches the TUI with the target pre-configured, saving a /target command. The -t flag is equivalent to setting the target interactively but enables scripted workflow initiation.

Running a Pre-Built Playbook

PentestAgent includes structured attack playbooks for common assessment types. The thp3_web playbook executes a web-focused black-box methodology:

pentestagent run -t example.com --playbook thp3_web

Playbooks define ordered phases—reconnaissance, discovery, vulnerability identification—reducing the planning burden on the operator. The framework handles tool selection and execution sequencing based on playbook definitions.

Spawning Parallel Child Agents

This example from the README demonstrates the hierarchical multi-agent pattern for network reconnaissance:

# 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>"

The spawn_mcp_agent tool accepts target, scope, model, no_rag, and no_mcp parameters. Children are automatically named (child_agent_1, child_agent_2, etc.) and their tools appear namespaced on the parent's next turn. The no_mcp: true default prevents recursive external MCP connections, containing complexity.

MCP Server Configuration for Claude Desktop

To expose PentestAgent as an MCP server for local clients, configure claude_desktop_config.json:

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

This enables Claude Desktop to submit tasks through PentestAgent's tool surface, with results returning through the MCP protocol. For remote access, substitute --type sse with --host and --port flags.

Async Task Workflow via MCP Tools

For long-running operations, the async pattern avoids blocking:

# 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>"

The await_tasks tool polls every 500 milliseconds with configurable timeout, providing a coordination primitive without external job schedulers.

Advanced Usage & Best Practices

Scope Discipline with Child Agents When using spawn_mcp_agent, explicitly define scope as CIDR ranges or host lists. The isolation is runtime-only; a child with overly broad scope can generate noise that complicates parent-level synthesis. The --no-mcp flag on children is recommended to prevent unintended external tool proliferation.

RAG Query Precision The MCP RAG optimizer retrieves tools per-query. Pass one focused query per capability needed rather than combining concepts. The README explicitly notes that ["list open ports on a host", "get process memory usage"] outperforms ["list ports and memory and CPU"] for retrieval accuracy.

Docker for Untrusted Targets The Kali image provides comprehensive tooling but increases attack surface. For internet-facing or less trusted targets, prefer the base image with explicit tool installation, or extend the Dockerfile with only required packages.

Conversation Hygiene Use /conversations to review and restore sessions, but prune aggressively with /clear when context window pressure rises. The memory display (/memory) shows token usage—monitor this during long Crew sessions where multiple agent histories accumulate.

Embedding Cost Awareness The RAG optimizer computes embeddings at startup. For large knowledge bases in pentestagent/knowledge/sources/, this incurs one-time API costs proportional to document volume. The cache eliminates repeated computation, but initial runs may surprise operators unfamiliar with embedding pricing.

Comparison with Alternatives

PentestAgent occupies a narrower niche than general autonomous agents but offers deeper security-specific integration. Against template scanners like Nuclei, it trades raw speed for adaptability—valuable in black-box scenarios where target-specific reasoning matters. The MCP architecture provides interoperability that closed alternatives cannot match, though this requires operational investment in MCP infrastructure.

FAQ

What LLM providers does PentestAgent support? Any LiteLLM-compatible provider, including OpenAI, Anthropic, and custom OpenAI-compatible endpoints via OPENAI_API_BASE or ANTHROPIC_API_BASE.

Is commercial use permitted under the MIT License? Yes. The MIT License allows commercial use, modification, and distribution with attribution.

Does PentestAgent require Docker? No. Docker is optional for tool isolation. Local installation with playwright install chromium suffices for most features.

How does the Crew mode differ from single Agent mode? Crew mode activates an orchestrator that builds a shadow knowledge graph from notes and can spawn specialized workers. Agent mode runs a single autonomous task without inter-agent coordination.

Can I use my own fine-tuned model? Yes, through LiteLLM's provider abstraction. Point PENTESTAGENT_MODEL and the appropriate API base to your model endpoint.

What happens when conversations exceed the context window? The TUI provides /memory for monitoring. Use /clear to truncate, or rewind/fork to manage branch complexity. The RAG optimizer also reduces tool description overhead for MCP servers with large catalogues.

Is there a web interface? No. PentestAgent is TUI-only as documented. MCP server mode enables external clients to build web interfaces if desired.

Conclusion

PentestAgent represents a pragmatic architectural approach to AI-assisted offensive security: it does not replace human judgment but structures and accelerates the mechanical portions of black-box testing. Its 2,791 stars and active maintenance suggest the security community finds this balance useful.

The framework suits bug bounty hunters needing rapid reconnaissance across scopes, red-team operators requiring isolated tooling environments, and security engineers building programmatic validation pipelines. The MCP architecture positions it well for organizations investing in composable AI infrastructure, though adopters should budget for LLM API costs and operational complexity.

PentestAgent is not a silver bullet—no tool is—but it meaningfully reduces friction in workflows that remain stubbornly manual. For practitioners ready to experiment, the project awaits at https://github.com/GH05TCREW/PentestAgent. Start with the base Docker image, configure your provider, and run a playbook against an authorized target to evaluate fit for your workflow.