protect-mcp

Portão de política Cedar fail-closed mais recibos assinados para chamadas de ferramentas de agentes de IA.

protect-mcp é um portão que fica à 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 IAM), bloqueia o que viola as regras antes de ser executado e assina um recibo Ed25519 verificável offline de cada decisão. Ele roda localmente, não envia telemetria das suas decisões para lugar nenhum e é licenciado sob MIT.

Por que ele é diferente

• Fail-closed por padrão. Em qualquer erro de política, ausência de engine ou falha de avaliação, a decisão é DENY. O portão nunca permite silenciosamente. Existe um modo de observação para implantação em sombra, mas mesmo nele uma chamada que seria bloqueada é sinalizada com would_deny: true, então uma falha nunca é silenciosa.
• Ele prova sua própria contenção. serve --enforce e doctor executam um autoteste de inicialização e se recusam a armar o portão a menos que consigam demonstrar que uma ação sabidamente proibida é de fato negada. Um portão que não consegue provar que nega não inicia.
• Toda 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.

Início rápido: da instalação à 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 em modo 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 é vinculado a 127.0.0.1, lê apenas arquivos locais de log/recibo e não envia nada. Use npx protect-mcp connect apenas se você quiser explicitamente um dashboard ScopeBlind hospedado.

O gate como um servidor MCP

Se você preferir chamar o gate como ferramentas em vez de configurar os hooks do Claude Code, execute-o como um servidor MCP:```bash npx protect-mcp mcp

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

- **`evaluate_action`**: decide uma chamada de ferramenta proposta contra uma política Cedar inline, fail-closed (qualquer erro de política é DENY). 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 isso, sem entradas. Uma ação conhecidamente proibida é negada, então um recibo assinado faz 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 byte a byte com os que o gate assina em tempo de execução, portanto um recibo emitido aqui é verificado com @veritasacta/verify e o verificador do navegador da mesma forma.

Painel de Ações Local

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

• Inventário de ferramentas: cada ferramenta observada, contagem de chamadas, risco alto/médio/baixo e se a política ativa tem uma regra exata, um fallback com wildcard ou nenhuma regra.
• Cobertura de política: edições de política local com um clique para Require approval, Block ou Observe. Reinicie o wrapper após revisar as alterações.
• Fila de aprovação de ação exata: a ferramenta exata, ação, destino, pré-visualização de payload redigido, hash do payload, base da política e captura do motivo antes que um humano aprove, negue, edite ou assuma o controle.
• Cadeia de recibos: ids de requisição correlacionados com hashes de recibos assinados, para que um revisor de auditoria possa ver quais decisões têm 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 habilitada primeiro.

Para aprovações de fallback 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 ativo quando esses sinalizadores estão presentes.
`Deny`, `Edit` e `Take over` são registrados localmente como registros de
resolução de aprovação; use-os como a instrução do operador e execute novamente a ferramenta quando necessário.

### MVP de Fronteira Paga: ancoragem de digest, não upload de dados

Recibos autoassinados locais permanecem gratuitos e verificáveis offline. A fronteira paga é
evidência independente de que o ScopeBlind viu um digest de recibo em um momento, sob uma identidade
de organização, sem receber o prompt bruto, o payload da ferramenta, a saída, a chave privada ou o
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

O preview local é deliberadamente rotulado como local-preview-not-independent. O modo hospedado ancora apenas hashes de recibos, ids de requisição, chaves públicas da organização e metadados de faturamento. Ele não faz upload de recibos brutos ou contexto sensível.

Killer Demo: shadow to policy to proof

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

Ele cria um sistema de arquivos simulado, atividade de GitHub, e-mail e PMS; mostra chamadas de risco em
modo shadow; aplica um pacote de políticas; exige aprovação para uma reserva de PMS sensível;
executa através do gateway; grava um recibo assinado; prova que o recibo
original é verificado; prova que um recibo adulterado falha; e cria um pacote de divulgação
seletiva que oculta contexto sensível enquanto mostra a prova mínima.

Abra o `DEMO-RUNBOOK.md` gerado primeiro. Em seguida, execute o comando de dashboard
impresso para guiar um cliente através da 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 checa o hash do recibo pai, a assinatura Ed25519, a raiz de compromisso e a prova de Merkle de cada campo divulgado. Em seguida, explica quais campos foram divulgados e quais campos comprometidos permanecem ocultos. Esta é a divulgação de compromisso com salt, não zero-knowledge completo, mas torna a alegação de privacidade concreta: auditores podem verificar fatos selecionados sem receber o payload completo da ferramenta ou contexto sensível da mesa.

Prove uma alegação sobre o registro (atestados cegos à posição)

Você pode provar uma ALEGAÇÃO sobre seu registro sem revelá-lo. Emita um atestado assinado e cego à posição sobre o registro inteiro que divulga apenas categorias por decisão (um digest do recibo, o veredito, tags de capacidade), nunca 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-o 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, de modo que o emissor não pode mentir sobre a afirmação dada a divulgação. Adicione --anchor para registrar o digest da afirmação no log de transparência público e somente-append do ScopeBlind, para que uma contraparte que não confia em você possa confirmar que o conjunto divulgado está completo e não foi silenciosamente recortado (apenas o hash é enviado; o registro permanece local):```bash npx protect-mcp claim --no net.egress --anchor

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

