zn-gate

zn-gate

La capa de seguridad local para agentes de codificación.
zn-gate protege tus secretos, tus datos y tus sistemas mientras usas Claude Code, Codex CLI, Cursor u OpenCode.
Una capa de seguridad de código abierto que se ejecuta en tu máquina, entre tu agente y las herramientas y el contenido que toca.

Documentación · Paquete npm · Paquete Python · Seguridad · Discord

Para: desarrolladores que usan Claude Code, Codex CLI, Cursor, OpenCode o cualquier cliente MCP, y equipos que construyen agentes con MCP, LangChain, CrewAI o LlamaIndex.

Qué hace: mantiene los valores secretos fuera de lo que tu agente envía a su modelo, verifica lo que tu agente lee y llama para detectar inyección de prompts, y audita prompts, habilidades y configuraciones. Todo se ejecuta en tu máquina, tiene licencia MIT y no requiere cuenta. El paquete Python no tiene dependencias en tiempo de ejecución; la única dependencia del paquete npm es age-encryption (con sus dependencias @noble/@scure) para la bóveda de secretos, incluida en el paquete.

Instalación

Todo se ejecuta en tu máquina; no se necesita cuenta ni clave API. Necesitas Node.js 18 o posterior (la versión LTS de nodejs.org). Con una versión anterior de Node.js, los comandos zn-gate y zn se detienen e indican cómo instalarlo. El plugin de Claude Code necesita Node.js 20.12 o posterior.

Cómo empezar: cuatro pasos, un comando cada uno. Ejecútalos en tu propia terminal.

1. npx -y zn-gate reach muestra lo que tus agentes de codificación pueden alcanzar en esta máquina: secretos en tus archivos .env (solo por nombre), archivos de credenciales y servidores MCP. Es de solo lectura y no envía nada. Detalles en docs/reach.md.
2. npx -y zn-gate init configura la protección para los agentes de codificación que encuentra, paso a paso, y pregunta antes de cada cambio.
3. npx -y zn-gate check prueba esa protección con un secreto falso en una carpeta temporal. init también lo ejecuta al final.
4. npx -y zn-gate env shadow .env mueve los valores reales de tus .env a la bóveda local y deja marcadores en el archivo. La primera vez, ejecuta npx -y zn-gate unlock para crear la bóveda.

Un comando para los agentes de codificación en tu máquina:

npx -y zn-gate init

Detecta Claude Code, Codex CLI, Cursor y OpenCode, muestra la configuración para cada uno que aún no esté protegido (el plugin zn-gate para Claude Code, los hooks de zn para los demás), ejecuta cada paso después de que lo confirmes y termina con zn-gate check. Ejecútalo tú mismo en tu propia terminal, sin argumentos: cuando un agente de IA o un script lo ejecuta, solo imprime los pasos.

Windows PowerShell: npm y npx pueden fallar con "running scripts is disabled on this system", porque la política de ejecución predeterminada bloquea npm.ps1. Usa npm.cmd, npx.cmd y zn.cmd en su lugar (por ejemplo npm.cmd install -g zn-gate), ejecuta los comandos desde el Símbolo del sistema, o permite scripts locales para tu cuenta con Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Luego mantén tus valores .env en la bóveda. Con el plugin o los hooks, el agente no puede leer archivos .env con valores reales; muévelos a la bóveda cifrada de zn-gate, y el archivo conserva marcadores como __ZN_STRIPE_KEY__:

npx -y zn-gate unlock            # creates the vault the first time
npx -y zn-gate env shadow .env

Después de esto, tu propia aplicación también lee los marcadores en .env: iníciala con el comando run de zn-gate una vez que lo permitas (docs/secrets.md). env shadow te indica cómo deshacerlo.

Tutorial de cinco minutos: docs/secrets.md. Límites: docs/threat-model.md.

claude plugin marketplace add usezn/zn
claude plugin install zn-gate@usezn

npm install -g zn-gate
zn hooks install codex           # or: cursor, opencode

