mcp-seatbelt

Proteções de tempo de execução para ferramentas MCP de agentes de IA. Bloqueia chamadas de ferramentas perigosas em tempo de execução com um proxy de política de negação por padrão.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP Seatbelt — Proteção em Tempo de Execução para Ferramentas de Agentes de IA

Bloqueie chamadas de ferramentas MCP perigosas na camada de protocolo. Analise, faça proxy, aplique.

Parte da Plataforma de Segurança MCP. Analise antes de confiar com mcp-observatory (236★) e, em seguida, aplique em tempo de execução com mcp-seatbelt. 📄 Leia o whitepaper técnico.

🌐 Site: kryptosai.github.io/mcp-seatbelt — demonstração, comparação, preços

O Problema

Agentes de codificação de IA (Cursor, Claude, VS Code, ChatGPT, Windsurf e outros) conectam-se a servidores MCP que expõem sistemas de arquivos, interpretadores de shell, acesso à rede e variáveis de ambiente. Scanners estáticos dizem que você está exposto — mas eles agem depois do fato. Quando um scanner sinaliza um servidor arriscado, o agente pode já ter executado um comando destrutivo, exfiltrado credenciais ou alcançado um endpoint não confiável.

MCP Seatbelt adiciona uma camada de aplicação em tempo de execução. Ele atua como um proxy de políticas entre o agente e cada servidor MCP, avaliando cada chamada de ferramenta JSON-RPC contra regras que você controla e negando solicitações perigosas antes que elas cheguem ao upstream. Ele não opera no nível TCP — ele inspeciona e verifica cada chamada na camada L7 (a camada de protocolo MCP) antes de encaminhar.

O Que Ele Faz

Detecção e Proxy

Detecta configurações MCP em 8 clientes — Descobre automaticamente configurações de servidores MCP de Cursor, Claude Desktop, VS Code (usuário + workspace), ChatGPT Desktop, Codex, IDEs JetBrains (IntelliJ, PyCharm, WebStorm, etc.), Windsurf e arquivos locais do projeto (.mcp.json, .mcp/config.json). Nenhuma configuração manual necessária.
Proxy em tempo de execução com aplicação de políticas — Inicia um proxy transparente JSON-RPC 2.0 na porta 9420. Cada chamada de ferramenta, acesso a recurso e solicitação de prompt é interceptada, avaliada contra sua política e permitida, negada, alertada ou redigida. Três modos: default-deny (confiança zero), allowlist (lista de permissões de itens conhecidos) e audit (somente registro, sem bloqueio).
13 regras de risco integradas — Cobre interpretadores de shell (bash, sh, zsh, python, node), bypass de sandbox (--no-sandbox, --disable-web-security), exposição de credenciais em variáveis de ambiente, contêineres Docker privilegiados, ferramentas de rede brutas (curl, nc, telnet), spawn de processos, operações destrutivas no sistema de arquivos, acesso a URLs remotas, executores de pacotes arriscados (npx, uvx), escalonamento de privilégios (sudo, chmod) e caminhos sensíveis do sistema de arquivos.
Mecanismo de políticas com regras de janela de tempo, modo de aprendizado, herança de regras e consciência de contexto — As regras suportam correspondência de padrões regex, correspondência exata e contenção de substrings. Restrinja o acesso a ferramentas por dia da semana e intervalo de horas (timeWindow). Condicione regras à identidade do cliente ou à taxa de solicitações (contextCondition). Políticas podem extend modelos pai. O modo audit serve como modo de aprendizado: execute-o para observar o uso real de ferramentas antes de alternar para enforce.
Painel ao vivo, relatórios SARIF, integração CI/CD e ponte com observatório — Um painel HTML em tempo real mostra estatísticas de solicitações, taxas de bloqueio, clientes conectados e chamadas bloqueadas recentes. Gere relatórios SARIF 2.1.0 para GitHub Code Scanning. Importe descobertas de segurança do mcp-observatory e converta-as automaticamente em regras de política. mcp-seatbelt check sai com código diferente de zero no CI quando riscos críticos são detectados.
Timeouts por chamada — Chamadas de ferramentas travadas são encerradas e retornam um erro JSON-RPC limpo em vez de um 503 bruto. Configurável por regra (10s para comandos de shell, 60s para ferramentas seguras).

Segurança Avançada

