vuln_mcp_app

Un laboratorio de seguridad del Model Context Protocol (MCP) intencionadamente vulnerable y ejecutable localmente — un objetivo controlado (conceptualmente un "DVWA para MCP") utilizado para evaluar un escáner de seguridad de un PFG independiente. Esta aplicación es el objetivo, no el escáner. Aloja un pequeño conjunto documentado de vulnerabilidades MCP y emite evidencia; nunca informa de si es vulnerable (sin oráculo, SEC-006).

⚠️ Uso exclusivamente educativo / de investigación. Todo se ejecuta localmente con datos sintéticos y secretos ficticios (DEMO_SECRET_*). Sin credenciales reales, sin objetivos externos, sin escaneo de Internet, sin acceso al host.

Alcance (exactamente tres laboratorios)

No hay laboratorios de vulnerabilidad adicionales en el alcance. Cada laboratorio implementado incluye un modo VULNERABLE y un modo SECURE genuinamente corregido.

Related MCP server: vuln-mcp-server

Ejecutarlo (sin Docker — un comando + un navegador)

Toda la aplicación se ejecuta desde un único proceso uvicorn: FastAPI sirve la interfaz compilada en / y la API bajo /api.

Primera vez

# 1) Build the UI once (Node 18+). Produces frontend/dist.
cd frontend && npm install && npm run build && cd ..

# 2) Run the app (uv resolves Python deps automatically; Python 3.12+).
uv run uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

A continuación, abre http://127.0.0.1:8000 — aparece la interfaz del laboratorio. La documentación interactiva de la API está en http://127.0.0.1:8000/docs.

¿Prefieres un venv clásico en lugar de uv?

python -m venv .venv && source .venv/Scripts/activate   # Windows Git Bash
pip install -r backend/requirements.txt
uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

Después de la primera compilación

Simplemente ejecuta el comando uvicorn y abre el navegador. Recompila la interfaz (npm run build) solo después de cambiar el código del frontend.

Recarga en caliente del frontend (opcional, para desarrollo de la interfaz)

Ejecuta la API en :8000 y el servidor de desarrollo de Vite en :5173 (hace proxy de /api):

# terminal 1
uv run uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000
# terminal 2
cd frontend && npm run dev      # open http://127.0.0.1:5173

Pruebas

# Backend (pytest)
uv run pytest                    # or: .venv/Scripts/python -m pytest

# Frontend (Vitest + tsc)
cd frontend && npm test && npx tsc --noEmit

Arquitectura

Browser (React SPA, served by FastAPI at :8000)
        │  HTTP/JSON  (/api)
        ▼
  FastAPI control plane (ordinarily secure)  ── MCP client ──►  MCP tool registry
        │                                                        (vulnerable | secure)
        ▼                                                              │
   SQLite (labs, tools, telemetry, evidence)  ◄── telemetry/evidence ─┘

El plano de control es infraestructura normalmente segura (SEC-004). Solo las herramientas del plano MCP claramente etiquetadas se vuelven vulnerables, y únicamente en modo vulnerable. Los archivos intencionadamente vulnerables llevan un aviso: # INTENTIONALLY VULNERABLE — <VULN-ID> — see docs/GROUND-TRUTH.md.

Transporte MCP: La fase 0 utiliza un transporte de registro en proceso para que toda la aplicación se ejecute en un solo proceso. El transporte MCP streamable-HTTP (SDK oficial) es una mejora futura detrás de la misma API de cliente.

Sandbox MCP05 (cuando se construya): con Docker eliminado, la ejecución de comandos para el laboratorio MCP05 se ejecuta en un ejecutor de subprocesos restringido en proceso — un directorio de trabajo temporal efímero, un shim convert falso proporcionado por el proyecto, un tiempo de espera máximo estricto y sin shell en modo seguro. El radio de explosión permanece local y sintético (SEC-001/003); el aislamiento a nivel de SO que proporcionaba Docker (sin red, cap-drop) se sustituye por ese ejecutor restringido. Ver sandbox/README.md.

Pila tecnológica

React + TypeScript + Vite + Tailwind · Python 3.12 + FastAPI + Pydantic v2 · SDK oficial de MCP para Python · SQLite + SQLModel · pytest + httpx · Vitest + Testing Library. Se ejecuta con uv/uvicorn (sin Docker).

Superficies de API (analizables por el PFG)

GET /api/health · GET /api/labs · GET /api/labs/{id} · POST /api/labs/{id}/mode|reset|attack|start · GET /api/labs/{id}/telemetry · GET /api/mcp/servers|tools · GET /api/mcp/tools/{id} · POST /api/mcp/tools/{id}/call · GET /api/vulnerabilities (solo metadatos del catálogo) · GET /api/evidence.

Ningún endpoint revela un veredicto de vulnerabilidad (SEC-006).

Uso contra el PFG (bucle de evaluación)

1. Inicia el objetivo (MCP03 está vulnerable por defecto). 2. Confirma que el laboratorio está activo mediante la verificación manual en docs/GROUND-TRUTH.md. 3. Ejecuta el PFG contra las superficies HTTP + MCP. 4. Compara los hallazgos con docs/GROUND-TRUTH.md.

2. Cambia a Secure y vuelve a ejecutar para medir los falsos positivos. 6. Restablece y repite.

Documentación del proyecto

• docs/GROUND-TRUTH.md — la clave de respuestas (por vulnerabilidad + matriz).

• docs/OWASP-MCP-MAPPING.md — mapeo del OWASP MCP Top 10.

• docs/TEST-SCENARIOS.md — escenarios de validación del PFG.

• CLAUDE.md — memoria de implementación / estado de la fase actual.

• docs/PRD.md, docs/TDD.md — contratos de diseño, mantenidos solo localmente (ignorados por git). Actualizados el 2026-08-21 al modelo de ejecución sin Docker.

Estado actual

MCP03 y MCP05 completos (todas las fases). Se ejecutan sin Docker mediante uvicorn. MCP10 está esbozado en el catálogo y aún no está construido. Ver CLAUDE.md.