mcp-seatbelt

Protecciones en tiempo de ejecución para las herramientas MCP de agentes de IA. Bloquea llamadas peligrosas a herramientas en tiempo de ejecución con un proxy de política de denegación por defecto.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP Seatbelt — Protecciones en Tiempo de Ejecución para Herramientas de Agentes de IA

Bloquea llamadas peligrosas a herramientas MCP en la capa de protocolo. Escanea, actúa como proxy, aplica políticas.

Parte de la Plataforma de Seguridad MCP. Escanea antes de confiar con mcp-observatory (236★), y luego aplica la política en tiempo de ejecución con mcp-seatbelt. 📄 Lee el documento técnico.

🌐 Sitio web: kryptosai.github.io/mcp-seatbelt — demo, comparación, precios

El Problema

Los agentes de codificación con IA (Cursor, Claude, VS Code, ChatGPT, Windsurf y otros) se conectan a servidores MCP que exponen sistemas de archivos, intérpretes de shell, acceso a red y variables de entorno. Los escáneres estáticos te dicen que estás expuesto, pero actúan después del hecho. Para cuando un escáner marca un servidor riesgoso, el agente ya puede haber ejecutado un comando destructivo, exfiltrado credenciales o contactado un endpoint no confiable.

MCP Seatbelt añade una capa de aplicación de políticas en tiempo de ejecución. Actúa como un proxy de políticas entre el agente y cada servidor MCP, evaluando cada llamada a herramienta JSON-RPC contra reglas que tú controlas y denegando solicitudes peligrosas antes de que lleguen al servidor upstream. No opera a nivel TCP — inspecciona y verifica cada llamada en la capa L7 (la capa de protocolo MCP) antes de reenviarla.

Qué Hace

Detección y Proxy

Detecta configuraciones MCP en 8 clientes — Descubre automáticamente configuraciones de servidores MCP desde Cursor, Claude Desktop, VS Code (usuario + espacio de trabajo), ChatGPT Desktop, Codex, IDEs JetBrains (IntelliJ, PyCharm, WebStorm, etc.), Windsurf y archivos locales del proyecto (.mcp.json, .mcp/config.json). Sin configuración manual.
Proxy en tiempo de ejecución con aplicación de políticas — Inicia un proxy JSON-RPC 2.0 transparente en el puerto 9420. Cada llamada a herramienta, acceso a recurso y solicitud de prompt es interceptada, evaluada contra tu política y permitida, denegada, advertida o redactada. Tres modos: default-deny (confianza cero), allowlist (lista blanca de lo conocido como seguro) y audit (solo registro, sin bloqueo).
13 reglas de riesgo integradas — Cubre intérpretes de shell (bash, sh, zsh, python, node), evasión de sandbox (--no-sandbox, --disable-web-security), exposición de credenciales en variables de entorno, contenedores privilegiados de Docker, herramientas de red sin procesar (curl, nc, telnet), creación de procesos, operaciones destructivas en el sistema de archivos, acceso a URLs remotas, ejecutores de paquetes riesgosos (npx, uvx), escalada de privilegios (sudo, chmod) y rutas sensibles del sistema de archivos.
Motor de políticas con reglas de ventana de tiempo, modo de aprendizaje, herencia de reglas y conciencia de contexto — Las reglas admiten coincidencia de patrones regex, coincidencia exacta y contención de subcadenas. Restringe el acceso a herramientas por día de la semana y rango horario (timeWindow). Condiciona reglas según la identidad del cliente o la tasa de solicitudes (contextCondition). Las políticas pueden extend plantillas padre. El modo audit sirve como modo de aprendizaje: ejecútalo para observar el uso real de herramientas antes de cambiar a enforce.
Panel en vivo, informes SARIF, integración CI/CD y puente con observatory — Un panel HTML en tiempo real muestra estadísticas de solicitudes, tasas de bloqueo, clientes conectados y llamadas bloqueadas recientes. Genera informes SARIF 2.1.0 para GitHub Code Scanning. Importa hallazgos de seguridad desde mcp-observatory y conviértelos automáticamente en reglas de política. mcp-seatbelt check sale con código distinto de cero en CI cuando se detectan riesgos críticos.
Tiempos de espera por llamada — Las llamadas a herramientas colgadas se eliminan y devuelven un error JSON-RPC limpio en lugar de un 503 sin procesar. Configurable por regla (10s para comandos de shell, 60s para herramientas seguras).

Seguridad Avanzada

