Pentestmcp

pentestMCP：通过 MCP 实现 AI 驱动的渗透测试

pentestMCP 通过模型上下文协议（MCP），在大模型（LLM）与实用渗透测试工具之间搭建了强大的桥梁。本项目作为 MCP 服务，提供一套精心挑选的 20 多种标准安全评估工具（Nmap、Nuclei、ZAP、SQLMap 等），并将其作为可调用的“工具”开放。这样一来，MCP 兼容客户端（例如 Claude Desktop 或特定的 VS Code 配置）中的 AI Agent 就能利用这些工具执行自动化和交互式安全分析任务。

本项目旨在通过自然语言控制复杂的安全工作流，让渗透测试能力更易于使用，并融入 AI 驱动的环境。本项目受到 Laurie Kirk 的 GhidraMCP 启发。

---

目录

• 核心概念与架构
• 主要功能
• 前置条件
• 安装与设置
  • 使用预构建的 Docker 镜像（推荐）
  • 在本地构建 Docker 镜像
• 客户端主机集成
  • Claude Desktop 集成
  • VS Code Copilot Chat 集成
• 工具参考
• 安全注意事项
• 参与贡献
• 许可证
• 免责声明
• 致谢

---

视频演示

https://github.com/user-attachments/assets/930c879a-5cb4-478a-b033-f30df0e770a6

核心概念与架构

pentestMCP 严格遵循 MCP 规范，仅作为 MCP 服务运行。它不嵌入任何特定大模型，也不直接与其通信。交互流程由 MCP 客户端主机应用协调：

1. 客户端主机应用（例如 Claude Desktop、自定义 Agent）：连接到 pentestMCP（通常通过 Docker 转发的 stdio），管理用户交互，并与所选大模型对接。
2. 大模型：接收用户提示词和工具定义（由客户端主机通过 pentestMCP 提供）。它根据上下文决定调用哪些工具。
3. pentestMCP 服务（本项目）：在 Docker 容器中运行。监听来自客户端主机的 tools/call 请求，执行相应的底层工具（例如 nmap），并返回结果。
4. 外部工具：封装在 Docker 镜像中的实际命令行工具。

该服务使用 Python MCP SDK（mcp.server.fastmcp.FastMCP）构建，具有以下特性：

• **工具发现：**利用 Python 类型提示和文档字符串自动生成 MCP 工具架构。
• **并发控制：**通过 threading.Semaphore 限制资源密集型扫描的同时执行数量。
• **异步扫描模式：**为耗时较长的任务（Nmap、Nuclei、SQLMap、Gobuster）实现启动和获取方法，避免阻塞 MCP 连接。

sequenceDiagram
    participant User
    participant ClientHost as Client Host (Claude, VS Code)
    participant LLM
    participant PentestMCP as pentestMCP Server (Docker via stdio)
    participant ExtTool as External Tool (e.g., Nmap)

    User->>ClientHost: "Perform Nmap service scan on scanme.nmap.org"
    ClientHost->>PentestMCP: tools/list Request
    PentestMCP-->>ClientHost: List of Tools (including 'run_nmap_scan')
    ClientHost->>LLM: User Prompt + Available Tools Description
    LLM-->>ClientHost: Decision: Use 'run_nmap_scan', target='scanme.nmap.org', args='-sV'
    ClientHost->>PentestMCP: tools/call (name='run_nmap_scan', args={...})
    Note over PentestMCP, ExtTool: pentestMCP executes 'nmap -sV scanme.nmap.org' internally
    PentestMCP-->>ClientHost: tools/call Result (pid, output_path for async or direct output)
    ClientHost->>LLM: Tool Execution Result
    LLM-->>ClientHost: Formulate Final Response
    ClientHost-->>User: "Nmap scan launched/completed. Results..."

主要功能