## Experimente em 60 segundos (nenhum agente necessário)

[![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), depois reproduza-o com 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

Coloque o demo-tampered.jsonl gerado na página de registro para ver uma edição pós-assinatura ser detetada. O sample recusa-se a tocar num registro existente, por isso execute-o numa pasta vazia. Quando estiver pronto para o caso real, ligue o gate abaixo e os mesmos comandos são executados contra o registro do seu próprio 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 one-shot, da forma como um hook PreToolUse a chama. Código de saída 2 significa negar
(a ferramenta é bloqueada); 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.

Claude Code hooks

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" } ] } ] } }

### Assine a própria decisão da política

A partir da versão 0.13.0, `sign` pode avaliar a política e registrar a decisão real no
recibo em vez de uma permissão incondicional. Passe o diretório da política e a
mesma entrada e contexto que o hook passaria para `evaluate`:```bash
npx [email protected] sign --cedar ./cedar --tool Bash \
  --input '{"command":"rm -rf /"}' --context '{"command_pattern":"rm -rf"}' \
  --receipts ./receipts --key ./keys/gateway.json

O payload do recibo então carrega decision (allow ou deny), reason (cedar_allow ou cedar_deny), e policy_digest (o digest acta-policy-digest-v1 do conjunto de políticas), e cita draft-farley-acta-signed-receipts-03. O comando imprime a decisão e o digest em stdout. Um deny ainda é assinado: o recibo é o registro da decisão, não permissão para prosseguir.

Dois modelos de ação Cedar são suportados. O gate de runtime avalia Action::"MCP::Tool::call" com a ferramenta como recurso, que é o que as políticas em cedar/ esperam e o que sign --cedar usa por padrão. Políticas que nomeiam a ferramenta como a ação (action == Action::"Bash"), como a política de conformidade publicada em agent-governance-testvectors, precisam de --action-model tool. evaluate aceita a mesma flag.

evaluate sai com 2 em deny para que o Claude Code bloqueie a chamada da ferramenta, e 0 em allow. sign é best-effort: ele anexa um recibo assinado com Ed25519 quando uma chave está configurada, e se nenhum assinador estiver disponível ele registra uma linha não assinada honesta ("signed": false) em vez de falhar a ferramenta.

Use-o em outros agentes (Codex, Cursor, Gemini, Hermes)

O mesmo gate fail-closed roda como um hook de ferramenta em qualquer agente que os suporte. Adicione --format <host> para que o verbo leia o payload de hook desse host a partir de 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 post-tool para obter comprovativos. O caso importante é o **Hermes**, que ignora os códigos de saída dos hooks e lê o veredicto do stdout, pelo que `--format hermes` nega através de `{"decision":"block"}` em vez de exit 2 (um exit-2 em bruto falharia silenciosamente em aberto nesse caso). Sem `--format`, os verbos leem os flags `--tool`/`--input` exatamente como na secção Claude Code acima.

## Escrever uma política

As políticas Cedar residem num diretório para o qual 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 corresponder uma string a uma lista. in é para hierarquias de entidades, não para pertencimento de strings. O Cedar trata a expressão como um erro de tipo e descarta silenciosamente toda a regra forbid, o que (sob um gate fail-open) deixa um permit residual de pé. Este é o defeito exato por trás do aviso abaixo. Use [...].contains(context.command) em vez disso. A partir da 0.7.0 o gate nega nesse erro em vez de permitir, e um teste de tripwire de CI falha a build se o padrão for reintroduzido numa política enviada. Veja GHSA-hm46-7j72-rpv9.

Pacotes de políticas iniciais

A maioria das equipes não deveria escrever Cedar do zero no primeiro dia. Instale um pacote inicial, execute em modo shadow, inspecione os recibos, depois 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 em arquivos e leituras de caminhos que parecem segredos.
- `git-safe`: force pushes, hard resets, limpeza destrutiva, exclusão de repositório.
- `email-safe`: permite rascunhos, bloqueia envios não supervisionados.
- `database-safe`: postura de BD orientada a leitura, bloqueia SQL de escrita/administração.
- `cloud-spend-safe`: criação óbvia de gastos na 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 listas restritas e de 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. Sem
rede, sem fornecedor, sem 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, juntamente com a chave pública de assinatura.

Segurança

O protect-mcp 0.7.0 falha de forma fechada por design. Em qualquer erro de avaliação de política, um motor ausente, ou uma política que apresentou erro na avaliação, a decisão é DENY, não allow. serve --enforce e doctor executam um autoteste de inicialização que prova que o gate nega um vetor conhecido como proibido antes de ser confiado, e recusam-se a armar se não conseguir.

Versões afetadas: 0.5.x e 0.6.x. Essas linhas falham de forma aberta (retornam ALLOW em erro de avaliação) e não avaliam o Cedar corretamente contra o motor fixado, então uma regra forbid pode falhar em bloquear. Atualize para >= 0.7.0.

Detalhes e remediação: GHSA-hm46-7j72-rpv9. Para reportar uma vulnerabilidade, consulte SECURITY.md.

Comandos

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

Links

• Protocolo (IETF): draft-farley-acta-signed-receipts
• CHANGELOG
• npm
• scopeblind.com

Licenciado sob MIT. Construído por ScopeBlind.