Novidades do zn-gate 1.13.0: zn-gate connect, zn-gate report e uma correção da GitHub Action

VersõesJohn Silver10 min de leitura

O zn-gate 1.13.0 adiciona o zn-gate connect, que liga a verificação opcional na nuvem com uma chave de API somente de análise guardada no chaveiro do seu sistema, e o zn-gate disconnect, que também pode revogar essa chave. Adiciona o zn-gate report, um resumo local do que o zn-gate fez nos últimos dias. Também corrige a versão padrão da GitHub Action, mantém o log de auditoria em uma única cadeia quando vários programas gravam nele e permite desligar a cor com NO_COLOR. O zn-gate continua sem exigir conta e não envia nada por padrão. Atualize com npm install -g zn-gate@1.13.0 e pip install -U zn-gate.

Como ligo a verificação opcional na nuvem?

Execute isto no seu próprio terminal:

npx -y zn-gate connect

A verificação na nuvem é opcional. O zn-gate funciona por completo no seu computador sem ela. Quando você a liga, o texto das chamadas a analyze_prompt (e a zn-gate analyze), com os segredos detectados ocultados antes, também é verificado pelo classificador Galvanize 2 em usezn.com. Os hooks, a proteção de arquivos e segredos e todos os outros comandos continuam locais.

O que o connect faz:

  1. Só roda em um terminal em que você digita. Se um agente de IA o iniciar, ele recusa.
  2. Abre usezn.com no seu navegador, onde você cria uma chave de API somente de análise.
  3. Você cola a chave em um prompt oculto. Ela nunca é lida da linha de comando.
  4. Guarda a chave no chaveiro do sistema, ou no cofre da zn quando não há chaveiro e o cofre está desbloqueado (zn unlock), e nunca em um arquivo.

Ele só aceita uma chave limitada a analisar texto. Uma chave assim não consegue ler o seu uso nem gerenciar chaves, então uma cópia vazada serve de pouco, e uma chave de acesso total é recusada. O zn-gate status mostra se há uma chave conectada e de onde ela vem, sem exibi-la. Uma chave em ZN_API_KEY ou --key só entra em jogo quando você também define ZN_CLOUD=1. A chave salva só é enviada para https://api.usezn.com. O guia completo, com o que é enviado e o que fazer se algo falhar, está na documentação do connect.

Como me desconecto e revogo a chave?

zn-gate disconnect

Ele remove a chave salva deste computador e pergunta se você também quer revogá-la em usezn.com, para que ela deixe de funcionar em qualquer lugar. A resposta padrão é não. Só um sim explícito envia algo: uma requisição com a chave para https://api.usezn.com. No seu próprio terminal, --revoke pula a pergunta e --no-revoke nunca revoga. Se a requisição de revogação falhar, a cópia local é removida mesmo assim e o comando indica a página de chaves de API de usezn.com para você revogar a chave por conta própria.

Assim como o connect, o disconnect só roda no seu próprio terminal. A partir de um script ou de um agente de IA, ele recusa e não altera nada. Os hooks também recusam comandos que pedem ao chaveiro do sistema as entradas da própria zn, então os caminhos diretos para um agente ler a chave salva estão fechados. Um programa que roda como você ainda pode consultar o chaveiro, como em qualquer entrada. Por isso a chave é limitada a analisar texto.

O que o zn-gate report mostra?

npx -y zn-gate report

Ele imprime um resumo curto dos últimos 7 dias neste computador:

  • ações bloqueadas, por agente;
  • segredos ocultados, por tipo;
  • novos servidores MCP que o zn-gate passou a proteger;
  • ferramentas de servidores MCP protegidos que mudaram e aguardam a sua aprovação;
  • o dia mais movimentado.

Use --since com um período de 1d a 90d para mudar o intervalo e --json para scripts. O relatório lê apenas arquivos locais, não grava nada e não envia nada. Ele termina com uma linha sobre o zn Team; --no-team-line a oculta, e ela não aparece depois que o computador entra em um Team. Veja a documentação do report.

Há alguma correção de segurança?

