使用说明

Metasploit MCP 服务器

一个模型上下文协议（MCP）服务器，它通过标准化接口为人工智能助手提供安全访问Metasploit框架功能的途径。该服务器将Metasploit的核心功能封装到MCP工具中，这些工具可以被兼容的客户端发现并使用。

特点/功能

🔧 执行Metasploit命令 - 在内置安全验证下运行原始Metasploit命令
🔍 搜索漏洞 - 通过名称、CVE编号或关键词查找漏洞
📋 模块信息 - 获取有关任何Metasploit模块的详细信息
📦 列出模块 - 按类型浏览可用模块（漏洞利用、辅助工具、有效载荷等）
🌐 网络扫描 - 通过Metasploit的数据库集成运行Nmap扫描
🔒 漏洞扫描 - 对目标系统执行漏洞扫描
ℹ️ 版本信息 - 检查您的Metasploit安装详情
🛡️ 安全控制措施 - 输入消毒和防止命令注入

要求

Node.js 16.0.0 或更高版本
Metasploit 框架 已安装并通过命令行访问（msfconsole）
兼容MCP的客户端 （Claude Desktop、带有MCP扩展的VS Code等）

安装

克隆仓库：

git clone https://github.com/RobertoDure/metasploit-mcp-server.git
cd metasploit-mcp-server

安装依赖项：
```
npm install
```
验证Metasploit安装：
```
msfconsole --version
```

用法

开发模式

npm run dev

生产模式

npm start

服务器通过STDIO传输进行通信，因此与任何支持此传输方法的MCP客户端兼容。

可用工具

MCP服务器通过以下方式提供以下工具： @modelcontextprotocol/sdk:

