Novedades de zn-gate 1.12.0: zn-gate reach, versiones firmadas y una corrección de seguridad

Q: ¿Qué novedades trae zn-gate 1.12.0?

zn-gate reach, un informe de solo lectura de lo que los agentes de programación de tu máquina pueden alcanzar, también en SARIF para code scanning. Las versiones se compilan y firman en un workflow aparte (SLSA Build Level 3) y las etiquetas de versión se firman con gitsign. zn audit oculta más valores secretos, los hooks de los agentes vuelven a rechazar rápido los parches largos de shell y una corrección de seguridad cierra GHSA-rccq-h3xc-j9qj.

Q: ¿Cómo actualizo a zn-gate 1.12.0?

Ejecuta npm install -g zn-gate@1.12.0 para el paquete de Node y pip install -U zn-gate para el de Python. Para reinstalar los hooks de los agentes, ejecuta npx -y zn-gate@1.12.0 init. Si usas el plugin de Claude Code, actualízalo desde el directorio de plugins cuando aparezca la 1.12.0.

zn-gate 1.12.0 añade zn-gate reach, un informe de solo lectura de lo que los agentes de programación de tu máquina pueden alcanzar, con el comando que corrige cada hallazgo. También traslada la compilación y la firma de las versiones a un workflow aparte, hace que zn audit oculte más valores secretos y corrige un problema de seguridad en los hooks de los agentes que afecta a las versiones 1.5.0 a 1.11.0. Actualiza con npm install -g zn-gate@1.12.0 y pip install -U zn-gate.

¿Qué muestra zn-gate reach?

Responde a una sola pregunta: ¿qué pueden alcanzar los agentes de programación de esta máquina? Ejecútalo en la carpeta en la que trabajas:

npx -y zn-gate reach

En una sola pantalla lista:

qué agentes encuentra (Claude Code, Codex CLI, Cursor, OpenCode) y si zn los protege;
los archivos .env de la carpeta, con los nombres de sus secretos y nunca los valores;
los archivos de credenciales de tu carpeta personal, como ~/.aws/credentials, las claves SSH y ~/.npmrc. Solo comprueba que existen y nunca los abre;
los nombres de las variables de entorno que contienen un secreto;
lo que zn audit encuentra en los servidores MCP y en los ajustes de los agentes de la carpeta y de tu usuario.

Cada hallazgo viene con el comando que lo corrige. El informe es de solo lectura: no muestra ningún valor, no envía nada, no arranca ningún hook y no escribe nada salvo que lo pidas con --remember, que guarda los recuentos de la ejecución (altos, medios, bajos y la fecha) en ~/.zn/reach-last.json para que la siguiente ejecución pueda mostrar cuáles eran. --json imprime el mismo informe en JSON. La descripción completa está en la documentación de reach.

El README y la página de npm muestran ahora un camino de cuatro pasos: zn-gate reach, zn-gate init, zn-gate check y zn-gate env shadow.

¿Se puede ejecutar reach en CI y enviarlo a code scanning?

Sí. zn-gate reach --sarif escribe el informe como SARIF 2.1.0. Los hallazgos sobre un archivo de la carpeta revisada son resultados: los hallazgos de zn audit conservan sus reglas, y un .env con secretos que un agente puede leer es ZNR002. Lo que pertenece a la máquina (agentes no protegidos, archivos de credenciales, variables de entorno con secretos) y los archivos de tu carpeta personal son notificaciones de la ejecución.

Por defecto reach termina con código 0, así que sigue siendo un informe. --fail-on high|medium|low termina con 1 cuando encuentra un hallazgo de ese nivel o superior, y un error de uso o un fallo termina con 2.

¿Qué cambia en la forma de firmar las versiones?

Dos cosas, ambas para quien verifica lo que instala.

Las versiones se compilan, se atestiguan y se firman ahora en un workflow reutilizable aparte, build-release.yml. El workflow de la versión llama a sus trabajos de compilación y firma, pero no puede acceder a ellos. Eso sitúa la procedencia de compilación de los paquetes de npm y de Python en SLSA Build Level 3.

Las etiquetas de versión las crea y firma un workflow, tag-release.yml, con gitsign (firma sin claves de Sigstore), de modo que la firma nombra ese workflow y no la identidad de ninguna persona. Solo se ejecuta desde main, comprueba que el commit es la cabeza de su rama de versión, que todas las versiones coinciden y que todas las comprobaciones han pasado, y espera una aprobación antes de firmar. Desde la 1.12.0, el workflow de la versión se niega a publicar una etiqueta que no lleve una firma válida de tag-release.yml.

Si verificas las versiones, ten en cuenta que, desde la 1.12.0, el workflow firmante de las atestaciones de GitHub y de las firmas de Sigstore es usezn/zn/.github/workflows/build-release.yml (versiones anteriores: release.yml). La procedencia de npm y las atestaciones de PyPI siguen nombrando release.yml. La página de verificación del repositorio tiene ambos y explica cómo comprobar una etiqueta.

¿Qué oculta ahora zn audit?

zn audit cita la línea de un hallazgo como evidencia. Ya sustituía los secretos de formatos conocidos. En la 1.12.0 oculta además:

un valor secreto en un formato que no conoce cuando sigue a una opción de credencial (--token, --api-key, --password), a una cabecera de autenticación (Authorization: Bearer ..., x-api-key: ...) o a un nombre como API_TOKEN=;
un secreto dado como el siguiente elemento de un array JSON tras una opción de credencial, como en los argumentos de un servidor MCP.

Las referencias como $TOKEN o ${API_KEY} se conservan. Las versiones anteriores podían citar un valor así en la evidencia de un hallazgo. Si alguna vez un hallazgo te mostró uno, rota esa credencial.

¿Qué más se ha corregido?

Un parche largo enviado como comando de shell (apply_patch en Codex) vuelve a rechazarse en una fracción de segundo. Para nombrar un archivo secreto en el mensaje, zn comprueba ahora solo los primeros 32 archivos del parche en lugar de todos los del disco, lo que tardaba varios segundos con un parche cercano al límite de 100 KB y podía alcanzar el límite de tiempo del hook del agente en una máquina lenta. La decisión no cambia.
En Windows, un comando de PowerShell que ya se ejecuta mediante zn-gate run -- ... con un marcador de secreto deja de rechazarse por error.
zn-gate check y zn hooks install codex avisan ahora cuando Codex no ejecutará los hooks de zn, porque están desactivados en requirements.toml, managed_config.toml o en tu propio config.toml, o allow_managed_hooks_only en requirements.toml sin zn entre los hooks gestionados. Codex no da ninguna señal de ello.

¿Cuál es la corrección de seguridad?

GHSA-rccq-h3xc-j9qj tiene gravedad media y afecta a zn-gate 1.5.0 a 1.11.0. En esas versiones, la protección de lectura de los hooks de los agentes podía dejar que se leyera un archivo protegido, como un .env con valores o un archivo de credenciales, sin rechazarlo cuando un comando llegaba a él de forma indirecta o cuando el comando era muy largo o lento de comprobar. La 1.12.0 resuelve estas formas antes de decidir, comprueba todos los comandos de una cadena y rechaza un comando que no puede comprobar dentro de un límite de tiempo muy inferior al límite de tiempo del hook del agente. También rechaza las claves privadas guardadas fuera de ~/.ssh, por ejemplo en un proyecto.

El equipo de zn lo encontró en una revisión interna. Describimos las clases de rutas y el diseño de la corrección en un artículo aparte: cómo un agente de programación podía leer tu archivo .env de forma indirecta y cómo la 1.12.0 cierra esas rutas.

Qué hacer:

Actualiza los paquetes y reinstala los hooks:

npm install -g zn-gate@1.12.0
pip install -U zn-gate
npx -y zn-gate@1.12.0 init

En cada carpeta que tenga un archivo .env con valores, ejecuta zn env shadow .env. Un archivo en sombra solo contiene marcadores, así que leerlo por cualquier ruta no revela ningún valor.
Ejecuta zn-gate check para ver qué agentes tienen los hooks instalados.

Si usas el plugin de Claude Code, actualízalo desde el directorio de plugins cuando aparezca la 1.12.0. Las formas de cadena larga y de tiempo de espera no tienen solución provisional en las versiones anteriores, así que actualizar es la única corrección para ellas.

Preguntas frecuentes

¿Qué novedades trae zn-gate 1.12.0?

zn-gate reach, un informe de solo lectura de lo que los agentes de programación de tu máquina pueden alcanzar, también en SARIF para code scanning. Las versiones se compilan y firman en un workflow aparte (SLSA Build Level 3) y las etiquetas de versión se firman con gitsign. zn audit oculta más valores secretos, los hooks de los agentes vuelven a rechazar rápido los parches largos de shell y una corrección de seguridad cierra GHSA-rccq-h3xc-j9qj.

¿Cómo actualizo a zn-gate 1.12.0?

Ejecuta npm install -g zn-gate@1.12.0 para el paquete de Node y pip install -U zn-gate para el de Python. Para reinstalar los hooks de los agentes, ejecuta npx -y zn-gate@1.12.0 init. Si usas el plugin de Claude Code, actualízalo desde el directorio de plugins cuando aparezca la 1.12.0.

¿zn-gate reach envía mis secretos a algún sitio?

No. Es de solo lectura: nunca muestra un valor, no envía nada, no arranca ningún hook y no escribe nada salvo que pases --remember. Lista los nombres de los secretos de tus archivos .env, comprueba si existen archivos de credenciales como ~/.aws/credentials sin abrirlos y muestra lo que zn audit encuentra en tus servidores MCP y en los ajustes de tus agentes.

¿Qué versiones afecta GHSA-rccq-h3xc-j9qj?

De zn-gate 1.5.0 a 1.11.0. Está corregido en la 1.12.0. El aviso tiene gravedad media.

¿Qué cambia si verifico las versiones de zn-gate?

Desde la 1.12.0, el workflow firmante de las atestaciones de GitHub y de las firmas de Sigstore es build-release.yml, no release.yml. La página de verificación del repositorio tiene ambos y la forma de comprobar una etiqueta firmada.

La lista completa de cambios está en las notas de la versión 1.12.0. zn-gate es MIT, se ejecuta en local y no necesita cuenta: empieza con npx -y zn-gate reach, o consulta Instalación para cada agente.