Colei uma chave de API no meu agente de código. E agora?

Faça primeiro a rotação ou a revogação da chave, depois cuide das cópias no histórico do seu agente e, por fim, configure o zn-gate para que a próxima seja bloqueada ou trocada por um marcador antes que o modelo a veja.

Ver .md

Você digitou ou colou uma chave de API no chat de um agente de código, ou o agente a leu de um arquivo. A chave agora está na conversa enviada ao modelo e, provavelmente, no histórico do agente no seu disco. Esta página traz os passos na ordem que importa: rotacionar a chave, limpar as cópias e evitar que aconteça de novo.

1. Rotacione ou revogue a chave primeiro

Faça isto antes de qualquer outra coisa. Apagar um chat ou um arquivo de histórico não desfaz uma cópia que já foi enviada a um provedor de modelos ou guardada em um backup. Só a revogação da chave torna inútil o valor vazado.

  1. Abra o console do serviço que emitiu a chave. Encontre a chave na lista de chaves de API, tokens ou chaves de acesso.
  2. Crie uma chave nova se algo depende da antiga. Se um serviço em produção usa a chave e você não pode ficar fora do ar, crie primeiro a substituta, faça sua aplicação passar a usá-la, atualize todos os outros lugares que usam a chave (segredos de CI, configurações de deploy, colegas de equipe) e só então revogue a antiga. AWS, GitHub e Google Cloud descrevem essa ordem em suas próprias páginas. Se nada depende da chave, revogue-a imediatamente.
  3. Revogue ou exclua a chave antiga. Não a deixe ativa "por enquanto".
  4. Dê à chave nova as permissões mínimas de que ela precisa.
  5. Guarde a chave nova onde o agente não a leia. Não no chat, nem em um arquivo .env comum que o agente possa abrir. Veja o passo 3 abaixo.
  6. Consulte o registro de uso ou de acesso do provedor para a chave antiga. Se aparecerem requisições que você não reconhece, trate a conta como comprometida e siga as orientações do provedor.

Onde revogar, segundo a documentação de cada provedor:

Provedor O que a documentação diz
AWS Updating IAM user access keys: crie uma segunda chave, passe suas aplicações para ela, desative a primeira e exclua-a quando nada mais precisar dela.
GitHub Remediating a leaked secret: um guia passo a passo que inclui revogar o segredo, encontrar os serviços que o usam e verificar acessos não autorizados. Os tokens são gerenciados em Managing your personal access tokens.
Google Cloud API keys: a página explica como rotacionar uma chave, o que cria uma chave nova com as mesmas restrições, e como excluir a antiga quando suas aplicações já usam a nova.
Stripe API keys: como renovar (roll) uma chave e quando a antiga expira.
Anthropic API key best practices: se você suspeita que uma chave foi comprometida, revogue-a na página de chaves de API do Claude Console com "Delete API key".

Para um serviço que não está na lista, abra a documentação dele e procure como revogar, rotacionar ou renovar uma chave. Só indicamos páginas que conseguimos abrir e ler.

2. Limpe as cópias que ficam na sua máquina

Claude Code, Codex CLI, Cursor e OpenCode guardam um histórico das suas conversas, e uma chave que você digitou ou que passou por uma ferramenta pode estar nele. O Claude Code também guarda cada prompt que você digita em um arquivo de histórico de prompts separado. Cada agente guarda o histórico em um lugar diferente e tem controles diferentes, e para alguns a documentação não diz nada sobre o caminho local nem sobre a retenção.

Reunimos isso em um único guia para que fique correto em um só lugar: Os agentes de código guardam suas chaves de API nas transcrições? Ele mostra onde cada um dos quatro agentes guarda o histórico segundo a documentação do fabricante, por quanto tempo o mantém, o que cada fabricante diz sobre envios, como encontrar os arquivos que contêm uma chave e apagá-los, e as cópias fáceis de esquecer, como backups e a sincronização na nuvem da sua pasta pessoal.

Faça isso depois do passo 1, não no lugar dele.

3. Evite a próxima com o zn-gate

O zn-gate é uma camada local entre seu agente de código e as ferramentas dele. Ele roda na sua máquina, sem conta. Seu Scrubber de segredos está disponível a partir do zn-gate 1.5.0 (no Windows, a partir da 1.5.1) e funciona com Claude Code, Codex CLI, Cursor (IDE) e OpenCode. O que ele consegue alterar depende de cada agente.

O que ele faz com uma chave que você está prestes a colar

