Equipes
Política da organização
Como uma política é escrita, publicada, assinada e aplicada por cada zn-gate da organização.
A política da organização é uma lista de regras sobre segredos: para onde podem ser enviados e como são injetados. Proprietários e administradores a editam em Políticas e publicam uma nova versão; cada zn-gate da organização a recebe.
Regras
Cada regra se aplica a um segredo (pelo nome, nunca pelo valor; PREFIXO* e * são aceitos):
| Campo | Significado |
|---|---|
secret |
O nome do segredo, por exemplo STRIPE_API_KEY |
agents |
Agentes aos quais um novo host pode ser oferecido, por exemplo claude-code, codex. Um deny ignora esta lista |
mode |
Só proxy é aplicado (a forma mais restritiva); os demais valores são ignorados |
allowHosts |
Hosts para os quais o segredo pode ser enviado |
allowCommands |
Comandos que podem receber o segredo |
injectAt |
Onde o segredo é injetado |
deny |
Bloqueia todo uso do segredo, por todos os agentes da máquina |
warn |
Deixa passar o uso dentro dos demais limites da regra, avisa o desenvolvedor e o registra como Avisado, para todos os agentes da máquina. Use warn ou deny, nunca os dois |
reason |
Exibido ao desenvolvedor quando uma regra de aviso se aplica; nas regras de bloqueio, é uma nota para os administradores |
Como as regras se combinam:
- Todas as regras correspondentes se aplicam, de cima para baixo; cada uma só pode restringir mais.
denybloqueia.warndeixa passar o uso, avisa o desenvolvedor e o registra no log de auditoria. Umdenytambém se aplica asecrets_render_file, então um segredo bloqueado pela política não pode ser gravado em um arquivo por essa ferramenta.- Os campos definidos por uma regra apenas restringem as configurações locais da máquina; os campos omitidos mantêm o valor local. Um novo host só é oferecido enquanto a política estiver vigente (não depois de expirada numa máquina em modo estrito), precisa da aprovação do membro, e um host com porta nunca é oferecido; comandos, modos e injectAt nunca são ampliados.
Há uma única política para a organização inteira, e não uma por agente. Um deny ou um warn se aplica a todos os agentes da máquina, independentemente de agents: essa lista só decide a quais agentes é oferecido um novo host.
Três estados
Cada regra tem um de três estados, escolhido no editor de regras:
| Estado | Na máquina do membro | No log de auditoria |
|---|---|---|
| Não bloqueado (padrão) | O uso segue, com as configurações locais e os limites da regra. | Permitido |
| Avisar | O uso segue dentro dos limites da regra; o zn-gate avisa o desenvolvedor e o registra. | Avisado |
| Bloquear | O uso é interrompido. | Bloqueado |
O aviso aparece na máquina do desenvolvedor; ele não interrompe o uso. Cada uso avisado ou bloqueado aparece em Equipe → Registro de auditoria, apenas com metadados (sem valores).
As regras Avisar se aplicam onde se aplica um bloqueio: zn run, secrets_http_request, secrets_render_file e as restaurações de marcadores e tokens nos hooks do agente. Quando um uso avisado segue adiante, o desenvolvedor e o agente veem este aviso, que permanece em inglês: zn: your team policy would block STRIPE_API_KEY here (policy note: "..."). It was allowed and recorded for your organization. Um registro de auditoria com a decisão warn é enviado ao log da sua organização. Um marcador restaurado pelos hooks segue as mesmas regras: um segredo que a política bloqueia continua como marcador e o hook explica o motivo; um segredo sob uma regra Avisar é restaurado e registrado.
As regras Avisar exigem zn-gate 1.8.0 ou posterior. Nas máquinas com um zn-gate anterior, uma regra Avisar age como Não bloqueado: o uso segue dentro dos demais limites da regra, mas nenhum aviso é mostrado e nada é registrado como Avisado. Peça aos membros que atualizem o zn-gate.
Em uma organização com regras Avisar, não volte para o zn-gate 1.7.1. Essa versão recusa uma política que contém regras Avisar e aplica apenas as configurações locais até a próxima sincronização, que baixa uma cópia que ela consegue ler. Fique na 1.8.0 ou posterior.
Publicação
Publicar cria uma nova versão. O painel a valida primeiro. Um uso bloqueado é informado com reason: policy:org_deny, e um uso avisado é informado com reason: policy:warn e fica no log de auditoria como Avisado. O painel também recusa uma regra que defina warn e deny ao mesmo tempo.
A publicação exige autenticação em dois fatores para proprietários e administradores. Alterações propostas a partir de um agente de programação com um token de administrador da organização sempre aguardam a aprovação de uma pessoa; veja Gerencie sua equipe a partir do seu agente.
Assinatura e versões
- A zn entrega cada política assinada com a chave Ed25519 da sua organização. Cada máquina a verifica com a chave pública que fixou ao ingressar.
- Uma política entregue é válida por 7 dias. As máquinas verificam regularmente se há uma nova versão e também quando você executa
zn team sync. - Uma máquina nunca aceita uma versão inferior à última que aceitou, uma política assinada com uma chave desconhecida ou uma cuja assinatura não seja verificada. Ela mantém a última política válida e registra
policy:rejected.
O que acontece sem rede, ou quando uma política expira, está em Modo offline.
O que a organização não pode fazer
O zn-gate é uma barreira de proteção local, não um MDM. A política da organização funciona sobre as proteções integradas do zn-gate e não pode desativá-las: arquivos de credenciais, ~/.zn e a configuração própria dos agentes permanecem protegidos, independentemente do que a política disser.