pentestMCP: Pruebas de penetración impulsadas por IA mediante MCP

pentestMCP proporciona un puente potente entre los Modelos de Lenguaje Grande (LLM) y las herramientas prácticas de pruebas de penetración a través del Protocolo de Contexto de Modelo (MCP). Este proyecto funciona como un Servidor MCP, exponiendo un conjunto seleccionado de más de 20 utilidades estándar de evaluación de seguridad (Nmap, Nuclei, ZAP, SQLMap, etc.) como 'herramientas' invocables. Esto permite que los agentes de IA dentro de clientes compatibles con MCP (como Claude Desktop o configuraciones específicas de VS Code) aprovechen estas utilidades para tareas de análisis de seguridad automatizadas e interactivas.

El objetivo es permitir el control en lenguaje natural sobre flujos de trabajo de seguridad complejos, haciendo que las capacidades de pentesting sean más accesibles e integradas en entornos impulsados por IA. Este trabajo está inspirado en GhidraMCP de Laurie Kirk.

Tabla de Contenidos

• Conceptos Clave y Arquitectura

• Características Principales

• Requisitos Previos

• Instalación y Configuración

  • Uso de la Imagen Docker Preconstruida (Recomendado)

  • Construcción de la Imagen Docker Localmente

• Integración con el Cliente Anfitrión

  • Integración con Claude Desktop

  • Integración con VS Code Copilot Chat

• Referencia de Herramientas

• Consideraciones de Seguridad

• Contribuciones

• Licencia

• Descargo de responsabilidad

• Agradecimientos

Related MCP server: redteam-mcp

Demostración en Vídeo

https://github.com/user-attachments/assets/930c879a-5cb4-478a-b033-f30df0e770a6

Conceptos Clave y Arquitectura

pentestMCP se adhiere estrictamente a la especificación MCP, funcionando únicamente como un Servidor MCP. No incorpora ni se comunica directamente con ningún LLM específico. El flujo de interacción está mediado por una aplicación Cliente Anfitrión MCP:

1. Aplicación Cliente Anfitrión (por ejemplo, Claude Desktop, agente personalizado): Se conecta a pentestMCP (normalmente a través de stdio intermediado por Docker), gestiona la interacción del usuario e interactúa con un LLM elegido.

2. LLM: Recibe las indicaciones del usuario y las definiciones de herramientas (de pentestMCP a través del Cliente Anfitrión). Decide qué herramientas invocar según el contexto.

3. Servidor pentestMCP (Este Proyecto): Se ejecuta dentro de un contenedor Docker. Escucha las solicitudes tools/call del Cliente Anfitrión, ejecuta la herramienta subyacente correspondiente (por ejemplo, nmap) y devuelve los resultados.

4. Herramientas Externas: Las utilidades de línea de comandos reales encapsuladas dentro de la imagen Docker.

El servidor está construido con el SDK de Python para MCP (mcp.server.fastmcp.FastMCP) y cuenta con:

• Descubrimiento de Herramientas: Utiliza sugerencias de tipo y docstrings de Python para la generación automática del esquema de herramientas MCP.

• Control de Concurrencia: Un threading.Semaphore limita la ejecución simultánea de escaneos intensivos en recursos.

• Patrón de Escaneo Asíncrono: Implementa métodos de lanzamiento/recuperación para tareas de larga duración (Nmap, Nuclei, SQLMap, Gobuster) para evitar bloquear la conexión MCP.

sequenceDiagram
    participant User
    participant ClientHost as Client Host (Claude, VS Code)
    participant LLM
    participant PentestMCP as pentestMCP Server (Docker via stdio)
    participant ExtTool as External Tool (e.g., Nmap)

    User->>ClientHost: "Perform Nmap service scan on scanme.nmap.org"
    ClientHost->>PentestMCP: tools/list Request
    PentestMCP-->>ClientHost: List of Tools (including 'run_nmap_scan')
    ClientHost->>LLM: User Prompt + Available Tools Description
    LLM-->>ClientHost: Decision: Use 'run_nmap_scan', target='scanme.nmap.org', args='-sV'
    ClientHost->>PentestMCP: tools/call (name='run_nmap_scan', args={...})
    Note over PentestMCP, ExtTool: pentestMCP executes 'nmap -sV scanme.nmap.org' internally
    PentestMCP-->>ClientHost: tools/call Result (pid, output_path for async or direct output)
    ClientHost->>LLM: Tool Execution Result
    LLM-->>ClientHost: Formulate Final Response
    ClientHost-->>User: "Nmap scan launched/completed. Results..."

Características Principales

