https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975

系统要求

• Python 3.10+
• OpenAI、Anthropic 或其他 LiteLLM 支持的提供商的 API 密钥

安装

# 克隆
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 支持的模型 均可使用。

运行

pentestagent                    # 启动 TUI
pentestagent -t 192.168.1.1     # 指定目标后启动
pentestagent --docker           # 在 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

# Kali 镜像，包含 metasploit、sqlmap、hydra 等
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 <task>	单次执行指令，包含工具调用
代理	/agent <task>	自主执行单个任务。
团队	/crew <task>	多代理模式。协调者会派生出专门的工作者。
交互	/interact <task>	交互模式。与代理聊天，它会在渗透测试过程中提供帮助和指导

TUI 命令

/assist <task>    单次执行指令。
/agent <task>     自主代理执行任务
/crew <task>      多代理团队执行任务
/interact <task>  引导模式下与代理聊天
/target <host>    设置目标
/tools            列出可用工具
/notes            显示保存的笔记
/report           生成会话报告
/memory           显示令牌/内存使用情况
/prompt           显示系统提示词
/mcp <list/add>   可视化或添加新的 MCP 服务器。
/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	string	—	传递给子代理的渗透测试目标
scope	string[]	—	子代理的范围内目标/CIDR
model	string	环境变量	模型标识符，覆盖子代理上的 PENTESTAGENT_MODEL
no_rag	boolean	false	跳过子代理的 RAG 引擎初始化
no_mcp	boolean	true	跳过子代理的外部 MCP 服务器连接（推荐）

spawn_mcp_agent 返回后，子代理的工具（run_task、run_task_async、await_tasks 等）将在下一次调用工具时可用。子代理的名称会自动分配（例如 child_agent_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"]

# 第二轮：子代理的工具现已可用——异步委派工作
child_agent_1__run_task_async  task="全面端口扫描及服务枚举"
child_agent_2__run_task_async  task="全面端口扫描及服务枚举"

# 第三轮：等待并收集结果
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>"

MCP RAG 工具优化器

当 MCP 服务器暴露超过 128 个工具时，PentestAgent 会自动将完整目录替换为单个 mcp_<server>_rag_optimizer 工具。这个元工具利用嵌入相似度（通过 LiteLLM，默认使用 text-embedding-3-small）来检索与当前任务最相关的工具，并将其注入到智能体的下一轮对话中——从而在不丢失对完整工具集访问的情况下，保持上下文窗口的可控性。

优化器对智能体是透明的：它会用聚焦的自然语言查询来调用 RAG 工具，描述所需的内容，匹配的工具将在下一轮直接可供调用。

智能体使用指南：

参数	类型	默认值	描述
queries	字符串数组	(必填)	每个所需能力对应一个聚焦查询。越具体，准确性越高
top_k	整数	20	每个查询要检索的工具数量（最多 128 个）。结果会被合并并去重

嵌入向量在启动时计算一次并缓存，因此重复查询速度很快。优化器是按服务器构建的，因此每个拥有大型工具目录的 MCP 服务器都会有自己的独立索引。

提示： 每个独立的能力传递一个查询，而不是将所有内容合并成一个查询。例如，["列出主机上的开放端口", "获取进程内存占用"] 比 ["列出端口、内存和 CPU 使用情况"] 能得到更好的结果。

MCP 集成

PentestAgent 支持 MCP（模型上下文协议），可以从两个方向进行集成：消费外部 MCP 服务器作为工具源，以及暴露自身作为 MCP 服务器，以便外部客户端（Claude Desktop、Cursor 等）能够以编程方式驱动 PentestAgent。

---

消费外部 MCP 服务器（客户端模式）

通过配置 mcp_servers.json 文件，可以将 PentestAgent 连接到任何外部 MCP 服务器。示例配置如下：

{
  "mcpServers": {
    "nmap": {
      "command": "npx",
      "args": ["-y", "gc-nmap-mcp"],
      "env": {
        "NMAP_PATH": "/usr/bin/nmap"
      }
    }
  }
}

---

将 PentestAgent 暴露为 MCP 服务器（服务器模式）

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 标志：

标志	默认值	描述
--type	(必填)	传输方式：stdio 或 sse
--host	0.0.0.0	SSE 绑定主机
--port	8080	SSE 绑定端口
--target	无	主要渗透测试目标（IP 地址或主机名）
--scope	[]	在范围内的目标/CIDR（用空格分隔）
--model	环境变量	模型标识符，覆盖 PENTESTAGENT_MODEL
--docker	false	使用 DockerRuntime 而不是 LocalRuntime
--no-rag	false	跳过 RAG 引擎的初始化
--no-mcp	false	跳过与外部 MCP 服务器的连接

示例：Claude Desktop 配置（claude_desktop_config.json）

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

---

MCP 服务器工具参考

当作为 MCP 服务器运行时，PentestAgent 会暴露以下工具：

服务器状态与配置

工具	描述
get_server_status	实时服务器状态：就绪情况、按状态划分的任务数量、主要目标/范围、内存存储大小
get_config	主要智能体配置：目标、范围、最大迭代次数、工具列表
update_config	更新目标、范围或最大迭代次数，应用于后续所有任务

任务执行

工具	描述
run_task	提交任务并阻塞直至完成。返回完整结果、使用的工具及笔记快照
run_task_async	提交任务并立即返回一个 task_id。可通过 get_task_status 轮询

任务检查

工具	描述
list_tasks	列出所有任务及其状态、目标和摘要。可按状态筛选
get_task_status	轮询任务的当前状态和结果预览
get_task_result	完整任务结果：最终输出、思考步骤、所有工具调用及结果、笔记快照
await_tasks	阻塞直至一组异步任务 ID 全部完成（每 500 毫秒轮询，可配置超时时间）

