MCPwner

MCPwner

Cuidado con el Tejón

Servidor del Protocolo de Contexto de Modelo para investigación autónoma de seguridad

Compatible con:

Tabla de Contenidos

• Resumen
• Flujo de Trabajo
• Herramientas Integradas
• Plugins
• Instalación
• Documentación
• Arquitectura
• Persistencia de Datos
• Licencia

Resumen

MCPwner es un servidor MCP que le brinda a tu agente LLM un kit completo de herramientas de seguridad ofensiva. Expone más de 55 herramientas contenerizadas a través de una única interfaz MCP: SAST, SCA, secretos, IaC, reconocimiento, DAST, fuzzing guiado por cobertura, CodeQL (consultas integradas y personalizadas), un navegador sin interfaz, un servidor de callbacks OOB, un sandbox de scripts PoC con oráculos deterministas y un registro persistente de hallazgos.

La arquitectura está diseñada para investigación de vulnerabilidades impulsada por agentes: una única sesión de agente —independiente del modelo (Claude, Cursor, Kiro, Gemini o cualquier agente de codificación compatible con MCP)— recorre las fases de investigación (reconocimiento, auditoría de código, validación de PoC, revisión adversarial), registrando cada paso en el registro compartido de hallazgos. Cada hallazgo progresa desde la hipótesis hasta la prueba empírica y el informe verificado: "sin exploit, sin informe".

Nota: Este proyecto está en desarrollo activo. Aprende más sobre MCPs aquí.

Flujo de Trabajo

MCPwner es el servidor de herramientas; tu agente LLM es el cerebro. Un compromiso típico de investigación profunda:

El registro utiliza upserts de fusión profunda, por lo que el veredicto de review de una fase posterior nunca sobrescribe los datos de poc anteriores (y viceversa), y se mantiene consistente si el contexto del agente se reinicia a mitad del compromiso.

Herramientas Integradas

Reconocimiento

Subfinder	Amass	Nmap	Masscan	ffuf

bbot	httpx	Katana	gau	Arjun

wafw00f	Kiterunner

Pruebas Estáticas de Seguridad de Aplicaciones (SAST)

CodeQL	Psalm	Gosec	Bandit	Semgrep

Brakeman	PMD	NodeJsScan	Joern	YASA	OpenGrep

Fuzzing de Código Fuente

Atheris	Jazzer	Jazzer.js	PHP-Fuzzer

Escaneo de Secretos

Gitleaks	TruffleHog	detect-secrets	Whispers	Hawk-Eye

Análisis de Composición de Software (SCA)

Grype	Syft	OSV-Scanner	Retire.js

Seguridad de Infraestructura e IaC

Checkov	KICS	Terrascan	TFSec	Hadolint

Pruebas Dinámicas de Seguridad de Aplicaciones (DAST)

sqlmap	NoSQLMap	Commix	Dalfox	SSTImap

SSRFmap	jwt_tool	interactsh

Utilidades

Linguist	WireMock	Mitmproxy	aiohttp	Chromium w. Playwright

Validación de PoC

Sandbox de Scripts PoC
Ejecutor de oráculos deterministas

El sandbox de PoC ejecuta scripts de exploit en Python/bash escritos por el agente dentro de la red objetivo y devuelve un veredicto de oráculo determinista (aprobado/fallido según el código de salida o marcadores explícitos). Así es como MCPwner prueba bugs lógicos, IDOR/BOLA, condiciones de carrera y bypass de control de acceso que el DAST estándar no puede expresar.

Plugins

MCPwner admite un sistema de plugins opcional para herramientas específicas de dominio. Los plugins agregan servicios Docker, reglas de escaneo personalizadas y plantillas de informes sin modificar el núcleo. MCPwner funciona con o sin plugins instalados.

Plugins Disponibles

Habilitar un Plugin

1. Agrega el nombre del plugin a .env:

   PLUGINS=wp-scan
   COMPOSE_PROFILES=sast,dast,...,wp-scan
   

2. Usa el wrapper de compose para iniciar los servicios (incluye automáticamente los archivos compose del plugin):

   ./scripts/compose.sh up -d --build
   

   O usa el apilamiento manual de -f:

   docker compose -f docker-compose.yaml -f plugins/wp-scan/docker-compose.yaml --profile wp-scan up -d
   

