GH05TCREW/pentestagent: AI Agent Framework for Black-Box Security Testing

Security teams and independent researchers face a persistent bottleneck: the gap between automated scanning tools and the creative, context-aware reasoning required for effective penetration testing. Traditional scanners miss business-logic flaws, while manual testing doesn't scale. GH05TCREW/pentestagent enters this space as an open-source AI agent framework designed specifically for black-box security testing—supporting bug bounty programs, red-team operations, and structured penetration testing workflows with an architecture that emphasizes extensibility over black-box magic.

What is GH05TCREW/pentestagent?

GH05TCREW/pentestagent is an AI-powered penetration testing framework built in Python^{↗ Bright Coding Blog} and released under the MIT License. With 2,783 GitHub stars and 555 forks as of its last commit on July 7, 2026, it has gained meaningful traction within the security tooling community. The project is maintained by GH05TCREW and positions itself at the intersection of large language model capabilities and practical offensive security workflows.

The framework operates as a Model Context Protocol (MCP) compatible system, meaning it can both consume external MCP servers as tool sources and expose itself as an MCP server for integration with clients like Claude Desktop or Cursor. This dual-direction MCP support is architecturally significant—it prevents vendor lock-in and allows pentestagent to slot into existing toolchains rather than forcing wholesale migration.

PentestAgent's core abstraction is the agent loop: an LLM-driven reasoning cycle that can execute terminal commands, control a browser via Playwright, search the web, take notes, and spawn child agents for parallel work. The framework supports multiple LLM providers through LiteLLM, including OpenAI, Anthropic, and any OpenAI-compatible endpoint—critical for teams with existing API contracts or privacy requirements that mandate self-hosted models.

The project ships with pre-built attack playbooks for structured black-box assessments, a RAG (Retrieval-Augmented Generation) system for methodology injection, and a shadow graph in multi-agent mode that derives strategic insights from accumulated findings. These aren't marketing features; they're concrete subsystems documented in the codebase with specific configuration paths and behavioral contracts.

Key Features

Multi-Modal Agent Execution PentestAgent provides four distinct operational modes accessible through its TUI: /assist for single-shot instructions with tool execution, /agent for autonomous single-task execution, /crew for multi-agent orchestration with specialized worker agents, and /interact for guided conversational pentesting. This granularity matters—bug bounty hunters need different interaction patterns than red-team operators running overnight campaigns.

Hierarchical Multi-Agent Spawning The spawn_mcp_agent tool enables a running agent to create isolated child copies of itself as subordinate MCP servers. Each child maintains independent runtime, LLM client, conversation history, and notes store. The parent's tool set expands dynamically after spawning, enabling delegation patterns like parallel reconnaissance across network segments without external orchestration infrastructure.

MCP RAG Tool Optimizer When an MCP server exposes more than 128 tools, PentestAgent automatically substitutes the full catalogue with an embedding-based retrieval layer. Using LiteLLM's embedding capabilities (defaulting to text-embedding-3-small), the system retrieves relevant tools per-query and injects them into the next turn. This prevents context window exhaustion while preserving access to large tool ecosystems—essential when integrating comprehensive security tool suites.

Docker^{↗ Bright Coding Blog}-Isolated Execution Environments The framework provides pre-built container images (ghcr.io/gh05tcrew/pentestagent:latest for base tools, :kali for extended arsenal including Metasploit, sqlmap, and hydra) alongside Docker Compose configurations. The --docker flag routes tool execution through containerized runtimes, reducing host contamination risks during active testing.

Conversation History with Branching Every TUI interaction supports rewind and fork operations. Rewind truncates history to retry from a specific point; fork saves the current conversation before branching, enabling systematic exploration of alternative attack paths. Conversations auto-save to workspace-scoped or project-root storage, with a 20-conversation retention policy.

Use Cases

Bug Bounty Reconnaissance at Scale A researcher targeting a wide scope can deploy /crew mode with multiple child agents, each scoped to a subdomain or IP range. The orchestrator's shadow graph correlates findings across workers—identifying credential reuse, service version clustering, or trust relationship patterns that isolated scans would miss. The RAG system injects methodology documents (like custom recon checklists) into agent context automatically.

Red-Team Infrastructure Assessment Teams conducting authorized adversary simulation benefit from the Docker isolation and async task patterns. Long-running operations—comprehensive port sweeps, slow directory bruteforcing, or web application crawling—submit via run_task_async and poll completion without blocking the operator's control channel. The notes system's categorical storage (credential, vulnerability, finding, artifact) structures loot for reporting pipelines.

Security Assessment Standardization Organizations building repeatable assessment capabilities use the playbook system to encode specific testing procedures. Running pentestagent run -t example.com --playbook thp3_web executes a structured web assessment with consistent coverage, reducing variability between assessors while preserving the LLM's ability to adapt to target-specific behaviors.

MCP Ecosystem Integration Teams already invested in MCP-compatible tools (custom internal scanners, proprietary data sources) connect them via mcp_servers.json configuration. Conversely, exposing PentestAgent as an MCP server allows security orchestration platforms to submit tasks programmatically—useful for CI/CD security gates or scheduled assessment workflows.

Installation & Setup

PentestAgent requires Python 3.10+ and an API key for an LLM provider supported by LiteLLM.

Quick Start with Setup Scripts

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

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

The setup scripts handle virtual environment creation and dependency installation. For manual control:

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

The playwright install chromium step is mandatory—the browser tool depends on Playwright's Chromium browser for web application interaction.

Configuration

