# PentestAgent

> An open-source AI agent framework for black-box penetration testing, supporting autonomous multi-agent workflows, MCP integration, and built-in security tools.

PentestAgent is an open-source Python framework built by GH05TCREW that brings AI-driven automation to black-box security testing, bug bounty, red-team, and penetration testing workflows. Released under the MIT license and hosted on GitHub, it reached version 0.2.0 with active development continuing through mid-2026. The project supports multiple LLM backends via LiteLLM, including OpenAI, Anthropic, and any OpenAI-compatible relay endpoint.

## What It Is

PentestAgent is a CLI/TUI-based AI agent framework that orchestrates LLM-powered agents to perform security assessments autonomously. It wraps common pentesting tools — nmap, metasploit, sqlmap, hydra, and others — behind an agent loop that can plan, execute, and report on findings without constant human input. The framework is designed for security professionals who want to automate repetitive recon and exploitation workflows while retaining full control over scope and targets.

## Modes and Workflow

The TUI exposes four distinct operating modes:

- **Assist** (`/assist`) — single-shot instruction with tool execution
- **Agent** (`/agent`) — autonomous execution of a scoped task
- **Crew** (`/crew`) — multi-agent mode where an orchestrator spawns specialized worker agents
- **Interact** (`/interact`) — guided conversational mode for step-by-step pentesting

Users set a target with `/target`, run playbooks via `pentestagent run -t example.com --playbook thp3_web`, and generate reports with `/report`. Conversation history is auto-saved and browsable via `/conversations`, with rewind and fork controls for branching sessions.

## Multi-Agent Architecture

A standout feature is the `spawn_mcp_agent` built-in tool, which allows a running agent to spawn isolated child copies of itself as subordinate MCP servers connected over stdio. Each child has its own runtime, LLM client, conversation history, and notes store. The parent agent can delegate scoped subtasks to children in parallel — for example, running simultaneous port scans across multiple subnets — and collect results asynchronously using `run_task_async` and `await_tasks`. This enables hierarchical multi-agent workflows without external orchestration infrastructure.

## MCP Integration

PentestAgent supports the Model Context Protocol (MCP) in both directions. As a **client**, it connects to external MCP servers (configured via `mcp_servers.json`) to pull in additional tools. As a **server**, it exposes itself over STDIO or SSE transports so external MCP clients — Claude Desktop, Cursor, and others — can submit tasks, inspect results, and control the agent remotely. When an MCP server exposes more than 128 tools, a built-in RAG optimizer automatically replaces the full catalogue with an embedding-based retrieval tool, keeping context windows manageable.

## Knowledge and Memory System

The framework includes a RAG engine that ingests methodologies, CVEs, and wordlists from `pentestagent/knowledge/sources/` for automatic context injection. Agents persist findings to `loot/notes.json` with structured categories (credential, vulnerability, finding, artifact), and notes survive across sessions. In Crew mode, an orchestrator builds a Shadow Graph — a knowledge graph derived from notes — to surface strategic insights such as credential reuse across hosts.

## Deployment Options

PentestAgent runs locally or inside Docker for tool isolation. Two pre-built images are available via GitHub Container Registry: a base image with nmap, netcat, and curl, and a Kali image with metasploit, sqlmap, hydra, and the full Kali toolset. The `--docker` flag routes all terminal tool calls through the container runtime, keeping the host system clean while giving the agent access to a complete pentesting environment.

## Features
- AI-driven autonomous penetration testing
- Multi-agent Crew mode with orchestrator and worker agents
- Agent self-spawning via spawn_mcp_agent tool
- MCP client and server support (STDIO and SSE transports)
- Built-in TUI with rewind and fork conversation controls
- Prebuilt attack playbooks for black-box security testing
- RAG engine for knowledge injection (CVEs, methodologies, wordlists)
- Shadow Graph knowledge graph in Crew mode
- Docker runtime with base and Kali images
- LiteLLM support for OpenAI, Anthropic, and custom relay endpoints
- Built-in tools: terminal, browser, notes, web_search, spawn_mcp_agent
- MCP RAG Tool Optimizer for large tool catalogues
- Async task execution with await_tasks
- Conversation history auto-save with browse and restore
- Report generation from session notes

## Integrations
OpenAI, Anthropic, LiteLLM, Claude Desktop, Cursor, nmap, Metasploit, sqlmap, Hydra, Tavily (web search), Docker, MCP servers (via mcp_servers.json)

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
0.2.0

## Links
- Website: https://github.com/GH05TCREW/pentestagent
- Documentation: https://github.com/GH05TCREW/pentestagent/blob/main/README.md
- Repository: https://github.com/GH05TCREW/pentestagent
- EveryDev.ai: https://www.everydev.ai/tools/pentestagent