Segundo a página Scrubber e cofre de segredos:

  • Prompts colados, leituras de arquivos, saída de comandos, buscas e resultados de ferramentas MCP passam pelo Scrubber antes de chegar ao modelo. Os valores que ele conhece (do cofre e dos seus arquivos .env) e mais de 60 formatos de segredos viram marcadores estáveis, como __ZN_AWS_KEY_1__, de modo que, onde o agente deixa o zn-gate reescrevê-los, o modelo recebe o marcador em vez do valor (veja os limites abaixo).
  • Os hooks bloqueiam a leitura de arquivos .env que contêm valores reais e de arquivos de credenciais como ~/.aws/credentials ou ~/.ssh/id_*. A documentação chama isso de uma proteção, não de um sandbox.
  • Os valores reais ficam em um cofre criptografado na sua máquina. O agente trabalha com marcadores, e um valor só é preenchido onde você permitiu.

Um segredo colado em um prompt é bloqueado nos quatro agentes, então o prompt não chega ao modelo. O bloqueio não apaga o que você digitou da sua própria máquina: o agente pode guardar o prompt localmente (o Claude Code o guarda em texto claro na transcrição). Os marcadores só aparecem na saída de ferramentas que o zn-gate limpou.

Os tokens que ficam no env ou nos headers de um servidor MCP são outro caso: Tokens em texto simples na sua configuração MCP: como tirá-los de lá mostra como tirá-los do arquivo de configuração.

Configure

Você precisa do Node.js 18 ou posterior. Execute isto no seu próprio terminal:

npx -y zn-gate init
npx -y zn-gate unlock
npx -y zn-gate env shadow .env
npx -y zn-gate check
  • init encontra os quatro agentes na sua máquina, mostra a configuração de cada um que ainda não está protegido e executa cada passo depois que você confirma.
  • unlock cria o cofre na primeira vez. Com o chaveiro do sistema, ele precisa de um terminal interativo.
  • env shadow .env move os valores do seu arquivo .env para o cofre. O arquivo fica com marcadores como __ZN_STRIPE_KEY__.
  • check testa com um segredo falso em uma pasta temporária e diz qual agente não está protegido. Nada é enviado a lugar nenhum. O que a saída significa.

Para adicionar um único segredo sem colá-lo em um chat nem colocá-lo em uma linha de comando, digite-o em um prompt oculto: zn secret set GITHUB_TOKEN --host api.github.com. A documentação diz para nunca passar um segredo como argumento.

Para testar com um valor falso, abra seu agente em uma pasta vazia e cole no prompt a chave de exemplo da documentação da AWS AKIAIOSFODNN7EXAMPLE. Se o zn-gate reconhecer o formato, o prompt é bloqueado. Se não for bloqueado, esse formato pode não ser um dos que o zn-gate detecta, e este teste não diz nada sobre as suas chaves reais.

O que o zn-gate não faz

Estes limites vêm da página Scrubber e cofre de segredos e do modelo de ameaças do zn-gate.

  • Ele não limpa as transcrições escritas antes de você instalá-lo. A chave que você colou hoje continua nelas até você apagá-las (passo 2).
  • Ele não revoga nada e não controla o que um fabricante de agente guarda em seus servidores. A rotação é sempre o passo 1.
  • 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.
  • No Cursor, só a saída das ferramentas MCP pode ser reescrita. A saída do shell e o conteúdo dos arquivos não são limpos ali.
  • Alguns agentes guardam as próprias cópias locais. O log de sessão do Codex mantém a saída original.
  • No Claude Code, um prompt que o zn-gate bloqueou permanece na transcrição em texto claro, como diz a própria documentação do Claude Code.

Perguntas frequentes

Preciso rotacionar a chave se apaguei a conversa? Sim. Apagar arquivos locais não remove uma cópia enviada ao provedor do modelo ou guardada em um backup. Revogue a chave primeiro.

Posso apagar a transcrição e continuar com a chave? Não é seguro. A chave foi enviada ao modelo como parte da conversa, então considere-a exposta.

O zn-gate remove uma chave que já está no meu histórico? Não. Ele atua sobre novos prompts e sobre a saída de ferramentas. Os arquivos de histórico existentes ficam como estão.

O zn-gate vai me impedir de colar uma chave? Ele bloqueia um segredo colado em um prompt quando reconhece o formato, no Claude Code, no Codex CLI, no Cursor e no OpenCode. Um segredo em um formato que ele não conhece pode passar, então mantenha as chaves fora dos chats de qualquer forma.

Como removo os hooks do zn-gate? zn hooks uninstall <agente>, por exemplo zn hooks uninstall codex.

Páginas relacionadas

Fontes