Create .env in the project root:

# Anthropic configuration
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 provider works. For custom endpoints:

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

The .env.example file contains full provider notes and embedding configuration options.

Docker Deployment

# Pre-built 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 extended toolset
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  ghcr.io/gh05tcrew/pentestagent:kali

Local builds use Docker Compose:

docker compose build
docker compose run --rm pentestagent

# Kali variant
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali

Real Code Examples

Example 1: Running a Structured Playbook

The playbook system encodes repeatable assessment procedures:

pentestagent run -t example.com --playbook thp3_web

This executes the thp3_web playbook against example.com. Playbooks define structured approaches to specific assessment types—this particular playbook targets web application security following a methodology that the framework injects into agent context. The agent maintains state across playbook stages, accumulating notes that feed into final report generation.

Example 2: Hierarchical Multi-Agent Reconnaissance

This pattern demonstrates the spawn_mcp_agent tool for parallel network reconnaissance:

# Turn 1: Spawn isolated child agents for parallel network segments
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: Delegate work asynchronously through child-specific tools
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 results
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 call creates fully isolated children—their no_mcp=true default prevents recursive complexity. Children's tools surface as child_agent_N__<tool_name> namespaced functions. The async pattern prevents blocking during long-running operations, with await_tasks providing synchronization.

Example 3: MCP Server Mode for External Integration

Expose PentestAgent as an MCP server for programmatic access:

# STDIO transport for local clients (Claude Desktop, Cursor)
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24

# SSE transport for remote/networked clients
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080

The SSE transport exposes a single /mcp endpoint supporting POST (requests), GET (persistent SSE stream), and DELETE (session teardown). Session tracking uses the Mcp-Session-Id header. This enables external orchestration systems to submit tasks, inspect status, and retrieve results without direct TUI interaction.

Example 4: Async Task Workflow via MCP Tools

For long-running operations through the MCP interface:

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

# Block until completion (configurable timeout)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# Retrieve full results with tool call chains
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

The get_task_result tool returns complete execution traces—including thinking steps, all tool calls and raw results, and notes snapshots—enabling thorough post-hoc analysis without re-running expensive operations.

Advanced Usage & Best Practices

Workspace Organization for Multi-Client Operations PentestAgent uses workspace-scoped paths for conversations (workspaces/<active>/memory/conversations/) and notes (loot/notes.json). For consultants or internal teams managing multiple concurrent assessments, explicit workspace switching prevents cross-contamination of findings and maintains clean audit trails.

RAG Source Curation The pentestagent/knowledge/sources/ directory accepts methodologies, CVE descriptions, and wordlists for automatic context injection. Quality here directly impacts agent reasoning—outdated or overly generic sources dilute context window efficiency. Teams should maintain client-specific methodology documents and purge stale entries.

Embedding Cost Management The MCP RAG Tool Optimizer computes embeddings at startup and caches results. However, large tool catalogues still incur initial embedding API costs. For budget-conscious operations, pre-filter MCP server tool manifests to essential capabilities rather than connecting maximalist tool suites.

Child Agent Lifecycle Hygiene Child agents persist until explicitly terminated via /despawn <server_name> or parent shutdown. In long-running crew sessions, despawn completed workers promptly to free process resources. Use /mcp list to audit active children.

Model Selection for Task Types The framework supports per-child model overrides via --model flags. Consider cheaper/faster models for deterministic reconnaissance tasks (port scanning, subdomain enumeration) while reserving capable reasoning models for vulnerability analysis and exploitation planning. The LiteLLM abstraction makes this cost optimization straightforward.

Comparison with Alternatives

PentestAgent doesn't replace these tools—it orchestrates them. The MCP client mode can surface Nuclei as an MCP server, Metasploit via terminal tool invocation, or Burp extensions through custom integrations. Its value proposition is reasoning and coordination rather than raw scanning throughput.

FAQ

What LLM providers work with PentestAgent? Any provider supported by LiteLLM, including OpenAI, Anthropic, and custom OpenAI-compatible endpoints. See .env.example for configuration patterns.

Is Docker required? No—local execution via Python virtual environment works. Docker provides tool isolation and pre-installed security tooling for convenience.

What's the license? MIT License, permitting commercial and private use with attribution.

How does the MCP RAG optimizer handle tool privacy? Tool names and descriptions are embedded locally; only embedding API calls (if using cloud embeddings) transmit data. Self-hosted embedding endpoints eliminate this concern.

Can I use my own attack methodologies? Yes—place documents in pentestagent/knowledge/sources/ for automatic RAG injection into agent context.

What's the conversation retention limit? 20 conversations auto-saved; older sessions are pruned. Critical sessions should be exported manually.

Does it work on Apple Silicon? Python 3.10+ and Playwright support Apple Silicon. Docker images should use platform-appropriate manifests.

Conclusion

GH05TCREW/pentestagent represents a pragmatic architectural approach to AI-assisted penetration testing—emphasizing composability through MCP, operational safety through Docker isolation, and scalability through hierarchical multi-agent patterns. It's best suited for security practitioners who need LLM reasoning integrated with existing toolchains rather than replaced by them: bug bounty hunters managing wide scopes, red teams requiring auditable async operations, and security engineers building repeatable assessment pipelines.

The framework's 2,783 stars and active development suggest growing community validation, though users should expect the rough edges typical of evolving open-source security tools. The MIT license removes commercial friction for evaluation.

Ready to explore? Clone the repository, configure your LLM provider, and run your first playbook: https://github.com/GH05TCREW/pentestagent