GHOSTCREW

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

要求

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

安装

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

# Setup (creates venv, installs deps)
.\scripts\setup.ps1   # Windows
./scripts/setup.sh    # Linux/macOS

# Or manual
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate     # Linux/macOS
pip install -e ".[all]"
playwright install chromium  # Required for browser tool

配置

在项目根目录中创建 .env：

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

或者使用 OpenAI：

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

任何 LiteLLM 支持的模型 均可使用。

使用中继／自定义 API 基础 URL

通过 OPENAI_API_BASE 将 PentestAgent 指向任意兼容 OpenAI 的端点：

OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>

对于兼容 Anthropic 的端点，请改用 ANTHROPIC_API_BASE。 完整的提供商说明和嵌入选项请参阅 .env.example。

运行

pentestagent                      # Launch TUI
pentestagent -t 192.168.1.1       # Launch with target
pentestagent tui --docker         # Run tools in Docker container

Docker

在 Docker 容器中运行工具，以实现隔离并使用预装的渗透测试工具。

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

# Base image with 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 image with metasploit, sqlmap, hydra, etc.
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  ghcr.io/gh05tcrew/pentestagent:kali

选项 2：本地构建

# Build
docker compose build

# Run
docker compose run --rm pentestagent

# Or with Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali

容器运行 PentestAgent，并可访问 Linux 渗透测试工具。Agent 可以直接通过终端工具使用 nmap、msfconsole、sqlmap 等工具。

需要安装并运行 Docker。

模式

PentestAgent 提供三种模式，可通过 TUI 中的命令访问：

模式	命令	说明
辅助	/assist <task>	一次性执行单条指令，并运行工具
Agent	/agent <task>	自主执行单项任务
Crew	/crew <task>	多 Agent 模式。协调器会启动专门的工作 Agent
交互	/interact <task>	交互模式。与 Agent 聊天；它会在渗透测试过程中为你提供帮助和指导

TUI 命令

/assist <task>    One single-shot instruction.
/agent <task>     Run autonomous agent on task
/crew <task>      Run multi-agent crew on task
/interact <task>  Chat with the agent in guided mode
/target <host>    Set target
/tools            List available tools
/notes            Show saved notes
/report           Generate report from session
/memory           Show token/memory usage
/prompt           Show system prompt
/conversations    Browse and restore saved conversations
/mcp <list/add>   Visualizes or adds a new MCP server.
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
                  Manually spawn a child MCP agent from the TUI.
/despawn <server_name>
                  Terminate and remove a previously spawned child agent.
/clear            Clear chat and history
/quit             Exit (also /exit, /q)
/help             Show help (also /h, /?)

按 Esc 停止正在运行的 Agent。按 Ctrl+Q 退出。

Playbook

PentestAgent 内置了适用于黑盒安全测试的攻击 Playbook。Playbook 为特定安全评估定义了结构化流程。

运行 Playbook：

pentestagent run -t example.com --playbook thp3_web

工具

PentestAgent 内置工具，并支持 MCP（模型上下文协议）以便扩展。

内置工具： terminal、browser、notes、web_search（需要 TAVILY_API_KEY）、spawn_mcp_agent

Agent 自我派生（spawn_mcp_agent）

spawn_mcp_agent 是一个内置工具，可让正在运行的 Agent 生成一个自身的子副本，作为通过 stdio 连接的从属 MCP 服务。子进程完全隔离——拥有自己的运行时、LLM 客户端、对话历史和笔记存储——生成后，其完整工具集会注入父 Agent 的可用工具中。

这无需任何外部编排即可实现分层多 Agent 工作流：Agent 可按需生成子 Agent，将范围明确的子任务委派给它们，从而自行组织工作。

参数	类型	默认值	说明
target	string	—	传递给子 Agent 的渗透测试目标
scope	string[]	—	子 Agent 的范围内目标/CIDR
model	string	env var	模型标识符，可覆盖子 Agent 上的 PENTESTAGENT_MODEL
no_rag	boolean	false	跳过子 Agent 上的 RAG 引擎初始化
no_mcp	boolean	true	跳过子 Agent 上的外部 MCP 服务连接（推荐）

spawn_mcp_agent 返回后，子 Agent 的工具（run_task、run_task_async、await_tasks 等）会在下一次工具调用时可用。子 Agent 的服务名称会自动分配（例如 child_agent_1），并在结果中返回。

示例——协调器将并行侦察任务委派给两个子 Agent：

# Turn 1: spawn two isolated child agents
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"]

# Turn 2: children's tools are now available — delegate work asynchronously
child_agent_1__run_task_async  task="Full port scan and service enumeration"
child_agent_2__run_task_async  task="Full port scan and service enumeration"

# Turn 3: wait and collect
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>"

手动控制子 Agent（/spawn 和 /despawn）

除了自动生成的 spawn_mcp_agent 工具外，TUI 还提供两个命令，让你可以在运行中的 Agent 循环之外，手动生成和终止子 Agent。

/spawn

/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]

通过 stdio 生成一个新的子 MCP Agent，并将其附加到当前会话。子 Agent 会作为可折叠的终端面板显示在 TUI 侧边栏中，其工具会在下一次工具调用时对父 Agent 可用。