Sim. Alguns formatos de token de provedores não eram ocultados pela API da biblioteca, pelas verificações das ferramentas MCP, pelo texto enviado à análise na nuvem e pela prévia local da evidência. Agora são ocultados da mesma forma que no pacote Python. Os hooks de agente não foram afetados. Atualize para o zn-gate 1.13.0.

O que mais há de novo?

  • Uma chave de API da zn (zn_ seguido de 48 caracteres) é reconhecida pelo scrubber e ocultada como as outras chaves de provedores.
  • Claude Code: um novo hook UserPromptExpansion verifica no que uma skill ou um comando digitado se expande. Ele bloqueia a expansão, com o motivo e o próximo passo, quando o modelo veria um valor secreto, uma chave privada ou as linhas de um arquivo .env. Execute zn-gate hooks install claude-code novamente para adicioná-lo; o plugin já o inclui.
  • O zn-gate check agora avisa quando os hooks do Claude Code instalados por um zn-gate mais antigo não têm essa verificação e sugere o mesmo comando.
  • O zn-gate init não instala mais o plugin do Claude Code quando o Node.js é anterior à 20.12, que o plugin exige. Em vez disso, configura os hooks da zn para o Claude Code e informa isso em uma linha.
  • Os hooks verificam o código que shells e wrappers executam a partir de uma string (sh -c, bash -lc, eval, pwsh -Command, cmd /c e outros) como um comando próprio, de modo que cada regra vale dentro dele.
  • O zn audit oculta o valor após uma opção de credencial em mais formas de listas de argumentos, nos relatórios de texto, JSON e SARIF.
  • Mais testes automatizados para os servidores MCP, o zn run, o cofre, o zn team, o reach, o audit e o pacote Python. Sem mudança de comportamento.

O que mudou na GitHub Action?

A entrada version agora usa por padrão a versão da própria release da Action (1.13.0 nesta release). A release 1.12.0 da Action usava por padrão a 1.10.0, então um workflow com usezn/zn@v1.12.0 e sem version instalava o zn-gate 1.10.0. Se você usa a Action, defina version no seu workflow para escolher exatamente o que roda. O guia do GitHub Actions traz as entradas e um exemplo mínimo de auditoria, e esta release também atualiza o texto da página do Marketplace sem mudar o comportamento.

O que acontece se o log de auditoria estiver danificado?

O log de auditoria (~/.zn/evidence.jsonl) agora é verificado quanto a danos antes de qualquer registro ser adicionado a ele. Um log com bytes ilegíveis ou com a última linha cortada é relatado como corrompido, com o número da linha, por evidence --verify (saída diferente de zero), evidence e evidence --export, em vez de falhar com um erro do Python. Um log danificado nunca é usado para iniciar uma nova cadeia. O evento não é gravado, um aviso é exibido e o seu comando ou agente segue normalmente.

Para recuperar, mova o arquivo danificado para o lado e o próximo evento inicia uma nova cadeia:

mv ~/.zn/evidence.jsonl ~/.zn/evidence.damaged.jsonl

No Windows, no cmd: move %USERPROFILE%\.zn\evidence.jsonl %USERPROFILE%\.zn\evidence.damaged.jsonl; no PowerShell: Move-Item $env:USERPROFILE\.zn\evidence.jsonl $env:USERPROFILE\.zn\evidence.damaged.jsonl. O arquivo antigo permanece para análise.

Vários programas podem gravar no log ao mesmo tempo, por exemplo dois agentes em um mesmo projeto, ou os pacotes Node.js e Python juntos. Cada gravação agora pega um bloqueio curto (um arquivo evidence.jsonl.lock ao lado do log), então os registros ficam em uma única cadeia. Se o bloqueio continuar ocupado por 2 segundos, ou se não for possível gravar no log (sem permissão, disco cheio), o evento é ignorado com um aviso e a decisão não muda. Um bloqueio deixado por um programa que travou é liberado após 10 segundos. Os pacotes Node.js e Python também podem compartilhar um log com texto não ASCII, como letras acentuadas ou CJK, e logs gravados por versões anteriores continuam sendo verificados.