• 全面的工具集： 通过 MCP 集成 20 多种必备渗透测试工具。
• 标准化访问： 让任何支持通过 stdio 启动服务的 MCP 客户端都能使用复杂的渗透测试工作流。
• 非阻塞扫描： 高效处理长时间运行的扫描，不会阻塞交互流程。
• 资源管理： 对扫描实施基本的并发限制。
• 可移植且可复现： Docker 化环境可确保所有依赖项和工具在不同平台（Windows、macOS、Linux）上都能一致使用。
• Web 扫描器集成： 可直接控制 OWASP ZAP Active Scan 和 AJAX Spider 功能。

前提条件

• Docker： 需要安装并运行 Docker Desktop（Windows/macOS）或 Docker Engine（Linux）。请确保 Docker 守护进程处于运行状态。
• Git： 仅在本地构建镜像时需要（git clone 步骤）。
• （可选但建议）OWASP ZAP 实例： 使用 ZAP 相关工具（run_zap_*、run_active_scan_*、run_ajax_*）时需要。此 ZAP 实例必须正在运行，并且可从 pentestMCP Docker 容器内部通过网络访问（配置请参见客户端主机集成部分）。

安装与设置

我们建议使用预构建的 Docker 镜像，以获得最快、最可靠的设置体验。

🐳 使用预构建的 Docker 镜像（推荐）

使用预构建镜像可避免本地构建耗时，并确保所有工具（如 gofang、nmap 和 nuclei）均已正确安装，不会出现依赖问题。

1. 从 Docker Hub 拉取镜像：

   docker pull ramgameer/pentest-mcp:latest
   

   ℹ️ 注意： 根据你的环境，你可能需要进行身份验证，或确保 Docker 守护进程正在运行。

---

🛠️ 在本地构建 Docker 镜像

⚠️ 重要： 目前，在 Linux 环境中进行本地构建效率最高，且受支持。

如果你希望修改服务端代码、使用最新版本，或无法获取预构建镜像，可以在本地构建 Docker 镜像。

1. 克隆仓库：

   git clone https://github.com/ramkansal/pentestMCP.git
   cd pentestMCP
   

2. 构建 Docker 镜像：

   docker build -t pentest-mcp-server:custom .
   

3. 安装 SecLists（可选，但强烈建议）：

   💡 提示： 一些工具（如 Gobuster 和模糊测试工具）依赖大量词表。必须克隆 SecLists 仓库，这些特定扫描才能有效运行。

   git clone https://github.com/danielmiessler/SecLists.git seclists
   

客户端主机集成

pentestMCP 在 Docker 容器内运行，并通过 stdio 与客户端主机通信。你需要配置主机（例如 Claude Desktop、VS Code），使用 docker run -i ... 启动服务。

Claude Desktop 集成

1. 定位或创建配置文件：

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json

2. 编辑配置： 添加或更新 mcpServers 部分。使用正确的镜像名称（ramgameer/pentest-mcp:latest 或你的自定义标签）。

   {
     "mcpServers": {
       "pentestMCP": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "ramgameer/pentest-mcp:latest"
         ]
       }
     }
   }
   

3. 完全重启 Claude Desktop。

4. 验证： 查找 图标。点击后应显示渗透测试工具列表。

5. 交互： 让 Claude 使用这些工具（示例见草稿）。

VS Code Copilot Chat 集成

集成需要配置 VS Code 设置，为支持 MCP 的 Copilot Chat Agent 定义 MCP 服务。

1. 安装前置条件： 确保已安装 Github Copilot extension 和相关的 GitHub Copilot 扩展。

2. 配置 VS Code 设置： 打开用户或工作区的 settings.json 文件（命令面板：“Preferences: Open Settings (JSON)”）。在相应路径下添加 MCP 服务配置（该路径可能因具体的 Copilot Chat Agent 实现而异，请查阅其文档）：

   "pentest-mcp": {
       "type": "stdio",
       "command": "docker",
       "args": [
           "run",
           "-i",
           "--rm",
           "ramgameer/pentest-mcp:latest"
       ]
   }
   