python3 -m venv .venv
.venv/bin/pip install zn-gate      # Windows: .venv\Scripts\pip install zn-gate

claude mcp add zn-gate -- npx -y zn-gate mcp     # Claude Code
codex mcp add zn-gate -- npx -y zn-gate mcp      # Codex CLI

npx -y zn-gate init --dry-run   # preview
npx -y zn-gate init --wrap-mcp  # wrap (backup first)
npx -y zn-gate init --revert    # undo

Verifica que funciona

npx -y zn-gate check

Para cada agente configurado para tu usuario, zn-gate pide a su hook que permita al agente leer un archivo .env con una clave falsa y un archivo ordinario, en una carpeta temporal. Muestra lo que se le diría a tu agente, y una línea que dice NOT protected indica cómo solucionarlo. No se envía nada por la red y no se cambia ninguna configuración. Qué significa la salida.

npx -y zn-gate test

Esto ejecuta la autoprueba local (51 vectores seleccionados: 26 ataques, 25 benignos) y muestra la latencia por decisión en tu máquina. Es una prueba de humo, no una tasa de detección. No se envía nada por la red.

Para desarrolladores: ve la redacción manualmente. Envía una salida de herramienta con una clave AWS falsa (el ejemplo de documentación de AWS) y una contraseña de base de datos a través de zn-gate, exactamente como lo haría tu agente, y busca sanitized_content en la salida; ese campo es lo que vería el modelo:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_tool_result","arguments":{"tool_name":"read_file","content":"AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nDATABASE_URL=postgres://app:hunter2@db:5432/main"}}}' \
  | npx -y zn-gate@latest mcp

Equivalente en Python:

.venv/bin/python -c "from zn_gate import sanitize_tool_result as s; print(s('read_file', 'AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE')['sanitized_content'])"

Qué hace cada parte

Dónde se ubica zn-gate en una llamada de herramienta, como servidor MCP o como proxy shield alrededor de otros servidores:

Scrubber: los secretos se mantienen fuera del contexto del modelo

• Hoy, a través de zn-gate: redacta claves AWS, claves de OpenAI y Anthropic, tokens de GitHub, JWTs, claves privadas y contraseñas de URL de bases de datos en todo lo que pasa por zn-gate: salida de herramientas verificada con check_tool_result, argumentos de herramientas verificados con check_tool_call, y salida de servidores MCP envueltos por zn-gate shield / init. Python: sanitize_tool_result, @guard(mask_secrets=True) y las integraciones de frameworks.
• Hoy, hooks de agente y bóveda (paquete npm): los hooks para Claude Code, Codex CLI y OpenCode depuran la salida de las herramientas integradas de los agentes y bloquean secretos pegados (en Cursor solo se depura la salida de herramientas MCP); una bóveda cifrada local con marcadores estables (__ZN_AWS_KEY_1__); zn run completa valores solo en comandos que aprobaste; también se detectan datos personales (tarjetas, IBAN, identificaciones nacionales, correo electrónico, teléfono). Lo que permite cada agente difiere: consulta docs/compat.md.

Galvanize: detección de inyección de prompts

• Hoy, local: un motor de reglas determinista (firmas más normalización contra homoglifos, caracteres de ancho cero, anulaciones BiDi, empalme de comentarios y Base64) verifica prompts, argumentos de herramientas, salida de herramientas y descripciones de herramientas MCP.
• Hoy, verificación en la nube opcional: el clasificador Galvanize 2 (pesos abiertos en Hugging Face, Apache-2.0) también puede verificar prompts enviados a analyze_prompt, solo si configuras ZN_CLOUD=1 y ZN_API_KEY. Los secretos que zn-gate detecta se eliminan del prompt en tu máquina antes de enviarlo; los datos personales no se eliminan en esta ruta.
• Hoja de ruta: ejecutar Galvanize localmente dentro de zn-gate.

Scan: audita lo que tu agente está a punto de confiar

