pentestagent - PentestAgent是black-bo的AI代理框架

项目说明

<di="center">

<img src="assets/pentestagent-logo.png" alt="PentestAgent Logo" width="220" style="margin-bottom: 20px;"/>

PentestAgent

AI Penetration Testing

<a href=" target="_blank" rel="noopener noreferrer"><img src=" alt="GH05TCREW%2Fpentestagent | Trendshift" width="250" height="55"/></a>

![Python]()  ![]() ![Security]() ![MCP]()

</div>

Requirements

Install

Configure

Create .env in the project root:

Or for OpenAI:

Any LiteLLM-supported model works.

Using a relay / custom API base

Point PentestAgent at any OpenAI-compatible endpoint via OPENAI_API_BASE:

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

Run

Docker

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

Option 1: Pull pre-built image (fastest)

Option 2: Build locally

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 in the TUI:

| Mode | Command | Description |
|------|---------|-------------|
| Assist | /assist <task> | One single-shot instruction, with 工具 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:

!Playbook Demo

Tools

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

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

Agent Self-Spawning (spawn_mcp_agent)

spawn_mcp_agent is a built-in 工具 that allows a running agent to spawn a child copy of itself as a subordinate MCP ser o. The child process is fully isolated — its own runtime, LLM 客户端, con history, and notes store — and its complete 工具 set is injected back into the parent agent's a 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, o PENTESTAGENT_MODEL on the child |
| no_rag | boolean | false | Skip RAG 引擎 initialisation on the child |
| no_mcp | boolean | true | Skip external MCP ser on the child (recommended) |

After spawn_mcp_agent returns, the child's tools (run_task, run_task_async, await_tasks, etc.) are a on the next 工具 call. The child's 服务端 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 工具, the TUI exposes two commands that let you spawn and terminate child agents manually, independently of a running agent loop.

#### /spawn

Spawns a new child MCP agent o and attaches it to the current session. The child appears as a collapsible terminal panel in the TUI sidebar and its tools become a to the parent agent on the next 工具 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 | O the model for the child agent |
| --no-rag | Skip RAG 引擎 initialisation on the child |
| --no-mcp | Skip external MCP ser on the child |

Examples:

#### /despawn

Terminates the child agent identified by ser (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 acti agents.

Example:

MCP RAG Tool Optimizer

When an MCP ser more than 128 tools, PentestAgent automatically replaces the full catalogue with a single mcp_<server>_rag_optimizer 工具. This meta-工具 uses embedding similarity (, 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 工具 set.

The optimizer is transparent to the agent: it calls the RAG 工具 with focused natural-language queries describing what it needs, and the matching tools become a 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-服务端, so each MCP 服务端 with a large catalogue gets its own independent index.

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

MCP Integration

PentestAgent supports MCP (Model Context 协议) in two directions: consuming external MCP servers as 工具 sources, and exposing itself as an MCP 服务端 so external clients (Claude Desktop, Cursor, etc.) can dri programmatically.

---

#### Consuming External MCP Servers (客户端 Mode)

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

---

#### Exposing PentestAgent as an MCP 服务端 (服务端 Mode)

PentestAgent can run as an MCP 服务端, allowing any MCP-compatible 客户端 to submit tasks, inspect results, and control the agent remotely. Two transports are supported:

STDIO — for local clients (e.g. Claude Desktop, Cursor):

SSE (HTTP) — for remote or networked clients:

The SSE transport exposes a single /mcp endpoint supporting POST (requests), GET (persistent SSE stream for ser 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, o PENTESTAGENT_MODEL |
| --docker | false | Use DockerRuntime instead of LocalRuntime |
| --no-rag | false | Skip RAG engine initialisation |
| --no-mcp | false | Skip external MCP ser |

##### Example: Claude Desktop config (claude_desktop_config.json)

---

#### MCP Ser Reference

When acting as an MCP 服务端, PentestAgent exposes the following tools:

Ser & Config

| Tool | Description |
|------|-------------|
| get_ser | Li status: readiness, task counts by state, primary target/scope, memory store size |
| get_config | Primary agent configuration: target, scope, max iterations, 工具 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 工具 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 a to the agent |
| enable_tool | Enable a named 工具 on the primary agent |
| disable_tool | Disable a named 工具 on the primary agent |

Con History

| Tool | Description |
|------|-------------|
| get_con | Return message history for a task or the primary agent. Supports a limit parameter |
| reset_con | Clear con history for a task or the primary agent |

Memory

| Tool | Description |
|------|-------------|
| store_memory | Persist a key-value pair to the in-process memory store |
| retrie | Retrieve by exact key, search by substring, or list all keys |
| clear_memory | Delete a specific key or wipe all memory with scope='all' |

Obser

| Tool | Description |
|------|-------------|
| get_logs | Return recent execution logs, optionally filtered by level (info / warning / error) |
| get_metrics | Runtime metrics: task counts, success rate, total 工具 calls, memory and log sizes |

---

#### Async Task Workflow Example

For long-running recon tasks, use the async pattern:

---

CLI Tool Management

Con History Controls

Each user message in the TUI exposes two inline action buttons: rewind and fork.

Rewind

Click rewind on any user message to truncate the con back to just before that message — both in the UI and in the agent's in-memory history. Use it to retry a query from scratch without saving the discarded path.

Fork

Click >> fork on any user message to branch the con from that point:

1. The current full con is saved to the con store and a short snapshot ID is shown.
2. The con is then truncated to just before the selected message (same as rewind).

This lets you try an alternati from any point while keeping the original thread retrievable via /con.

---

Con History

PentestAgent automatically persists every con so you can review, compare, and restore past sessions.

Auto-save triggers after each /assist, /agent, /crew, and /interact task, and before /clear. Up to 20 con are kept; older ones are pruned automatically.

Storage location: workspaces/<active>/memory/con/ when a workspace is active, or con/ at the project root otherwise. Each con is a JSON file.

Browse & restore with /con:

The /con command opens a split-pane modal inside the TUI:

<img width="1657" height="662" alt="imagen" src=" />

Select a con and press Restore to reload it into the current session, or Close to dismiss the modal.

Knowledge

Project Structure

De

Legal

Only use against systems you ha authorization to test. Unauthorized access is illegal.

License

MIT

项目信息

开发语言：Python

Star 数：3143

技术要点

该项目属于黑客技术方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕PentestAgent is an AI agent 框架 for black-box security testing, supporting bug bounty, red-team, and penetration testing workflows.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。