Pentesting MCP Server v2.0

Este repositorio contiene un servidor Model Context Protocol (MCP) diseñado para orquestar, normalizar y auditar operaciones de seguridad ofensiva y defensiva. Permite que agentes de IA (como Claude) interactúen con un ecosistema de herramientas de pentesting profesionales de forma segura y estructurada.

🚀 Propósito del Proyecto

El objetivo no es reemplazar al pentester humano, sino proporcionarle un agente inteligente capaz de ejecutar flujos de trabajo complejos, analizar resultados y generar reportes de forma autónoma bajo una supervisión estricta.

Diferenciadores Clave:

• Seguridad por Diseño (SCM): Validación rigurosa de alcance (scope) y políticas antes de cada ejecución.
• Auditoría Inmutable: Registro completo de cada acción con integridad asegurada por HMAC.
• Aprobación Humana (HITL): Las acciones críticas (explotación, robo de credenciales) requieren aprobación explícita de un operador.
• Sandboxing: Ejecución de herramientas en contenedores Docker aislados para prevenir efectos laterales no deseados.
• Modularidad Total: Capa de adaptadores para integrar fácilmente Nmap, Shodan, Nuclei, Metasploit, etc.

---

🏗️ Arquitectura del Sistema

El servidor se divide en tres planos operacionales:

Plano	Descripción	Control de Seguridad
Analítico	Búsqueda, correlación y generación de reportes.	Solo sesión activa
Reconocimiento	Interacción pasiva o no intrusiva (DNS, Escaneo de puertos).	Validación de Alcance (Scope)
Ofensivo	Explotación, manipulación de datos, exfiltración.	Aprobación Humana + Política

Estructura de Directorios:

• adapters/: Conectores específicos para herramientas externas (Nmap, Shodan, etc.).
• core/: Lógica central (Seguridad, Auditoría, Sandbox, Políticas).
• tools/: Definición de las herramientas expuestas vía MCP.
• plugins/: Módulos de alta criticidad (desactivados por defecto).
• models/: Esquemas de datos para entidades (Hosts, Findings, Sessions).

---

🛠️ Instalación y Configuración

Requisitos Previos

• Python 3.10+
• Docker (para ejecución de herramientas en sandbox)
• Llaves de API para servicios externos (opcional: Shodan, Censys)

Instalación

1. Clonar el repositorio:

   git clone https://github.com/anarcoiris/MCP_Pentesting.git
   cd MCP_Pentesting

2. Instalar dependencias:

   pip install -r requirements.txt

3. Configurar entorno:

   cp .env.example .env
   # Edita .env con tus API Keys y secretos

🌐 Conectividad de Red

Para que los contenedores Docker y las interfaces de usuario remotas puedan comunicarse con el servidor central:

• El Bridge API escucha por defecto en 0.0.0.0:8321. Esto permite conexiones desde el host, los contenedores y otros equipos de la red.
• CORS: En modo de laboratorio, se permite el acceso desde cualquier origen ("*") para facilitar el uso de la consola web desde cualquier dispositivo.
• Seguridad: Se recomienda encarecidamente usar un firewall para restringir el acceso al puerto 8321 únicamente a las IPs autorizadas.

4. Construir la imagen de Docker para el Sandbox:

   docker build -t mcp-kali-pentesting .

---

📖 Guía de Uso

Inicio del Servidor

El servidor utiliza el transporte stdio por defecto, diseñado para integrarse con clientes MCP.

python main.py

Configuración en Claude Desktop

Añade lo siguiente a tu archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "pentesting-mcp": {
      "command": "python",
      "args": ["C:/ruta/a/MCP_Pentesting/main.py"],
      "env": {
        "AUDIT_HMAC_SECRET": "tu_secreto_aqui",
        "AUTO_APPROVE_CRITICAL": "0"
      }
    }
  }
}

Flujo de Trabajo Típico

1. Crear Sesión: Define el alcance (IPs, dominios permitidos).
   • Herramienta: session_create
2. Reconocimiento Pasivo: Busca información en fuentes abiertas.
   • Herramientas: shodan_search, dns_lookup, whois_query.
3. Escaneo de Activos: Identifica hosts y servicios vivos.
   • Herramientas: ping_sweep, port_scan, subdomain_enum.
4. Análisis de Vulnerabilidades: Escaneo automático.
   • Herramientas: vuln_scan (Nuclei), nikto_scan, zap_scan.
