pentestMCP

pentestMCP: Pruebas de penetración impulsadas por IA a través de MCP, un MCP diseñado para probadores de penetración.

Documentación

pentestMCP: Pruebas de penetración impulsadas por IA vía MCP

pentestMCP proporciona un puente potente entre los Modelos de Lenguaje Grande (LLMs) 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 Laurie Kirk y su GhidraMCP.

Tabla de contenido

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 host cliente
- Integración con Claude Desktop
- Integración con VS Code Copilot Chat
Referencia de herramientas
Consideraciones de seguridad
Contribuciones
Licencia
Descargo de responsabilidad
Agradecimientos

Demostración en video

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 host cliente MCP:

Aplicación host cliente (p. ej., 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.
LLM: Recibe las indicaciones del usuario y las definiciones de herramientas (de pentestMCP a través del host cliente). Decide qué herramientas invocar según el contexto.
Servidor pentestMCP (este proyecto): Se ejecuta dentro de un contenedor Docker. Escucha las solicitudes tools/call del host cliente, ejecuta la herramienta subyacente correspondiente (p. ej., nmap) y devuelve los resultados.
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/obtenció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 completo: Integra más de 20 herramientas esenciales de pruebas de penetración vía 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 garantiza 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 OWASP ZAP Active Scan y AJAX Spider.

Requisitos previos

Docker: Requiere que Docker Desktop (Windows/macOS) o Docker Engine (Linux) estén instalados y en ejecución. Asegúrate de que el daemon 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 host cliente 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 construcción local y garantiza que todas las herramientas (como gofang, nmap y nuclei) estén correctamente instaladas sin problemas de dependencias.

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 daemon 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.

Clona el repositorio:

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

Construye la imagen Docker:

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

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.
```
git clone https://github.com/danielmiessler/SecLists.git seclists
```

Integración con el host cliente

pentestMCP se ejecuta dentro de Docker y se comunica con el host cliente a través de stdio. Configuras tu host (p. ej., Claude Desktop, VS Code) para lanzar el servidor usando docker run -i ....

Integración con Claude Desktop

Localiza/Crea el archivo de configuración:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

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"
      ]
    }
  }
}

Reinicia Claude Desktop por completo.
Verifica: Busca el icono . Al hacer clic en él debería listar las herramientas de pentesting.
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.

Instala el requisito previo: Asegúrate de que la extensión de Github Copilot y las extensiones relevantes de GitHub Copilot estén instaladas.
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"
    ]
}
```
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.
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, hosts, ips).
- run_dig_tool: Ejecuta consultas DNS dig.
- fetch_whois_data: Recupera información WHOIS para 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 mismo 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 API de ZAP configurada proporciona control sobre la instancia.
Validación de entrada: Aunque MCP proporciona entrada estructurada, las herramientas subyacentes podrían seguir siendo vulnerables a argumentos manipulados si no se manejan de manera robusta dentro de las funciones envolventes de Python.

Contribuciones

¡Las contribuciones son muy bienvenidas! 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 características 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 ÚNICAMENTE a fines educativos y a 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 mal uso o los 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 profunda inspiración para este proyecto proviene de Laurie Kirk y su trabajo innovador en GhidraMCP.