Mapeo OWASP LLM Top 10 — Cada llamada bloqueada se etiqueta con categorías OWASP (LLM01 Inyección de Prompts, LLM06 Agencia Excesiva, etc.)
Mapeo de marcos de cumplimiento — Las reglas de política llevan etiquetas de control SOC2, HIPAA, GDPR, ISO 27001 y PCI-DSS
Detección de cadenas de ataque de múltiples pasos — Máquina de estados basada en XState que rastrea secuencias de llamadas: reconocimiento → ejecución → persistencia → exfiltración
Inyección y detección de honeytokens — Planta credenciales señuelo (claves AWS, tokens de GitHub, URLs de bases de datos) en respuestas de herramientas, alerta sobre acceso
Captura forense de sesiones — Registra pares completos de solicitud/respuesta como .mcpcap.json para análisis de incidentes
Validación de argumentos consciente del esquema — Valida argumentos de herramientas contra JSON Schemas declarados, detecta path traversal e inyección
Integración de inteligencia de amenazas — Consulta la base de datos de IOC de ThreatFox para verificaciones de reputación de IP/dominio
Fuzzing de entrada — Genera payloads de casos límite contra reglas de política para encontrar evasiones
Control de acceso basado en roles — Permisos por agente con casbin. El administrador puede ejecutar todas las herramientas, los agentes obtienen acceso limitado
DLP de respuestas — Escanea respuestas upstream en busca de patrones de secretos (claves API, tokens, claves privadas) y los redacta

Inicio Rápido

npm install -g @kryptosai/mcp-seatbelt  # or: brew install mcp-seatbelt
npx @kryptosai/mcp-seatbelt init        # scan all clients, assess risk, generate policy
npx mcp-seatbelt proxy         # start the enforcing proxy on port 9420
npx mcp-seatbelt dashboard     # view live stats at http://localhost:9421

En la primera ejecución, init crea .mcp-seatbelt/policy.yml (tu conjunto de reglas editable) y .mcp-seatbelt/risk-report.md (un resumen de cada servidor y sus banderas de riesgo). El proxy se inicia en modo audit por defecto — observa el uso real de herramientas, luego cambia a enforce cuando estés listo.

mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200    # find policy bypasses
mcp-seatbelt record --output .mcp-seatbelt/sessions                      # forensic recording mode
mcp-seatbelt rbac-init -o .mcp-seatbelt                                  # init RBAC model + policy files

Docker

Las imágenes se construyen y publican automáticamente en cada release mediante GitHub Actions.

docker run -p 9420:9420 -v $(pwd)/.mcp-seatbelt:/app/.mcp-seatbelt ghcr.io/kryptosai/mcp-seatbelt:latest proxy

GitHub Action

Ejecuta MCP Seatbelt como una puerta de seguridad de CI con la GitHub Action oficial — verifica las configuraciones MCP detectadas, simula tu política contra llamadas de herramientas representativas y falla la compilación ante riesgos críticos.

Integración CI/CD

- uses: KryptosAI/mcp-seatbelt@v0.4
  with:
    mode: enforce
    fail-on-critical: true

Consulta action.yml para todas las entradas, salidas y opciones de aplicación de políticas.

Cómo Funciona

┌─────────┐     JSON-RPC 2.0     ┌────────────────────────────────────┐     JSON-RPC 2.0     ┌─────────────┐
│  Agent  │ ────────────────────▶ │         MCP Seatbelt Proxy        │ ────────────────────▶ │  MCP Server │
│ (Cursor) │                      │          (localhost:9420)          │                       │  (filesystem)│
└─────────┘                      │                                    │                      └─────────────┘
                                 │  ┌──────────────┐  ┌───────────┐  │
                                 │  │ Policy Engine│──│Interceptor │  │
                                 │  │   ┌───────┐  │  │  ┌──────┐ │  │
                                 │  │   │ Rules  │  │  │  │Allow?│ │  │
                                 │  │   │Allowlist│  │  │  │Deny? │ │  │
                                 │  │   │Templates│  │  │  │Redact│ │  │
                                 │  │   │TimeWin │  │  │  │Warn? │ │  │
                                 │  │   └───────┘  │  │  └──────┘ │  │
                                 │  └──────────────┘  └─────┬─────┘  │
                                 │                          │        │
                                 │                    ┌─────▼─────┐  │
                                 │                    │ Transport │  │
                                 │                    │  Client   │  │
                                 │                    └───────────┘  │
                                 └────────────────────────────────────┘

