Saltar al contenido

Tu agente de IA puede leer tu .env: cómo proteger tus llaves

En la práctica/ 14 min de lectura

Tu agente de IA lee el .env sin pedir permiso. Tres medidas: una regla deny de Read, llaves de prueba en desarrollo y las reales solo en el gestor de secretos.

  • IA
  • Seguridad
  • Claude Code
En este artículo (9)
  1. Por qué tu agente de IA puede leer el .env
  2. Bloquear la lectura con deny
  3. Llaves de prueba en desarrollo
  4. Llaves reales en el gestor de secretos
  5. .gitignore no basta
  6. Qué hacer si una llave se filtró: rotarla
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

Un agente de IA como Claude Code puede leer tu .env sin pedirte permiso: leer archivos del proyecto no requiere aprobación, y lo que lee entra en la conversación. Protégelo con tres medidas: una regla deny de Read para los archivos de secretos, llaves de prueba en desarrollo y las reales solo en el gestor de secretos de tu plataforma.

Aquí no repetimos lo que ya está escrito: la sintaxis completa de reglas vive en permisos de Claude Code en settings.json y el bloqueo desde la terminal en el hook para proteger tu .env. Este artículo junta las tres medidas, explica por qué .gitignore no te protege del agente y qué hacer si una llave ya se filtró. Revisado contra la documentación oficial el 19 de noviembre de 2026.

Por qué tu agente de IA puede leer el .env

Según la documentación de permisos de Claude Code, las herramientas de solo lectura, como leer un archivo o buscar con Grep, no piden aprobación dentro del directorio de trabajo. Comandos como cat, head o grep forman parte de un conjunto de solo lectura que corre sin preguntar en todos los modos. Tu .env está en el directorio de trabajo, así que para el agente leerlo es tan normal como leer package.json.

El modo auto tampoco lo frena. En la lista de lo que su clasificador permite por defecto, la documentación de los modos de permisos incluye leer el .env y enviar las credenciales a la API que les corresponde. Para el trabajo diario tiene sentido; para tus llaves significa que su valor entra en la conversación.

Y lo que entra en la conversación no se queda en tu pantalla. La página de uso de datos explica que Claude Code envía por la red los prompts y las respuestas del modelo, cifrados con TLS, y que guarda las transcripciones en texto plano en ~/.claude/projects/ durante 30 días por defecto (se ajusta con cleanupPeriodDays). Desde ahí, una llave también puede acabar en un archivo de prueba que el agente escribió, en un log o en un commit.

lo que el agente lee entra en la conversación.envSECRET_KEY=…en tu carpetaagente de IARead · cat · grepsin pedir permisoconversaciónviaja al modelopor TLSdenyReadarchivo, log o commitlo que el agente escribe~/.claude/projects/texto plano, 30 días por defectodeny corta la primera flechafuente: documentación de Claude Code (permisos, uso de datos)

Desliza la figura para verla completa

Tampoco hace falta que el agente se equivoque. Basta una instrucción escondida en un README, un issue o una skill que instalaste: el agente la lee como parte del contexto y puede seguirla. Por eso conviene escanear una skill antes de instalarla, y por eso ninguna de las tres medidas depende de que el modelo se porte bien.

Bloquear la lectura con deny

La primera medida es una regla deny de Read para tus archivos de secretos. Va en .claude/settings.json, el archivo del proyecto que se sube al repo, así protege a todo el equipo:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(!.env.example)",
      "Read(*.pem)"
    ]
  }
}
  1. $schema le da a tu editor el esquema de SchemaStore, que marca una regla mal escrita, como un paréntesis sin cerrar. Valida la forma, no lo que la regla bloquea.
  2. permissions.deny es la lista de usos que Claude Code bloquea. Un deny gana en cualquier modo y desde cualquier archivo de configuración.
  3. Read(.env): un nombre de archivo suelto sigue la sintaxis de .gitignore y coincide a cualquier profundidad, así que bloquea el .env de la raíz y el de apps/web/.env.
  4. Read(.env.*) cubre .env.local, .env.production y cualquier otra variante.
  5. Read(!.env.example) empieza con !: es una excepción que reabre la plantilla. Funciona porque va después de la regla que la bloquea y está en el mismo archivo; un ! puesto primero no recorta nada. El agente necesita los nombres de las variables, no sus valores.
  6. Read(*.pem) bloquea certificados y llaves privadas en formato PEM, también a cualquier profundidad.

