Arquitectura

Cómo está construido zn-gate. Tres puntos de control alrededor de cada acción del agente y los principios que los sostienen.

Ver .md

zn-gate es un punto de control pequeño que se ejecuta en tu máquina, entre tu agente de código y todo lo que lee y ejecuta. Mira tres momentos de cada acción y no estorba el resto del tiempo. Esta página explica la estructura y los principios que hay detrás. Para ver las piezas con detalle, consulta Cómo funciona zn-gate.

Tres puntos de control

Paso	Punto de control	Cuándo	Qué hace
1	`analyze_prompt`	Antes de que el agente actúe sobre un prompt o un contenido	Busca inyección de prompts, jailbreaks y secretos pegados en el texto
2	`check_tool_call`	Antes de que se ejecute una herramienta	Revisa los argumentos en busca de inyección, patrones de exfiltración y rutas sensibles. Una llamada bloqueada nunca llega a la herramienta. Los secretos de los argumentos se enmascaran
3	`check_tool_result`	Después de ejecutar la herramienta y antes de que el modelo lea la salida	Redacta los secretos y neutraliza la inyección indirecta de prompts. Un resultado que lleva una inyección se sustituye por un aviso breve

Cada punto de control responde allow o block y nombra la rule y el reason que decidieron. Las mismas tres comprobaciones funcionan en cada forma de configurar zn-gate: hooks del agente, el servidor MCP o zn-gate shield delante de tus otros servidores MCP. Las configuraciones y lo que cubre cada una están en Cómo funciona zn-gate.

Principios

Pocas dependencias. El paquete de Python usa solo la biblioteca estándar. El paquete de npm tiene una única dependencia en ejecución, age-encryption (con sus bibliotecas @noble y @scure), que cifra la bóveda de secretos. Va incluida en el paquete con las versiones fijadas en package-lock.json y no se compila nada en tu máquina.
Primero local y predecible. Las comprobaciones se ejecutan en tu máquina con reglas fijas: coincidencia de patrones más normalización de caracteres parecidos, caracteres de ancho cero y texto codificado. La misma entrada da la misma respuesta, y cada respuesta nombra su regla. Se guardan en caché los últimos 2.048 resultados, así que un texto repetido se revisa una sola vez. Los tiempos medidos están en la página de Rendimiento.
Una segunda opinión opcional desde la nube. Solo el análisis de prompts puede consultar el clasificador en la nube, y solo después de que lo actives: define ZN_API_KEY y ZN_CLOUD=1, o ejecuta zn-gate connect. ZN_LOCAL_ONLY=true lo vuelve a desactivar. El texto que las reglas locales ya bloquean nunca se envía, y los secretos del texto se eliminan en tu máquina antes de enviar nada (los datos personales no). Los argumentos de herramientas, la salida de herramientas y las descripciones de herramientas nunca salen de tu máquina, con ninguna configuración. Detalles: Qué sale de tu máquina.
Un registro local que delata las alteraciones. Cada decisión que registran zn-gate shield y los SDK se añade a ~/.zn/evidence.jsonl con un hash SHA-256 que la enlaza con la anterior, con una vista previa redactada y nunca el secreto. zn-gate evidence --verify comprueba la cadena. Detecta ediciones accidentales o parciales, pero no protege frente a alguien que pueda escribir en el archivo, porque puede recalcularla. Consulta Evidencia.

Lo que esta estructura no hace

Es una frontera, no todo tu modelo de seguridad. Mantén permisos mínimos en las herramientas y revisión humana para las acciones de alto impacto.
Lo que ven los puntos de control depende de cómo esté configurado zn-gate y del agente. Un servidor MCP por sí solo solo ve las llamadas que tu agente decide enviarle. Los hooks cubren además las herramientas integradas del agente, en la medida en que cada agente lo permite. Consulta el Modelo de amenazas.
Las reglas locales no son un clasificador semántico: los ataques parafraseados pueden pasar.