Equipos

Política de la organización

Cómo se escribe, publica, firma y aplica una política en cada zn-gate de la organización.

La política de la organización es una lista de reglas sobre secretos: a dónde pueden enviarse y cómo se inyectan. Los propietarios y administradores la editan en Políticas y publican una nueva versión; cada zn-gate de la organización la recibe.

Reglas

Cada regla se aplica a un secreto (por nombre, nunca por valor; se admiten PREFIJO* y *):

Campo	Significado
`secret`	El nombre del secreto, por ejemplo `STRIPE_API_KEY`
`agents`	Agentes a los que puede ofrecerse un host nuevo, por ejemplo `claude-code`, `codex`. Un `deny` ignora esta lista
`mode`	Solo se aplica `proxy` (la forma más restrictiva); los demás valores se ignoran
`allowHosts`	Hosts a los que puede enviarse el secreto
`allowCommands`	Comandos que pueden recibir el secreto
`injectAt`	Dónde se inyecta el secreto
`deny`	Bloquea todo uso del secreto, por parte de todos los agentes de la máquina
`warn`	Deja pasar el uso dentro de los demás límites de la regla, avisa al desarrollador y lo registra como Avisado, para todos los agentes de la máquina. Usa `warn` o `deny`, nunca los dos
`reason`	Se muestra al desarrollador cuando se aplica una regla de aviso; en las reglas de bloqueo es una nota para los administradores

Cómo se combinan las reglas:

Se aplican todas las reglas que coincidan, de arriba abajo; cada una solo puede restringir más.
deny bloquea. warn deja pasar el uso, avisa al desarrollador y lo registra en el registro de auditoría. Un deny también se aplica a secrets_render_file, así que un secreto que la política bloquea no se puede escribir en un fichero con esa herramienta.
Los campos que una regla establece solo restringen la configuración local de la máquina; los que omite conservan el valor local. Un host nuevo solo se ofrece mientras la política esté vigente (no cuando haya caducado en una máquina en modo estricto), necesita la aprobación del miembro y nunca se ofrece un host con puerto; los comandos, los modos e injectAt nunca se amplían.

Hay una sola política para toda la organización, no una por agente. Un deny o un warn se aplica a todos los agentes de la máquina, sin importar lo que diga agents: esa lista solo decide a qué agentes se ofrece un host nuevo.

Tres estados

Cada regla tiene uno de tres estados, que se eligen en el editor de reglas:

Estado	En la máquina del miembro	En el registro de auditoría
No bloqueado (por defecto)	El uso sigue adelante, con la configuración local y los límites de la regla.	Permitido
Avisar	El uso sigue adelante dentro de los límites de la regla; zn-gate avisa al desarrollador y lo registra.	Avisado
Bloquear	El uso se detiene.	Bloqueado

El aviso aparece en la máquina del desarrollador; no detiene el uso. Todo uso avisado o bloqueado aparece en Equipo → Registro de auditoría, solo con metadatos (sin valores).

Las reglas Avisar se aplican allí donde se aplica un bloqueo: zn run, secrets_http_request, secrets_render_file y las restauraciones de marcadores y tokens en los hooks del agente. Cuando un uso avisado sigue adelante, el desarrollador y el agente ven este aviso, que se muestra en inglés: zn: your team policy would block STRIPE_API_KEY here (policy note: "..."). It was allowed and recorded for your organization. Se envía al registro de auditoría de la organización un registro con la decisión warn. Un marcador que restauran los hooks sigue las mismas reglas: un secreto que la política bloquea sigue siendo un marcador y el hook explica por qué; un secreto con una regla Avisar se restaura y se registra.

Las reglas Avisar requieren zn-gate 1.8.0 o posterior. En las máquinas con un zn-gate anterior, una regla Avisar actúa como No bloqueado: el uso sigue adelante dentro de los demás límites de la regla, pero no se muestra ningún aviso ni se registra nada como Avisado. Pide a los miembros que actualicen zn-gate.

En una organización con reglas Avisar, no vuelvas a zn-gate 1.7.1. Esa versión rechaza una política que contiene reglas Avisar y aplica solo la configuración local hasta la siguiente sincronización de la política, que descarga una copia que sí puede leer. Mantente en 1.8.0 o posterior.

Publicación

Publicar crea una nueva versión. El panel la valida primero. Un uso bloqueado se registra con reason: policy:org_deny, y un uso avisado se registra con reason: policy:warn y queda en el registro de auditoría como Avisado. El panel también rechaza una regla que tenga warn y deny a la vez.

Publicar exige autenticación de dos factores a propietarios y administradores. Los cambios propuestos desde un agente de programación con un token de administrador de la organización siempre esperan a que una persona los apruebe; consulta Gestiona tu equipo desde tu agente.

Firma y versiones

zn sirve cada política firmada con la clave Ed25519 de tu organización. Cada máquina la verifica con la clave pública que fijó al unirse.
Una política servida es válida durante 7 días. Las máquinas buscan una nueva versión periódicamente y cuando ejecutas zn team sync.
Una máquina nunca acepta una versión anterior a la última que aceptó, una política firmada con una clave desconocida ni una cuya firma no se verifica. Conserva la última política válida y registra policy:rejected.

Lo que ocurre sin red o cuando una política caduca se describe en Modo sin conexión.

Lo que la organización no puede hacer

zn-gate es una barrera de protección local, no una solución MDM. La política de la organización funciona por encima de las protecciones integradas de zn-gate y no puede desactivarlas: los archivos de credenciales, ~/.zn y la configuración propia de los agentes siguen protegidos independientemente de lo que indique la política.