工具名称	描述	必需参数	可选参数
`execute-command`	执行带有安全验证的原始Metasploit命令	`command` (字符串)	无
`search-exploit`	通过名称、CVE 或关键词搜索漏洞	`query` (字符串)	无
`module-info`	获取特定模块的详细信息	`modulePath` (字符串)	无
`list-modules`	按类型列出可用模块	`type` (利用模块	辅助模块
`get-version`	获取Metasploit框架版本信息	无	无
`run-nmap-scan`	通过Metasploit数据库执行Nmap扫描	`target` （字符串）	`options` （字符串）
`run-vuln-scan` 使用辅助模块运行漏洞扫描 `target` （字符串）	无

工具详情

`execute-command`

执行任何有效的Metasploit命令
包括输入净化以防止命令注入
以安静的非交互模式运行，以确保输出的一致性
超时保护（30秒）

`search-exploit`

搜索Metasploit的漏洞利用数据库
支持CVE编号、漏洞利用名称和关键词
返回带有模块路径和描述的格式化结果

`module-info`

提供全面的模块信息
包括选项、目标、有效载荷和参考文献
与任何模块类型兼容（如漏洞利用模块、辅助模块等）

`list-modules`

按类别列出模块并进行验证
支持所有主要模块类型
返回组织好的模块列表

`run-nmap-scan`

与Metasploit的数据库功能集成
支持自定义Nmap选项
将结果存储在Metasploit数据库中以便进一步分析

`run-vuln-scan`

使用辅助扫描模块
目前实施SMB MS17-010（EternalBlue）漏洞扫描
可以扩展以进行额外的漏洞检查

示例用法

当连接到一个与MCP兼容的客户端时，您可以使用自然语言与Metasploit进行交互：

搜索与信息：

“搜索Apache Log4j漏洞利用方法”
“向我展示关于EternalBlue漏洞（exploit/windows/smb/ms17_010_eternalblue）的详细信息”
“列出所有可用的Windows有效载荷”
“有哪些可用的辅助模块？”

扫描与侦察：

“对192.168.1.100运行Nmap扫描”
“对10.0.0.0/24网络执行带-sS -O选项的隐蔽扫描”
“检查192.168.1.50是否易受MS17-010漏洞攻击”

系统信息：

“我运行的是哪个版本的Metasploit？”
执行“help”命令以查看可用命令

示例回答

服务器返回结构化的JSON响应：

{
  "success": true,
  "output": "Metasploit Framework Console Output...",
  "command": "search apache"
}

或者在出现错误的情况下：

{
  "success": false,
  "output": "Command contains potentially dangerous characters",
  "error": "Security violation"
}

建筑

该服务器遵循简洁、模块化的架构设计：

src/
├── index.js                     # Main MCP server with tool registrations
└── services/
    └── metasploit-service.js    # Metasploit Framework integration layer

tests/
└── metasploit-service.test.js   # Unit tests with Jest

关键组件

**McpServer（可直接作为专有名词保留，若需解释性翻译，可译为“MCP服务器”）**用途 @modelcontextprotocol/sdk 用于MCP协议的实现
Metasploit服务封装了Metasploit与安全控制的所有交互
**StdioServerTransport 翻译为中文是：“标准输入输出服务器传输（或：标准IO服务器传输）”**通过STDIO处理通信，以实现客户端兼容性
**Zod Schema（或Zod模式）**为所有工具输入提供运行时类型验证

安全特性

**输入净化（或输入验证与清理）**移除危险的shell字符（;&|$()`) （这个符号组合在中文中没有直接对应的翻译，它可能是一个特定上下文或领域内的符号，或者是一个无实际意义的字符组合。如果是在编程或特定软件中使用的，需要根据具体上下文来解释。）
命令验证确保命令为非空字符串
超时保护所有命令执行的超时时间为30秒
错误处理结构化格式的全面错误响应
模块类型验证对模块类型参数进行严格验证

配置

包配置

服务器被配置为一个ES模块，具有以下关键设置：

{
  "name": "metasploit-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "main": "src/index.js",
  "engines": {
    "node": ">=16.0.0"
  }
}

依赖项

生产依赖项：

@modelcontextprotocol/sdk (^1.12.0) - MCP 协议实现
zod (^3.22.4) - 运行时类型验证和模式定义

开发依赖项：

jest (^29.7.0) - 支持ES模块的测试框架
eslint (^8.57.0) - 代码检查和风格强制执行

MCP客户端配置

对于 Claude Desktop（可译为“Claude桌面版”或保持原样，若“Claude”为特定产品名且无需翻译），在您的MCP设置中添加：

{
  "mcpServers": {
    "metasploit": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "/path/to/metasploit-mcp-server"
    }
  }
}

为了 带有MCP扩展的VS Code：

{
  "mcpServers": {
    "metasploit-mcp-server": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/path/to/metasploit-mcp-server"
    }
  }
}

安全考虑事项

⚠️（表示警告或注意的符号） 重要安全通知

这个MCP服务器提供了直接访问Metasploit Framework功能的途径。请遵守以下安全指南：

🔒 访问控制

没有内置认证功能 - 考虑为生产环境添加身份验证
建议使用本地访问 - 避免将此服务器暴露于不受信任的网络中
最小特权原则 - 以最小必要的系统权限运行

🛡️ 内置安全功能

命令消毒（或命令净化） - 防止命令注入攻击
输入验证 - 所有参数均使用Zod模式进行验证
超时保护 - 30秒执行限制可防止进程挂起
错误隔离 - 故障被控制在一定范围内，不会导致服务器崩溃

⚖️ 法律与伦理考量

需要授权 - 仅对您拥有或明确获得测试许可的系统进行使用
负责任地披露 - 对于发现的漏洞，遵循负责任的披露原则
合规性 - 确保使用符合当地法律和组织政策
文档 - 保存授权测试活动的记录

🔧 推荐的部署实践

在隔离/沙盒环境中运行
使用专用的测试网络
实施网络级别的访问控制
监控并记录所有活动
对依赖项进行定期安全更新

🚨 风险意识

执行的命令具有与运行服务器的用户相同的权限
Metasploit模块可以在目标系统上执行入侵性操作
某些模块可能会导致服务中断或系统不稳定
始终先在非生产环境中进行测试

发展

脚本

# Start in development mode with file watching
npm run dev

# Run production server
npm start

# Run tests with Jest
npm test

# Run tests in watch mode
npm run test:watch

# Lint code with ESLint
npm run lint

# Fix linting issues automatically
npm run lint:fix

测试

该项目包含了全面的Jest测试：

# Run all tests
npm test

# Generate coverage report
npm test -- --coverage

# Watch mode for development
npm run test:watch

测试覆盖率包括：

✅ 命令执行验证
✅ 安全消毒
✅ 错误处理
✅ 模块类型验证
✅ 输入验证边界情况

项目结构

metasploit-mcp-server/
├── src/
│   ├── index.js                   # MCP server entry point
│   └── services/
│       └── metasploit-service.js  # Metasploit integration
├── tests/
│   └── metasploit-service.test.js # Unit tests
├── package.json                   # Dependencies and scripts
├── jest.config.json              # Jest testing configuration
└── README.md                     # Documentation

扩展服务器

添加新工具

为Metasploit添加新功能：

在MetasploitService中添加一个方法:

async myNewFeature(param) {
  return this.executeCommand(`my_command ${param}`);
}

在 index.js 中注册该工具：

server.registerTool("my-new-tool", {
  title: "My New Tool",
  description: "Description of what it does",
  inputSchema: {
    param: z.string().describe("Parameter description")
  }
}, async ({ param }) => {
  const result = await metasploitService.myNewFeature(param);
  return {
    content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
  };
});

添加测试:

describe('myNewFeature', () => {
  it('should execute the new feature', async () => {
    // Test implementation
  });
});

自定义模块集成

对于特定模块的集成，您可以创建专门的方法：

async scanForWebVulns(target) {
  const commands = [
    `use auxiliary/scanner/http/dir_scanner`,
    `set RHOSTS ${target}`,
    `run`,
    `back`
  ].join('; ');
  
  return this.executeCommand(commands);
}

错误处理模式

遵循已建立的错误处理模式：

if (!param || typeof param !== 'string') {
  return {
    success: false,
    output: 'Invalid parameter',
    error: 'Validation failed'
  };
}

故障排除

常见问题

未找到Metasploit：

# Ensure Metasploit is in PATH
which msfconsole

# Or check installation
msfconsole --version

权限错误：

# Check file permissions
ls -la src/index.js

# Ensure Node.js has execution rights
chmod +x src/index.js

模块导入错误：

验证 "type": "module" 设定于 package.json
使用 .js 在所有导入语句中添加扩展
检查 Node.js 版本（要求 >=16.0.0）

MCP客户端连接问题：

验证是否正确使用了STDIO传输
检查服务器是否无错误启动
确保客户端配置指向正确的路径

调试模式

通过设置环境变量来启用调试日志记录：

DEBUG=mcp* npm start

性能调优

为了提升大型扫描的性能：

// Increase timeout for long-running operations
const { stdout, stderr } = await execAsync(fullCommand, { 
  timeout: 60000  // 60 seconds
});

许可证

MIT 许可证 - 详情请参见 LICENSE 文件。

做出贡献

欢迎投稿！请遵循以下指南：

为仓库创建分支（或“克隆仓库”） 并创建一个特性分支
编写测试 为了新增功能
遵循现有的代码风格 （使用 ESLint）
更新文档 按需
提交拉取请求 附有清晰描述

开发工作流程

# Clone your fork
git clone https://github.com/yourusername/metasploit-mcp-server.git

# Install dependencies
npm install

# Create a feature branch
git checkout -b feature/new-tool

# Make changes and test
npm test
npm run lint

# Commit and push
git commit -m "Add new tool for X"
git push origin feature/new-tool

代码标准

使用 ES 模块（import/export)
遵循JSDoc文档风格
保持测试覆盖率在80%以上
使用有意义的变量名和函数名
以结构化的响应优雅地处理错误

祝你编程愉快！ 🚀🔒（火箭🚀与锁🔒的组合，可象征快速且安全的推进或发展）