用于黑盒安全测试的AI代理框架，具备自主多代理编排、内置渗透测试工具以及MCP集成，适用于漏洞赏金、红队和渗透测试工作流程。
https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975
# 克隆
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent
# 设置（创建虚拟环境，安装依赖）
.\scripts\setup.ps1 # Windows
./scripts/setup.sh # Linux/macOS
# 或手动安装
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
source venv/bin/activate # Linux/macOS
pip install -e ".[all]"
playwright install chromium # 浏览器工具所需
在项目根目录创建 .env 文件：
ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514
或对于 OpenAI：
OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5
任何 LiteLLM 支持的模型 均可使用。
通过 OPENAI_API_BASE 将 PentestAgent 指向任何兼容 OpenAI 的端点：
OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<模型名称（在你的中继上）>
对于兼容 Anthropic 的端点，请改用 ANTHROPIC_API_BASE。
有关完整的提供商说明和嵌入选项，请参阅 .env.example。
pentestagent # 启动 TUI
pentestagent -t 192.168.1.1 # 启动并指定目标
pentestagent tui --docker # 在 Docker 容器中运行工具
在 Docker 容器内运行工具，以实现隔离并获取预装的渗透测试工具。
# 包含 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
# 包含 metasploit、sqlmap、hydra 等的 Kali 镜像
docker run -it --rm \
-e ANTHROPIC_API_KEY=your-key \
ghcr.io/gh05tcrew/pentestagent:kali
# 构建
docker compose build
# 运行
docker compose run --rm pentestagent
# 或使用 Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali
容器运行 PentestAgent，并可以访问 Linux 渗透测试工具。代理可以通过终端工具直接使用 nmap、msfconsole、sqlmap 等。
需要安装并运行 Docker。
PentestAgent 有三种模式，可通过 TUI 中的命令访问：
| 模式 | 命令 | 描述 |
|---|---|---|
| Assist | /assist <任务> | 一次性指令，执行工具 |
| Agent | /agent <任务> | 自主执行单个任务 |
| Crew | /crew <任务> | 多代理模式。编排器生成专用工作代理 |
| Interact | /interact <任务> | 交互模式。与代理聊天，它会在渗透测试过程中帮助你并指导 |
/assist <任务> 一次性指令。
/agent <任务> 运行自主代理执行任务
/crew <任务> 运行多代理团队执行任务
/interact <任务> 在引导模式下与代理聊天
/target <主机> 设置目标
/tools 列出可用工具
/notes 显示已保存的笔记
/report 从会话生成报告
/memory 显示令牌/内存使用情况
/prompt 显示系统提示
/conversations 浏览和恢复已保存的对话
/mcp <list/add> 可视化或添加新的 MCP 服务器。
/spawn [目标] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
从 TUI 手动生成一个子 MCP 代理。
/despawn <服务器名称>
终止并移除先前生成的子代理。
/clear 清除聊天记录和历史
/quit 退出（也可用 /exit, /q）
/help 显示帮助（也可用 /h, /?）
按 Esc 停止正在运行的代理。按 Ctrl+Q 退出。
PentestAgent 包含预构建的攻击剧本，用于黑盒安全测试。剧本定义了针对特定安全评估的结构化方法。
运行剧本：
pentestagent run -t example.com --playbook thp3_web
PentestAgent 包含内置工具，并支持 MCP（模型上下文协议）以实现可扩展性。
内置工具： terminal, browser, notes, web_search（需要 TAVILY_API_KEY），spawn_mcp_agent
spawn_mcp_agent)spawn_mcp_agent 是一个内置工具，允许正在运行的代理生成自身的一个子副本，作为通过 stdio 连接的从属 MCP 服务器。子进程完全隔离——拥有自己的运行时、LLM 客户端、对话历史和笔记存储——并且其完整工具集在生成后会被注入到父代理的可用工具中。
这使得无需任何外部编排即可实现分层多代理工作流：代理通过将其作用域内的子任务委托给按需生成的子代理来进行自组织。
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
target | 字符串 | — | 传递给子代理的渗透目标 |
scope | 字符串数组 | — | 子代理的作用域目标/CIDR |
model | 字符串 | 环境变量 | 模型标识符，覆盖子代理上的 PENTESTAGENT_MODEL |
no_rag | 布尔值 | false | 跳过子代理上的 RAG 引擎初始化 |
no_mcp | 布尔值 | true | 跳过子代理上的外部 MCP 服务器连接（推荐） |
在 spawn_mcp_agent 返回后，子代理的工具（run_task、run_task_async、await_tasks 等）将在下一次工具调用时可用。子代理的服务器名称会自动分配（例如 child_agent_1）并在结果中返回。
示例——编排器将并行侦察委托给两个子代理：
# 第1步：生成两个隔离的子代理
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"]
# 第2步：子代理的工具现已可用——异步分配工作
child_agent_1__run_task_async task="完整端口扫描和服务枚举"
child_agent_2__run_task_async task="完整端口扫描和服务枚举"
# 第3步：等待并收集
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>"
/spawn 和 /despawn）除了自动的 spawn_mcp_agent 工具外，TUI 还提供了两个命令，允许你手动生成和终止子代理，独立于正在运行的代理循环。
/spawn/spawn [目标] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]
通过 stdio 生成一个新的子 MCP 代理，并将其附加到当前会话。子代理在 TUI 侧边栏中显示为可折叠的终端面板，其工具将在下一次工具调用时对父代理可用。
| 参数 | 描述 |
|---|---|
target | 传递给子代理的渗透目标（位置参数或 --target） |
--scope CIDR | 一个或多个作用域 CIDR（可重复） |
--model MODEL | 覆盖子代理的模型 |
--no-rag | 跳过子代理上的 RAG 引擎初始化 |
--no-mcp | 跳过子代理上的外部 MCP 服务器连接 |
示例：
/spawn 10.0.1.1
/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag
/despawn/despawn <服务器名称>
终止由 server_name（例如 child_agent_1）标识的子代理，从 TUI 中移除其终端面板，并从父会话中断开其工具。使用 /mcp list 查看所有当前活动的子代理名称。
示例：
/despawn child_agent_1
当 MCP 服务器暴露超过 128 个工具时，PentestAgent 会自动将完整目录替换为单个 mcp_<服务器>_rag_optimizer 工具。该元工具使用嵌入相似性（通过 LiteLLM，默认 text-embedding-3-small）检索与手头任务最相关的工具，并在代理的下一次轮次中将其注入——从而在保持上下文窗口可管理的同时，不会丢失对完整工具集的访问。
优化器对代理透明：它使用聚焦的自然语言查询（描述所需内容）调用 RAG 工具，匹配的工具将在下一次轮次中直接可用。
代理使用指南：
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
queries | 字符串数组 | (必需) | 每个所需能力一个聚焦查询。越具体，精度越高 |
top_k | 整数 | 20 | 每个查询检索的工具数（最大 128）。结果合并并去重 |
嵌入在启动时计算一次并缓存，因此重复查询速度很快。优化器按服务器构建，因此每个拥有大目录的 MCP 服务器都有自己独立的索引。
提示： 每个不同能力传递一个查询，而不是将所有内容合并到一个查询中。
["列出主机上的开放端口", "获取进程内存使用情况"]比["列出端口、内存和 CPU"]获得更好的结果。
PentestAgent 支持双向 MCP（模型上下文协议）：消费外部 MCP 服务器作为工具源，以及将自身暴露为 MCP 服务器，以便外部客户端（Claude Desktop、Cursor 等）可以程序化地驱动 PentestAgent。
配置 mcp_servers.json 以将 PentestAgent 连接到任何外部 MCP 服务器。示例配置：
{
"mcpServers": {
"nmap": {
"command": "npx",
"args": ["-y", "gc-nmap-mcp"],
"env": {
"NMAP_PATH": "/usr/bin/nmap"
}
}
}
}
PentestAgent 可以作为 MCP 服务器运行，允许任何兼容 MCP 的客户端提交任务、检查结果并远程控制代理。支持两种传输方式：
STDIO — 用于本地客户端（例如 Claude Desktop、Cursor）：
pentestagent mcp_server --type stdio
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24
pentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker
SSE（HTTP） — 用于远程或网络客户端：
pentestagent mcp_server --type sse
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080
pentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0/24 --docker
SSE 传输暴露一个 /mcp 端点，支持 POST（请求）、GET（持久 SSE 流，用于服务器主动推送）和 DELETE（会话拆除）。会话通过 Mcp-Session-Id 头跟踪。
所有 mcp_server 标志：