Mapeamento OWASP LLM Top 10 — Cada chamada bloqueada é marcada com categorias OWASP (LLM01 Injeção de Prompt, LLM06 Agência Excessiva, etc.)
Mapeamento de frameworks de conformidade — Regras de política carregam tags de controle SOC2, HIPAA, GDPR, ISO 27001 e PCI-DSS
Detecção de cadeia de ataque em múltiplas etapas — Máquina de estados baseada em XState rastreia sequências de chamadas: reconhecimento → execução → persistência → exfiltração
Injeção e detecção de honeytokens — Planta credenciais iscas (chaves AWS, tokens GitHub, URLs de banco de dados) em respostas de ferramentas, alerta sobre acesso
Captura forense de sessão — Registra pares completos de solicitação/resposta como .mcpcap.json para análise de incidentes
Validação de argumentos ciente de esquema — Valida argumentos de ferramentas contra JSON Schemas declarados, detecta path traversal e injeção
Integração com inteligência de ameaças — Consulta o banco de dados de IOC do ThreatFox para verificações de reputação de IP/domínio
Fuzzing de entrada — Gera payloads de casos extremos contra regras de política para encontrar bypasses
Controle de acesso baseado em papéis — Permissões por agente com casbin. Administrador pode executar todas as ferramentas, agentes obtêm acesso limitado
DLP de resposta — Analisa respostas upstream em busca de padrões de segredos (chaves de API, tokens, chaves privadas) e os redige

Início 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

Na primeira execução, init cria .mcp-seatbelt/policy.yml (seu conjunto de regras editável) e .mcp-seatbelt/risk-report.md (um resumo de cada servidor e seus sinalizadores de risco). O proxy inicia no modo audit por padrão — observe o uso real de ferramentas e, em seguida, alterne para enforce quando estiver pronto.

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

As imagens são automaticamente construídas e publicadas em cada lançamento via GitHub Actions.

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

GitHub Action

Execute MCP Seatbelt como um gate de segurança de CI com a GitHub Action oficial — ela verifica configurações MCP detectadas, simula sua política contra chamadas de ferramentas representativas e falha o build em riscos críticos.

Integração CI/CD

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

Veja action.yml para todas as entradas, saídas e opções de aplicação.

Como 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 — Escuta solicitações JSON-RPC 2.0 de entrada do agente de IA. Gerencia registro de servidores, roteamento de URLs com proxy e ciclo de vida de conexões.
Mecanismo de Políticas — Avalia cada solicitação contra a política carregada. Verifica nome da ferramenta, argumentos e descrição contra regras. Retorna allow, deny, warn ou redact com motivos.
Interceptador — Aplica a decisão do mecanismo. Chamadas permitidas são encaminhadas. Chamadas negadas recebem uma resposta de erro MCP. Chamadas com alerta prosseguem, mas são registradas. redact substitui valores de argumentos que correspondem a padrões de credenciais por ***.
Cliente de Transporte — Encaminha solicitações permitidas ao servidor MCP upstream real e transmite respostas de volta ao agente.

O proxy nunca retorna um erro upstream bruto ao agente. Se uma chamada exceder seu timeout, o processo filho é encerrado e o agente recebe uma mensagem de erro limpa — sem 503s, sem conexões penduradas.

Cada solicitação flui por um pipeline de 11 estágios: RBAC → Validação de Esquema → Segurança de Caminho → Mecanismo de Políticas → Inteligência de Ameaças → Honeytokens → Cadeias de Ataque → Proxy → DLP de Resposta → Forense → Log de Auditoria.

Comparação

Recurso	mcp-seatbelt	mcp-firewall	mcp-guardian	Prismor	mcp-proxy
Bloqueio em tempo de execução	✓	✓	✓	✓	✗
Análise pré-instalação	✓	✗	✗	✗	✗
Detecção de 8+ clientes	✓	✗	✗	✗	✗
Redação de argumentos	✓	✗	✗	✗	✗
Modo de aprendizado	✓	✗	✗	✗	✗
Painel ao vivo	✓	✗	✓	✗	✗
SARIF / GitHub Code Scanning	✓	✗	✗	✗	✗
Integração com mcp-observatory	✓	✗	✗	✗	✗
Timeouts por chamada	✓	✗	✗	✗	✗
Mapeamento OWASP LLM Top 10	✓	✗	✗	✗	✗
Tags de conformidade (SOC2/HIPAA)	✓	✗	✗	✗	✗
Detecção de cadeia de ataque	✓	✗	✗	✗	✗
Detecção de honeytoken/injeção	✓	✗	✗	✗	✗
Validação ciente de esquema	✓	✗	✗	✗	✗
Inteligência de ameaças (consulta IOC)	✓	✗	✗	✗	✗
RBAC (acesso por agente)	✓	✗	✗	✗	✗