Las herramientas de plugins (p. ej., wpscan, phpggc) se registran automáticamente mediante manifest.yaml y aparecen como herramientas MCP cuando sus contenedores están en buen estado.

Cómo escribir un plugin

Un plugin es un directorio bajo plugins/ con:

• docker-compose.yaml — servicios (contextos de compilación relativos a la raíz del proyecto para el apilamiento de -f)
• manifest.yaml — registro de herramientas (nombre, categoría, ruta de configuración, URL predeterminada)
• docker/ — Dockerfiles y código de servicio
• rules/ — reglas SAST personalizadas (opcional)
• templates/ — plantillas de informes (opcional)
• install.sh / uninstall.sh — scripts de configuración para instalaciones externas

Los plugins también pueden residir en un repositorio separado y vincularse a plugins/ mediante un enlace simbólico o install.sh.

Instalación

Requisitos previos

Requisitos del sistema:

• Docker Engine 20.10+ y Docker Compose 2.0+
• 8 GB de RAM como mínimo (se recomiendan 16 GB para ejecutar varias herramientas)
• 20 GB de espacio libre en disco (las imágenes de las herramientas de seguridad son grandes)
• Plataformas compatibles: Linux, macOS, Windows (con WSL2)

Cliente MCP:

• Claude Desktop, Cursor, Kiro o cualquier cliente compatible con MCP

Configuración

1. Clonar el repositorio:

   git clone https://github.com/nedlir/mcpwner.git
   cd mcpwner
   

2. Configurar el servidor:

   cp .env.example .env
   cp config/config.yaml.example config/config.yaml
   

3. Iniciar los servicios:

   docker compose up -d --build
   

4. Verificar que los servicios estén en ejecución:

   docker compose ps
   

Conectar tu IDE

Una vez que los contenedores Docker estén en ejecución, agrega MCPwner a tu cliente MCP.

Registro dinámico de herramientas: MCPwner usa Docker Compose profiles para categorías de herramientas opcionales. La variable COMPOSE_PROFILES del archivo .env controla qué contenedores se inician. El servidor MCP sondea los contenedores en ejecución al iniciar y registra solo las herramientas en buen estado; si un contenedor está caído, sus herramientas simplemente no aparecen. Linguist (detección de idioma / índice de hechos de código) se ejecuta incondicionalmente; las utilidades de pruebas dinámicas (Chromium, WireMock, mitmproxy, fuzzer) son opcionales y se activan con los perfiles dast y poc.

Instalación con un clic (requiere Docker en ejecución):

Configuración manual:

Agrega a tu archivo de configuración MCP (claude_desktop_config.json, mcp.json, etc.):

{
  "mcpServers": {
    "mcpwner": {
      "command": "docker",
      "args": ["exec", "-i", "mcpwner-server", "python", "src/server.py"],
      "env": {}
    }
  }
}

Reinicia tu cliente MCP para cargar la nueva configuración del servidor.

Escaneo de proyectos locales

Monta tus proyectos en el contenedor agregando un volumen en docker-compose.yaml:

services:
  mcpwner:
    volumes:
      - /path/to/your/projects:/mnt/projects:ro

Luego usa create_workspace con source_type="local" y source="/mnt/projects/my-project".

Documentación

Guías adicionales en la wiki del proyecto:

• Inicio rápido — inicia la flota de herramientas con COMPOSE_PROFILES y conecta el servidor MCP a tu cliente.
• Configuración — .env / COMPOSE_PROFILES, config.yaml y el mapa de puertos de herramientas.
• Solución de problemas — herramientas faltantes, contenedores en mal estado y fallos de compilación de imágenes.
• Agregar una herramienta — conecta un nuevo contenedor de escáner a la flota y al registro de herramientas.

¿Quieres contribuir? Consulta CONTRIBUTING.md para conocer el estilo de código, los hooks de pre-commit y las pruebas.

Arquitectura