• Conjunto de Herramientas Integral: Integra más de 20 herramientas esenciales de pruebas de penetración a través de MCP.

• Acceso Estandarizado: Permite que cualquier cliente MCP que admita el lanzamiento de servidores stdio utilice flujos de trabajo complejos de pentesting.

• Escaneos No Bloqueantes: Maneja eficientemente escaneos de larga duración sin bloquear el flujo de interacción.

• Gestión de Recursos: Implementa limitación básica de concurrencia para escaneos.

• Portátil y Reproducible: El entorno Dockerizado asegura que todas las dependencias y herramientas estén disponibles de manera consistente en todas las plataformas (Windows, macOS, Linux).

• Integración de Escáner Web: Proporciona control directo sobre las funcionalidades de Escaneo Activo y Araña AJAX de OWASP ZAP.

Requisitos Previos

• Docker: Requiere Docker Desktop (Windows/macOS) o Docker Engine (Linux) instalado y en ejecución. Asegúrate de que el demonio de Docker esté activo.

• Git: Solo se necesita si se construye la imagen localmente (paso git clone).

• (Opcional pero Recomendado) Instancia de OWASP ZAP: Para usar herramientas relacionadas con ZAP (run_zap_*, run_active_scan_*, run_ajax_*). Esta instancia de ZAP debe estar en ejecución y ser accesible desde la red dentro del contenedor Docker de pentestMCP (consulta la sección de Integración con el Cliente Anfitrión para la configuración).

Instalación y Configuración

Recomendamos usar la imagen Docker preconstruida para la configuración más rápida y confiable.

🐳 Uso de la Imagen Docker Preconstruida (Recomendado)

El uso de la imagen preconstruida evita los tiempos de compilación locales y asegura que todas las herramientas (como gofang, nmap y nuclei) estén correctamente instaladas sin problemas de dependencias.

1. Descarga la imagen desde Docker Hub:

   docker pull ramgameer/pentest-mcp:latest

   ℹ️ Nota: Dependiendo de tu entorno, es posible que necesites autenticarte o asegurarte de que el demonio de Docker esté en ejecución.

🛠️ Construcción de la Imagen Docker Localmente

⚠️ IMPORTANTE: La construcción local es actualmente más eficiente y compatible en entornos Linux.

Si deseas modificar el código del servidor, usar la versión más reciente, o si la imagen preconstruida no está disponible, puedes construir la imagen Docker localmente.

1. Clona el repositorio:

   git clone https://github.com/ramkansal/pentestMCP.git
   cd pentestMCP

2. Construye la imagen Docker:

   docker build -t pentest-mcp-server:custom .

3. Instala SecLists (Opcional pero muy recomendado):

   💡 Consejo: Varias herramientas (como Gobuster y utilidades de fuzzing) dependen de listas de palabras masivas. Debes clonar el repositorio de SecLists para que estos escaneos específicos funcionen de manera efectiva. GXP5

Integración con el Cliente Anfitrión

pentestMCP se ejecuta dentro de Docker y se comunica con el Cliente Anfitrión a través de stdio. Configuras tu anfitrión (por ejemplo, Claude Desktop, VS Code) para lanzar el servidor usando docker run -i ....

Integración con Claude Desktop

1. Localiza/Crea el Archivo de Configuración:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Edita la Configuración: Agrega/actualiza la sección mcpServers. Usa el nombre de imagen correcto (ramgameer/pentest-mcp:latest o tu etiqueta personalizada).

   {
     "mcpServers": {
       "pentestMCP": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "ramgameer/pentest-mcp:latest"
         ]
       }
     }
   }

3. Reinicia Claude Desktop por completo.

4. Verifica: Busca el icono . Al hacer clic en él debería aparecer la lista de herramientas de pentesting.

5. Interactúa: Pide a Claude que use las herramientas (consulta ejemplos en el borrador).

Integración con VS Code Copilot Chat

La integración requiere configurar los ajustes de VS Code para definir el servidor MCP para los agentes de Copilot Chat que admiten MCP.

1. Instala el Requisito Previo: Asegúrate de que la extensión de GitHub Copilot y las extensiones relevantes de GitHub Copilot estén instaladas.

2. Configura los Ajustes de VS Code: Abre tu archivo settings.json de Usuario o Espacio de Trabajo (Paleta de Comandos: "Preferencias: Abrir Configuración (JSON)"). Agrega la configuración del servidor MCP en la ruta adecuada (esta ruta puede cambiar según la implementación específica del agente de Copilot Chat, consulta su documentación):

   "pentest-mcp": {
       "type": "stdio",
       "command": "docker",
       "args": [
           "run",
           "-i",
           "--rm",
           "ramgameer/pentest-mcp:latest"
       ]
   }

