Mantén los secretos fuera de tu agente de código (5 minutos)

zn-gate mantiene los valores secretos fuera de lo que tu agente de código envía a su modelo. El agente trabaja con marcadores como __ZN_GITHUB_TOKEN__; los valores reales se quedan en una bóveda cifrada de tu máquina y solo se rellenan donde tú lo has permitido. Todo se ejecuta en local y no necesita cuenta.

Funciona con Claude Code, Codex CLI, Cursor (IDE) y OpenCode. Lo que puede y no puede hacer cada agente está en Agentes compatibles; los límites, en el modelo de amenazas.

1. Instala y desbloquea la bóveda

npm install -g zn-gate
zn unlock

En Windows PowerShell, npm y npx pueden fallar con "la ejecución de scripts está deshabilitada en este sistema". Usa npm.cmd y npx.cmd, ejecuta los comandos desde el Símbolo del sistema o permite los scripts locales para tu cuenta con Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. Más en Instalar en Windows.

El primer zn unlock crea la bóveda: una identidad age guardada en el llavero de tu sistema (Llavero de macOS, Administrador de credenciales de Windows o Secret Service en Linux), o protegida con una frase de contraseña si no hay llavero. La bóveda permanece desbloqueada 8 horas, o hasta 30 minutos sin uso, o hasta que ejecutes zn lock.

Tras actualizar zn-gate, una bóveda que sigue en marcha con la versión anterior mantiene los secretos como marcadores en los hooks del agente hasta que se reinicie. zn vault status muestra la versión de la bóveda en ejecución y avisa si está desactualizada, y zn unlock la reinicia por ti.

zn te pide confirmar algunas cosas fuera del agente (paso 4). En un equipo de escritorio muestra un diálogo del sistema. En un servidor o por SSH no hay diálogo: ejecuta la bóveda en una terminal aparte y responde allí.

zn unlock --foreground

2. Mueve los valores de tu .env a la bóveda

zn env shadow .env

Cada valor sensible pasa a la bóveda y .env conserva solo marcadores:

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

Se guarda una copia cifrada del original, y zn env unshadow la restaura. Para añadir un solo secreto, escríbelo en un aviso oculto (nunca como argumento):

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

3. Instala los hooks de tu agente

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

A partir de ahora, cada lectura de fichero, salida de comando y prompt pegado pasa por el depurador antes de llegar al modelo. Los valores conocidos, más de 60 formatos de secreto (claves de nube, tokens, claves privadas, cadenas de conexión) y los datos personales que superan una suma de control se sustituyen por marcadores. Los detalles están en Redacción.

Lo que bloquean los hooks:

• Las lecturas de ficheros .env que contienen valores reales.
• Ficheros de credenciales como ~/.aws/credentials, ~/.ssh/id_* y ~/.npmrc, y la propia carpeta ~/.zn de zn.
• Un prompt que contiene un secreto: no se envía. En los prompts, zn también bloquea un valor de 8 o más caracteres asignado a un nombre de credencial, incluso en mitad de una frase (my key is STRIPE_KEY=..., DB_PASSWORD=...). Deja pasar un valor de ejemplo (changeme123, <key>), una referencia (${API_KEY}, __ZN_STRIPE_KEY__) o código. Guarda el valor con zn secret set NAME y escribe __ZN_NAME__ en el prompt.

Codex ejecuta los hooks nuevos solo después de que confíes en ellos: abre Codex y usa /hooks.

En un equipo gestionado por una organización, Claude Code puede estar configurado para ignorar los hooks y los servidores MCP que instalas tú mismo (disableAllHooks, allowManagedHooksOnly, managed-mcp.json o una lista de permitidos o bloqueados de MCP), y no te lo dice. zn hooks install claude-code y zn-gate status leen los ficheros de configuración gestionada de este equipo y los tuyos, y avisan cuando uno de ellos detiene los hooks de zn o su servidor secrets. Pide a tu administrador que añada zn a la configuración gestionada. La política enviada a través de claude.ai, la gestión de dispositivos (MDM) o el registro de Windows no se lee, así que cuando existe una política así Claude Code puede ignorar los ficheros de configuración gestionada. claude doctor y /status muestran qué origen ha usado Claude Code.

4. Deja que un comando use un secreto

Permite el programa que necesita el valor:

zn secret allow DATABASE_URL_PASSWORD --command psql

Cuando el agente ejecuta psql "postgres://app:__ZN_DATABASE_URL_PASSWORD__@db/app", el hook lo envía a través de zn run. El valor va solo a ese proceso y su salida se enmascara: las formas en bruto, base64, hexadecimal y codificada en URL vuelven como el marcador. La primera vez, la bóveda te pide confirmar en su diálogo o en su terminal, y el aviso muestra el programa exacto que se va a ejecutar. Cambiar la política de un secreto (zn secret allow) se confirma del mismo modo. El agente no puede responder a estos avisos desde su propia terminal.

Permite un programa concreto. node, python, npm, make y otros intérpretes ejecutan cualquier código que reciben, así que permitir uno deja que todos los scripts que ejecuta lean el secreto. zn te avisa cuando lo haces.

5. Deja que el agente llame a una API

Para las APIs HTTP, usa el servidor MCP secrets en lugar de poner el valor en un proceso. zn hooks install muestra cómo registrarlo en tu agente. El agente llama a secrets_http_request con el marcador en una cabecera:

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

zn envía la petición solo a los hosts permitidos del secreto (allowHosts), solo con el valor en cabeceras (para usarlo en la URL o en el cuerpo, ejecuta zn secret allow NAME --in query|body), y devuelve la respuesta con los secretos sustituidos por marcadores. No existe ninguna herramienta que devuelva un valor.

Configuraciones MCP

El servidor secrets de arriba es la forma segura de que el agente use una clave. Una clave escrita en texto plano en un fichero de configuración del agente es lo contrario: viaja con el repositorio. zn audit avisa de un valor secreto en un fichero de configuración o de instrucciones de un agente (hallazgo ZNA011) y nunca imprime el valor. Consulta Auditoría.

Referencia de comandos

Si la bóveda está bloqueada, los hooks siguen ocultando lo que reconocen, pero con marcadores que no se pueden restaurar (__ZN_REDACTED_AWS_KEY__), y te recuerdan que ejecutes zn unlock.

Para comprobar qué está protegido en tu máquina, ejecuta npx -y zn-gate check.