Limpiador y bóveda de secretos

zn-gate mantiene los valores secretos fuera de lo que tu agente de programación envía a su modelo. El agente trabaja con marcadores como __ZN_GITHUB_TOKEN__; los valores reales permanecen en una bóveda cifrada en tu equipo y solo se rellenan donde lo hayas permitido. La detección, el reemplazo y la bóveda son 100 % locales: ningún servicio en la nube, tampoco los nuestros, participa.

Disponible en zn-gate 1.5.0 y posteriores (npm); en Windows usa la 1.5.1 o posterior (GHSA-rf3f-ppm5-3xrx). Agentes compatibles: Claude Code, Codex CLI, Cursor (IDE) y OpenCode. Lo que cada agente permite modificar a los hooks varía: consulta compat.md y los límites en threat-model.md.

Qué hace

• Limpia lo que ve el modelo. Las lecturas de archivos, la salida de comandos, las búsquedas, los resultados de herramientas MCP y los prompts pegados pasan por el limpiador antes de llegar al modelo. Los valores conocidos (de la bóveda y de tus archivos .env), unos 30 formatos de secretos (claves de nube, tokens, claves privadas, contraseñas en cadenas de conexión) y los datos personales (números de tarjeta, IBAN, DNI/NIE y SSN con validación de suma de control; correos electrónicos, números de teléfono y direcciones IPv4) se convierten en marcadores estables. El mismo valor siempre recibe el mismo marcador, de modo que el modelo puede seguir razonando sobre él y la línea conserva su forma: DATABASE_URL=postgres://app:__ZN_DATABASE_URL_PASSWORD__@db:5432/app. En Cursor solo se puede reescribir la salida de MCP: la salida de la shell y de los archivos no se limpia allí.
• Bloquea las lecturas de credenciales en bruto. Los archivos .env con valores reales, los archivos de credenciales como ~/.aws/credentials o ~/.ssh/id_*, y el propio ~/.zn de zn: los hooks impiden que las herramientas del agente los lean (es una barrera de protección, no un sandbox).
• Guarda los valores en una bóveda cifrada. La bóveda se cifra con age; su clave se guarda en el llavero del sistema operativo (o protegida con una frase de contraseña). Nunca sale de tu equipo y nunca se sincroniza. Un registro de auditoría local documenta qué secreto se usó y dónde, sin guardar nunca los valores.
• Rellena los valores solo donde lo hayas permitido. Un comando permitido recibe el valor mediante zn run, y su salida se enmascara. Las API HTTP se invocan a través del servidor MCP secrets, que envía el valor solo a los hosts permitidos y devuelve la respuesta con los secretos sustituidos por marcadores. Ninguna herramienta devuelve un valor al agente.
• Te pregunta a ti, no al agente. El primer uso de un secreto por parte de un programa y cualquier cambio que amplíe la política de un secreto se confirman en un diálogo del sistema o en la terminal propia de la bóveda. El agente no puede responder a estas solicitudes.

Primeros pasos

npm install -g zn-gate
zn unlock                         # creates the vault the first time
zn env shadow .env                # moves the values into the vault; .env keeps markers
zn hooks install claude-code      # or: codex, cursor, opencode

Para que un comando use un secreto, permite ese programa:

zn secret allow DATABASE_URL_PASSWORD --command psql

Permite un programa concreto: node, python, npm, make y otros intérpretes ejecutan cualquier código que reciban, así que permitir uno de ellos hace que cada script que ejecute pueda leer el secreto, y zn te avisa cuando lo haces.

Para añadir un único secreto, escríbelo en un aviso oculto, nunca como argumento: zn secret set GITHUB_TOKEN --host api.github.com.

El recorrido completo está en la guía de secretos.

Comandos útiles

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

Límites

• El limpiador encuentra valores conocidos y formatos reconocibles. Un secreto sin formato conocido que no esté en la bóveda ni en un archivo .env puede pasar: mueve tus secretos a la bóveda.
• Aprobar un archivo por lotes (.cmd, .bat) en Windows aprueba ese archivo, no los programas que inicia por nombre. Prefiere secrets_http_request para las API HTTP, o aprueba el propio programa.
• Mientras la bóveda está desbloqueada, cualquier programa que se ejecute con tu usuario del sistema operativo, incluido un comando que ejecute el agente, puede pedirle un secreto por nombre. Bloquéala con zn lock cuando no la necesites.
• Un programa permitido tiene el valor y puede enviarlo a cualquier parte: permite programas concretos, usa tokens de alcance reducido y el sandbox de tu agente.
• Algunos agentes mantienen sus propias copias locales (el registro de sesión de Codex conserva la salida original).
• El paquete de Python (PyPI) tiene limpieza de secretos en sus funciones de biblioteca (redact_secrets, sanitize_tool_result, guard), pero no incluye la bóveda, los hooks, zn run ni la limpieza de datos personales.

Para la limpieza solo en la salida y los argumentos de herramientas MCP, consulta Redacción de secretos.

Código abierto

MIT, como el resto de zn-gate: github.com/usezn/zn. Los cambios se enumeran en el CHANGELOG.