tomjwxf/scopeblind-gatewayGateway de segurança para servidores MCP com aplicação de políticas por ferramenta, recibos de auditoria assinados com Ed25519 e registro em modo shadow. Suporta mecanismos de políticas externas Cedar, OPA e Cerbos para controle de acesso de agentes de IA.
⚠️ 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.
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.
# 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 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:
block, rate_limit e min_tierTodas as outras mensagens MCP (initialize, tools/list, notificações) passam de forma transparente.
stderr com [PROTECT_MCP]signing.key_path, persistidos em .protect-mcp-receipts.jsonl e expostos em http://127.0.0.1:9876/receiptsnpx @veritasacta/verifyEstes são importantes antes de implementar isso ou falar com usuários:
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.unknown por padrão, a menos que uma integração de host chame a API de admissão programaticamente.{
"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"
}
}
}
| Campo | Valores | Descrição |
|---|---|---|
block | true | Bloquear explicitamente esta ferramenta |
require | "any", "none" | Requisito básico de acesso |
min_tier | "unknown", "signed-known", "evidenced", "privileged" | Nível mínimo exigido se seu host definir estado de admissão |
rate_limit | "N/unit" | Limite de taxa (ex.: "5/hour", "100/day") |
Os nomes das ferramentas correspondem exatamente, com "*" como fallback curinga.
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"
]
}
}
}
Mesmo padrão — substitua o comando do servidor por protect-mcp envolvendo-o.
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
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:
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
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": ["..."]
}
}