⚠️ Este repositório foi movido. O desenvolvimento ativo continua em ScopeBlind/scopeblind-gateway.

Este fork pessoal pode estar desatualizado em relação ao repositório canônico. Por favor, use o repositório da organização para issues, pull requests e o código mais recente.

protect-mcp

Gateway de segurança para servidores MCP. Por padrão, registra em modo de observação, políticas por ferramenta, recibos Ed25519 opcionais locais e saída de auditoria amigável para verificação.

Caminho atual da CLI: envolve qualquer servidor MCP stdio como um proxy transparente. Em modo de observação, registra toda requisição tools/call e permite tudo. Adicione um arquivo de política para aplicar regras por ferramenta. Execute protect-mcp init para gerar chaves de assinatura locais e configuração, para que o gateway também possa emitir recibos assinados.

Início Rápido

# Envolver uma configuração OpenClaw / MCP existente em um pacote utilizável
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# Modo de observação — registrar toda chamada de ferramenta, não impor nada
npx protect-mcp -- node my-server.js

# Gerar chaves + modelo de configuração para assinatura local
npx protect-mcp init

# Modo de observação com assinatura local ativada
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# Modo de imposição
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# Exportar um pacote de auditoria verificável offline
npx protect-mcp bundle --output audit.json

O Que Faz

O protect-mcp fica entre seu cliente MCP e servidor como um proxy stdio:

Cliente MCP ←stdin/stdout→ protect-mcp ←stdin/stdout→ seu servidor MCP

Ele intercepta requisições JSON-RPC tools/call e:

• Modo de observação (padrão): registra cada chamada de ferramenta e permite tudo
• Modo de imposição: aplica regras de política por ferramenta como block, rate_limit e min_tier
• Assinatura local opcional: quando configurada, emite um recibo assinado com Ed25519 junto com o registro estruturado

Todas as outras mensagens MCP (initialize, tools/list, notificações) passam de forma transparente.

O Que Está Disponível Hoje

• Políticas por ferramenta — bloqueie ferramentas destrutivas, limite a taxa das caras e anexe requisitos de nível mínimo
• Registros de decisão estruturados — cada decisão é emitida no stderr com [PROTECT_MCP]
• Recibos assinados locais opcionais — gerados quando executado com uma política contendo signing.key_path, persistidos em .protect-mcp-receipts.jsonl e expostos em http://127.0.0.1:9876/receipts
• Verificação offline — verifique recibos ou pacotes com npx @veritasacta/verify
• Nenhuma conta necessária — chaves locais, política local, processo local

Limites Atuais de Capacidade

Estes são importantes antes de implementar isso ou falar com usuários:

• A assinatura não é automática no caminho básico npx protect-mcp -- .... Esse caminho registra decisões em modo de observação. Para assinatura local, execute npx protect-mcp init e inicie o gateway com o arquivo de política gerado.
• As verificações de política sensíveis a nível estão ativas, mas a admissão por manifesto não está conectada ao caminho padrão da CLI/stdio. A CLI define sessões como unknown por padrão, a menos que uma integração de host chame a API de admissão programaticamente.
• A configuração de credenciais atualmente valida referências de credenciais baseadas em env e registra rótulos de credenciais em logs/recibos. A injeção genérica por chamada em ferramentas stdio arbitrárias é específica do adaptador e não é realizada pelo caminho de proxy padrão.
• Adaptadores PDP externos e auxiliares de pacote de auditoria existem como utilitários exportados. Eles ainda não estão totalmente conectados ao caminho padrão da CLI.

Arquivo de Política

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  },
  "credentials": {
    "internal_api": {
      "inject": "env",
      "name": "INTERNAL_API_KEY",
      "value_env": "INTERNAL_API_KEY"
    }
  }
}

Regras de Política

Os nomes das ferramentas correspondem exatamente, com "*" como fallback curinga.

Configuração do Cliente MCP

Claude Desktop

Adicione em claude_desktop_config.json:

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

Mesmo padrão — substitua o comando do servidor por protect-mcp envolvendo-o.

Opções da CLI

protect-mcp [options] -- <command> [args...]
protect-mcp init

Comandos:
  init              Gerar par de chaves Ed25519 + modelo de configuração
  status            Mostrar estatísticas de decisão e identidade local do passport
  digest            Gerar um resumo local legível por humanos
  receipts          Mostrar recibos assinados persistentes recentes
  bundle            Exportar um pacote de auditoria verificável offline

Opções:
  --policy <path>   Arquivo JSON de política/configuração
  --slug <slug>     Identificador de serviço para logs/recibos
  --enforce         Ativar modo de imposição (padrão: observação)
  --verbose         Ativar registro de depuração
  --help            Mostrar ajuda

Hooks Programáticos

A biblioteca também expõe os primitivos que ainda não estão conectados ao caminho padrão da CLI:

import {
  ProtectGateway,
  loadPolicy,
  evaluateTier,
  meetsMinTier,
  resolveCredential,
  initSigning,
  signDecision,
  queryExternalPDP,
  buildDecisionContext,
  createAuditBundle,
} from 'protect-mcp';

Use-os se quiser adicionar:

• admissão por manifesto antes de uma sessão iniciar
• um PDP externo (OPA, Cerbos ou um webhook HTTP genérico)
• integrações personalizadas com credenciais intermediadas
• exportação de pacote de auditoria em torno do seu próprio armazenamento de recibos

Logs de Decisão e Recibos

Cada chamada de ferramenta emite JSON estruturado para stderr:

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}

Quando a assinatura está configurada, um recibo assinado segue:

[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}

Verifique com a CLI: npx @veritasacta/verify receipt.json Verifique no navegador: scopeblind.com/verify

Pacotes de Auditoria

O pacote exporta um auxiliar para pacotes de auditoria autocontidos:

{
  "format": "scopeblind:audit-bundle",
  "version": 1,
  "tenant": "my-service",
  "receipts": ["..."],
  "verification": {
    "algorithm": "ed25519",
    "signing_keys": ["..."]
  }
}

Use createAuditBundle() em torno dos seus próprios recibos assinados coletados.

Filosofia

• Observação primeiro. Veja o que os agentes estão fazendo antes de impor qualquer coisa.
• Recibos vencem logs baseados em painel. Artefatos assinados devem ser verificáveis independentemente.
• Mantenha as afirmações enxutas. O caminho padrão da CLI ainda não faz tudo que a arquitetura de longo prazo suportará.
• Camada sobre autenticação existente. Não remova sua pilha apenas para adicionar controle e evidência.

Pacotes de Política Ancorados em Incidentes

Acompanham o protect-mcp — cada um previne um ataque real:

npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js

Mapeamento completo OWASP Agentic Top 10: scopeblind.com/docs/owasp

BYOPE: Mecanismos de Política Externos

Suporta OPA, Cerbos, Cedar (AWS AgentCore) e endpoints HTTP genéricos:

{
  "policy_engine": "hybrid",
  "external": {
    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
    "format": "cedar",
    "timeout_ms": 200,
    "fallback": "deny"
  }
}

Padrões e PI

• IETF Internet-Draft: draft-farley-acta-signed-receipts-00 — Recibos de Decisão Assinados para Controle de Acesso Máquina a Máquina
• Status de Patente: 4 patentes provisórias australianas pendentes (2025-2026) cobrindo recibos de decisão com divulgação configurável, gateway de chamada de ferramenta, manifestos de agente e identidade portátil
• Verificação: Licença MIT — npx @veritasacta/verify --self-test

Licença

MIT — livre para usar, modificar, distribuir e construir sobre sem restrições.

scopeblind.com · npm · GitHub · IETF Draft