• Hoy: zn-gate scan <path> audita plantillas de prompts, archivos AGENTS.md / SKILL.md y configuraciones para detectar trampas de inyección y secretos filtrados (código de salida 1 en hallazgos, para CI). Un secreto filtrado se reporta como Secret found, con el siguiente paso: npx -y zn-gate env shadow <file> mueve los valores de un archivo .env a la bóveda local, npx -y zn-gate secret set NAME almacena cualquier otro. Encuentra claves y tokens de proveedores, tokens opacos Authorization: Bearer, contraseñas en URLs y secretos pasados como banderas de línea de comandos (--token=...) o asignados a un nombre como password o api_key. La misma verificación se ejecuta como GitHub Action. Los servidores MCP se pueden verificar en la web en usezn.com/scan.
• Hoja de ruta: auditar servidores MCP y habilidades desde la CLI antes de agregarlos.

Qué añade la nube para equipos

Todo lo anterior se ejecuta localmente, de forma gratuita y sin cuenta. La nube opcional en usezn.com es para equipos que necesitan un registro compartido de lo que hicieron sus agentes:

• Auditoría y trazabilidad: un panel de evidencia con los metadatos de cada decisión en la nube (veredicto, regla, puntuación, latencia), retención de 90 días y exportación CSV/JSONL.
• Un modelo de detección más grande para prompts, cuando lo aceptas (ZN_CLOUD=1).
• Controles de equipo (políticas compartidas, auditoría a nivel de organización): en progreso.

Por defecto no se envía nada. Si configuras ZN_CLOUD=1 y una clave API (o la opción de clave API del plugin de Claude Code), analyze envía el texto del prompt después de eliminar los secretos que zn-gate detecta localmente: los datos personales no se eliminan en esta ruta, y un secreto que no detecte se enviaría con el texto. El panel conserva los metadatos de cada decisión en la nube. La salida de herramientas y los argumentos de llamadas de herramientas nunca se envían.

Qué sale de tu máquina

Nada, por defecto.

ZN_API_KEY solo no habilita nada. ZN_LOCAL_ONLY=true anula ZN_CLOUD=1. npx -y zn-gate status imprime lo que tu configuración envía.

1.4.0 y anteriores: con ZN_API_KEY configurado, el paquete Node enviaba la salida de herramientas y los argumentos de llamadas a herramientas a api.usezn.com sin redacción. 1.4.1 elimina esa ruta. Detalles en el CHANGELOG.

Rendimiento y precisión

Solo publicamos números que podemos reproducir, con el método junto a ellos.

• Latencia del motor local: una tabla por tamaño de entrada, con hardware, fecha y el script para reproducirla (bench/bench_by_size.js), en el README del paquete npm. Resumen breve de esa ejecución, con redacción de secretos (p50): aproximadamente 0.045 ms para un prompt de 200 B, 0.3 ms para una salida de herramienta de 4 KB, aproximadamente 4 ms para 64 KB.
• Autoprueba: 51 vectores seleccionados pasan. Es una prueba de humo, no una tasa de detección o falsos positivos.
• Limitación conocida: en archivos fuente completos, las reglas pueden marcar comentarios de código ordinarios. La versión 1.5.0 reduce estos en código y documentación, a costa de dejar pasar algunos intentos de anulación con redacción flexible a través de las reglas locales. Para comprobarlo en tus propios archivos fuente, ejecuta zn-gate scan --code <path>; para los servidores MCP que envuelves, --shadow registra detecciones sin bloquear.
• Limitación conocida: la detección de credenciales bajo nombres de variables con prefijo (por ejemplo, OPENAI_API_KEY=) es parcial en esta versión.
• Tasas de detección: en un conjunto privado reservado de 3,309 ejemplos, Galvanize 2 tiene un 83.4% de recall con una tasa de falsos positivos del 0.81% (umbral de servicio 0.662); estos números son para el clasificador en la nube, no para el motor de reglas local. Método, resultados por idioma, puntos débiles conocidos y un benchmark reproducible están en la tarjeta del modelo y el anuncio. Es una capa de defensa, no una garantía.

Configuración