参数	说明
target	传递给子 Agent 的渗透测试目标（位置参数或 --target）
--scope CIDR	一个或多个范围内的 CIDR（可重复指定）
--model MODEL	覆盖子 Agent 使用的模型
--no-rag	跳过子 Agent 上的 RAG 引擎初始化
--no-mcp	跳过子 Agent 上的外部 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>

终止由 server_name 标识的子 Agent（例如 child_agent_1），从 TUI 中移除其终端面板，并断开其工具与父会话的连接。使用 /mcp list 查看所有当前活跃的子 Agent 名称。

示例：

/despawn child_agent_1

MCP RAG 工具优化器

当 MCP 服务暴露的工具超过 128 个时，PentestAgent 会自动将完整目录替换为一个 mcp_<server>_rag_optimizer 工具。这个元工具使用嵌入相似度（通过 LiteLLM，默认使用 text-embedding-3-small）检索与当前任务最相关的工具，并将它们注入 Agent 的下一轮对话中，从而在不失去对完整工具集访问权限的情况下，控制上下文窗口的大小。

这个优化器对 Agent 是透明的：Agent 会调用 RAG 工具，使用聚焦的自然语言查询描述所需内容；匹配的工具会在下一轮中直接提供调用。

Agent 使用指南：

参数	类型	默认值	说明
queries	string[]	（必填）	每项所需能力使用一个聚焦的查询。描述越具体，准确度越高
top_k	integer	20	每个查询检索的工具数量（最多 128 个）。结果会合并并去重

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

提示： 每种不同的能力使用一个查询，而不是将所有内容合并到一个查询中。["list open ports on a host", "get process memory usage"] 比 ["list ports and memory and 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 的客户端提交任务、检查结果并远程控制 Agent。支持两种传输方式：

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	主要 Agent 的配置：目标、范围、最大迭代次数、工具列表
update_config	更新后续所有任务的目标、范围或最大迭代次数

任务执行

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

任务检查

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

任务控制

工具	描述
cancel_task	按 ID 取消正在运行或等待中的任务

工具管理

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

对话历史

工具	描述
get_conversation_history	返回任务或主要 Agent 的消息历史。支持 limit 参数
reset_conversation	清除任务或主要 Agent 的对话历史

记忆

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

可观测性

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

---

异步任务工作流示例

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

# 1. Submit tasks without blocking
run_task_async  task="Enumerate subdomains of example.com"  target="example.com"
run_task_async  task="Run nmap SYN scan on example.com"     target="example.com"

# 2. Block until both finish (up to 5 minutes)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. Retrieve full results
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

---

CLI 工具管理

pentestagent tools list         # List all tools
pentestagent tools info <name>  # Show tool details
pentestagent mcp list           # List MCP servers
pentestagent mcp add <name> <command> [args...]  # Add MCP server
pentestagent mcp test <name>    # Test MCP connection

对话历史控制

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

回退

点击任意用户消息上的回退，即可将对话截断至该消息之前——界面和 Agent 的内存历史都会同步截断。可用此功能从头重试查询，而不保存被丢弃的路径。

分支

点击任意用户消息上的 >> fork，即可从该处创建对话分支：

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

这样，你就可以从任意位置尝试其他方法，同时仍可通过 /conversations 找回原始对话。

---

对话历史记录

PentestAgent 会自动保存每次对话，方便你查看、比较和恢复之前的会话。

自动保存会在每次 /assist、/agent、/crew 和 /interact 任务后触发，并在 /clear 前触发。最多保留 20 个对话；较早的对话会自动清理。

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

使用 /conversations 浏览和恢复：

/conversations 命令会在 TUI 中打开一个分栏弹窗：

• 左侧面板 — 已保存对话的列表，包含标题和日期。
• 右侧面板 — 元数据预览及前 5 条消息（用户消息为蓝色、Agent 回复为绿色、工具调用为黄色、工具结果为灰色）。计数会显示还有多少条消息。

选择一个对话并按 Restore，即可将其载入当前会话；按 Close 可关闭弹窗。

知识

• **RAG：**将方法论、CVE 或字典文件放入 pentestagent/knowledge/sources/，即可自动注入上下文。
• **笔记：**Agent 会将发现保存到 loot/notes.json，并归入相应类别（credential、vulnerability、finding、artifact）。笔记会跨会话保留，并注入 Agent 上下文。
• **Shadow Graph：**在 Crew 模式下，协调器会根据笔记构建知识图谱，以推导战略洞察（例如，“我们有主机 X 的凭据”）。

项目结构

pentestagent/
  agents/         # Agent implementations
  config/         # Settings and constants
  interface/      # TUI and CLI
  knowledge/      # RAG system and shadow graph
  llm/            # LiteLLM wrapper
  mcp/            # MCP client and server configs
  playbooks/      # Attack playbooks
  runtime/        # Execution environment
  tools/          # Built-in tools

开发

pip install -e ".[dev]"
pytest                       # Run tests
pytest --cov=pentestagent    # With coverage
black pentestagent           # Format
ruff check pentestagent      # Lint

法律声明

仅可对你明确获准测试的系统进行测试。未经授权访问属于违法行为。

许可证

MIT