PentestAgent

AI 渗透测试

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

使用中继 / 自定义 API 基础地址

通过 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

在 Docker 容器内运行工具，以实现隔离并获取预装的渗透测试工具。

选项 1：拉取预构建镜像（最快）

# 包含 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

选项 2：本地构建

# 构建
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 中的命令访问：

TUI 命令

/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 客户端、对话历史和笔记存储——并且其完整工具集在生成后会被注入到父代理的可用工具中。

这使得无需任何外部编排即可实现分层多代理工作流：代理通过将其作用域内的子任务委托给按需生成的子代理来进行自组织。

在 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 侧边栏中显示为可折叠的终端面板，其工具将在下一次工具调用时对父代理可用。

示例：

/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 RAG 工具优化器

当 MCP 服务器暴露超过 128 个工具时，PentestAgent 会自动将完整目录替换为单个 mcp_<服务器>_rag_optimizer 工具。该元工具使用嵌入相似性（通过 LiteLLM，默认 text-embedding-3-small）检索与手头任务最相关的工具，并在代理的下一次轮次中将其注入——从而在保持上下文窗口可管理的同时，不会丢失对完整工具集的访问。

优化器对代理透明：它使用聚焦的自然语言查询（描述所需内容）调用 RAG 工具，匹配的工具将在下一次轮次中直接可用。

代理使用指南：

参数	类型	默认值	描述
`queries`	字符串数组	(必需)	每个所需能力一个聚焦查询。越具体，精度越高

嵌入在启动时计算一次并缓存，因此重复查询速度很快。优化器按服务器构建，因此每个拥有大目录的 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 标志：

示例：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`

任务控制

工具	描述
`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  task="枚举 example.com 的子域名"  target="example.com"
run_task_async  task="对 example.com 运行 nmap SYN 扫描"     target="example.com"

# 2. 阻塞直到两者完成（最多 5 分钟）
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. 检索完整结果
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

CLI 工具管理

pentestagent tools list         # 列出所有工具
pentestagent tools info <名称>  # 显示工具详情
pentestagent mcp list           # 列出 MCP 服务器
pentestagent mcp add <名称> <命令> [参数...]  # 添加 MCP 服务器
pentestagent mcp test <名称>    # 测试 MCP 连接

对话历史控制

TUI 中的每条用户消息都暴露两个内联操作按钮：回退和分叉。

回退

点击任意用户消息上的回退，将对话截断回该消息之前——同时更新 UI 和代理内存中的历史记录。用于从头重试查询，而不保存丢弃的路径。

分叉

点击任意用户消息上的 >> 分叉，从该点分支对话：

当前完整对话保存到对话存储，并显示一个简短快照 ID。
对话随后截断回所选消息之前（与回退相同）。

这样你可以从任意点尝试替代方法，同时通过 /conversations 保留原始线程以供检索。

对话历史

PentestAgent 自动持久化每个对话，以便你可以查看、比较和恢复过去的会话。

自动保存 在每个 /assist、/agent、/crew 和 /interact 任务之后以及 /clear 之前触发。最多保留 20 个对话；较旧的会自动修剪。

存储位置： 当工作区激活时，位于 workspaces/<active>/memory/conversations/，否则位于项目根目录的 conversations/。每个对话是一个 JSON 文件。

使用 /conversations 浏览和恢复：

/conversations 命令在 TUI 中打开一个分屏模态框：

左面板 — 已保存对话列表，带有标题和日期。
右面板 — 元数据预览以及前 5 条消息（用户消息为蓝色，代理响应为绿色，工具调用为黄色，工具结果为灰色）。计数显示还存在多少条额外消息。

选择一个对话并按恢复将其重新加载到当前会话中，或按关闭关闭模态框。

知识

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

Assist	`/assist <任务>`	一次性指令，执行工具
Agent	`/agent <任务>`	自主执行单个任务
Crew	`/crew <任务>`	多代理模式。编排器生成专用工作代理
Interact	`/interact <任务>`	交互模式。与代理聊天，它会在渗透测试过程中帮助你并指导

`target`	字符串	—	传递给子代理的渗透目标
`scope`	字符串数组	—	子代理的作用域目标/CIDR
`model`	字符串	环境变量	模型标识符，覆盖子代理上的 `PENTESTAGENT_MODEL`
`no_rag`	布尔值	`false`	跳过子代理上的 RAG 引擎初始化
`no_mcp`	布尔值	`true`	跳过子代理上的外部 MCP 服务器连接（推荐）

`target`	传递给子代理的渗透目标（位置参数或 `--target`）
`--scope CIDR`	一个或多个作用域 CIDR（可重复）
`--model MODEL`	覆盖子代理的模型
`--no-rag`	跳过子代理上的 RAG 引擎初始化
`--no-mcp`	跳过子代理上的外部 MCP 服务器连接

`--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 服务器连接

最受欢迎

pentestagent