Seatbelt é a única ferramenta que combina análise pré-instalação com aplicação em tempo de execução, cobre todos os principais clientes de agentes de IA, redige argumentos de credenciais inline e conecta resultados de análise estática do mcp-observatory em regras de política ao vivo.

Recursos Avançados de Segurança

mcp-seatbelt inclui um pipeline de segurança em profundidade que avalia cada chamada de ferramenta por meio de múltiplas camadas:

Camada	Recurso	Descrição
1	RBAC	Controle de acesso baseado em papéis com casbin para agentes e ferramentas. `mcp-seatbelt rbac-init` gera arquivos de modelo e política.
2	Validação de Esquema	Validação de JSON Schema baseada em AJV de argumentos de ferramentas contra esquemas compilados.
3	Segurança de Caminho	Detecta path traversal, injeção de byte nulo e acesso a caminhos sensíveis em argumentos.
4	Mecanismo de Políticas	Avaliação baseada em regras com correspondência regex/exata/contém, janelas de tempo, condições de contexto e restrições de argumentos.
5	Inteligência de Ameaças	Consulta assíncrona de IOC do ThreatFox para IPs e domínios em argumentos de ferramentas.
6	Honeytokens	Planta credenciais iscas em respostas; detecta exfiltração quando honeytokens aparecem em chamadas subsequentes.
7	Rastreamento de Cadeia de Ataque	Máquina de estados baseada em XState rastreando padrões de ataque em múltiplas etapas (reconhecimento→execução→persistência→exfiltração).
8	Captura Forense	Registra todas as solicitações e respostas em arquivos de sessão `.mcpcap.json` assinados quando habilitado.
9	DLP de Resposta	Analisa respostas upstream em busca de padrões de segredos (chaves de API, tokens, chaves privadas) e os redige.
10	Fuzzing de Entrada	Gera payloads de casos extremos a partir de JSON schemas e testa resiliência a bypass de políticas. `mcp-seatbelt fuzz --policy policy.yml`

Fuzzing de Entrada

mcp-seatbelt fuzz gera argumentos de chamadas de ferramentas aleatórios usando json-schema-faker, injeta payloads de casos extremos (path traversal, injeção de comando, injeção SQL, Log4Shell) e avalia cada payload contra sua política. Bypasses são relatados com o payload específico e a regra que deveria tê-los bloqueado.

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

Referência 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

Novos Comandos (v0.4.0)

Comando	Descrição
`mcp-seatbelt fuzz`	Aplica fuzzing em uma política contra esquemas de ferramentas para encontrar bypasses
`mcp-seatbelt record`	Inicia proxy em modo de gravação forense
`mcp-seatbelt rbac-init`	Inicializa modelo RBAC e arquivos de política
`mcp-seatbelt simulate`	Simula uma chamada de ferramenta contra a política e mostra rastreamento de avaliação
`mcp-seatbelt benchmark`	Executa benchmarks de desempenho contra o proxy
`mcp-seatbelt test-policy`	Executa testes de política a partir de um arquivo YAML de teste
`mcp-seatbelt baseline`	Gera uma linha de base comportamental a partir de logs de auditoria
`mcp-seatbelt verify-audit`	Verifica integridade de logs de auditoria assinados

Regras Integradas (Política Padrão)

Regra	Alvo	Descrição
`block-shell-execution`	comando	Bloqueia invocações diretas de interpretadores de shell (bash, sh, zsh, cmd, powershell)
`block-sensitive-paths`	arquivo	Bloqueia gravações no sistema de arquivos em `/etc`, `/root`, `~/.ssh`, `~/.aws`, `C:\Windows`
`block-credential-access`	comando	Bloqueia ferramentas cujas descrições mencionam senhas, segredos, tokens, chaves
`redact-credentials`	comando	Redige valores de argumentos cujos nomes de chave correspondem a padrões de credenciais
`block-private-network`	rede	Bloqueia solicitações HTTP para faixas de endereços privados/loopback
`block-process-execution`	processo	Bloqueia ferramentas que geram processos filhos ou avaliam código
`allow-filesystem-writes-business-hours`	arquivo	Permite gravações no sistema de arquivos apenas de seg a sex, 09:00-17:00

Modelos de Políticas

