Cómo evitar que Cursor lea tu .env

Qué cubre el archivo .cursorignore de Cursor y qué no, qué añaden los hooks de zn-gate para los archivos .env y una prueba corta que puedes hacer en tu propia máquina con valores falsos.

Ver .md

Dos capas ayudan a mantener un archivo .env fuera del alcance del agente de Cursor. El archivo de exclusión propio de Cursor, .cursorignore, controla qué archivos pueden ver el agente, Tab e Inline Edit. zn-gate añade hooks que bloquean las lecturas de archivos y la mayoría de los comandos de shell que leen archivos .env con valores. Esta página explica qué hace cada una según su documentación y te da una prueba para hacer tú mismo.

Qué hace .cursorignore

Según la documentación de Cursor sobre archivos de exclusión:

  • Creas un archivo .cursorignore en el directorio raíz, con la sintaxis de .gitignore.
  • Cursor impide que los archivos listados en él lleguen a "Code accessible by Agent, Tab, and Inline Edit" y a "Code accessible via @ mention references."
  • Cursor "automatically ignores files in .gitignore and the default ignore list". Esa lista por defecto incluye .env*.
  • Puedes activar los archivos de exclusión jerárquicos en Cursor Settings > Indexing > Ignore Files > Hierarchical Cursor Ignore y definir patrones globales en los ajustes de usuario (la lista global está vacía por defecto).

Un .cursorignore mínimo:

.env
.env.*

Qué no cubre .cursorignore

La misma página de Cursor indica dos límites:

  • "The terminal and MCP server tools used by Agent cannot block access to code governed by .cursorignore." (Las herramientas de terminal y de servidores MCP que usa el agente no pueden bloquear el acceso a lo que gobierna .cursorignore.)
  • "While Cursor blocks ignored files, complete protection isn't guaranteed due to LLM unpredictability." (Cursor bloquea los archivos ignorados, pero no garantiza una protección completa por la imprevisibilidad de los LLM.)

Por tanto, un archivo de exclusión es una primera capa útil, pero, según la propia documentación de Cursor, no cubre todos los caminos hasta un archivo.

Qué añade zn-gate en Cursor

zn hooks install cursor escribe el hooks.json de Cursor. La documentación de hooks de Cursor describe los eventos que usa zn-gate: beforeReadFile ("Called before Agent reads a file. Use for access control to block sensitive files from being sent to the model") y beforeShellExecution (se llama antes de ejecutar un comando de shell y devuelve una decisión de permiso). Con los hooks instalados:

  • Se bloquean las lecturas de archivos y la mayoría de los comandos de shell que leen archivos .env con valores y los archivos de credenciales habituales.
  • Se bloquea un secreto pegado en un prompt.
  • Se bloquean las llamadas MCP que llevan un valor secreto.
  • Los secretos que zn-gate reconoce se eliminan de la salida de las herramientas MCP.

Instálalo:

npm install -g zn-gate
zn hooks install cursor

Reinicia Cursor y ejecuta zn-gate check en una terminal. Debería mostrar OK para Cursor (qué significa la salida).

Qué no cubre zn-gate en Cursor

  • La salida del shell y el contenido de los archivos no se limpian. La documentación de Cursor no lista ningún hook que los cambie: postToolUse solo puede reemplazar la salida de las herramientas MCP (updated_mcp_tool_output, "For MCP tools only").
  • Un secreto impreso por un comando de shell, o escrito en un archivo que el agente lee y que no está bloqueado, llega al modelo.
  • La protección de escritura es de mejor esfuerzo, porque Cursor no documenta la entrada de todas sus herramientas.
  • El CLI de Cursor (cursor-agent) no está cubierto.
  • Si el hook de zn falla, las lecturas y los prompts se bloquean, y los demás eventos se ejecutan sin comprobar.
  • No probado en Windows.

Si quieres sacar los valores del archivo por completo, guárdalos en la bóveda de zn-gate: zn unlock y después zn env shadow .env. Tu .env pasa a contener marcadores en lugar de valores reales (Scrubber).

Pruébalo en tu propia máquina

Esta prueba usa valores falsos. No la hemos ejecutado de principio a fin en Cursor (mira la nota de estado en la página de Cursor), así que lo que sigue es lo que cabe esperar según la documentación y cómo comprobar cada paso tú mismo.

  1. En una carpeta nueva y vacía, crea un archivo .env solo con valores falsos:

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

  2. Abre la carpeta en Cursor y pide al agente: "Lee el archivo .env y dime qué contiene." Anota lo que pasa. Según la lista de exclusión por defecto de Cursor, los archivos .env* ya deberían estar ignorados.

  3. Crea un archivo .cursorignore con el contenido .env. Si la carpeta es un repositorio git, ejecuta git check-ignore -v .env (la documentación de Cursor sugiere git check-ignore -v [file] para probar patrones). Vuelve a preguntar y compara.

  4. Pide al agente que ejecute un comando de terminal que imprima el archivo. La documentación de Cursor dice que las herramientas de terminal no están gobernadas por .cursorignore, así que comprueba qué ves.

  5. Instala los hooks (zn hooks install cursor), reinicia Cursor y repite los pasos 2 y 4. Según la documentación de zn-gate, las lecturas y la mayoría de los comandos de shell que leen el .env deberían bloquearse, y el agente debería recibir un mensaje del hook en lugar de los valores.

  6. Borra la carpeta de prueba al terminar. Para quitar los hooks: zn hooks uninstall cursor.

Aquí solo cuentan tus propios resultados. Si algún paso se comporta distinto de lo que dice esta página, escríbenos e incluye tu versión de Cursor.

Preguntas frecuentes

¿.cursorignore impide que Cursor lea .env? Bloquea los archivos listados para el agente, Tab, Inline Edit y las menciones con @. La documentación de Cursor dice que las herramientas de terminal y MCP que usa el agente no están gobernadas por él y que la protección no está garantizada.

¿.env se ignora por defecto en Cursor? La documentación de Cursor incluye .env* en su lista de exclusión por defecto, junto con los archivos de tu .gitignore.

¿zn-gate sustituye a .cursorignore? No. Actúan en puntos distintos. Usa los dos.

¿Puede zn-gate ocultar secretos de la salida del shell de Cursor? No. Cursor no permite que los hooks cambien la salida del shell ni de los archivos; solo se limpia la salida de las herramientas MCP.

¿Cómo lo deshago? zn hooks uninstall cursor.

Fuentes