zn Team: zn team join <token> conecta una máquina a la política de secretos firmada de tu organización y sube su registro de auditoría (solo metadatos). Lo que la organización puede y no puede cambiar en la máquina, el comportamiento sin conexión y la exportación de OpenTelemetry (zn vault log export --otlp): docs/team.md.

Reglas personalizadas: agrega patrones prohibidos y rutas bloqueadas en .znrules o zn.config.json en la raíz de tu proyecto (ejemplo).

Registro de auditoría: zn-gate shield agrega cada decisión a ~/.zn/evidence.jsonl como un registro encadenado por hash (SHA-256) con una vista previa redactada. Detecta ediciones accidentales o parciales; no es a prueba de manipulaciones contra alguien con acceso de escritura al archivo. Compruébalo con npx -y zn-gate evidence --verify.

Acción de GitHub

La acción instala los paquetes publicados de zn-gate en una versión exacta y se ejecuta solo en el runner; no envía nada a ningún lugar. Tiene dos comprobaciones, elegidas con mode:

• scan (predeterminado): zn-gate scan busca trampas de inyección de prompts y secretos filtrados en prompts, definiciones de herramientas y archivos de configuración (paquete Python de PyPI). Esto es lo que hacían las versiones anteriores de la acción.
• audit: zn audit revisa lo que tus agentes de codificación están configurados para confiar: .claude/, .mcp.json, .codex/, .cursor/, hooks, AGENTS.md / CLAUDE.md, plugins y habilidades (paquete npm; necesita versión 1.6.0 o posterior).
• both: ejecuta ambos. Con un version anterior a 1.6.0, o una versión de .post solo PyPI, ejecuta solo el escaneo e imprime una advertencia.

Escanea prompts en solicitudes de extracción:

name: AI agent security scan

on:
  pull_request:
    paths:
      - 'prompts/**'
      - '**/*.prompt'
      - '**/AGENTS.md'
      - '**/SKILL.md'

permissions:
  contents: read

jobs:
  zn-gate-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Scan AI agent prompts and tools
        # Pin the action to a full commit SHA; the comment names the release.
        uses: usezn/zn@003a95ae7ef63c22b969496422131a49fa107f8d # v1.12.0
        with:
          version: '1.12.0'
          package-sha256: '9e7b7ac4a43722249c10623dcb5817c1cd956b6100d6ca02faa8b6451dd72dbf'
          path: '.'
          fail-on-threat: 'true'
          format: 'github'

Audita configuraciones de agentes y plugins en cada solicitud de extracción, y muestra los hallazgos en el escaneo de código. La auditoría toma segundos, por lo que el ejemplo no tiene filtro paths:: un filtro omitiría las configuraciones de agentes que no lista.

name: AI agent config audit

on:
  pull_request:

permissions:
  contents: read

jobs:
  zn-gate-audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # only for the SARIF upload
      actions: read            # private repositories only, for upload-sarif
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Audit agent configs
        id: zn
        # Pin to the full commit SHA of the first Action release that has the
        # mode input. The zn-gate package version is set by version below.
        uses: usezn/zn@<commit-sha> # <first Action release with mode>
        with:
          version: '1.12.0'
          mode: 'both'
          format: 'sarif'
          severity-threshold: 'medium'   # stricter than the default (high)
      - name: Upload SARIF
        if: ${{ !cancelled() && steps.zn.outputs.sarif-file != '' }}
        uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
        with:
          sarif_file: ${{ steps.zn.outputs.sarif-file }}

El escaneo encuentra más tipos de secretos con cada versión (1.9.1 agregó secretos pasados como banderas de línea de comandos y asignados a nombres como password o api_key), por lo que un trabajo que falla en hallazgos puede comenzar a fallar en archivos que pasaban antes: fija version y lee los hallazgos antes de actualizarlo.

Las versiones anteriores de la acción ignoran las entradas que no tienen, solo con una advertencia: con una de ellas, mode: audit ejecuta el escaneo en su lugar.

