Scrubber e cofre de segredos

O zn-gate mantém os valores secretos fora do que o seu agente de programação envia ao modelo. O agente trabalha com marcadores como __ZN_GITHUB_TOKEN__; os valores reais ficam em um cofre criptografado na sua máquina e são preenchidos apenas onde você permitiu. A detecção, a substituição e o cofre são 100% locais: nenhum serviço em nuvem, nem o nosso, participa.

Disponível no zn-gate 1.5.0 e versões posteriores (npm); no Windows, use a 1.5.1 ou posterior (GHSA-rf3f-ppm5-3xrx). Agentes suportados: Claude Code, Codex CLI, Cursor (IDE) e OpenCode. O que cada agente permite que os hooks alterem é diferente: veja compat.md e os limites em threat-model.md.

O que faz

• Higieniza o que o modelo vê. Leituras de arquivos, saída de comandos, buscas, resultados de ferramentas MCP e prompts colados passam pelo scrubber antes de chegar ao modelo. Valores conhecidos (do cofre e dos seus arquivos .env), cerca de 30 formatos de segredos (chaves de nuvem, tokens, chaves privadas, senhas em strings de conexão) e dados pessoais (números de cartão, IBANs, DNI/NIE e SSNs com validação de checksum; e-mails, números de telefone e endereços IPv4) são transformados em marcadores estáveis. O mesmo valor sempre recebe o mesmo marcador, para que o modelo ainda possa raciocinar sobre ele e a linha mantenha sua forma: DATABASE_URL=postgres://app:__ZN_DATABASE_URL_PASSWORD__@db:5432/app. No Cursor, apenas a saída MCP pode ser reescrita: a saída de shell e de arquivos não é higienizada ali.
• Bloqueia leituras de credenciais brutas. Arquivos .env com valores reais, arquivos de credenciais como ~/.aws/credentials ou ~/.ssh/id_*, e o próprio ~/.zn do zn: os hooks impedem que as ferramentas do agente os leiam (uma barreira de proteção, não um sandbox).
• Mantém os valores em um cofre criptografado. O cofre é criptografado com age; sua chave fica no chaveiro do sistema operacional (ou protegida por uma senha). Ele nunca sai da sua máquina e nunca é sincronizado. Um log de auditoria local registra qual segredo foi usado onde, nunca os valores.
• Preenche valores apenas onde você permitiu. Um comando permitido recebe o valor por meio de zn run, e a saída dele é mascarada. APIs HTTP são chamadas pelo servidor MCP secrets, que envia o valor somente aos hosts que você permitiu e devolve a resposta com os segredos substituídos por marcadores. Nenhuma ferramenta devolve um valor ao agente.
• Pergunta a você, não ao agente. O primeiro uso de um segredo por um programa e qualquer alteração que amplie a política de um segredo são confirmados em um diálogo do sistema ou no próprio terminal do cofre. O agente não pode responder a esses prompts.

Primeiros passos

npm install -g zn-gate
zn unlock                         # creates the vault the first time
zn env shadow .env                # moves the values into the vault; .env keeps markers
zn hooks install claude-code      # or: codex, cursor, opencode

Para permitir que um comando use um segredo, autorize esse programa:

zn secret allow DATABASE_URL_PASSWORD --command psql

Autorize um programa específico: node, python, npm, make e outros interpretadores executam qualquer código que recebam, então permitir um deles faz com que todo script que ele execute possa ler o segredo, e o zn avisa você quando isso acontece.

Para adicionar um único segredo, digite-o em um prompt oculto, nunca como argumento: zn secret set GITHUB_TOKEN --host api.github.com.

O passo a passo completo está no guia de segredos.

Comandos úteis

Se o cofre estiver bloqueado, os hooks ainda ocultam o que reconhecem, com marcadores que não podem ser restaurados (__ZN_REDACTED_AWS_KEY__), e lembram você de executar zn unlock.

Limites

• O scrubber encontra valores conhecidos e formatos reconhecíveis. Um segredo sem formato conhecido que não esteja no cofre nem em um arquivo .env pode passar: mova seus segredos para o cofre.
• Aprovar um arquivo de lote (.cmd, .bat) no Windows aprova esse arquivo, não os programas que ele inicia pelo nome. Prefira secrets_http_request para APIs HTTP, ou aprove o próprio programa.
• Enquanto o cofre estiver desbloqueado, qualquer programa executado com o seu usuário do sistema operacional, inclusive um comando que o agente execute, pode pedir a ele um segredo pelo nome. Bloqueie-o com zn lock quando não precisar dele.
• Um programa que você permitiu mantém o valor e pode enviá-lo para qualquer lugar: permita programas específicos, use tokens de escopo restrito e o sandbox do seu agente.
• Alguns agentes mantêm cópias locais próprias (o log de sessão do Codex mantém a saída original).
• O pacote Python (PyPI) tem redação de segredos nas suas funções de biblioteca (redact_secrets, sanitize_tool_result, guard), mas não o cofre, os hooks, o zn run nem a higienização de dados pessoais.

Para redação apenas na saída e nos argumentos de ferramentas MCP, veja Redação de segredos.

Código aberto

MIT, como o restante do zn-gate: github.com/usezn/zn. As alterações estão listadas no CHANGELOG.