Proxy — Escucha solicitudes JSON-RPC 2.0 entrantes del agente de IA. Gestiona el registro de servidores, el enrutamiento de URLs proxy y el ciclo de vida de las conexiones.
Motor de Políticas — Evalúa cada solicitud contra la política cargada. Verifica el nombre de la herramienta, los argumentos y la descripción contra las reglas. Devuelve allow, deny, warn o redact con razones.
Interceptor — Aplica la decisión del motor. Las llamadas permitidas se reenvían. Las llamadas denegadas reciben una respuesta de error MCP. Las llamadas advertidas continúan pero se registran. redact reemplaza los valores de argumentos que coinciden con patrones de credenciales con ***.
Cliente de Transporte — Reenvía solicitudes permitidas al servidor MCP upstream real y transmite las respuestas de vuelta al agente.

El proxy nunca devuelve un error upstream sin procesar al agente. Si una llamada excede su tiempo de espera, el proceso hijo se elimina y el agente recibe un mensaje de error limpio — sin 503, sin conexiones colgadas.

Cada solicitud fluye a través de un pipeline de 11 etapas: RBAC → Validación de Esquema → Seguridad de Rutas → Motor de Políticas → Inteligencia de Amenazas → Honeytokens → Cadenas de Ataque → Proxy → DLP de Respuestas → Forense → Registro de Auditoría.

Comparación

Característica	mcp-seatbelt	mcp-firewall	mcp-guardian	Prismor	mcp-proxy
Bloqueo en tiempo de ejecución	✓	✓	✓	✓	✗
Escaneo previo a la instalación	✓	✗	✗	✗	✗
Detección de 8+ clientes	✓	✗	✗	✗	✗
Redacción de argumentos	✓	✗	✗	✗	✗
Modo de aprendizaje	✓	✗	✗	✗	✗
Panel en vivo	✓	✗	✓	✗	✗
SARIF / GitHub Code Scanning	✓	✗	✗	✗	✗
Integración con mcp-observatory	✓	✗	✗	✗	✗
Tiempos de espera por llamada	✓	✗	✗	✗	✗
Mapeo OWASP LLM Top 10	✓	✗	✗	✗	✗
Etiquetado de cumplimiento (SOC2/HIPAA)	✓	✗	✗	✗	✗
Detección de cadenas de ataque	✓	✗	✗	✗	✗
Detección de honeytokens/inyección	✓	✗	✗	✗	✗
Validación consciente del esquema	✓	✗	✗	✗	✗
Inteligencia de amenazas (consulta IOC)	✓	✗	✗	✗	✗
RBAC (acceso por agente)	✓	✗	✗	✗	✗

Seatbelt es la única herramienta que combina escaneo previo a la instalación con aplicación de políticas en tiempo de ejecución, cubre todos los principales clientes de agentes de IA, redacta argumentos de credenciales en línea y conecta los resultados de análisis estático de mcp-observatory con reglas de política en vivo.

Características Avanzadas de Seguridad

mcp-seatbelt incluye un pipeline de seguridad de defensa en profundidad que evalúa cada llamada a herramienta a través de múltiples capas:

Capa	Característica	Descripción
1	RBAC	Control de acceso basado en roles con casbin para agentes y herramientas. `mcp-seatbelt rbac-init` genera archivos de modelo y política.
2	Validación de Esquema	Validación de JSON Schema basada en AJV de los argumentos de herramientas contra esquemas compilados.
3	Seguridad de Rutas	Detecta path traversal, inyección de byte nulo y acceso a rutas sensibles en argumentos.
4	Motor de Políticas	Evaluación basada en reglas con coincidencia regex/exacta/por contención, ventanas de tiempo, condiciones de contexto y restricciones de argumentos.
5	Inteligencia de Amenazas	Consulta asíncrona de IOC de ThreatFox para IPs y dominios en argumentos de herramientas.
6	Honeytokens	Planta credenciales señuelo en respuestas; detecta exfiltración cuando los honeytokens aparecen en llamadas posteriores.
7	Seguimiento de Cadenas de Ataque	Máquina de estados basada en XState que rastrea patrones de ataque de múltiples pasos (reconocimiento→ejecución→persistencia→exfiltración).
8	Captura Forense	Registra todas las solicitudes y respuestas en archivos de sesión firmados `.mcpcap.json` cuando está habilitado.
9	DLP de Respuestas	Escanea respuestas upstream en busca de patrones de secretos (claves API, tokens, claves privadas) y los redacta.
10	Fuzzing de Entrada	Genera payloads de casos límite a partir de JSON schemas y prueba la resiliencia de evasión de políticas. `mcp-seatbelt fuzz --policy policy.yml`

