Mantenha os segredos fora do seu agente de código (5 minutos)

O zn-gate mantém os valores secretos fora do que seu agente de código 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ó são preenchidos onde você permitiu. Tudo roda localmente e não precisa de conta.

Funciona com Claude Code, Codex CLI, Cursor (IDE) e OpenCode. O que cada agente pode e não pode fazer está em Agentes compatíveis; os limites estão no modelo de ameaças.

1. Instale e desbloqueie o cofre

npm install -g zn-gate
zn unlock

No Windows PowerShell, npm e npx podem falhar com "a execução de scripts foi desabilitada neste sistema". Use npm.cmd e npx.cmd, execute os comandos pelo Prompt de Comando ou permita scripts locais para a sua conta com Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. Mais em Instalar no Windows.

O primeiro zn unlock cria o cofre: uma identidade age guardada no chaveiro do seu sistema (Chaveiro do macOS, Gerenciador de Credenciais do Windows ou Secret Service no Linux), ou protegida por uma senha quando não há chaveiro. O cofre fica desbloqueado por 8 horas, ou até 30 minutos sem uso, ou até você executar zn lock.

Depois de atualizar o zn-gate, um cofre que ainda roda a versão anterior mantém os segredos como marcadores nos hooks do agente até ser reiniciado. zn vault status mostra a versão do cofre em execução e avisa se ela está desatualizada, e zn unlock o reinicia para você.

O zn pede que você confirme algumas coisas fora do agente (passo 4). Em um computador de mesa, ele mostra uma caixa de diálogo do sistema. Em um servidor ou por SSH não há diálogo: execute o cofre em um terminal separado e responda lá.

zn unlock --foreground

2. Mova os valores do seu .env para o cofre

zn env shadow .env

Cada valor sensível vai para o cofre e o .env guarda só marcadores:

DATABASE_URL=postgres://app:__ZN_DATABASE_URL_PASSWORD__@db:5432/app
STRIPE_KEY=__ZN_STRIPE_KEY__
PORT=3000

Uma cópia criptografada do original é mantida, e zn env unshadow a restaura. Para adicionar um único segredo, digite-o em um prompt oculto (nunca como argumento):

zn secret set GITHUB_TOKEN --host api.github.com

3. Instale os hooks do seu agente

zn hooks install claude-code     # ou: codex, cursor, opencode

A partir de agora, cada leitura de arquivo, saída de comando e prompt colado passa pelo depurador antes de chegar ao modelo. Valores conhecidos, mais de 60 formatos de segredo (chaves de nuvem, tokens, chaves privadas, strings de conexão) e dados pessoais que passam em uma soma de verificação são substituídos por marcadores. Os detalhes estão em Redação.

O que os hooks bloqueiam:

• Leituras de arquivos .env que contêm valores reais.
• Arquivos de credenciais como ~/.aws/credentials, ~/.ssh/id_* e ~/.npmrc, e a própria pasta ~/.zn do zn.
• Um prompt que contém um segredo: ele não é enviado. Nos prompts, o zn também bloqueia um valor de 8 ou mais caracteres atribuído a um nome de credencial, mesmo no meio de uma frase (my key is STRIPE_KEY=..., DB_PASSWORD=...). Deixa passar um valor de exemplo (changeme123, <key>), uma referência (${API_KEY}, __ZN_STRIPE_KEY__) ou código. Guarde o valor com zn secret set NAME e escreva __ZN_NAME__ no prompt.

O Codex só executa hooks novos depois que você confia neles: abra o Codex e use /hooks.

Em um computador gerenciado por uma organização, o Claude Code pode ser configurado para ignorar os hooks e os servidores MCP que você instala por conta própria (disableAllHooks, allowManagedHooksOnly, managed-mcp.json ou uma lista de permissão ou bloqueio de MCP), sem avisar você. zn hooks install claude-code e zn-gate status leem os arquivos de configuração gerenciada deste computador e os seus, e avisam quando um deles impede os hooks do zn ou o servidor secrets. Peça ao seu administrador para adicionar o zn à configuração gerenciada. Uma política enviada pelo claude.ai, pelo gerenciamento de dispositivos (MDM) ou pelo registro do Windows não é lida, então, quando essa política existe, o Claude Code pode ignorar os arquivos de configuração gerenciada. claude doctor e /status mostram qual origem o Claude Code usou.

4. Deixe um comando usar um segredo

Permita o programa que precisa do valor:

zn secret allow DATABASE_URL_PASSWORD --command psql

Quando o agente executa psql "postgres://app:__ZN_DATABASE_URL_PASSWORD__@db/app", o hook o encaminha por zn run. O valor vai só para esse processo e a saída é mascarada: as formas bruta, base64, hexadecimal e codificada em URL voltam como o marcador. Na primeira vez, o cofre pede que você confirme na caixa de diálogo ou no terminal dele, e o aviso mostra o programa exato que vai rodar. Mudar a política de um segredo (zn secret allow) é confirmado do mesmo jeito. O agente não consegue responder a esses avisos pelo próprio terminal.

Permita um programa específico. node, python, npm, make e outros interpretadores executam qualquer código que recebem, então permitir um deles deixa todo script que ele roda ler o segredo. O zn avisa quando você faz isso.

5. Deixe o agente chamar uma API

Para APIs HTTP, use o servidor MCP secrets em vez de colocar o valor em um processo. zn hooks install mostra como registrá-lo no seu agente. O agente chama secrets_http_request com o marcador em um cabeçalho:

{ "method": "GET", "url": "https://api.github.com/user",
  "headers": { "Authorization": "Bearer __ZN_GITHUB_TOKEN__" } }

O zn envia a requisição só aos hosts permitidos do segredo (allowHosts), só com o valor em cabeçalhos (para usá-lo na URL ou no corpo, execute zn secret allow NAME --in query|body), e devolve a resposta com os segredos trocados por marcadores. Não existe nenhuma ferramenta que devolva um valor.

Configurações MCP

O servidor secrets acima é o jeito seguro de o agente usar uma chave. Uma chave escrita em texto simples em um arquivo de configuração do agente é o oposto: ela viaja com o repositório. O zn audit aponta um valor secreto em um arquivo de configuração ou de instruções de um agente (achado ZNA011) e nunca imprime o valor. Veja Auditoria.

Referência de comandos

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

Para verificar o que está protegido na sua máquina, execute npx -y zn-gate check.