5. Explotación (Requiere Aprobación): Ejecuta payloads específicos.
   • Herramientas: sql_injection, metasploit_run.
6. Reporting: Genera el informe final del engagement.
   • Herramientas: report_generate.

Caution

SEGURIDAD CRÍTICA: Las herramientas del Plano Ofensivo (SQLMap, Metasploit, etc.) están bloqueadas por defecto y requieren obligatoriamente la activación del nivel de ejecución L3 y la aprobación humana explícita (HITL) a través de la interfaz de mando. No intente saltar estos controles en entornos de producción.

---

🛡️ Seguridad y Auditoría

Security Control Model (SCM)

El servidor implementa un modelo de seguridad de 5 capas que rige cada invocación de herramienta. Para más detalles técnicos, consulte la Guía de Controles de Seguridad.

🚀 Getting Started with the Console

The easiest way to test the orchestration is using the new Interactive CLI Console.

1. Launch the Services: Run the following command in PowerShell to start the Bridge and the Console:

   ./launch.ps1

2. Start a Mission: Inside the console, type mission and enter an objective like:

   "Perform a port scan on 127.0.0.1 and check for open web services."

3. Monitor Thinking: You will see the agent's internal reasoning (Thoughts) and tool invocations in real-time.

4. Manage Approvals: If the agent attempts a high-risk action (like an exploit), it will pause. Type approvals to list pending requests and authorize them using their Request ID.

🛡️ Security Levels (SCM)

The SCM enforces five layers of validation:

• L0 (READ): Public info, safe.
• L1 (PROBE): Non-intrusive discovery.
• L2 (SCAN): Vulnerability scanning (Nuclei, Nikto).
• L3 (EXPLOIT): Active exploitation (Metasploit, SQLMap) -> Requires HITL Approval.
• L4 (CRITICAL): Post-exploitation, data exfiltration -> Requires Mandatory Human Authorization.

Auto-Aprobación: Es posible configurar rangos de red (CIDR) o dominios para auto-aprobación en entornos controlados (Lab/Staging), evitando la intervención manual para objetivos conocidos.

Audit Trail

Todos los logs se guardan en ./audit_trail/. Cada entrada incluye:

• Timestamp y ID de ejecución.
• Parámetros exactos utilizados.
• Resultado (o error) de la ejecución.
• Hash de integridad HMAC para prevenir manipulación.

---

⚠️ Aviso Legal

ESTA HERRAMIENTA ES SOLO PARA FINES EDUCATIVOS Y PRUEBAS DE SEGURIDAD AUTORIZADAS.

El uso de este software para atacar objetivos sin consentimiento previo es ilegal. Los desarrolladores no se hacen responsables del mal uso de esta herramienta o de cualquier daño causado. El usuario es el único responsable de asegurar que sus acciones cumplen con las leyes locales y los acuerdos de servicio.

---

🧠 SRE Knowledge Base (RAG)

El framework utiliza un sistema de Generación Aumentada por Recuperación (RAG) para potenciar las capacidades de ingeniería inversa de la IA.

Estructura de Directorios

• knowledge/sre/: Raíz de todo el conocimiento de SRE.
• knowledge/sre/ghidra_docs/: Documentación oficial de Ghidra convertida a Markdown.
• knowledge/sre/patterns/: Patrones de código y modismos binarios identificados.
• knowledge/sre/api_ref/: Referencias de API (Ghidra, SDL, Windows).
• knowledge/sre/devilutionx_mapping.md: La "Verdad Absoluta" sobre el mapeo actual del binario.

Cómo Añadir Conocimiento

1. Formato: Todos los archivos deben estar en Markdown (.md).
2. Carga Automática: El script scripts/reversing/ollama_re_expert.py escanea recursivamente knowledge/sre/ e inyecta el contenido en el contexto de Qwen antes de cada análisis.
3. Conversión: Usa scratch/convert_ghidra_docs.py para transformar materiales HTML (como los de GhidraClass) en Markdown compatible.
4. Mantenimiento: Mantén actualizado devilutionx_mapping.md para asegurar que la IA no pierda el hilo de las funciones ya identificadas.

Herramientas Live Recomendadas

• get_re_current_state: Sincroniza la IA con tu cursor en Ghidra.
• analyze_re_function: El "cerebro" del análisis. Decompilea, consulta el RAG y propone nombres/comentarios.
• rename_re_symbol: Aplica los nombres propuestos directamente en la base de datos de Ghidra.