pentestMCP：基于 MCP 的 AI 驱动渗透测试

pentestMCP 通过模型上下文协议（MCP）在大语言模型（LLM）与实用渗透测试工具之间搭建了一座强大的桥梁。本项目作为一个 MCP 服务器运行，将一套精选的 20 余种标准安全评估工具（Nmap、Nuclei、ZAP、SQLMap 等）以可调用的"工具"形式暴露出来。这使得 MCP 兼容客户端（如 Claude Desktop 或特定的 VS Code 配置）中的 AI 代理能够利用这些工具执行自动化、交互式的安全分析任务。

其目标是实现对复杂安全工作流的自然语言控制，使渗透测试能力更易获取，并深度集成到 AI 驱动的环境中。本作品受 Laurie Kirk 的 GhidraMCP 启发。

目录

• 核心概念与架构

• 主要特性

• 前置要求

• 安装与配置

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

  • 本地构建 Docker 镜像

• 客户端主机集成

  • Claude Desktop 集成

  • VS Code Copilot Chat 集成

• 工具参考

• 安全注意事项

• 贡献

• 许可证

• 免责声明

• 致谢

Related MCP server: redteam-mcp

视频演示

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

核心概念与架构

pentestMCP 严格遵守 MCP 规范，仅作为一个 MCP 服务器 运行。它不嵌入或直接与任何特定的 LLM 通信。交互流程由 MCP 客户端主机应用进行中介：

1. 客户端主机应用（例如 Claude Desktop、自定义代理）：连接到 pentestMCP（通常通过 Docker 代理的 stdio），管理用户交互，并与所选的 LLM 进行接口对接。

2. LLM：接收用户提示和工具定义（通过客户端主机从 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 主动扫描和 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 仓库，这些特定扫描才能有效运行。 GXP5

客户端主机集成

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 代理定义 MCP 服务器。

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

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

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

3. 重新加载 VS Code / 代理： 重启 VS Code 或使用相关命令重新加载 Copilot 代理的配置，以使更改生效。有关详细信息，请参阅具体 Copilot 代理的文档。

4. 交互： 使用 Copilot Chat 界面，如果代理支持，可以通过提及（mentions）调用工具，或者让代理根据您的提示自动调用工具。

工具参考

服务器暴露了多种按功能分类的工具：

• 侦察与枚举：

  • 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 仓库、创建功能分支并提交 Pull Request。请确保所有贡献都遵守道德测试准则。欢迎通过 GitHub Issues 提交错误报告和功能建议。

许可证

本项目根据 MIT 许可证 的条款进行分发。

免责声明

本软件仅供教育目的及经授权的、合乎道德的渗透测试使用。 未经明确许可对任何系统进行使用均被严格禁止且属违法行为。作者与贡献者不对因滥用或使用本程序造成的任何损害承担任何责任。请自行承担使用风险，并确保遵守所有适用法律与协议。

致谢

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