Qué cubre exactamente, según la documentación de permisos y la referencia de permissions.deny: las herramientas de archivos de Claude (Read, y como mejor esfuerzo Grep y Glob), las menciones con @, el contexto que comparte el IDE, los comandos de archivos que Claude Code reconoce en Bash, como cat, head, tail, sed y tee, y los destinos de redirecciones como < .env. Además, un deny de Read bloquea Edit y Write sobre la misma ruta.

Lo que no cubre, también según la documentación: un comando que lee archivos sin nombrarlos, como grep -r pattern ., ni un script de Python o de Node que abre el archivo por su cuenta. La documentación nombra comandos de Bash y no dice nada de Get-Content en PowerShell; en Windows, el hook PreToolUse cierra ese hueco. Para un bloqueo a nivel del sistema operativo, la documentación remite al sandbox, que limita lo que leen los comandos de shell y sus procesos. Funciona en macOS, Linux y WSL2; en Windows nativo, Claude Code corre los comandos sin sandbox. Y un detalle que confunde: un archivo .claudeignore no tiene ningún efecto.

Para cubrir todos tus proyectos, pon reglas con ruta absoluta en ~/.claude/settings.json: Read(//**/.env) y Read(//**/.env.*). Ahí la excepción no sirve: un ! solo recorta reglas relativas del mismo archivo, así que .env.example queda bloqueado en todos lados y ningún archivo de proyecto lo reabre. La sintaxis de rutas está explicada a fondo en el artículo de permisos.

Llaves de prueba en desarrollo

La regla deny reduce lo que el agente ve, pero tiene huecos documentados. La segunda medida hace que esos huecos importen poco: que en tu máquina no haya ninguna llave capaz de mover dinero o tocar datos reales. Si el agente lee una llave de prueba, lo peor que pasa es que rotas una llave sin clientes detrás.

Casi todos los proveedores separan los dos mundos. En Stripe, por ejemplo, cada entorno de prueba tiene sus propias claves, que empiezan con sk_test_, rk_test_ y pk_test_, mientras que las del modo activo empiezan con sk_live_, rk_live_ y pk_live_; los objetos de un modo no existen en el otro. También ofrece claves restringidas, con solo los permisos que tu código usa. Una regla práctica: si una llave de tu .env dice live o abre la base de datos de producción, no debería estar ahí. Para la base de datos, usa una copia local o un usuario de solo lectura, como en el MCP de Postgres de solo lectura.

Ojo con la plataforma donde despliegas. Según su documentación de variables, Railway pasa las variables del entorno vinculado a tu terminal con railway run y railway shell. Si tu carpeta está vinculada al entorno de producción y abres el agente dentro de railway shell, las llaves reales quedan en el entorno de cada comando que ejecute, y la regla deny no lo nota porque no hay archivo que leer. Vincula tu máquina a un entorno de desarrollo. Para lo que sí quede en el entorno, la variable CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 quita las credenciales que reconoce, por nombre o por valor, del entorno de los comandos, hooks y servidores MCP que lanza Claude Code (deja los tokens de GitHub).

tres medidas, cada una cubre un hueco de las otras01deny de Readsettings.jsonbloquea Read y cathuecos: grep -r, scriptsreduce lo que ve02llaves de pruebask_test_… en localsin clientes detrásrotarla cuesta pocoacota el daño03gestor de secretosRailway (sealed)Secret Managerfuera de tu discoaleja la llave realninguna depende de que el modelo obedezcasi una falla, las otras dos siguen en pieprefijos sk_test_ de Stripe como ejemplo

Desliza la figura para verla completa

Llaves reales en el gestor de secretos

La tercera medida: las llaves de producción viven en un solo lugar, el gestor de secretos de la plataforma que corre tu app, y en ningún archivo. Tu servicio las recibe como variables de entorno al arrancar; ni tu disco ni tu repo las tienen. Dos ejemplos, descritos desde la documentación de cada plataforma:

  • Railway. Las variables de cada servicio se definen en su pestaña Variables y llegan al build y al despliegue como variables de entorno; cada cambio queda pendiente hasta que lo revisas y despliegas. Una variable sellada (sealed) se entrega a builds y despliegues, pero no se ve en la interfaz, no se puede leer por la API y no se entrega con railway run ni con railway variables. Sellarla no tiene vuelta atrás.
  • Google Cloud. Para Cloud Run, Google recomienda guardar llaves y contraseñas en Secret Manager y pasarlas como variable de entorno o como volumen. Las variables de entorno se resuelven al arrancar la instancia, así que Google recomienda fijar una versión del secreto en lugar de latest. La identidad del servicio necesita el rol roles/secretmanager.secretAccessor.

Con las tres medidas, cada llave tiene un lugar y sabes qué pasa si se escapa:

LlaveDónde vive¿La ve el agente?Si se filtra
Nombres de variables, sin valores.env.example, en el repoSí, a propósitoNada que rotar
Llave de prueba.env.local en tu máquina, fuera de gitBloqueada por deny, salvo por los huecos documentadosRotas una llave sin datos reales
Llave real de producciónGestor de secretos de la plataformaNo: solo la recibe el servicio desplegadoRotación urgente
Llave real en un .env localTu disco y, si el agente la leyó, la transcripciónSí, en cuanto falla una barreraRotación urgente; no debería existir
dónde vive cada llave y quién la vellavedónde vive¿la ve el agente?.env.examplesolo nombresel repoen gitsía propósitollave de pruebask_test_….env.localtu máquina, fuera de gitno con denysalvo huecos documentadosllave realde produccióngestor de secretosRailway, Secret Managernosolo el servicio en líneallave real en .envlocaltu disco y la transcripción~/.claude/projects/sísi falla una barrerala llave real nunca en tu discohuecos: grep -r y scripts que abren el archivo

Desliza la figura para verla completa

.gitignore no basta

.gitignore le dice a git qué archivos dejar fuera de un commit. No es una regla para el agente: en Claude Code, el ajuste respectGitignore solo cambia lo que muestra el selector de archivos de @, no lo que puede leer la herramienta Read. Y en git tampoco cubre todo: la documentación de gitignore dice que los archivos que git ya rastrea no se ven afectados. Lo probamos en un repo desechable con git 2.54 y una llave falsa: un primer commit con el .env dentro y, después, .env en .gitignore.

$ git check-ignore -v .env
$ git check-ignore -v --no-index .env
.gitignore:1:.env	.env
$ git ls-files .env
.env
$ git status --short
 M .env
$ git rm --cached .env
rm '.env'
$ git commit -qm "stop tracking .env"
$ git log --oneline --all -- .env
<hash> stop tracking .env
<hash> first commit
$ git show HEAD~2:.env
PAYMENTS_SECRET_KEY=sk_test_FALSO_123
  1. git check-ignore -v .env no imprime nada: para git, un archivo rastreado no está ignorado, aunque aparezca en .gitignore.
  2. Con --no-index sí muestra la regla: el patrón existe, pero no se aplica a este archivo.
  3. git ls-files confirma que .env sigue en el índice.
  4. git status lo marca como modificado: el siguiente git commit -a sube el valor nuevo.
  5. git rm --cached lo saca del índice sin borrarlo del disco, y el commit registra ese cambio.
  6. git log -- .env muestra que el archivo sigue en dos commits del historial.
  7. git show recupera la llave del primer commit. Cualquiera con una copia del repo puede hacer lo mismo.

Por eso la guía de GitHub para quitar datos sensibles pide, como primer paso, revocar o rotar el secreto; reescribir el historial viene después y a veces ni hace falta. Si te cuesta ver qué entra en cada commit cuando trabaja el agente, revisa el flujo de git para trabajar con agentes de IA.

Qué hacer si una llave se filtró: rotarla

Una llave que el agente leyó está en la transcripción local y viajó en una petición al modelo. Una que llegó a un commit está en cada clon. En ningún caso se puede "desleer": se rota. Los pasos generales, con el orden para una llave que mueve dinero, están en variables NEXT_PUBLIC_ y secretos. Aquí va la parte que cambia con un gestor de secretos, en el caso de Secret Manager y Cloud Run (los números de versión son ilustrativos):

# 1. Add the new key as a new version, read from standard input
gcloud secrets versions add PAYMENTS_KEY --data-file=-

# 2. Point the service at that version; this deploys a new revision
gcloud run services update my-service \
  --update-secrets=PAYMENTS_SECRET_KEY=PAYMENTS_KEY:2

# 3. When the new revision serves traffic, disable the old version
gcloud secrets versions disable 1 --secret=PAYMENTS_KEY
  1. versions add crea la versión 2 del secreto. Con --data-file=-, gcloud lee el valor de la entrada estándar, así no lo dejas en un archivo.
  2. services update con --update-secrets cambia la variable de entorno a la versión 2. Como el valor se resuelve al arrancar la instancia, hace falta esta revisión nueva; la revisión anterior sigue con la llave vieja.
  3. versions disable apaga la versión 1 en Secret Manager. Se puede volver a activar con versions enable si algo falla.

Los comandos salen de la documentación de Google (agregar una versión del secreto y la de Cloud Run de arriba) y los revisamos con la ayuda local de Google Cloud SDK 581.0.0; no los ejecutamos contra un proyecto. Deshabilitar la versión vieja en Secret Manager no invalida la llave: eso solo lo hace el proveedor. El orden completo:

  1. Crea la llave nueva en el proveedor. En Stripe, "rotar" revoca la clave y crea la de reemplazo; si eliges un vencimiento futuro, las dos funcionan hasta 7 días. Si la llave se filtró, elige vencimiento inmediato.
  2. Guárdala en el gestor de secretos: los comandos de arriba, o en Railway editas la variable y despliegas el cambio pendiente.
  3. Comprueba que la app funciona con la llave nueva.
  4. Revoca la llave vieja en el proveedor. Es el paso que cierra la filtración.
  5. Revisa los registros del proveedor desde el día en que la llave pudo salir.
  6. Cierra la puerta por donde salió: la regla deny, la llave real fuera de tu .env y fuera de cualquier archivo o commit que el agente haya escrito. La transcripción local la conserva hasta que se limpia; por eso se rota y no basta con borrar.

Errores comunes

  • Contar con .gitignore para frenar al agente. Solo afecta a git y al selector de @; la herramienta Read lo ignora.
  • Poner la excepción antes de la regla. Read(!.env.example) listado primero no recorta nada.
  • Escribir Write(.env) o Grep(.env) en deny. Las reglas con ruta solo se comparan con Read y Edit; esas no bloquean nada.
  • Crear un .claudeignore. No tiene efecto; pasa sus entradas a reglas deny de Read.
  • Dejar llaves live en el .env "solo para probar". Es justo la llave que no quieres en una transcripción.
  • Abrir el agente dentro de railway shell vinculado a producción. Las llaves quedan en el entorno, donde la regla deny no mira.
  • Borrar el archivo o reescribir el historial en vez de rotar. La llave sigue en clones, transcripciones y logs.
  • Dar por hecho el sandbox en Windows. En Windows nativo los comandos corren sin sandbox; necesitas WSL2.

Preguntas frecuentes

¿La regla deny impide que el agente ejecute cat .env?

Sí. La documentación dice que los deny de Read se aplican a los comandos de archivos que Claude Code reconoce en Bash, como cat, head, tail, sed y tee, y a redirecciones como < .env. No se aplican a grep -r sobre la carpeta ni a un script que abre el archivo por su cuenta.

¿Basta con escribir en CLAUDE.md que no lea el .env?

No. Según la documentación de memoria, Claude trata CLAUDE.md como contexto, no como configuración obligatoria. La de los modos de permisos lo dice directo: para una garantía firme, agrega una regla deny.

¿El agente puede usar mis llaves sin leer el archivo?

Sí, si están en el entorno de la terminal donde lo abriste: exportadas, o cargadas con railway run o railway shell. Ahí la regla deny no aplica. Usa llaves de prueba en local y CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 para quitarlas del entorno de los comandos.

¿Tengo que rotar una llave de prueba que el agente leyó?

Conviene, y cuesta poco: no tiene clientes detrás, así que la rotas sin prisa y sin riesgo. Esa es la ventaja de tener solo llaves de prueba en tu máquina. Si fue una llave real, la rotación es urgente.

Checklist

  • .claude/settings.json tiene Read(.env), Read(.env.*) y la excepción para .env.example, en ese orden.
  • ~/.claude/settings.json bloquea //**/.env si quieres cubrir todos tus proyectos.
  • En Windows, el hook PreToolUse cubre PowerShell.
  • El .env local solo tiene llaves de prueba o de solo lectura.
  • Tu carpeta está vinculada a un entorno de desarrollo, no al de producción.
  • Las llaves reales viven en el gestor de secretos, selladas o con versión fija.
  • git ls-files no muestra ningún .env, y git log --all -- .env está vacío.
  • Sabes cómo rotar cada llave y dónde ver sus registros.

Las reglas deny son una parte de la configuración de permisos. Para el resto, como allow y ask, revisa permisos de Claude Code en settings.json.

¿Viste esto en Instagram? Todas las guías de los Reels están en ecomlabs.dev/guias.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 19 de noviembre de 2026 · actualizado el 20 de noviembre de 2026

← Blog