3. 重新加载 VS Code / Agent： 重启 VS Code，或使用相关命令重新加载 Copilot Agent 的配置，使更改生效。详情请参阅相应 Copilot Agent 的文档。

4. 开始交互： 使用 Copilot Chat 界面；如果 Agent 支持，可以通过提及来调用工具，也可以让 Agent 根据你的提示词调用工具。

工具参考

该服务提供了多种按功能分类的工具：

• 侦察与枚举：
  • run_subfinder：使用 ProjectDiscovery 的 Subfinder 发现子域名。
  • launch_nmap_scan / fetch_nmap_results：执行 Nmap 网络扫描并异步获取结果。
  • run_gobuster_scan / check_gobuster_status：使用 Gobuster 异步执行目录 / 文件 / DNS 暴力破解。
  • launch_gofang_scan / fetch_gofang_results：运行 gofang，这是一款集多种功能于一体、具备强大数据提取能力的网络爬虫。
  • run_harvester / check_harvester_status：异步运行 theHarvester 以收集 OSINT 信息（电子邮件、主机、IP）。
  • run_dig_tool：执行 DNS dig 查询。
  • fetch_whois_data：获取域名的 WHOIS 信息。
  • run_curl_tool：执行 cURL 命令以进行 HTTP 交互。
• 漏洞扫描：
  • launch_nuclei_scan / fetch_nuclei_results：使用 ProjectDiscovery 的 Nuclei 异步执行基于模板的漏洞扫描。
• Web 应用分析：
  • launch_arjun_scan / fetch_arjun_results：使用 Arjun 查找隐藏的 HTTP 参数。
• 漏洞利用支持：
  • run_searchsploit：使用 Searchsploit 搜索本地 Exploit-DB 数据库。
  • run_sqlmap_tool / check_sqlmap_status：异步运行 SQLmap 进行 SQL 注入测试。
• Active Directory 分析（ad_* 工具）：
  • 枚举： ad_user_enum、ad_shares_enum、ad_smb_signing_check、ad_certipy_enum、ad_ldap_dump、ad_bloodhound_collect
  • 攻击 / 强制： ad_asreproast、ad_kerberoast、ad_password_spray、ad_coerce_petitpotam、ad_coerce_printerbug、ad_responder_poison、ad_relay_setup
  • 凭据 / 域操作： ad_check_credentials、ad_secrets_dump、ad_dcsync

安全注意事项

• 执行权限： 工具在 Docker 中以 appuser 身份运行，但 Docker 本身以主机权限运行。使用会修改文件或需要提升系统访问权限的工具时，请务必谨慎。
• 目标授权： 重要： 仅可对你事先获得明确书面授权的系统使用这些工具。未经授权的扫描属于违法且不道德的行为。
• 网络暴露： 如果映射 ZAP 的端口（-p 8888:8888），且机器位于不受信任的网络中，请确保主机防火墙限制访问。已配置的 ZAP API 密钥可用于控制该实例。
• 输入验证： 尽管 MCP 提供结构化输入，但如果 Python 封装函数处理不当，底层工具仍可能受到精心构造的参数攻击。

贡献

非常欢迎贡献！请 Fork 此仓库，创建功能分支，然后提交拉取请求。请确保所有贡献都遵循道德测试准则。欢迎通过 GitHub Issues 提交 Bug 报告和功能建议。

许可证

本项目根据 MIT 许可证 的条款发布。

免责声明

本软件仅用于教育目的以及经授权的道德安全测试。 严禁在未经明确许可的情况下将其用于任何系统，此类行为属于违法行为。作者和贡献者对因使用本程序不当而造成的滥用或损害概不负责。使用风险自负，并确保遵守所有适用的法律和协议。

致谢

本项目深受 Laurie Kirk 在 GhidraMCP 上的开创性工作启发。