任务控制

工具	描述
cancel_task	根据任务 ID 取消正在运行或待处理的任务

工具管理

工具	描述
list_tools	列出智能体可用的所有工具
enable_tool	在主智能体上启用指定工具
disable_tool	在主智能体上禁用指定工具

对话历史

工具	描述
get_conversation_history	返回某个任务或主智能体的消息历史。支持 limit 参数
reset_conversation	清除某个任务或主智能体的对话历史

内存

工具	描述
store_memory	将键值对持久化到进程内内存存储中
retrieve_memory	可按精确键检索、按子字符串搜索，或列出所有键
clear_memory	删除特定键，或使用 scope='all' 清空全部内存

可观测性

工具	描述
get_logs	返回最近的执行日志，可选择按级别过滤（info / warning / error）
get_metrics	运行时指标：任务数量、成功率、工具总调用次数、内存和日志大小

---

异步任务工作流示例

对于长时间运行的侦察任务，可以使用异步模式：

# 1. 提交任务而不阻塞
run_task_async  任务="枚举 example.com 的子域名"  目标="example.com"
run_task_async  任务="对 example.com 执行 nmap SYN 扫描"     目标="example.com"

# 2. 阻塞直至两者完成（最长 5 分钟）
await_tasks  任务 IDs=["<id1>", "<id2>"]  超时时间=300 秒

# 3. 获取完整结果
get_task_result  任务 ID="<id1>"
get_task_result  任务 ID="<id2>"

---

CLI 工具管理

pentestagent tools list         # 列出所有工具
pentestagent tools info <name>  # 显示工具详情
pentestagent mcp list           # 列出 MCP 服务器
pentestagent mcp add <name> <command> [args...]  # 添加 MCP 服务器
pentestagent mcp test <name>    # 测试 MCP 连接

知识库

• RAG： 将方法论、CVE 漏洞或字典文件放置在 pentestagent/knowledge/sources/ 目录下，以实现上下文的自动注入。
• 笔记： 代理会将发现结果保存到 loot/notes.json 文件中，并按类别（credential、vulnerability、finding、artifact）进行分类。这些笔记会在会话之间持久化，并被注入到代理的上下文中。
• 影子图谱： 在 Crew 模式下，编排器会根据笔记构建知识图谱，从而得出战略性的洞察（例如：“我们已获取主机 X 的凭据”）。

项目结构

pentestagent/
  agents/         # 代理实现
  config/         # 配置和常量
  interface/      # TUI 和 CLI 界面
  knowledge/      # RAG 系统和影子图谱
  llm/            # LiteLLM 封装
  mcp/            # MCP 客户端和服务器配置
  playbooks/      # 攻击剧本
  runtime/        # 执行环境
  tools/          # 内置工具

开发

pip install -e ".[dev]"
pytest                       # 运行测试
pytest --cov=pentestagent    # 带覆盖率
black pentestagent           # 格式化代码
ruff check pentestagent      # 代码检查

法律声明

仅可在获得明确授权的情况下对目标系统进行测试。未经授权的访问属违法行为。

许可证

MIT

PentestAgent 快速上手指南

PentestAgent 是一款基于 AI 的自动化渗透测试工具，支持自主执行任务、多智能体协作及与各类渗透测试工具集成。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.10 或更高版本
• API 密钥：需拥有 OpenAI、Anthropic 或其他 LiteLLM 支持的服务商 API Key
• 可选依赖：若需使用浏览器工具，需安装 Chromium（安装脚本会自动处理）；若需使用 Docker 模式，请确保已安装并运行 Docker。

安装步骤

1. 克隆项目

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

2. 设置环境

推荐使用官方提供的脚本自动创建虚拟环境并安装依赖：

Windows:

.\scripts\setup.ps1

Linux / macOS:

./scripts/setup.sh

手动安装方式（如果脚本执行失败）：

python -m venv venv
# Windows 激活
.\venv\Scripts\Activate.ps1
# Linux/macOS 激活
source venv/bin/activate
pip install -e ".[all]"
playwright install chromium

基本使用

1. 配置 API 密钥

在项目根目录创建 .env 文件，填入您的模型提供商密钥和模型名称。

使用 Anthropic (推荐):

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

使用 OpenAI:

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

注：支持任何 LiteLLM 兼容的模型。

2. 启动工具

安装完成后，您可以通过以下命令启动交互式终端界面 (TUI)：

直接启动：

pentestagent

指定目标启动：

pentestagent -t 192.168.1.1

在 Docker 容器中运行（隔离环境，预装 nmap, metasploit 等工具）：

pentestagent --docker

3. 执行任务

进入 TUI 界面后，您可以使用斜杠命令与 AI 交互。以下是常用模式：

• 辅助模式 (/assist)：单次指令执行，适合简单任务。

  /assist 对目标进行端口扫描
  

• 代理模式 (/agent)：自主执行单个复杂任务。

  /agent 查找目标系统的 SQL 注入漏洞
  

• 团队模式 (/crew)：多智能体协作，由协调者分配任务给专业子代理。

  /crew 对目标进行全面的安全评估
  

• 交互模式 (/interact)：引导式聊天，AI 逐步指导您进行操作。

  /interact 帮我分析当前的网络服务
  

其他实用命令：

• /target <host>：设置或更改测试目标
• /report：生成当前会话的报告
• /quit 或 Ctrl+Q：退出程序
• Esc：停止正在运行的代理

4. 运行预设剧本 (Playbooks)

PentestAgent 内置了针对黑盒测试的攻击剧本。例如，运行 Web 测试剧本：

pentestagent run -t example.com --playbook thp3_web