protect-mcp

Portão de política Cedar com falha-fechada mais recibos assinados para chamadas de ferramentas de agente de IA.

protect-mcp é um gate que fica na frente das chamadas de ferramentas de um agente de IA. Ele avalia cada chamada contra uma política Cedar (a mesma linguagem que a AWS usa para o IAM), bloqueia o que viola as regras antes de executar e assina um recibo Ed25519 verificável offline de cada decisão. Funciona localmente, não envia telemetria de suas decisões a lugar nenhum e é licenciado sob MIT.

Por que é diferente

Fail-closed por padrão. Em qualquer erro de política, engine ausente ou falha de avaliação, a decisão é NEGAR. O gate nunca permite silenciosamente. Existe um modo de observação para implantação shadow, mas mesmo lá, uma chamada que seria bloqueada é sinalizada como would_deny: true, então uma falha nunca é silenciosa.
Prova sua própria contenção. serve --enforce e doctor executam um autoteste de inicialização e se recusam a armar o gate a menos que possam mostrar que uma ação conhecida como proibida é realmente negada. Um gate que não pode provar que nega não inicia.
Cada decisão é um recibo que qualquer um pode verificar. As decisões são assinadas com Ed25519 e verificáveis offline com @veritasacta/verify. Nenhuma confiança em fornecedor necessária: a matemática não se importa com quem a executa.

Quickstart: instalar até a primeira prova útil```bash

1. Generate an Ed25519 keypair, config template, and sample policy.

npx protect-mcp init

2. Wrap any MCP server in shadow mode. Nothing is blocked yet; calls are logged.

npx protect-mcp wrap -- node your-mcp-server.js

3. Inspect the local-only dashboard: tool inventory, risk, approvals, receipts.

npx protect-mcp dashboard --open

4. Draft a reviewable policy from observed calls.

npx protect-mcp recommend --write

5. When reviewed, restart the wrapper in enforce mode with that policy.

npx protect-mcp --policy protect-mcp.recommended.json --enforce -- node your-mcp-server.js

Para o Claude Desktop, execute primeiro um patch de configuração de dry-run e depois aplique-o:```bash
npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

O dashboard vincula-se a 127.0.0.1, lê apenas arquivos de log/recibos locais e não faz upload de nada. Use npx protect-mcp connect apenas se você quiser explicitamente um dashboard ScopeBlind hospedado.

A gate como servidor MCP