graph LR
    subgraph IDE[" "]
        LLM[🤖<br/>LLM]
        Client[MCP Client]
        LLM -.-> Client
    end

    Server[MCPwner Server]

    SAST[SAST Tools]
    Secrets[Secrets Scanning]
    SCA[SCA Tools]
    Recon[Reconnaissance]
    CodeQL[CodeQL Service]
    Linguist[Language Detection]
    Utilities[Utilities]
    IaC[IaC Security]
    Fuzzing[Source Fuzzing]
    DAST[DAST Tools]
    PoC[PoC Sandbox]

    Client -->|JSON-RPC 2.0| Server
    Server -->|HTTP| SAST
    Server -->|HTTP| Secrets
    Server -->|HTTP| SCA
    Server -->|HTTP| Recon
    Server -->|HTTP| CodeQL
    Server -->|HTTP| Linguist
    Server -->|HTTP| Utilities
    Server -->|HTTP| IaC
    Server -->|HTTP| Fuzzing
    Server -->|HTTP| DAST
    Server -->|HTTP| PoC

    style LLM fill:#7C3AED,stroke:#5B21B6,stroke-width:3px,color:#fff
    style Client fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
    style Server fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#fff
    style SAST fill:#E74C3C,stroke:#C0392B,stroke-width:2px,color:#fff
    style Secrets fill:#9B59B6,stroke:#7D3C98,stroke-width:2px,color:#fff
    style SCA fill:#1ABC9C,stroke:#16A085,stroke-width:2px,color:#fff
    style Recon fill:#00BCD4,stroke:#0097A7,stroke-width:2px,color:#fff
    style CodeQL fill:#E67E22,stroke:#CA6F1E,stroke-width:2px,color:#fff
    style Linguist fill:#3498DB,stroke:#2874A6,stroke-width:2px,color:#fff
    style Utilities fill:#6D28D9,stroke:#4C1D95,stroke-width:2px,color:#fff
    style IaC fill:#059669,stroke:#047857,stroke-width:2px,color:#fff
    style Fuzzing fill:#B91C1C,stroke:#7F1D1D,stroke-width:2px,color:#fff
    style DAST fill:#D35400,stroke:#A04000,stroke-width:2px,color:#fff
    style PoC fill:#DC2626,stroke:#991B1B,stroke-width:2px,color:#fff
    style IDE fill:none,stroke:#ddd,stroke-width:2px,stroke-dasharray: 5 5

Principios de diseño:

• Aislamiento de contenedores para la ejecución de herramientas de seguridad
• Salida estandarizada (SARIF/JSON) para el consumo por LLM
• Registro dinámico de herramientas: solo los contenedores en buen estado aparecen como herramientas
• Registro persistente de hallazgos con semántica de fusión profunda entre fases de investigación
• Oráculos deterministas para la validación de PoC (código de salida, marcadores, callbacks OOB, ejecución de XSS)

Flujo de trabajo del agente

MCPwner es infraestructura de herramientas. Una sesión de agente única — independiente del modelo (Claude, Cursor, Kiro, Gemini o cualquier agente de codificación compatible con MCP) — impulsa todo el compromiso, ejecutando cada fase por sí misma (reconocimiento → mapeo de API → entorno → auditoría de código → investigación de vulnerabilidades → PoC → revisión) y registrando el progreso en el registro de hallazgos. No hay un servicio de orquestación ni un archivo de configuración separado: MCPwner expone herramientas, el agente proporciona el flujo de trabajo.

Para una subtarea larga y aislada — normalmente, levantar y manejar un entorno objetivo en vivo en un contenedor — el agente puede opcionalmente delegar a una sesión auxiliar si su host lo admite, pero el flujo nunca depende de ello.

Persistencia de datos

MCPwner persiste metadatos del espacio de trabajo, bases de datos de CodeQL y hallazgos entre reinicios de contenedores mediante almacenamiento basado en archivos en el volumen Docker compartido (/workspaces/.metadata/). El registro de hallazgos está siempre disponible (sin compuerta de estado de contenedor): es cómo el agente rastrea hallazgos entre fases y recupera el estado después de un reinicio de contexto.

Limpieza del espacio de trabajo:

• delete_files=True, delete_metadata=False — Libera espacio en disco, conserva el historial
• delete_files=True, delete_metadata=True — Eliminación completa
• delete_files=False, delete_metadata=True — Eliminar de la lista, conservar archivos

Licencia

Apache 2.0