Template	Ação Padrão	Caso de Uso
`minimal-workstation`	allow	Bloqueia apenas execução de shell e acesso a credenciais; todo o resto é permitido
`pci-compliance`	deny	Bloqueia shell, credenciais, caminhos de dados PAN/dados de cartão e adulteração de trilhas de auditoria
`strict-production`	deny	Bloqueia todas as chamadas de ferramentas, requisições de rede e operações de sistema de arquivos por padrão

Os templates podem ser estendidos por meio do campo extends no seu arquivo de política:

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

Esquema de Regras

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 Permissões

Entradas na lista de permissões ignoram todas as regras de negação. Use após executar init para colocar na lista de permissões ferramentas, caminhos, hosts e variáveis de ambiente conhecidos como seguros:

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

Guia de Integração com Clientes

Após iniciar o proxy, atualize a configuração MCP de cada cliente para rotear através de localhost:9420. O proxy imprime uma tabela de URLs de proxy na inicialização — copie e cole-os.

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 ou configurações do usuário

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

ChatGPT Desktop — Configuração do aplicativo

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

Codex / JetBrains / Windsurf — Mesmo padrão: substitua o transporte command/args por "url": "http://localhost:9420/<server-name>".

Combinado com mcp-observatory

mcp-observatory escaneia servidores MCP em repouso — auditando código-fonte, postura da cadeia de suprimentos e higiene de manifestos. O Seatbelt fornece a contraparte em tempo de execução.

Fluxo de trabalho:

Escaneie primeiro — Execute o mcp-observatory para auditar cada servidor MCP antes da instalação. Ele produz um artefato de descobertas de segurança (JSON).
Converta — mcp-seatbelt import-observatory ./observatory-results.json converte descobertas em regras de política.
Aplique em tempo de execução — O proxy carrega essas regras e bloqueia qualquer chamada de ferramenta que corresponda a uma descoberta do observatory, fechando o ciclo da análise estática à aplicação em tempo real.

A ponte do observatory (mergeObservatoryPolicy) pode mesclar descobertas em uma política existente do seatbelt sem sobrescrever suas regras personalizadas.

Desempenho

Medido em Apple M3, Node.js 22, macOS — 1.000 requisições com concorrência de 10 contra um upstream de resposta instantânea (mediana de 3 execuções, zero requisições com falha):

Métrica	Valor
Throughput	~2.000 req/s (vs ~4.300 req/s direto, sem proxy)
Latência ponta a ponta (p50)	~3,9 ms (adiciona ~2 ms sobre o direto)
Latência ponta a ponta (p95)	~6,6 ms
Avaliação de política (p50)	6,6 µs (7 regras); 8,5 µs (20 regras)
Avaliação de política (p95)	7,7 µs (7 regras)
Sobrecarga de DLP	~+0,1 ms por resposta
Sobrecarga de validação de esquema	< 1 µs por chamada
Memória (ocioso)	~74 MB
Memória (sob carga)	~74 MB (estável após 10.000 requisições)

O tamanho da política (1 → 20 regras) não tem impacto mensurável ponta a ponta; o custo por regra é de ~0,25 µs, muito abaixo da E/S de transporte. Metodologia completa e tabelas por cenário: docs/benchmarks.md. Execute mcp-seatbelt benchmark no seu próprio hardware.

Empresarial

mcp-observatory Cloud fornece painéis hospedados, varredura de CI privada, selos de certificação e relatórios de conformidade da cadeia de suprimentos para equipes e organizações. O Seatbelt integra-se como a camada de aplicação em tempo de execução — o observatory valida o que você instala; o seatbelt controla o que ele pode fazer no momento da execução.

Observatory Cloud: varredura hospedada, registros privados, painéis de equipe
Seatbelt: proxy na máquina com aplicação de política, redação e monitoramento ao vivo
Juntos: escaneie em repouso + aplique em tempo de execução = ciclo de vida completo de segurança MCP

Roadmap

Contribuindo

Consulte CONTRIBUTING.md para configuração de desenvolvimento, instruções de teste e diretrizes de pull requests. Problemas de segurança devem seguir o processo em SECURITY.md.

485 testes em 18 suítes de teste (CLI, detectores, motor de política, servidor proxy, interceptação de proxy, relatórios, módulos de segurança, RBAC, inteligência de ameaças, juiz LLM, forense, honeytokens, cadeias de ataque, validador de esquema, auditoria, notificações, linha de base, integração)
npm test executa a suíte completa do Vitest; npm run typecheck verifica TypeScript
PRs devem incluir testes para novas regras, detectores ou recursos de política

Licença

MIT — contribuidores do mcp-seatbelt