MCPGuard-Lab

Un proyecto de experimentación de seguridad en la invocación de herramientas MCP basado en el SDK real mcp==2.0.0. No depende de modelos grandes externos ni de claves API, y completa la lista blanca de herramientas, la validación de parámetros, los límites de archivos, la protección SSRF, la confirmación de operaciones sensibles, la desinfección de salidas, la detección de envenenamiento de descripciones de herramientas y la auditoría JSONL mediante políticas deterministas. Además, utiliza casos de regresión para verificar que las protecciones no se vean comprometidas por cambios posteriores.

Límite de uso: Este proyecto está destinado únicamente a experimentos locales, pruebas autorizadas e investigación defensiva. No incluye funciones de ataque dirigidas a objetivos no autorizados.

Capacidades implementadas

• Pruebas de ida y vuelta entre un servidor stdio MCP 2.0 real y un cliente real.

• Seis herramientas de demostración: cálculo seguro, lectura de archivos dentro del directorio raíz, consulta de notas, solicitud de URL pública, inspección de metadatos de herramientas, y escritura de notas después de confirmación.

• Lista blanca de herramientas y validación estricta de JSON Schema, rechazando parámetros adicionales.

• Normalización de rutas de archivos, rechazando rutas absolutas, traversal de directorios y escape del directorio raíz.

• Verificación de protocolo URL, información de usuario, puerto, resultados de resolución DNS; rechazo de direcciones de loopback, privadas, link-local y otras no públicas.

• Puerta de acceso confirmed=true para operaciones de escritura.

• Etiquetado explícito de salidas de herramientas no confiables; desinfección recursiva de contraseñas, tokens, claves API y credenciales Bearer.

• Detección de señales de inyección de alto riesgo en nombres/descripciones de herramientas.

• Cada decisión se escribe en JSONL: ID de solicitud, hora, herramienta, parámetros, permitir/rechazar, motivo y resultado.

• Pruebas unitarias/integración con pytest e informe de regresión de ataques repetible.

Related MCP server: meok-mcp-injection-scan-mcp

Arquitectura

MCP Client
   │ stdio / MCP 2.0
   ▼
MCP Server ──► GuardedGateway ──► PolicyEngine
                      │                 ├─ allowlist + schema
                      │                 ├─ path boundary
                      │                 ├─ URL / SSRF
                      │                 └─ confirmation
                      ├─ Tool handler
                      ├─ untrusted labeling + redaction
                      └─ JSONL audit

El principio central es "primero decidir, luego ejecutar, luego purificar la salida, registrar todo el proceso". El texto del prompt no obtiene permisos adicionales directamente; los permisos se basan en la lista blanca y las políticas en el código.

Ejecución rápida (Windows)

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m mcpguard.regression

También se puede ejecutar directamente:

powershell -ExecutionPolicy Bypass -File .\scripts\verify.ps1

El informe se genera en:

• reports/regression-report.md

• reports/regression-report.json

• reports/regression-audit.jsonl

Ejemplo de configuración del cliente MCP

Primero ejecute pip install -e ., luego reemplace la siguiente estructura con la ruta absoluta del repositorio actual:

{
  "mcpServers": {
    "mcpguard-lab": {
      "command": "D:/path/to/mcpguard-lab/.venv/Scripts/python.exe",
      "args": ["-m", "mcpguard.server"],
      "env": {
        "MCPGUARD_WORKSPACE": "D:/path/to/mcpguard-lab/fixtures/workspace",
        "MCPGUARD_NOTES": "D:/path/to/mcpguard-lab/fixtures/workspace/notes",
        "MCPGUARD_AUDIT": "D:/path/to/mcpguard-lab/reports/audit.jsonl"
      }
    }
  }
}

Límites reales

• La detección de envenenamiento de descripciones de herramientas es una capa de reglas de alta señal, no puede reemplazar la revisión humana y la lista blanca fija.

• confirmed=true es una puerta de explicitación en experimentos locales; en producción se deben usar credenciales de confirmación emitidas por el sistema de identidad/UI del host, que no pueden ser falsificadas por el modelo.

• La herramienta URL actualmente tiene deshabilitadas las redirecciones para evitar que después de pasar la primera verificación se redirija a la red interna; la versión de producción también debe limitar el tamaño de la respuesta, el tipo de contenido y la red de salida.

• El etiquetado de contenido no confiable reduce el riesgo de que "los datos se interpreten como instrucciones", pero el agente host final aún debe cumplir con los límites de confianza.

• Los datos de regresión representan solo casos fijos dentro del repositorio, no garantizan el bloqueo de todas las inyecciones de prompt o todos los riesgos de MCP.

Índice

src/mcpguard/       核心实现
tests/              单元测试与真实 MCP stdio 集成测试
fixtures/           可公开的本地测试数据
reports/            自动生成的测试和审计证据
scripts/verify.ps1  一键验证入口

Referencias

• Model Context Protocol Python SDK

• AgentDojo