Modelo de ameaças

O zn-gate mantém os valores secretos fora do contexto do modelo. No modo env, um comando que você permitiu continua com o valor: restrinja o escopo dele e ative o sandbox do seu agente.

Esta página trata do Scrubber e do cofre de segredos (detalhes). Ela descreve o zn-gate 1.12.0 ou posterior. Para saber o que sai da sua máquina, veja O que sai da sua máquina.

Contra o que o zn-gate protege

O objetivo: que um valor secreto nunca chegue ao modelo, nem aos logs e caches do provedor por trás dele, pelos caminhos normais de ferramentas do agente. Isso inclui leituras de arquivos, saída de comandos, resultados de busca, resultados MCP e prompts colados.

Contra o que o zn-gate não protege

Os hooks são uma proteção, não um sandbox: um processo determinado pode achar outro jeito de ler um arquivo. O ponto é que as ferramentas normais do agente não entregam valores ao modelo.

Os hooks também impedem que as ferramentas de arquivos e os comandos de shell do agente gravem em ~/.zn e nas configurações de hooks e plugins dos próprios agentes (por exemplo .claude/settings*.json, os arquivos de .codex/, .cursor/hooks.json e opencode.json, e os diretórios que os contêm). É um esforço de boa-fé: uma gravação que os hooks não conseguem ler como uma palavra do comando (um caminho montado dentro de um script, código em linha como python -c "open(...)" ou uma variável definida antes no mesmo comando) não é vista.

O que o processo do cofre protege

O processo do cofre (zn unlock) mantém o cofre decifrado durante a sessão e responde a requisições em um socket privado (um pipe nomeado no Windows). Cada conexão precisa provar que consegue ler ~/.zn/run/session.key.

• Ele protege contra outros usuários do sistema. Eles não conseguem ler a chave de sessão, então não conseguem se conectar.
• Ele não verifica qual programa do seu usuário está pedindo. Qualquer processo executado como você pode pedir ao cofre desbloqueado um segredo guardado, pelo nome. Isso inclui um comando que o agente executa, tenha ou não um marcador que os hooks possam ver. As verificações acima (lista de comandos permitidos, confirmação do primeiro uso, impressão digital do programa, allowHosts e allowIn) protegem os caminhos que o próprio zn-gate oferece, zn run e o servidor MCP secrets. Elas não são aplicadas a uma requisição direta ao processo do cofre.
• O que fazer: mantenha o cofre bloqueado (zn lock) quando não estiver usando segredos, deixe que ele se bloqueie sozinho por inatividade (30 minutos por padrão) e use o sandbox ou as regras de permissão do seu agente para que ele não execute programas arbitrários sem perguntar.

O limite é o processo do mesmo usuário, como no ssh-agent. Verificar o programa que chama e aplicar a política dentro do processo do cofre não está feito na 1.12.0.

Início do programa aprovado

O zn run resolve o nome do comando uma única vez, para o caminho real de um arquivo. Ele abre esse arquivo, confere com a sua aprovação, confere de novo logo antes de iniciar e inicia esse caminho. Nunca procura o nome no PATH uma segunda vez. O rigor depende do programa e do sistema:

• Programas nativos no Linux são iniciados pelo arquivo que o zn-gate abriu e conferiu, então o que executa é exatamente o que foi conferido.
• Scripts (#!) em qualquer sistema são executados pelo interpretador, que reabre o script pelo caminho depois da última conferência. Um processo do seu usuário que consiga gravar no diretório do script poderia substituí-lo nessa breve janela. Uma linha #!/usr/bin/env X procura X no PATH de quem chama, e a conferência cobre o script, não o interpretador encontrado ali.
• Todos os programas no macOS e no Windows são iniciados pelo caminho logo após a última conferência, então existe a mesma breve janela.
• As variáveis do carregador (LD_*, DYLD_*) e as variáveis da glibc que carregam arquivos ou módulos à escolha de quem chama são removidas do ambiente do programa sempre que valores secretos são injetados, e o zn run avisa uma vez. No Windows, um programa que carrega DLLs do próprio diretório não é coberto.
• As variáveis de inicialização de interpretadores (como NODE_OPTIONS, PYTHONPATH, PERL5OPT, RUBYOPT, JAVA_TOOL_OPTIONS e BASH_ENV) também são removidas, desde a 1.5.1. Um interpretador ainda executa qualquer código que receba, então aprove interpretadores só com isso em mente: o zn-gate avisa que eles executam qualquer código que recebam.

O zn-gate avisa quando você aprova um programa se o seu usuário puder gravar no programa ou em qualquer diretório acima dele. Gerenciadores de versão como nvm, volta, pipx ou Homebrew instalam ferramentas nesses diretórios, então ele avisa em vez de recusar. Para evitar a janela, aprove programas nativos instalados em diretórios onde o seu usuário não possa gravar (por exemplo, pacotes do sistema), não scripts da sua pasta pessoal.

Cópias locais, por agente

O zn-gate controla o que chega ao modelo. Alguns agentes também guardam seus próprios registros locais:

• Claude Code: a transcrição da sessão guarda a saída das ferramentas já limpa. Duas coisas ficam em claro ali: um prompt que o zn-gate bloqueou (a própria documentação do Claude Code diz isso) e o comando mostrado em uma caixa de confirmação quando o zn-gate restaura um valor detectado para um comando local. Nenhuma das duas é enviada ao modelo, nem quando a sessão é retomada.
• Codex: o Codex não consegue reescrever a saída das ferramentas, então o zn-gate substitui por "block" o resultado que o modelo vê. O log de sessões do próprio Codex (~/.codex/sessions) e os eventos --json mantêm a saída original.
• OpenCode: a saída das ferramentas e sua prévia são reescritas. A saída ao vivo que o OpenCode guarda enquanto um comando ainda executa é gravada antes que o zn-gate possa vê-la, então fica no banco de dados local do OpenCode.
• Cursor: o Cursor não consegue reescrever de jeito nenhum a saída de comandos de shell nem de leituras de arquivos. Os valores em arquivos que você deixa o agente ler, ou impressos por comandos, chegam ao modelo. Guarde os segredos no cofre e mantenha os arquivos .env ocultos por marcadores.

Canal de confirmação

O primeiro uso de um segredo com um comando, e as mudanças de política que ampliam um segredo, são confirmados pelo processo do cofre:

• zn unlock --foreground: no terminal próprio do cofre. O shell de um agente tem outro terminal.
• Caso contrário, uma caixa de diálogo do sistema: osascript no macOS, uma janela com "Não" como padrão no Windows, zenity ou kdialog no Linux (só com sessão de desktop). Uma caixa sem resposta conta como "não" após 120 segundos.
• Sem canal (sem tela, SSH, processo desacoplado): recusado, com instruções.

Essas confirmações barram a prompt injection que conduz as ferramentas do agente. Não barram malware executado como o mesmo usuário.

Quando algo dá errado

• Cofre bloqueado: os hooks continuam executando o scrubber sem ele. Eles ocultam padrões, dados pessoais e valores encontrados em arquivos locais com marcadores irreversíveis. O broker se recusa a preencher qualquer valor.
• Erro do scrubber: falha fechada. A chamada da ferramenta é negada, a saída retida ou o prompt bloqueado. A falta do motor também falha fechada, e a mensagem explica como reinstalar. Você pode deixar os eventos passarem enquanto ele falta com {"hooks": {"whenUnavailable": "allow"}} em ~/.zn/config.json (os hooks impedem que as ferramentas de arquivos do agente gravem ali). A variável ZN_HOOK_FAIL_MODE só pode deixar isso mais rígido.
• Um evento ilegível é recusado: quando a entrada do hook está vazia ou não é JSON, o hook escreve o motivo e sai com o código 2. Claude Code e Codex bloqueiam a chamada com esse código antes de a ferramenta executar. Depois que a ferramenta executou, o código 2 não desfaz nada.
• O processo do hook nem chega a iniciar (por exemplo, o Node mudou de lugar após uma atualização e o comando do hook aponta para o caminho antigo, ou o hook expira): as chamadas de ferramentas na maioria dos agentes seguem então sem verificação. Execute zn hooks install de novo depois de mover ou atualizar o Node. Os agentes que bloqueiam prompts quando o hook falha (Claude Code, Cursor, OpenCode) bloqueiam todos os prompts até lá: veja If your agent blocks every prompt (em inglês).

Limites conhecidos e decisões de projeto

• Um segredo com allowHosts pode ser usado por HTTP seja qual for o modo dele. A lista de hosts é a autorização explícita.
• Arquivos versionados mantêm os marcadores. O zn-gate nunca grava um valor em um arquivo que o git acompanha. Restaurar um valor em um arquivo versionado que já o contém não é suportado: o token permanece.
• O pipe nomeado do Windows não tem lista de acesso explícita. Cada conexão se autentica nos dois sentidos com uma verificação com chave sobre uma chave de sessão que só o seu usuário pode ler, então outra conta não consegue usá-lo.
• Restaurar uma cópia antiga, porém genuína, de secrets.age é aceito e traz de volta as aprovações e a política que ela tinha. Mantenha privados os backups de ~/.zn.
• Cada hook é um processo curto de Node: cerca de 78 ms de mediana por chamada de ferramenta, medidos em um desktop com Windows.
• Os comandos de monitor executam como bash -c atrás do pipe do scrubber. As funções e os aliases do shell do agente não são carregados ali.

O texto completo, mantido junto ao código, é docs/threat-model.md (em inglês).