内容
# Metasploit MCP 服务器
[](https://www.python.org/downloads/)
[](https://python-poetry.org/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/psf/black)
一个现代、安全、模型上下文协议（MCP）服务器，为AI助手提供受控访问Metasploit Framework功能。
> **分支通知：** 该项目是 [GH05TCREW/MetasploitMCP](https://github.com/GH05TCREW/MetasploitMCP) 的分支，
> 是GH05TCREW创建的原始Metasploit MCP服务器，在相同的Apache License 2.0下分发。
> 参见 [与上游的关系](#relationship-to-upstream) 以了解此分支更改和改进的内容。
## 功能
### 核心能力
- **漏洞管理**：搜索、配置和执行Metasploit漏洞
- **载荷生成**：创建具有高级编码选项的自定义载荷
- **会话管理**：控制活动会话并执行命令
- **监听器管理**：启动和管理反向处理程序
- **安全验证**：内置绑定地址验证和输入净化
### 安全功能
- **绑定地址验证**：确保监听器仅绑定到授权接口
- **输入净化**：全面验证所有参数
- **安全默认值**：监听器默认绑定到 `0.0.0.0` 以实现最大兼容性
- **错误处理**：通过适当错误管理防止信息泄露
### 现代开发
- **Poetry依赖管理**：现代Python打包和依赖解析
- **全面测试**：92+个测试涵盖单元、集成和安全场景
- **类型提示**：支持更好的IDE体验的完整类型注释
- **FastMCP HTTP传输**：现代基于HTTP的MCP协议实现
- **开发工具**：集成linting、格式化和类型检查
## 先决条件
- **Python 3.10+** （推荐3.11+）
- **Poetry** 用于依赖管理（[安装指南](https://python-poetry.org/docs/#installation)）
- **Metasploit Framework** 启用RPC
## 快速入门
### 1. 安装
```bash
# 克隆仓库
git clone https://github.com/cbdmaul/MetasploitMCP.git
cd MetasploitMCP
# 使用Poetry安装
poetry install
poetry shell
```
### 2. 启动Metasploit RPC
```bash
# 启动Metasploit RPC服务
msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553
# 或从msfconsole
msfconsole -q
msf6 > load msgrpc ServerHost=127.0.0.1 ServerPort=55553 User=msf Pass=yourpassword
```
### 3. 配置环境（可选）
```bash
export MSF_PASSWORD=yourpassword
export MSF_SERVER=127.0.0.1
export MSF_PORT=55553
export PAYLOAD_SAVE_DIR=/path/to/save/payloads
export MSF_RPC_PROTOCOL=msgpack # 选项：'msgpack'（默认）或'jsonrpc'
```
**RPC协议选项：**
- `msgpack` （默认）：使用MessagePack二进制序列化（更快、更紧凑）
- `jsonrpc`：使用JSON-RPC协议（人类可读、更容易调试）
### 4. 运行服务器
```bash
# 使用CLI入口点（推荐）
metasploit-mcp --transport http --host 127.0.0.1 --port 8085
# 或直接使用Poetry
poetry run metasploit-mcp --transport http --host 127.0.0.1 --port 8085
# 或运行模块
poetry run python -m metasploit_mcp
# 使用Make
make run
# 调试模式
make run-debug
```
## 开发
### 开发环境设置
```bash
# 完成开发环境设置
make dev-setup
# 或手动
poetry install
poetry run pre-commit install
make test
```
### 可用命令
```bash
# 显示所有可用命令
make help
# 快速开发工作流
make quick-check # 格式化、linting和快速测试
make full-check # 完整的质量检查，包含覆盖率
# 测试
make test # 运行所有测试
make test-coverage # 运行并生成覆盖率报告
make test-watch # 监视模式，用于开发
# 代码质量
make format # 使用black格式化代码
make lint # 运行linting检查
make type-check # 运行类型检查
```
### 项目结构
```
MetasploitMCP/
├── src/
│ └── metasploit_mcp/ # 主包
│ ├── __init__.py # 包入口点，包含main()
│ ├── server.py # MCP服务器实现
│ ├── event_loop_monitor.py # 异步事件循环监控
│ ├── instance_manager.py # Metasploit实例管理
│ └── jsonrpc_patch.py # pymetasploit3 JSON-RPC补丁
├── scripts/ # 实用脚本
│ ├── bump_version.py # 版本提升
│ ├── run_tests.py # 测试运行器
│ └── ...
├── tests/ # 全面的测试套件
│ ├── conftest.py # Pytest夹具
│ ├── harness.py # Metasploitable3测试夹具
│ └── test_*.py # 测试模块
├── docs/ # 文档
│ ├── API.md # 完整的API参考
│ ├── DEVELOPMENT.md # 开发指南
│ ├── TROUBLESHOOTING.md # 常见问题和解决方案
│ ├── METASPLOITABLE3_TESTING.md # 集成测试指南
│ └── QUICK_START_TESTING.md # 快速启动测试
├── examples/ # 示例脚本
├── pyproject.toml # Poetry配置
├── Makefile # 开发命令
├── CHANGELOG.md # 版本历史
└── CONTRIBUTING.md # 贡献指南
```
## 集成
### Claude Desktop
配置 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"metasploit": {
"command": "poetry",
"args": [
"run", "metasploit-mcp",
"--transport", "stdio"
],
"cwd": "/path/to/MetasploitMCP",
"env": {
"MSF_PASSWORD": "yourpassword"
}
}
}
}
```
### 其他MCP客户端
对于基于HTTP的MCP客户端：
```bash
# 启动HTTP服务器
metasploit-mcp --transport http --host 0.0.0.0 --port 8085
# MCP端点：http://your-server:8085/mcp
```
## 安全考虑
**重要**：此工具提供直接访问Metasploit Framework功能。请负责任地使用，并仅在授权环境中使用。
### 安全功能
- **绑定地址验证**：防止绑定到非授权网络接口
- **输入净化**：所有参数在处理前都会进行验证
- **安全默认值**：监听器默认绑定到 `0.0.0.0` 以实现最大兼容性
- **错误处理**：通过适当错误管理防止信息泄露
### 最佳实践
- 仅在授权测试环境中使用
- 验证执行前的所有命令
- 监控生成的载荷及其使用
- 为Metasploit RPC使用强密码
- 定期更新依赖项
## API参考
### 核心工具
| 工具 | 描述 | 关键参数 |
|------|-------------|----------------|
| `list_exploits` | 搜索漏洞模块 | `platform_filter`, `search_term` |
| `run_exploit` | 执行漏洞 | `module_name`, `options`, `payload_name` |
| `generate_payload` | 创建载荷 | `payload_type`, `format_type`, `options` |
| `start_listener` | 启动处理程序 | `payload_type`, `lhost`, `lport` |
| `list_active_sessions` | 显示会话 | 无 |
| `send_session_command` | 执行命令 | `session_id`, `command` |
### v3.0中的功能
- **现代src布局**：正确的Python包结构
- **CLI入口点**：`metasploit-mcp`命令
- **绑定地址控制**：`reverse_listener_bind_address`参数
- **端口绑定**：`reverse_listener_bind_port`参数
- **IP验证**：自动验证绑定地址
- **FastMCP传输**：现代基于HTTP的MCP协议
有关完整的API文档，请参见 [docs/API.md](docs/API.md)。
## 测试
### 运行测试
```bash
# 所有测试，包含覆盖率
make test-coverage
# 快速测试运行
make test-quick
# 监视模式，用于开发
make test-watch
# 特定测试类别
make test-unit # 单元测试
make test-integration # 集成测试
```
### 测试覆盖率
该项目通过92+个测试保持高测试覆盖率，涵盖：
- **单元测试**：单个函数测试
- **集成测试**：端到端工作流测试
- **安全测试**：绑定地址验证和输入净化
- **错误处理**：全面错误场景测试
在`htmlcov/index.html`中生成覆盖率报告。
### Metasploitable 3集成测试
使用包含的测试工具包测试MetasploitMCP对抗真实漏洞目标：
```bash
# 列出可用的漏洞测试
poetry run python tests/harness.py --list-tests
# 对Metasploitable 3运行所有测试
poetry run python tests/harness.py \
--target 10.0.2.15 \
--lhost 10.0.2.4 \
--lport 4444
# 运行特定测试
poetry run python tests/harness.py \
--target 10.0.2.15 \
--lhost 10.0.2.4 \
--test "ProFTPD ModCopy Exec"
```
测试工具包包括以下测试：
- ProFTPD ModCopy Exec
- Apache Shellshock
- Drupal Drupageddon
- phpMyAdmin RCE
- Ruby on Rails ActionPack
- UnrealIRCd后门
有关详细文档，请参见：
- [快速入门指南](docs/QUICK_START_TESTING.md)
- [完整测试文档](docs/METASPLOITABLE3_TESTING.md)
## 文档
- **[API参考](docs/API.md)**：完整的工具文档，包含示例
- **[开发指南](docs/DEVELOPMENT.md)**：设置、测试和贡献指南
- **[故障排除](docs/TROUBLESHOOTING.md)**：常见问题和解决方案
- **[集成测试](docs/METASPLOITABLE3_TESTING.md)**：使用Metasploitable 3进行测试
- **[快速启动测试](docs/QUICK_START_TESTING.md)**：5分钟测试设置
- **[Poetry迁移](docs/POETRY_MIGRATION.md)**：从requirements.txt迁移
- **[发布](docs/RELEASING.md)**：维护人员如何发布
- **[变更日志](CHANGELOG.md)**：版本历史和重大更改
- **[贡献](CONTRIBUTING.md)**：如何为项目贡献
## 从v2.x迁移
### v3.0中的关键更改
- **src布局**：包移动到`src/metasploit_mcp/`
- **CLI入口点**：使用`metasploit-mcp`命令
- **导入路径**：使用`from metasploit_mcp import ...`
### 迁移步骤
```bash
# 拉取最新更改
git pull
# 重新安装依赖项
poetry install
# 运行测试以验证
make test
```
有关详细的迁移信息，请参见 [docs/POETRY_MIGRATION.md](docs/POETRY_MIGRATION.md)。
## 贡献
我们欢迎贡献！请参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取指南。
### 快速贡献工作流
1. 分叉仓库
2. 创建功能分支：`git checkout -b feature/your-feature`
3. 设置开发环境：`make dev-setup`
4. 进行更改并添加测试
5. 运行质量检查：`make full-check`
6. 提交拉取请求
## 与上游的关系
该项目是 **[GH05TCREW/MetasploitMCP](https://github.com/GH05TCREW/MetasploitMCP)** 的分支，
由 **GH05TCREW** (`harmasic@gmail.com`) 创建的原始Metasploit MCP服务器。在相同的Apache License 2.0下分发。
完整的设计和实现功劳归属于上游作者。此分支保留上游的 **Apache License 2.0** （参见 [`LICENSE`](LICENSE) 和 [`NOTICE`](NOTICE)）。
**上游基础（GH05TCREW）：** 核心Metasploit RPC集成、漏洞/载荷/会话/控制台管理以及后台作业处理 — 原始的单个文件服务器，具有`requirements.txt`安装和SSE传输。
**此分支更改和改进的内容：**
- **打包和布局** — 基于Poetry的打包、`src/metasploit_mcp/`布局和`metasploit-mcp` CLI入口点（替换单个文件`requirements.txt`设置）。
- **传输** — FastMCP HTTP（可流式）传输，替换SSE。
- **动态选项检测** — 模块/载荷选项实时查询自Metasploit，而不是硬编码，并检测混淆的模块/载荷选项。
- **并发安全性** — 会话级锁定以防止并发Meterpreter/ shell访问，以及用于隔离的每个代理的Metasploit实例管理器。
- **可靠性** — 异步事件循环监控（阻塞/积压检测），MCP心跳以防止客户端超时，RPC超时上限和客户端清理以及身份验证注销，会话ID规范化以及备用查找，强制选项验证对抗模块功能。
- **质量** — 全面的测试套件，Metasploitable 3集成测试工具包以及依赖安全更新。
参见 [`CHANGELOG.md`](CHANGELOG.md) 以获取详细的版本历史。
## 许可证
该项目在 **Apache License 2.0** 下许可 — 参见 [`LICENSE`](LICENSE) 文件以获取完整文本和 [`NOTICE`](NOTICE) 文件以获取属性。作为分支，它保留了上游 [GH05TCREW/MetasploitMCP](https://github.com/GH05TCREW/MetasploitMCP) 项目的许可证。
## 致谢
- **[GH05TCREW/MetasploitMCP](https://github.com/GH05TCREW/MetasploitMCP)**：此分支基于的原始项目
- **Metasploit Framework**：强大的渗透测试平台
- **模型上下文协议**：标准化的AI工具通信协议
- **FastMCP**：现代MCP服务器实现框架
- **Poetry**：现代Python依赖管理
---
**免责声明**：此工具仅用于授权的安全测试。用户在使用此工具之前，必须确保在任何环境中都具有适当的授权。