O que mais foi corrigido?

  • O hook não recusa mais um comando que grava um arquivo a partir de um here-document (cat > file <<'EOF') quando o corpo contém um * ou outro caractere curinga, e verifica um corpo de 100 KB em poucos milissegundos, em vez de dezenas de milissegundos. O corpo de um here-document só é lido como dado em um comando de dados simples, como cat ou tee. Corpos que um shell, um interpretador ou o xargs executa continuam recusados, assim como toda leitura de .env ou de um arquivo de credenciais na linha de comando.
  • A saída da linha de comando dos pacotes Node.js e Python não tem códigos de cor quando NO_COLOR tem qualquer valor não vazio, quando TERM=dumb ou quando a saída não é um terminal. Com NO_COLOR ou TERM=dumb, ela também omite símbolos e linhas de moldura. As palavras de status, como ALLOWED e BLOCKED, mantêm o significado, e os códigos de saída e as saídas JSON, SARIF e dos hooks de agentes não mudam.
  • Os hooks recusam um arquivo .env alcançado por uma raiz do Windows, um compartilhamento de rede ou um caminho de comprimento estendido (type %CD%\.env, more \\server\share\.env, gc \\?\C:\path\.env), porque a zn não consegue ler um caminho assim para verificar se o arquivo contém valores.
  • A regra que protege a chave da zn não confunde mais um módulo chamado cloud-keys com o módulo cloud-key próprio da zn, e agora também reconhece nomes de módulo escritos com sequências de escape ou divididos por aspas.
  • O scrubber não relata mais como segredo um exemplo mascarado (uma chave da Anthropic ou um valor bearer formado quase todo por um mesmo caractere repetido).
  • O zn-gate reach --remember mostra a data da execução anterior apenas quando é uma data simples, então um arquivo de memória editado não consegue colocar outro texto no relatório.

Perguntas frequentes

O que há de novo no zn-gate 1.13.0?

O zn-gate connect e o zn-gate disconnect, para ligar e desligar a verificação opcional na nuvem com uma chave de API somente de análise, guardada no chaveiro do sistema ou no cofre. O zn-gate report, um resumo local dos últimos dias. O scrubber reconhece chaves de API da zn, os hooks verificam no que uma skill digitada se expande, um log de auditoria danificado é relatado em vez de causar uma falha e a versão padrão da GitHub Action foi corrigida. O log de auditoria mantém uma única cadeia quando vários programas gravam nele, e a saída da linha de comando pode ser texto simples com NO_COLOR.

Como atualizo para o zn-gate 1.13.0?

Execute npm install -g zn-gate@1.13.0 para o pacote Node e pip install -U zn-gate para o pacote Python. Se o Claude Code usa os hooks da zn em vez do plugin, execute npx -y zn-gate@1.13.0 hooks install claude-code para adicionar o novo hook; o npx -y zn-gate@1.13.0 check avisa quando ele estiver faltando. Se você usa o plugin do Claude Code, atualize-o pelo diretório de plugins assim que a 1.13.0 aparecer lá.

Preciso de uma conta para usar o zn-gate 1.13.0?

Não. O zn-gate continua sem exigir conta e não envia nada por padrão. O zn-gate connect é opcional: só depois de executá-lo, o texto das chamadas a analyze_prompt (com os segredos detectados ocultados antes) também é verificado pelo classificador Galvanize 2 em usezn.com.

O zn-gate report envia meus dados para algum lugar?

Não. Ele lê apenas arquivos locais, não grava nada e não envia nada. Compartilhar estatísticas de uso com a zn é uma escolha separada, desativada a menos que você a ative.

Qual versão a GitHub Action instala se eu omitir version?

A partir da 1.13.0, cada release da Action usa por padrão a sua própria versão do zn-gate. A release 1.12.0 da Action usava por padrão a 1.10.0, então um workflow com usezn/zn@v1.12.0 e sem version instalava o zn-gate 1.10.0. Defina version no seu workflow para escolher exatamente o que roda.

A lista completa de mudanças está nas notas da release 1.13.0. O zn-gate é MIT, roda localmente e não exige conta: comece com npx -y zn-gate report ou veja Instalação para cada agente.

Compartilhar