Skip to content

README.md

Latest commit

 

History

History
199 lines (149 loc) · 8.8 KB

README.md

File metadata and controls

199 lines (149 loc) · 8.8 KB
Raw

Pentesting MCP Server v2.0

Pentesting MCP Version License

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