3. Recarga VS Code / Agente: Reinicia VS Code o usa los comandos relevantes para recargar la configuración del agente de Copilot para que los cambios surtan efecto. Consulta la documentación del agente de Copilot específico para más detalles.

4. Interactúa: Usa la interfaz de Copilot Chat, potencialmente invocando herramientas mediante menciones si el agente lo admite, o deja que el agente las invoque según tus indicaciones.

Referencia de Herramientas

El servidor expone una variedad de herramientas categorizadas por función:

• Reconocimiento y Enumeración:

  • run_subfinder: Descubre subdominios usando Subfinder de ProjectDiscovery.

  • launch_nmap_scan / fetch_nmap_results: Ejecuta escaneos de red con Nmap y recupera los resultados de forma asíncrona.

  • run_gobuster_scan / check_gobuster_status: Realiza fuerza bruta de directorios/archivos/DNS con Gobuster de forma asíncrona.

  • launch_gofang_scan / fetch_gofang_results: Ejecuta gofang, un rastreador web todo en uno con superpoderes de extracción.

  • run_harvester / check_harvester_status: Ejecuta theHarvester de forma asíncrona para la recopilación de OSINT (correos electrónicos, hosts, IPs).

  • run_dig_tool: Ejecuta consultas dig de DNS.

  • fetch_whois_data: Recupera información WHOIS de un dominio.

  • run_curl_tool: Ejecuta comandos cURL para interacción HTTP.

• Escaneo de Vulnerabilidades:

  • launch_nuclei_scan / fetch_nuclei_results: Ejecuta escaneos de vulnerabilidades basados en plantillas con Nuclei de ProjectDiscovery de forma asíncrona.

• Análisis de Aplicaciones Web:

  • launch_arjun_scan / fetch_arjun_results: Localiza parámetros HTTP ocultos usando Arjun.

• Soporte de Explotación:

  • run_searchsploit: Busca en la base de datos local de Exploit-DB usando Searchsploit.

  • run_sqlmap_tool / check_sqlmap_status: Ejecuta SQLmap para pruebas de inyección SQL de forma asíncrona.

• Análisis de Active Directory (herramientas ad_*):

  • Enumeración: ad_user_enum, ad_shares_enum, ad_smb_signing_check, ad_certipy_enum, ad_ldap_dump, ad_bloodhound_collect

  • Ataques/Coerción: ad_asreproast, ad_kerberoast, ad_password_spray, ad_coerce_petitpotam, ad_coerce_printerbug, ad_responder_poison, ad_relay_setup

  • Operaciones de Credenciales/Dominio: ad_check_credentials, ad_secrets_dump, ad_dcsync

Consideraciones de Seguridad

• Permisos de Ejecución: Las herramientas se ejecutan como appuser dentro de Docker, pero Docker en sí se ejecuta con privilegios del host. Ten cuidado con las herramientas que modifican archivos o requieren acceso elevado al sistema.

• Autorización del Objetivo: CRÍTICO: Solo usa estas herramientas contra sistemas para los cuales tengas autorización explícita, previa y por escrito. El escaneo no autorizado es ilegal y poco ético.

• Exposición de Red: Si mapeas el puerto de ZAP (-p 8888:8888), asegúrate de que el firewall de tu host restrinja el acceso si la máquina está en una red no confiable. La clave de API de ZAP configurada proporciona control sobre la instancia.

• Validación de Entrada: Aunque MCP proporciona entrada estructurada, las herramientas subyacentes aún podrían ser vulnerables a argumentos manipulados si no se manejan de manera robusta dentro de las funciones envolventes de Python.

Contribuciones

¡Se anima encarecidamente a contribuir! Haz un fork del repositorio, crea una rama de características y envía una solicitud de extracción. Asegúrate de cumplir con las pautas de pruebas éticas en todas las contribuciones. Los informes de errores y las sugerencias de funciones son bienvenidos a través de GitHub Issues.

Licencia

Este proyecto se distribuye bajo los términos de la Licencia MIT.

Descargo de responsabilidad

Este software está destinado EXCLUSIVAMENTE a fines educativos y pruebas de seguridad autorizadas y éticas. Cualquier uso contra sistemas sin permiso explícito está estrictamente prohibido y es ilegal. Los autores y colaboradores NO asumen ninguna responsabilidad por el uso indebido o daños resultantes de este programa. Úsalo bajo tu propio riesgo y asegúrate de cumplir con todas las leyes y acuerdos aplicables.

Agradecimientos

La inspiración profunda para este proyecto proviene del trabajo innovador de Laurie Kirk en GhidraMCP.