wangqiongpeng/pengstrike-mcp

## 目录 - [什么是 PengStrike？](#what-is-pengstrike) - [核心特性](#key-features) - [架构](#architecture) - [快速开始](#quick-start) - [AI 使用协议](#ai-usage-protocol) - [一次典型的 AI 会话](#a-typical-ai-session) - [工具清单](#tool-inventory) - [API 参考](#api-reference) - [对比](#comparison) - [目录结构](#directory-structure) - [常见问题](#faq) - [贡献](#contributing) - [安全](#security) - [许可与免责声明](#license--disclaimer) ## 什么是 PengStrike？ PengStrike 是一个 **MCP (Model Context Protocol) 服务器**，可将任何支持 MCP 的 AI agent（Trae、Claude、GPT、Cursor 等）转变为**专业的渗透测试平台**。AI 通过统一的 MCP 接口调用 150 多个真实的安全工具——如 `nmap`、`nuclei`、`sqlmap`、`metasploit`、`hydra`、`ghidra` 等，同时由服务器处理复杂的底层逻辑：**并发任务调度、任务生命周期管理、流式输出和内存保护**。 它是一个**双脚本系统**： | 脚本 | 作用 | 运行位置 | | --- | --- | --- | | `pengstrike_server.py` | HTTP 服务器：执行真实工具，管理任务，流式输出，保护内存 | Kali Linux / 任何安装了 Python 3.10+ 的 Linux | | `pengstrike_mcp.py` | MCP 客户端：一个轻量级的 FastMCP 包装器，负责将 AI IDE 连接到服务器 | 任何托管 AI IDE 的机器（Windows / macOS / Linux） | **适用人群？** - **红队和渗透测试人员**——希望利用真实且经过实战检验的工具进行 AI 辅助的侦察、扫描和漏洞利用。 - **CTF 选手**——需要通过单一聊天界面进行自动化扫描和二进制/pwn 分析。 - **安全研究人员**——正在构建 AI agent，需要一个可靠、并发的工具执行后端。 **它解决了什么问题？** 简单的 MCP 工具集成采用同步方式运行工具：长时间的 `nmap` 扫描会阻塞整个对话数分钟，AI 会误判为“失败”并重试（从而产生重复扫描），而且繁重的扫描会耗尽资源，导致像 `curl` 这样的快速查询被饿死。PengStrike 的**自适应任务模型**消除了所有这些痛点：快速工具立即返回结果，慢速工具会立刻返回一个 `task_id`，AI 稍后可以通过一次 `harvest_tasks` 调用来收集结果。 ## 核心特性 ### 1. 自适应同步/异步任务模型 无需 AI 进行任何特殊操作，每个工具调用都能以最优方式执行： - **快速工具 (<10s)** —— `httpx`、`dig`、`curl`、快速探测 —— **同步**返回**完整结果**。AI 会收到正常的答复，行为无需改变。 - **慢速工具** —— `nmap`、`nuclei`、`sqlmap`、`hydra` —— **立即**返回 `{task_id, status: "running"}`，并在后台继续运行。AI 可以并行启动多个扫描，然后通过一次 `harvest_tasks` 调用收集所有结果。 - **Python 脚本**拥有 120 秒的扩展同步窗口（`PY_SCRIPT_SYNC_WINDOW`），以便典型的分析/探测脚本能返回完整的输出，而无需在成功和“运行中快照”的状态之间来回切换。 ### 2. 具有 QoS 调度的 10 并发硬限制 - 固定的 `ThreadPoolExecutor(10)` 线程池 —— 并发任务永远不会超过 10 个，保护服务器免受任务风暴的冲击。 - **QoS 两级调度**：2 个快速槽位（用于 `httpx`/`dig`/`curl` 等即时工具）+ 8 个繁重槽位（`nmap`/`sqlmap`）。长时间的繁重扫描**绝不会饿死**快速的查询请求。 ### 3. 流式输出引擎（设计上保证内存稳定） - 输出**在流式传输时直接写入磁盘**；内存中每个流仅保留 `head (16KB) + tail (64KB)`。 - 即使有 10 个并发任务产生总计 140MB 的输出，服务器的 RSS（常驻内存集）也仅保持在 ~15MB 左右 —— **内存占用在结构上有严格上限，而非被动削减**。 ### 4. SQLite (WAL) 任务账本 - 每个任务及其结果都会持久化到 `pengstrike_tasks.db`（WAL 模式）中。 - **服务器重启也不会丢失已完成的结果** —— AI 依然可以通过 `task_id` 从账本中提取数据。 - 被重启中断的运行中任务会被如实地标记为 `interrupted`（绝不会虚假地标记为“completed”）。 ### 5. 孤儿任务回收 - 当 AI 完成回答并离线后，**在 25 分钟内未被查询且没有产生新输出**的后台扫描将被自动取消，从而释放并发槽位。 - 持续产生实时输出的长时间扫描**不会**受到影响。 ### 6. 四级内存保护 - 每个流截断至 8MB，全局预算为 60MB，外加具有升级机制的**运行时内存监视器**：`ok → tight → critical → kill`。从设计上杜绝了 OOM 的发生。 ### 7. 聚合收集 / 增量同步 / 实时进度 - `harvest_tasks(task_ids=[...])` 可在一次往返中收集**多个**任务。 - `list?since_seq=N` 提供增量任务同步（提高轮询效率）。 - 每个运行中的任务都附带实时进度：`elapsed`、`bytes`、`lines`、`last_line`、PID。 ### 8. 健壮的传输层 - 客户端会自动重试瞬态连接错误（带有退避机制）—— 在繁重的并行扫描期间不再出现“MCP 偶发失败”。 - 读超时绝不会引发重复扫描（ReadTimeout 不会被重试）。 - 大输出会被截断，并带有指向 `read_output_file` 以进行分页的提示。 ## 架构 ``` ┌─ AI Agent (Trae / Claude / GPT / Cursor) ───────────────────┐ │ Rule 1: any tool call → result within 10s; else task_id │ │ Rule 2: got task_id → do other work in parallel → │ │ harvest_tasks() collects everything at once │ └───────────────────── MCP protocol ─────────────────────────┘ ┌─ MCP Client (pengstrike_mcp.py, thin shell) ───────────────┐ │ safe_post: pure submit, no hidden polling │ │ Tools: harvest_tasks / get_task_result / cancel_task / │ │ list_active_tasks / read_output_file │ └───────────────────── HTTP ─────────────────────────────────┘ ┌─ Server (pengstrike_server.py, TaskManager v2) ────────────┐ │ ThreadPoolExecutor(10) + QoS (2 fast + 8 heavy) │ │ SQLite(WAL) task ledger + orphan reaper + TTL cleanup │ │ Streaming to disk: memory keeps head+tail only │ └────────────────────────────────────────────────────────────┘ ``` 设计原则很简单：**一切操作都立即返回，数据收集是显式的**。没有隐藏的阻塞，也没有隐式的轮询魔法 —— AI 始终确切知道正在运行的任务以及如何获取结果。 ## 快速开始 ### 环境要求 | 端 | 要求 | | --- | --- | | **服务器** | Kali Linux 2024.1+（或任何安装了 Python 3.10+ 的 Linux），需从官方源安装 150+ 外部安全工具 | | **客户端** | Windows / macOS / Linux，任何支持 MCP 的 AI IDE | ### 第 1 步 — 部署服务器 (Kali / Linux) ``` # 创建并激活 virtualenv python3 -m venv pengstrike_env source pengstrike_env/bin/activate # 安装 Python 依赖 pip install -r requirements.txt # 启动服务器（仅限 SINGLE INSTANCE！） python3 pengstrike_server.py --port 8888 # 验证健康状态 curl http://127.0.0.1:8888/health # 验证 task API 是否在线 curl -X POST http://127.0.0.1:8888/api/task/cleanup_all \ -H "Content-Type: application/json" -d '{"reason":"check"}' # 预期：{"success":true,"canceled_count":0} ``` ### 第 2 步 — 配置 MCP 客户端 (AI IDE) 使用你的实际路径编辑 `pengstrike-ai-mcp.json`，然后将其导入到 AI IDE 的 MCP 设置中： ``` { "mcpServers": { "pengstrike-ai": { "command": "C:\\path\\to\\pengstrike_env\\Scripts\\python.exe", "args": [ "C:\\path\\to\\pengstrike_mcp.py", "--server", "http://127.0.0.1:8888" ], "description": "PengStrike AI v6.0 - Advanced Cybersecurity Automation Platform", "timeout": 1200, "alwaysAllow": [] } } } ``` 如果服务器不在同一台机器上，请通过 SSH 隧道暴露它： ``` ssh -L 8888:127.0.0.1:8888 kali@ ``` ### 第 3 步 — 端到端验证 1. 在你的 AI IDE 中，向 agent 提问：*“针对 127.0.0.1 运行 `nmap -sV`”*。 2. 你应该会看到返回的完整结果（快速）或立即返回的 `task_id`。 3. 要求 agent *“收集任务 (harvest the tasks)”* —— 结果将通过一次调用返回。 ## AI 使用协议 AI 遵循一个简单且具有确定性的协议： 1. **快速工具 (<10s)** → 返回完整结果。正常使用即可。 2. **收到 `{task_id, status:"running"|"queued"}`** → **不要**重试相同的工具。并行启动其他侦察任务，并积累一批 `task_id`。 3. **收集 (Harvest)** → 调用 `harvest_tasks(task_ids=[...], wait=120)` 一次性收集所有已完成的结果。 4. **决策 (Decide)** → 使用 `list_active_tasks()` 检查未完成任务的进度；对无价值的任务使用 `cancel_task()` 以释放槽位。 5. **海量输出** → 当 `output_truncated=true` 时，使用 `read_output_file` 对剩余部分进行分页查看。 ## 一次典型的 AI 会话 这是一个端到端真实会话的示例 —— 没有任何魔法，仅仅是遵循协议： **用户：** *“扫描 127.0.0.1 并告诉我上面运行了什么。”* 1. **AI** 调用 `nmap_scan(target="127.0.0.1", args="-sV -sC -O")`。 2. **服务器** 知道扫描将耗时超过 10 秒，因此**立即**回复： {"task_id": "a1b2c3d4", "status": "running", "elapsed": 0} 3. **AI 不会重试。** 相反，它会在 `nmap` 于后台运行的同时启动并行任务： - `subfinder_scan(target="example.com")` — 域名侦察 - `httpx_probe(targets=["127.0.0.1"])` — Web 发现 - 快速执行 `curl http://127.0.0.1/` — 快速工具同步返回结果 4. **AI** 通过单次调用收集所有结果： `harvest_tasks(task_ids=["a1b2c3d4", "e5f6g7h8"], wait=120)` 5. **服务器** 为该批次等待最多 120 秒，然后在一个 JSON payload 中返回完整的 `nmap` + `httpx` 输出。 6. **AI** 分析开放端口并继续下一步 —— 例如针对已知 CVE 的 `nuclei_scan`，或针对发现的 SSH 服务的 `hydra_attack`。 同样的模式可扩展至 20 个步骤的测试行动：每个慢速工具都返回一个 `task_id`，AI 可并行处理多个任务，并分批收集它们。快速、可预测且防崩溃。 ## 工具清单 PengStrike 集成了 150 多款外部安全工具（需从官方源单独安装），涵盖以下类别： - **网络与侦察 (25+)：** nmap, masscan, rustscan, autorecon, amass, subfinder, fierce, dnsenum, theharvester, responder, netexec, enum4linux-ng, smbmap, ... - **Web 应用程序 (40+)：** gobuster, feroxbuster, ffuf, dirb, dirsearch, nuclei, nikto, sqlmap, wpscan, arjun, paramspider, x8, katana, httpx, dalfox, jaeles, hakrawler, gau, waybackurls, wafw00f, ... - **认证与密码 (12+)：** hydra, john, hashcat, medusa, patator, netexec, evil-winrm, ... - **二进制分析与逆向工程 (25+)：** ghidra, radare2, gdb, binwalk, ropgadget, checksec, strings, objdump, volatility, foremost, steghide, exiftool, pwntools, angr, ... - **云与容器 (20+)：** prowler, scout-suite, trivy, kube-hunter, kube-bench, docker-bench-security, checkov, terrascan, falco, ... - **CTF 与取证 (20+)：** volatility3, autopsy, sleuthkit, stegsolve, zsteg, outguess, photorec, testdisk, scalpel, bulk-extractor, ... - **OSINT 与情报 (20+)：** sherlock, social-analyzer, recon-ng, maltego, spiderfoot, shodan-cli, censys-cli, ... ## API 参考 | 端点 | 方法 | 描述 | | --- | --- | --- | | `/api/command` POST | 执行工具（同步返回结果或 `task_id`） | | `/api/task/harvest` | POST | 聚合收集多个任务 | | `/api/task/status/` | GET | 任务状态 + 实时进度 | | `/api/task/result/?wait=N` | GET | 单任务收集（head+tail payload） | | `/api/task/cancel/` | POST | 取消任务（杀死进程树） | | `/api/task/list?since_seq=N` | GET | 增量任务列表同步 | | `/api/task/cleanup_all` | POST | 取消所有活动任务 | | `/api/output/read` | GET | 对海量输出进行分页 | | `/health` | GET | 健康检查 | ### 请求流程示例 提交一个慢速工具 —— 服务器会立即返回一个 `task_id`： ``` curl -s -X POST http://127.0.0.1:8888/api/command \ -H "Content-Type: application/json" \ -d '{"tool": "nmap_scan", "args": {"target": "127.0.0.1", "args": "-sV"}}' ``` ``` {"task_id": "a1b2c3d4", "status": "running", "elapsed": 0} ``` 检查实时进度，然后收集批次任务： ``` curl -s http://127.0.0.1:8888/api/task/status/a1b2c3d4 curl -s -X POST http://127.0.0.1:8888/api/task/harvest \ -H "Content-Type: application/json" \ -d '{"task_ids": ["a1b2c3d4"], "wait": 120}' ``` ``` {"results": [{"task_id": "a1b2c3d4", "status": "completed", "stdout": "...", "output_truncated": false}]} ``` 当 `output_truncated: true` 时，使用以下命令对剩余部分进行分页 `GET /api/output/read?path=&offset=`。 ## 对比 | 能力 | 典型 MCP 工具集成 | PengStrike | | --- | --- | --- | | 长时间扫描 (nmap/sqlmap) | 阻塞对话 / 有被误判为“失败”的风险 | 立即返回 `task_id`；稍后收集 | | 并行扫描 | 默认串行执行 | 10 个并发，QoS 两级调度 | | 负载下的服务器内存 | 随输出增加而增长 | 稳定在 ~15MB（流式写入磁盘） | | 服务器重启 | 丢失所有任务状态 | SQLite 账本保留结果 | | 孤儿扫描 | 继续运行，浪费槽位 | 25 分钟后自动回收 | | 重复重试 | AI 重试 → 产生重复扫描 | ReadTimeout 绝不被重试；`task_id` 语义明确 | ## 目录结构 ``` pengstrike_server.py # HTTP server (tool execution / task management / memory guard) pengstrike_mcp.py # MCP client (FastMCP wrapper) pengstrike-ai-mcp.json # MCP server configuration example TASK_MODEL_DESIGN.md # Task model architecture design (v1 → v2 evolution) requirements.txt # Python dependencies ``` ## 常见问题 **问：为什么 AI 有时会收到 `task_id` 而不是结果？** 因为该工具运行时间超过了 10 秒。这是设计预期的行为 —— 任务会在后台运行，你可以通过 `harvest_tasks` / `get_task_result` 来收集结果。请不要重试相同的工具。 **问：我可以在 Windows 上运行服务器吗？** 客户端可以在 Windows 上运行，但服务器是专为 Kali/Linux 设计的（许多外部工具仅限 Linux，例如 `enum4linux-ng`、`responder`）。如果你的 AI IDE 在 Windows 上，请使用 SSH 隧道模式。 **问：如何避免大规模并行扫描期间发生 OOM？** 你不需要这样做 —— 服务器在结构上限定了内存：单流 8MB 截断，60MB 全局预算，以及一个运行时监视器，它会在发生 OOM 之前升级并杀死进程。 **问：多个服务器实例可以共享数据库吗？** 不可以。SQLite(WAL) 是单写入者的。请只运行一个服务器实例。 **问：`read_output_file` 什么时候用得上？** 当扫描的输出超过返回的块大小时，结果会包含 `output_truncated=true` 以及完整输出文件的路径。调用 `read_output_file(file_path=..., offset=...)` 即可进行分页查看。 **问：这是 Metasploit / Cobalt Strike 的替代品吗？** 不是。PengStrike 是*编排层*：它允许 AI 通过单一的 MCP 接口驱动 150 多个独立工具（包括 Metasploit 本身，通过 `metasploit_run`）。它是对现有框架的补充，而不是替代。 **问：AI 真的可以运行任意命令吗？** 是的 —— `execute_command` 运行 shell 命令，`execute_python_script` 运行 Python。这是设计初衷（它是一个渗透测试工具）。请仅在你完全信任的主机上部署服务器，并仅针对你已获得授权的目标进行测试。 **问：如何添加清单中没有的工具？** 请阅读 [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-new-tool) —— 添加一个工具只需在服务器上增加一个端点，并在客户端进行一次 MCP 注册，通常不超过 30 行代码。 **问：服务器重启后输出还在吗？** 已完成的结果存在于 SQLite 账本中，可以在重启后收集。被中断的运行中任务会被如实地标记为 `interrupted` —— 绝不会虚假地报告为已完成。 ## 安全 在 PengStrike 本身发现了安全问题？请阅读我们的 [SECURITY.md](SECURITY.md) 并遵循协调披露流程。**切勿**针对漏洞公开提交 issue。 ## 许可与免责声明 基于 [MIT License](LICENSE) 授权。

标签：CISA项目, MCP, Python, XXE攻击, 插件系统, 无后门