Se preferir chamar a gate como ferramentas em vez de conectar os hooks do Claude Code, execute-a como servidor MCP:```bash npx protect-mcp mcp

Ele fala MCP via stdio e expõe quatro ferramentas somente leitura, todo o loop:

- **`evaluate_action`**: decide uma chamada de ferramenta proposta contra uma política Cedar inline, falha-fechada (qualquer erro de política é NEGAR). Retorna `{ allowed, decision, reason, policy_digest }`.
- **`sign_decision`**: transforma uma decisão em um recibo assinado com Ed25519 (uma negação assina um `gateway_restraint`, uma permissão um `decision_receipt`). Retorna o recibo e sua chave pública; gera uma chave efêmera se você não fornecer uma.
- **`verify_receipt`**: verifica um recibo assinado offline contra uma chave pública. Retorna `{ valid, error, type, kid, issuer }`.
- **`self_test`**: prova, sem entradas. Uma ação conhecidamente proibida é negada, depois um recibo assinado faz um round-trip e uma cópia adulterada falha.

Aponte qualquer host MCP para ele, por exemplo Claude Desktop:```json
{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

Os recibos são compatíveis em nível de bytes com os que o gateway assina em tempo de execução, portanto, um recibo gerado aqui verifica com @veritasacta/verify e o verificador do navegador da mesma forma.

Painel de Ações Locais

protect-mcp dashboard é a visão do operador para passar de visibilidade para aplicação de regras:

Inventário de ferramentas: todas as ferramentas observadas, contagem de chamadas, risco alto/médio/baixo e se a política ativa tem uma regra exata, um fallback curinga ou nenhuma regra.
Cobertura de políticas: edições locais de política com um clique para Exigir aprovação, Bloquear ou Observar. Reinicie o wrapper após revisar as alterações.
Fila de aprovação de ação exata: a ferramenta, ação, destino, pré-visualização do payload com dados sensíveis ocultados, hash do payload, base da política e motivo da captura antes de um humano aprovar, negar, editar ou assumir o controle.
Cadeia de recibos: IDs de solicitação correlacionados com hashes de recibos assinados, para que um revisor de auditoria possa ver quais decisões possuem prova criptográfica.
Exportação de auditoria: baixa o pacote de auditoria verificável offline quando existem recibos assinados. Se existirem apenas logs locais não assinados, o painel explica que a assinatura deve ser ativada primeiro.

Para aprovações alternativas em desktop ao vivo, inicie o painel com o endpoint de aprovação do gateway local e o nonce impresso pelo wrapper:```bash npx protect-mcp dashboard --open
--approval-endpoint http://127.0.0.1:9876
--approval-nonce "$PROTECT_MCP_APPROVAL_NONCE"

`Approve` encaminha para o gateway local ao vivo quando essas flags estão presentes.
`Deny`, `Edit`, e `Take over` são registados localmente como registos de resolução de aprovação;
use-os como instrução do operador e reexecute a ferramenta quando necessário.

### MVP do Limite Pago: ancoragem de digest, não upload de dados

Recibos autoassinados locais permanecem gratuitos e verificáveis offline. O limite pago é
uma evidência independente de que o ScopeBlind viu um digest de recibo num determinado momento,
sob uma identidade de organização, sem receber o prompt bruto, payload da ferramenta, saída,
chave privada ou recibo bruto.```bash
# Create or refresh a local org identity and public-key directory.
npx protect-mcp registry init --org "Meridian Global Macro" --billing-account acct_meridian

# Local preview: writes a digest registry and shareable static verifier page.
npx protect-mcp registry anchor

# Hosted mode: uploads receipt digests only for independent anchoring.
SCOPEBLIND_TOKEN=... npx protect-mcp registry anchor \
  --hosted \
  --endpoint https://api.scopeblind.com \
  --verifier-base https://legate.scopeblind.com

A prévia local é deliberadamente rotulada como local-preview-not-independent. O modo hospedado ancora apenas hashes de recibos, IDs de solicitação, chaves públicas da organização e metadados de faturamento. Ele não envia recibos brutos ou contexto sensível.

Demonstração Matadora: sombra para política para prova

protect-mcp killer-demo gera um pacote completo de vendas/demonstração de três minutos:```bash npx protect-mcp killer-demo --dir ./scopeblind-demo

It creates mock filesystem, GitHub, email, and PMS activity; shows risky calls in
shadow mode; applies a policy pack; requires approval for a sensitive PMS booking;
executes through the gateway; writes a signed receipt; proves the original
receipt verifies; proves a tampered receipt fails; and creates a selective
disclosure package that hides sensitive context while showing the minimum proof.

Abra o `DEMO-RUNBOOK.md` gerado primeiro. Em seguida, execute o comando impresso do dashboard para guiar um cliente pela sequência exata.

### Divulgação Seletiva v0

Recibos em modo de compromisso podem carregar um `committed_fields_root` em vez de expor todos os campos em texto claro. Posteriormente, o titular pode divulgar apenas campos selecionados:```bash
npx protect-mcp verify-disclosure \
  --receipt ./receipts/selective-disclosure.receipt.json \
  --disclosure ./receipts/selective-disclosure.tool-only.json

O verificador verifica o hash do recibo pai, a assinatura Ed25519, a raiz do compromisso, e a prova Merkle de cada campo divulgado. Em seguida, explica quais campos foram divulgados e quais campos comprometidos permanecem ocultos. Esta é uma divulgação de compromisso com sal, não de conhecimento zero completo, mas torna a afirmação de privacidade concreta: auditores podem verificar factos selecionados sem receber a carga útil completa da ferramenta ou o contexto sensível da secretária.

Prove uma reivindicação sobre o registo (atestados cegos à posição)

Pode provar uma REIVINDICAÇÃO sobre o seu registo sem o revelar. Crie uma atestação assinada e cega à posição sobre todo o registo que divulga apenas por decisão categorias (um resumo do recibo, o veredito, tags de capacidade), nunca as suas entradas, saídas ou dados da ferramenta:```bash

"No action reached the network across the record":

npx protect-mcp claim --no net.egress

other predicates:

--only fs.read,fs.write all actions were confined to these capabilities

--no-verdict blocked no action was blocked

--count blocked how many were blocked

Qualquer pessoa verifica offline, vendo apenas as categorias, nunca o conteúdo:```bash
npx protect-mcp verify-claim claim-<id>.json

O verificador recalcula uma raiz Merkle sobre o conjunto divulgado e recalcula o predicado de forma independente, portanto o emissor não pode mentir sobre a afirmação dada a divulgação. Adicione --anchor para registrar o resumo da afirmação no registro de transparência ScopeBlind público e somente de acréscimo, para que uma contraparte que não confia em você possa confirmar que o conjunto divulgado está completo e não foi recortado silenciosamente (apenas o hash é enviado; o registro permanece local):```bash npx protect-mcp claim --no net.egress --anchor

Isto é uma atestação responsável e cega à posição, não de conhecimento zero completo: ela revela a forma, não o conteúdo.

## Experimente em 60 segundos (sem necessidade de agente)

[![Assista ao filme de demonstração de dois minutos](https://assets.kitploit.com/production/public/readmes/13151/01d856d6ca762bf76992ad56ab4c05824f272e9d98d62516a8f53bb90bce0db5.jpg)](https://legate.scopeblind.com/record)

Assista ao filme de dois minutos em [legate.scopeblind.com/record](https://legate.scopeblind.com/record) e depois reproduza-o contra sua própria cópia:```bash
npx protect-mcp sample     # seed a labeled sample record (8 decisions: 1 blocked, 2 payments)
npx protect-mcp record     # open it: signatures verified in your browser

npx protect-mcp claim --payment-under 100 --anchor --output payments-under-100.json
npx protect-mcp verify-claim payments-under-100.json
npx protect-mcp anchor-record

Solte o demo-tampered.jsonl gerado na página do registro para ver uma edição pós-assinatura ser detectada. sample recusa-se a tocar em um registro existente, então execute-o em uma pasta vazia. Quando estiver pronto para a versão real, conecte o gate abaixo e os mesmos comandos serão executados contra o próprio registro do seu agente.

Início rápido do hook do Claude Code```bash

Generate hook config and a sample Cedar policy.

npx protect-mcp init-hooks

Serve the Claude Code hook gate in enforce mode. It runs a restraint self-test

first and refuses to start if it cannot prove it denies a forbidden vector.

npx protect-mcp serve --enforce --cedar ./cedar

Avaliação única, da forma como um hook PreToolUse a chama. O código de saída 2 significa negar (a ferramenta está bloqueada); o código de saída 0 significa permitir:```bash
npx protect-mcp evaluate --cedar ./cedar --tool Bash --input '{"command":"rm"}'
echo $?   # 2  -> denied, fail-closed

npx protect-mcp evaluate --cedar ./cedar --tool Read --input '{"path":"README.md"}'
echo $?   # 0  -> allowed

Uma política ausente ou não carregável nega (exit 2) a menos que você passe explicitamente --fail-on-missing-policy false.

Hooks do Claude Code

protect-mcp init-hooks escreve um .claude/settings.json para você. Para conectar o gate manualmente, os dois verbos que você precisa são evaluate (PreToolUse, bloqueia no exit 2) e sign (PostToolUse, registra um recibo). Fixe a versão para que uma sessão do Claude Code sempre execute o gate que você testou:```json { "hooks": { "PreToolUse": [ { "matcher": "", "hooks": [ { "type": "command", "command": "npx [email protected] evaluate --cedar ./cedar --tool "$TOOL_NAME" --input "$TOOL_INPUT"" } ] } ], "PostToolUse": [ { "matcher": "", "hooks": [ { "type": "command", "command": "npx [email protected] sign --tool "$TOOL_NAME" --receipts ./receipts --key ./keys/gateway.json" } ] } ] } }

`evaluate` sai com código 2 em caso de negação, então o Claude Code bloqueia a chamada da ferramenta, e 0 em caso de permissão.
`sign` é de melhor esforço: anexa um recibo assinado com Ed25519 quando uma chave está configurada e, se não houver assinante disponível, registra uma linha honesta não assinada (`"signed": false`) em vez de falhar a ferramenta.

## Use em outros agentes (Codex, Cursor, Gemini, Hermes)

O mesmo portão de falha fechada é executado como um hook de ferramenta em qualquer agente que os suporte. Adicione `--format <host>` para que o verbo leia o payload do hook desse host a partir do stdin e negue em seu contrato:```bash
# the PreToolUse / before-tool command for each host
npx -y protect-mcp@latest evaluate --format codex  --cedar ./cedar   # OpenAI Codex
npx -y protect-mcp@latest evaluate --format gemini --cedar ./cedar   # Gemini CLI BeforeTool
npx -y protect-mcp@latest evaluate --format cursor --cedar ./cedar   # Cursor beforeShellExecution
npx -y protect-mcp@latest evaluate --format hermes --cedar ./cedar   # Hermes pre_tool_call

Emparelhe cada um com sign --format <host> no evento pós-ferramenta para recibos. O caso importante é Hermes, que ignora os códigos de saída do hook e lê o veredito do stdout, então --format hermes nega via {"decision":"block"} em vez de exit 2 (um exit-2 bruto falharia silenciosamente em aberto ali). Sem --format, os verbos leem as flags --tool/--input exatamente como na seção Claude Code acima.

Escrever uma política

As políticas Cedar residem em um diretório que você aponta com --cedar. Uma regra forbid nega, uma regra permit permite. Para corresponder a um valor na entrada da ferramenta, use o idioma .contains():```cedar // Allow read-only tools. permit( principal, action == Action::"MCP::Tool::call", resource == Tool::"Read" );

// Deny dangerous shell commands by matching the command against a list. forbid( principal, action == Action::"MCP::Tool::call", resource == Tool::"Bash" ) when { ["rm", "dd", "mkfs"].contains(context.command) };

// Block destructive tools outright. forbid( principal, action == Action::"MCP::Tool::call", resource == Tool::"delete_file" );

> **Perigo:** NÃO escreva `context.command in ["rm", "dd"]` para verificar se uma string
> pertence a uma lista. `in` é para hierarquias de entidades, não para associação de strings. O Cedar
> trata a expressão como um erro de tipo e descarta silenciosamente toda a regra `forbid`, o que (sob um gateway configurado para permitir por omissão) deixa um `permit` residual em vigor. Este é exatamente o defeito por trás do advisory abaixo. Use `[...].contains(context.command)`
> em vez disso. A partir da versão 0.7.0, o gateway nega permissão nesse erro, em vez de permitir, e um teste de CI (integração contínua) faz a construção falhar se o padrão for reintroduzido numa política distribuída. Veja [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9).

### Pacotes de políticas iniciais

A maioria das equipas não deve escrever Cedar do zero logo no primeiro dia. Instale um pacote inicial, execute em modo de observação (shadow mode), inspecione os recibos e, em seguida, restrinja ou aplique:```bash
npx protect-mcp policy-packs list
npx protect-mcp policy-packs show secrets-safe
npx protect-mcp policy-packs install filesystem-safe --dir ./cedar
npx protect-mcp policy-packs install all --dir ./cedar
npx protect-mcp serve --cedar ./cedar

Pacotes integrados:

filesystem-safe: ações destrutivas de arquivos e leituras de caminhos semelhantes a segredos.
git-safe: pushes forçados, resets duros, limpeza destrutiva, exclusão de repositórios.
email-safe: permitir rascunho, bloquear envios não supervisionados.
database-safe: postura de BD orientada a leitura, bloquear SQL de escrita/admin.
cloud-spend-safe: criação óbvia de gastos em nuvem e destruição de infraestrutura.
secrets-safe: exfiltração comum de segredos em arquivos, env, shell e nuvem.
finance-mandate-safe: violações de lista restrita e concentração em fluxos de reserva.

Verificar um recibo

Os recibos são assinados e verificáveis offline por qualquer pessoa com a chave pública. Nem rede, nem fornecedor, nem confiança na ScopeBlind:```bash npx @veritasacta/verify ./receipts/receipts.jsonl --format jsonl

Exit 0 = valid, non-zero = tampered or malformed

`npx protect-mcp bundle --output audit.json` exporta um pacote de auditoria autocontido e verificável offline dos seus recibos mais a chave pública de assinatura.

## Segurança

`protect-mcp` 0.7.0 falha em modo fechado por design. Em qualquer erro de avaliação de política, um mecanismo ausente ou uma política que apresentou erro na avaliação, a decisão é NEGAR, não permitir. `serve --enforce` e `doctor` executam um autoteste de inicialização que prova que o portão nega um vetor conhecido como proibido antes de ser confiado, e recusam-se a armar se não conseguirem.

**Versões afetadas: 0.5.x e 0.6.x.** Essas versões falham em modo aberto (retornam PERMITIR em erro de avaliação) e não avaliam Cedar corretamente em relação ao mecanismo fixado, portanto uma regra `forbid` pode falhar em bloquear. **Atualize para >= 0.7.0.**

Detalhes e correção: [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9). Para relatar uma vulnerabilidade, veja [SECURITY.md](https://github.com/scopeblind/scopeblind-gateway/blob/HEAD/SECURITY.md).

## Comandos

| Comando | Descrição |
|---------|-------------|
| `serve` | Inicia o servidor HTTP hook para Claude Code (porta 9377). `--enforce` executa o autoteste de restrição primeiro; `--cedar <dir>` e `--policy <path>` selecionam a política. |
| `init` | Gera um par de chaves Ed25519 (`keys/gateway.json`), um modelo de configuração e uma política de exemplo. |
| `sample` | Semeia um registro de amostra claramente rotulado (8 decisões: uma chamada bloqueada, dois pagamentos; kid `sample-demo`) mais uma cópia adulterada, para que `record`, `claim`, `verify-claim` e `anchor-record` sejam reproduzíveis do zero antes de conectar um agente. Recusa-se a tocar em um registro existente; `--force` substitui. |
| `policy` | Veja e altere a política Cedar a partir do terminal: `policy list` (permitir / proibir / negar por padrão por ferramenta, com quantas vezes o portão permitiu ou negou), `policy show`, `policy allow <tool>`, `policy deny <tool>`, `policy path`. Um `serve` em execução recarrega a quente na alteração. |
| `wrap` | Imprime um comando MCP protegido ou corrige servidores MCP do Claude Desktop. Simulação por padrão; use `--write` para atualizar a configuração do Claude Desktop. |
| `dashboard` | Inicia um painel local apenas em `127.0.0.1` mostrando inventário de ferramentas, risco, cobertura de políticas, aprovações de ações exatas, cadeias de recibos e exportação de auditoria. |
| `recommend` | Elabora uma política JSON revisável a partir de chamadas locais observadas. Simulação por padrão; use `--write` para criar `protect-mcp.recommended.json`. |
| `registry` | Cria uma identidade organizacional, ancora resumos de recibos e escreve uma página de verificador estático. O modo hospedado envia apenas resumos. |
| `record` | Abre um visualizador local e pesquisável sobre seus recibos (`--live` transmite enquanto o agente executa): assinaturas Ed25519 verificadas no seu navegador contra sua chave de gateway, tags de capacidade, uma árvore de proveniência e exportação assinada com um clique. Tudo local, nada enviado. |
| `claim` | Cria uma atestação assinada e cega à posição de um predicado sobre o registro (`--no <cap>` incl. `--no payment`, `--only <c1,c2>`, `--no-verdict <verdict>`, `--count <verdict>`, `--payment-under <cap>`), divulgando apenas categorias de decisão. Adicione `--anchor` para registrar o resumo da reivindicação no log de transparência público; chaves inscritas ancoram como uma organização nomeada. |
| `anchor-record` | Faz checkpoint da raiz Merkle do registro + contagem + intervalo de tempo no log público (amigável para heartbeat: pula quando inalterado). Uma reivindicação posterior cujo compromisso corresponda a um checkpoint ancorado é comprovadamente sobre o registro completo a partir daquele checkpoint. |
| `verify-claim` | Verifica um pacote de reivindicação offline: assinatura, raiz Merkle recalculada, predicado recalculado independentemente e o sidecar da âncora quando presente (vincula o envelope ancorado a esta reivindicação exata, então confirma que o log público a possui). `--check-anchor` requer a âncora; `--offline` pula a verificação no log. |
| `killer-demo` | Gera um pacote de demonstração completo de modo oculto para política para aprovação para recibo assinado. |
| `verify-disclosure` | Verifica um pacote `scopeblind.selective_disclosure.v0` e explica campos divulgados versus ocultos. |
| `policy-packs` | Lista, inspeciona e instala pacotes iniciais de políticas Cedar. |
| `evaluate` | Avalia uma chamada de ferramenta contra uma política Cedar (portão PreToolUse). Saída 2 = negar (falha fechada), saída 0 = permitir. |
| `sign` | Assina uma chamada de ferramenta em um recibo (PostToolUse). Melhor esforço: registra uma linha honesta não assinada se não houver chave. |
| `simulate` | Simula uma política contra um log de decisão registrado para ver o que ela teria bloqueado. |
| `demo` | Inicia um servidor de demonstração embutido envolvido com o portão, para ver recibos instantaneamente. |
| `doctor` | Verifica sua configuração (chaves, políticas, mecanismo Cedar, verificador) e executa o autoteste de restrição. |
| `bundle` | Exporta um pacote de auditoria verificável offline de recibos mais a chave pública. |
| `report` | Gera um relatório de conformidade (Markdown ou JSON) a partir do log de decisão e recibos. |

Execute `npx protect-mcp --help` para a referência completa de flags.

## Links

- Protocol (IETF): [draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/)
- [CHANGELOG](https://github.com/scopeblind/scopeblind-gateway/blob/HEAD/CHANGELOG.md)
- [npm](https://www.npmjs.com/package/protect-mcp)
- [scopeblind.com](https://scopeblind.com)

MIT licensed. Built by [ScopeBlind](https://scopeblind.com).

Mais Populares

scopeblind-gateway