Como impedir que o Cursor leia o seu .env

O que o arquivo .cursorignore do Cursor cobre e o que não cobre, o que os hooks do zn-gate acrescentam para arquivos .env e um teste curto que você pode fazer na sua própria máquina com valores falsos.

Ver .md

Duas camadas ajudam a manter um arquivo .env longe do agente do Cursor. O arquivo de exclusão do próprio Cursor, .cursorignore, controla quais arquivos o agente, o Tab e o Inline Edit podem ver. O zn-gate acrescenta hooks que bloqueiam leituras de arquivos e a maioria dos comandos de shell que leem arquivos .env com valores. Esta página explica o que cada uma faz segundo a sua documentação e traz um teste para você mesmo executar.

O que o .cursorignore faz

Segundo a documentação do Cursor sobre arquivos de exclusão:

  • Você cria um arquivo .cursorignore no diretório raiz, com a sintaxe do .gitignore.
  • O Cursor impede que os arquivos listados nele cheguem a "Code accessible by Agent, Tab, and Inline Edit" e a "Code accessible via @ mention references."
  • O Cursor "automatically ignores files in .gitignore and the default ignore list". Essa lista padrão inclui .env*.
  • Você pode ativar os arquivos de exclusão hierárquicos em Cursor Settings > Indexing > Ignore Files > Hierarchical Cursor Ignore e definir padrões globais nas configurações de usuário (a lista global vem vazia).

Um .cursorignore mínimo:

.env
.env.*

O que o .cursorignore não cobre

A mesma página do Cursor indica dois limites:

  • "The terminal and MCP server tools used by Agent cannot block access to code governed by .cursorignore." (As ferramentas de terminal e de servidores MCP usadas pelo agente não conseguem bloquear o acesso ao que o .cursorignore controla.)
  • "While Cursor blocks ignored files, complete protection isn't guaranteed due to LLM unpredictability." (O Cursor bloqueia os arquivos ignorados, mas a proteção completa não é garantida por causa da imprevisibilidade dos LLMs.)

Assim, um arquivo de exclusão é uma primeira camada útil, mas, segundo a própria documentação do Cursor, não cobre todos os caminhos até um arquivo.

O que o zn-gate acrescenta no Cursor

zn hooks install cursor grava o hooks.json do Cursor. A documentação de hooks do Cursor descreve os eventos que o zn-gate usa: beforeReadFile ("Called before Agent reads a file. Use for access control to block sensitive files from being sent to the model") e beforeShellExecution (chamado antes de um comando de shell ser executado, com uma decisão de permissão). Com os hooks instalados:

  • Leituras de arquivos e a maioria dos comandos de shell que leem arquivos .env com valores, e arquivos de credenciais comuns, são bloqueados.
  • Um segredo colado em um prompt é bloqueado.
  • Chamadas MCP que carregam um valor secreto são bloqueadas.
  • Os segredos que o zn-gate reconhece são removidos da saída das ferramentas MCP.

Instale:

npm install -g zn-gate
zn hooks install cursor

Reinicie o Cursor e execute zn-gate check em um terminal. Ele deve mostrar OK para o Cursor (o que a saída significa).

O que o zn-gate não cobre no Cursor

  • A saída do shell e o conteúdo dos arquivos não são limpos. A documentação do Cursor não lista nenhum hook que os altere: o postToolUse só pode substituir a saída das ferramentas MCP (updated_mcp_tool_output, "For MCP tools only").
  • Um segredo impresso por um comando de shell, ou escrito em um arquivo que o agente lê e que não está bloqueado, chega ao modelo.
  • A proteção de escrita é de melhor esforço, porque o Cursor não documenta a entrada de todas as ferramentas.
  • A CLI do Cursor (cursor-agent) não é coberta.
  • Se o hook do zn falhar, leituras e prompts são bloqueados, e os demais eventos rodam sem verificação.
  • Não testado no Windows.

Se você quer tirar os valores do arquivo por completo, guarde-os no cofre do zn-gate: zn unlock e depois zn env shadow .env. O seu .env passa a ter marcadores no lugar dos valores reais (Scrubber).

Teste na sua própria máquina

Este teste usa valores falsos. Não o executamos de ponta a ponta no Cursor (veja a nota de status na página do Cursor), então o que segue é o que esperar segundo a documentação e como conferir cada passo você mesmo.

  1. Em uma pasta nova e vazia, crie um arquivo .env somente com valores falsos:

    EXAMPLE_KEY=not-a-real-key
EXAMPLE_URL=https://example.com

  2. Abra a pasta no Cursor e peça ao agente: "Leia o arquivo .env e diga o que há nele." Anote o que acontece. Pela lista de exclusão padrão do Cursor, os arquivos .env* já deveriam estar ignorados.

  3. Crie um arquivo .cursorignore com o conteúdo .env. Se a pasta for um repositório git, execute git check-ignore -v .env (a documentação do Cursor sugere git check-ignore -v [file] para testar padrões). Pergunte de novo e compare.

  4. Peça ao agente que execute um comando de terminal que imprima o arquivo. A documentação do Cursor diz que as ferramentas de terminal não são controladas pelo .cursorignore, então confira o que você vê.

  5. Instale os hooks (zn hooks install cursor), reinicie o Cursor e repita os passos 2 e 4. Segundo a documentação do zn-gate, as leituras e a maioria dos comandos de shell que leem o .env devem ser bloqueados, e o agente deve receber uma mensagem do hook no lugar dos valores.

  6. Apague a pasta de teste ao terminar. Para remover os hooks: zn hooks uninstall cursor.

Aqui só contam os seus próprios resultados. Se algum passo se comportar de forma diferente do que esta página diz, escreva para nós informando a sua versão do Cursor.

Perguntas frequentes

O .cursorignore impede o Cursor de ler o .env? Ele bloqueia os arquivos listados para o agente, o Tab, o Inline Edit e as menções com @. A documentação do Cursor diz que as ferramentas de terminal e MCP usadas pelo agente não são controladas por ele e que a proteção não é garantida.

O .env é ignorado por padrão no Cursor? A documentação do Cursor inclui .env* na lista de exclusão padrão, junto com os arquivos do seu .gitignore.

O zn-gate substitui o .cursorignore? Não. Eles atuam em pontos diferentes. Use os dois.

O zn-gate consegue esconder segredos da saída do shell do Cursor? Não. O Cursor não permite que hooks alterem a saída do shell nem dos arquivos; só a saída das ferramentas MCP é limpa.

Como desfaço? zn hooks uninstall cursor.

Fontes