Qué hallazgos de auditoría fallan el paso: fail-on si está configurado; de lo contrario, ninguno cuando fail-on-threat es false; de lo contrario, severity-threshold. Para el escaneo, solo se aplica fail-on-threat.

Con mode: both y format: sarif, el archivo contiene una ejecución SARIF por comprobación (zn-gate scan y la propia ejecución de la auditoría), cada una con su propia categoría, por lo que el escaneo de código rastrea sus alertas por separado. El paso falla con el peor de los dos resultados: un error supera a los hallazgos.

Permisos: la acción en sí solo necesita contents: read; agrega security-events: write al trabajo solo cuando subes SARIF (y, en repositorios privados, actions: read, que upload-sarif necesita). Los paquetes se instalan sin ejecutar scripts de instalación o pasos de compilación (--only-binary=:all: --no-deps para la rueda, --ignore-scripts para el tarball npm, cuyas dependencias están incluidas) en directorios privados bajo el directorio temporal del runner. pip aún lee la configuración de pip del propio runner (variables de entorno PIP_* y pip.conf), por lo que se usa un espejo o proxy que configures allí; configura package-sha256 para que la rueda se verifique sin importar de qué índice provenga (y npm-integrity para el tarball npm). Ejecútalo en pull_request, nunca en pull_request_target: no verifiques código de solicitudes de extracción no confiables en un flujo de trabajo pull_request_target. Con mode: audit o both la acción también configura Node.js 22 para el resto del trabajo.

Estructura del repositorio

• packages/zn-gate: CLI de Node.js, servidor MCP y proxy shield (npm).
• packages/zn-gate-py: SDK y CLI de Python (PyPI).
• src/: gateway Rust heredado, no publicado (docs/rust-core.md).
• bench/: scripts de benchmark y resultados.
• assets/brand/: archivos de logotipo (SVG maestro y variantes claro/oscuro, PNG lockup y banners).

Preguntas frecuentes

¿Necesito una cuenta o clave API? No. Todo lo local funciona sin una. Una cuenta solo es necesaria para la nube opcional (auditoría de equipo y el modelo de detección más grande).

¿zn-gate ralentiza mi agente? La comprobación local agrega menos de un milisegundo para prompts y salidas de herramientas típicos (p99 0.8 ms a 4 KB en nuestro host de prueba). Ver la tabla medida arriba. ¿Bloqueará contenido legítimo? A veces. Usa init --shadow o shield --shadow para registrar detecciones sin bloquear mientras lo evalúas.

¿Qué agentes son compatibles? Cualquier cliente MCP. init puede reescribir configuraciones para los agentes listados en Instalación.

¿Cómo lo elimino? npx -y zn-gate init --revert restaura tus configuraciones desde la copia de seguridad. Para un servidor independiente, elimina la entrada zn-gate de la configuración de tu agente.

Seguridad

Reporta vulnerabilidades a security@usezn.com. Política, alcance y puerto seguro: SECURITY.md. Salón de la fama: usezn.com/security.

Los lanzamientos publicados por el flujo de trabajo de lanzamiento, comenzando con el primero después de 1.5.0-beta.1, están firmados y llevan procedencia de compilación. 1.5.0-beta.1 y versiones anteriores fueron publicados manualmente y no tienen firmas ni procedencia. Para verificar una descarga: docs/verify-release.md.

Comunidad y soporte

• Discusiones: preguntas sobre configuración y uso, ideas, y mostrar y contar. Comienza aquí si no estás seguro de dónde pertenece tu pregunta.
• Problemas: errores reproducibles y solicitudes de funciones concretas.
• Vulnerabilidades de seguridad: no las publiques en Discusiones o Problemas. Repórtalas de forma privada como se describe en SECURITY.md.

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas. Consulta CONTRIBUTING.md.

Licencia

MIT. Copyright (c) 2026 usezn (usezn.com). Los pesos Galvanize 2 y Galvanize-60M son Apache-2.0. El conjunto de datos zn-prompt-injection-bench es CC-BY-4.0. El paquete npm incluye código de terceros listado en THIRD_PARTY_NOTICES.md.