Fuzzing de Entrada

mcp-seatbelt fuzz genera argumentos de llamadas a herramientas aleatorizados usando json-schema-faker, inyecta payloads de casos límite (path traversal, inyección de comandos, inyección SQL, Log4Shell) y evalúa cada payload contra tu política. Las evasiones se reportan con el payload específico y la regla que debería haberlas bloqueado.

mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200 --json

Referencia de Políticas

CLI

mcp-seatbelt init --policy enforce     # generate an enforcing policy
mcp-seatbelt proxy --config my.yml     # start proxy with custom policy
mcp-seatbelt report --sarif           # SARIF 2.1.0 output for CI
mcp-seatbelt check                    # exit 1 if critical risks found
mcp-seatbelt diff old.yml new.yml     # compare two policy files
mcp-seatbelt import-observatory       # convert observatory findings to rules

Nuevos Comandos (v0.4.0)

Comando	Descripción
`mcp-seatbelt fuzz`	Fuzzea una política contra esquemas de herramientas para encontrar evasiones
`mcp-seatbelt record`	Inicia el proxy en modo de grabación forense
`mcp-seatbelt rbac-init`	Inicializa el modelo RBAC y los archivos de política
`mcp-seatbelt simulate`	Simula una llamada a herramienta contra la política y muestra el rastro de evaluación
`mcp-seatbelt benchmark`	Ejecuta benchmarks de rendimiento contra el proxy
`mcp-seatbelt test-policy`	Ejecuta pruebas de política desde un archivo YAML de pruebas
`mcp-seatbelt baseline`	Genera una línea base de comportamiento a partir de registros de auditoría
`mcp-seatbelt verify-audit`	Verifica la integridad de los registros de auditoría firmados

Reglas Integradas (Política Predeterminada)

Regla	Objetivo	Descripción
`block-shell-execution`	comando	Bloquea invocaciones directas de intérpretes de shell (bash, sh, zsh, cmd, powershell)
`block-sensitive-paths`	archivo	Bloquea escrituras al sistema de archivos en `/etc`, `/root`, `~/.ssh`, `~/.aws`, `C:\Windows`
`block-credential-access`	comando	Bloquea herramientas cuyas descripciones mencionan contraseñas, secretos, tokens, claves
`redact-credentials`	comando	Redacta valores de argumentos cuyos nombres de clave coinciden con patrones de credenciales
`block-private-network`	red	Bloquea solicitudes HTTP a rangos de direcciones privadas/loopback
`block-process-execution`	proceso	Bloquea herramientas que crean procesos hijos o evalúan código
`allow-filesystem-writes-business-hours`	archivo	Permite escrituras al sistema de archivos solo de lunes a viernes, 09:00-17:00

Plantillas de Políticas

Plantilla	Acción predeterminada	Caso de uso
`minimal-workstation`	permitir	Bloquea solo la ejecución de shell y el acceso a credenciales; todo lo demás está permitido
`pci-compliance`	denegar	Bloquea shell, credenciales, rutas de datos PAN/datos de tarjetahabiente, manipulación de registros de auditoría
`strict-production`	denegar	Bloquea todas las llamadas a herramientas, solicitudes de red y operaciones del sistema de archivos por defecto

Las plantillas se pueden extender mediante el campo extends en tu archivo de política:

version: '1'
mode: enforce
extends:
  - pci-compliance
rules:
  - id: custom-rule
    target: network
    match: pattern
    values: ['.*']
    action: deny

Esquema de reglas

rules:
  - id: example-rule                # unique identifier
    description: What this blocks   # human-readable explanation
    target: command                 # command | file | network | env | process
    match: pattern                  # exact | pattern | contains
    values:                         # list of strings or regex patterns
      - '^rm\s+-rf'
    action: deny                    # allow | deny | warn | redact
    timeWindow:                     # optional — restrict by day/hour
      days: [Monday, Tuesday, Wednesday, Thursday, Friday]
      startHour: 9
      endHour: 17
    contextCondition:               # optional — restrict by client or rate
      clientIn: [cursor, claude-desktop]
      maxRequestsPerMinute: 60

Lista de permitidos

Las entradas en la lista de permitidos omiten todas las reglas de denegación. Úsala después de ejecutar init para incluir en la lista blanca herramientas, rutas, hosts y variables de entorno conocidos como seguros:

allowlist:
  tools: [safe-tool, read-only-fs]
  paths: [/home/user/projects/]
  hosts: [api.github.com]
  envVars: [NODE_ENV, PATH]

Guía de integración de clientes

Después de iniciar el proxy, actualiza la configuración MCP de cada cliente para enrutar a través de localhost:9420. El proxy imprime una tabla de URLs de proxy al iniciarse — cópialas y pégalas.

Cursor — ~/.cursor/mcp.json

{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }

VS Code — .vscode/mcp.json o configuración de Usuario

{ "servers": { "my-server": { "url": "http://localhost:9420/my-server" } } }

ChatGPT Desktop — Configuración de la aplicación

{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }

Codex / JetBrains / Windsurf — Mismo patrón: reemplaza el transporte command/args con "url": "http://localhost:9420/<server-name>".

Combinado con mcp-observatory

mcp-observatory escanea servidores MCP en reposo — auditando código fuente, postura de la cadena de suministro e higiene de manifiestos. Seatbelt proporciona la contraparte en tiempo de ejecución.

Flujo de trabajo:

Escanea primero — Ejecuta mcp-observatory para auditar cada servidor MCP antes de la instalación. Produce un artefacto de hallazgos de seguridad (JSON).
Convierte — mcp-seatbelt import-observatory ./observatory-results.json convierte los hallazgos en reglas de política.
Aplica en tiempo de ejecución — El proxy carga esas reglas y bloquea cualquier llamada a herramienta que coincida con un hallazgo de observatory, cerrando el ciclo desde el análisis estático hasta la aplicación en vivo.

El puente de observatory (mergeObservatoryPolicy) puede fusionar hallazgos en una política de seatbelt existente sin sobrescribir tus reglas personalizadas.

Rendimiento

Medido en Apple M3, Node.js 22, macOS — 1,000 solicitudes con concurrencia 10 contra un upstream de respuesta instantánea (mediana de 3 ejecuciones, cero solicitudes fallidas):

Métrica	Valor
Rendimiento	~2,000 req/s (vs ~4,300 req/s directo, sin proxy)
Latencia de extremo a extremo (p50)	~3.9 ms (añade ~2 ms sobre el directo)
Latencia de extremo a extremo (p95)	~6.6 ms
Evaluación de política (p50)	6.6 µs (7 reglas); 8.5 µs (20 reglas)
Evaluación de política (p95)	7.7 µs (7 reglas)
Sobrecarga de DLP	~+0.1 ms por respuesta
Sobrecarga de validación de esquema	< 1 µs por llamada
Memoria (inactivo)	~74 MB
Memoria (bajo carga)	~74 MB (plana después de 10,000 solicitudes)

El tamaño de la política (1 → 20 reglas) no tiene impacto medible de extremo a extremo; el costo por regla es ~0.25 µs, muy por debajo de la E/S de transporte. Metodología completa y tablas por escenario: docs/benchmarks.md. Ejecuta mcp-seatbelt benchmark en tu propio hardware.

Empresarial

mcp-observatory Cloud proporciona paneles alojados, escaneo CI privado, insignias de certificación e informes de cumplimiento de la cadena de suministro para equipos y organizaciones. Seatbelt se integra como la capa de aplicación en tiempo de ejecución — observatory valida lo que instalas; seatbelt controla lo que puede hacer en el momento de la ejecución.

Observatory Cloud: escaneo alojado, registros privados, paneles de equipo
Seatbelt: proxy en la máquina con aplicación de políticas, redacción y monitoreo en vivo
Juntos: escanea en reposo + aplica en tiempo de ejecución = ciclo de vida completo de seguridad MCP

Hoja de ruta

Contribuciones

Consulta CONTRIBUTING.md para la configuración de desarrollo, instrucciones de prueba y pautas de solicitudes de extracción. Los problemas de seguridad deben seguir el proceso en SECURITY.md.

485 pruebas en 18 suites de pruebas (CLI, detectores, motor de políticas, servidor proxy, interceptación de proxy, informes, módulos de seguridad, RBAC, inteligencia de amenazas, juez LLM, forense, honeytokens, cadenas de ataque, validador de esquemas, auditoría, notificaciones, línea base, integración)
npm test ejecuta la suite completa de Vitest; npm run typecheck verifica TypeScript
Las solicitudes de extracción deben incluir pruebas para nuevas reglas, detectores o características de políticas

Licencia

MIT — contribuyentes de mcp-seatbelt