Novidades do zn-gate 1.12.0: zn-gate reach, releases assinadas e uma correção de segurança

Q: O que há de novo no zn-gate 1.12.0?

O zn-gate reach, um relatório somente leitura do que os agentes de programação da sua máquina conseguem acessar, também em SARIF para o code scanning. As releases são geradas e assinadas em um workflow separado (SLSA Build Level 3) e as tags de release são assinadas com gitsign. O zn audit oculta mais valores secretos, os hooks dos agentes voltam a recusar rapidamente patches longos de shell e uma correção de segurança fecha o GHSA-rccq-h3xc-j9qj.

Q: Como atualizo para o zn-gate 1.12.0?

Execute npm install -g zn-gate@1.12.0 para o pacote Node e pip install -U zn-gate para o pacote Python. Para reinstalar os hooks dos agentes, execute npx -y zn-gate@1.12.0 init. Se você usa o plugin do Claude Code, atualize-o pelo diretório de plugins assim que a 1.12.0 aparecer lá.

O zn-gate 1.12.0 adiciona o zn-gate reach, um relatório somente leitura do que os agentes de programação da sua máquina conseguem acessar, com o comando que corrige cada achado. Ele também move o build e a assinatura das releases para um workflow separado, faz o zn audit ocultar mais valores secretos e corrige um problema de segurança nos hooks dos agentes que afeta as versões 1.5.0 a 1.11.0. Atualize com npm install -g zn-gate@1.12.0 e pip install -U zn-gate.

O que o zn-gate reach mostra?

Ele responde a uma única pergunta: o que os agentes de programação desta máquina conseguem acessar? Execute-o na pasta em que você trabalha:

npx -y zn-gate reach

Em uma única tela, ele lista:

quais agentes encontra (Claude Code, Codex CLI, Cursor, OpenCode) e se o zn os protege;
os arquivos .env da pasta, com os nomes dos seus segredos e nunca os valores;
os arquivos de credenciais da sua pasta pessoal, como ~/.aws/credentials, chaves SSH e ~/.npmrc. Ele só verifica se existem e nunca os abre;
os nomes das variáveis de ambiente que guardam um segredo;
o que o zn audit encontra nos servidores MCP e nas configurações de agentes da pasta e do seu usuário.

Cada achado vem com o comando que o corrige. O relatório é somente leitura: não mostra nenhum valor, não envia nada, não inicia nenhum hook e não grava nada, a menos que você peça com --remember, que guarda as contagens da execução (alta, média, baixa e a data) em ~/.zn/reach-last.json para que a próxima execução possa mostrar como estavam. --json imprime o mesmo relatório em JSON. A descrição completa está na documentação do reach.

O README e a página do npm agora mostram um caminho de quatro passos: zn-gate reach, zn-gate init, zn-gate check e zn-gate env shadow.

Dá para rodar o reach no CI e enviá-lo ao code scanning?

Sim. zn-gate reach --sarif grava o relatório como SARIF 2.1.0. Os achados sobre um arquivo da pasta verificada são resultados: os achados do zn audit mantêm suas regras, e um .env com segredos que um agente consegue ler é ZNR002. O que pertence à máquina (agentes sem proteção, arquivos de credenciais, variáveis de ambiente com segredos) e os arquivos da sua pasta pessoal são notificações da execução.

Por padrão, o reach sai com 0, então continua sendo um relatório. --fail-on high|medium|low sai com 1 quando encontra um achado naquele nível ou acima, e um erro de uso ou uma falha sai com 2.

O que mudou na forma como as releases são assinadas?

Duas coisas, ambas para quem verifica o que instala.

As releases agora são geradas, atestadas e assinadas por um workflow reutilizável separado, build-release.yml. O workflow de release chama seus jobs de build e de assinatura, mas não consegue acessá-los. Isso faz da procedência de build dos pacotes npm e Python um SLSA Build Level 3.

As tags de release são criadas e assinadas por um workflow, tag-release.yml, com gitsign (assinatura sem chave do Sigstore), de modo que a assinatura nomeia esse workflow e não a identidade de uma pessoa. Ele só roda a partir da main, verifica se o commit é a ponta da sua branch de release, se todas as versões coincidem e se todas as verificações passaram, e espera uma aprovação antes de assinar. A partir da 1.12.0, o workflow de release se recusa a publicar uma tag que não tenha uma assinatura válida do tag-release.yml.

Se você verifica releases, observe que, a partir da 1.12.0, o workflow signatário das atestações do GitHub e das assinaturas do Sigstore é usezn/zn/.github/workflows/build-release.yml (releases anteriores: release.yml). A procedência do npm e as atestações do PyPI continuam nomeando release.yml. A página de verificação no repositório traz ambos e explica como verificar uma tag.

O que o zn audit oculta agora?

O zn audit cita a linha de um achado como evidência. Ele já substituía segredos em formatos conhecidos. Na 1.12.0, ele também oculta:

um valor secreto em um formato que ele não conhece quando vem depois de uma flag de credencial (--token, --api-key, --password), de um cabeçalho de autenticação (Authorization: Bearer ..., x-api-key: ...) ou de um nome como API_TOKEN=;
um segredo passado como o próximo item de um array JSON depois de uma flag de credencial, como nos argumentos de um servidor MCP.

Referências como $TOKEN ou ${API_KEY} são mantidas. Versões anteriores podiam citar um valor assim na evidência de um achado. Se algum achado já lhe mostrou um, troque essa credencial.

O que mais foi corrigido?

Um patch longo enviado como comando de shell (apply_patch no Codex) volta a ser recusado em uma fração de segundo. Para nomear um arquivo secreto na mensagem, o zn agora verifica apenas os 32 primeiros arquivos do patch em vez de todos os que estão no disco, o que levava vários segundos para um patch perto do limite de 100 KB e podia estourar o limite de tempo do agente para o hook em uma máquina lenta. A decisão não muda.
No Windows, um comando do PowerShell que já roda por zn-gate run -- ... com um placeholder de segredo não é mais recusado por engano.
zn-gate check e zn hooks install codex agora avisam quando o Codex não vai executar os hooks do zn, porque eles estão desativados em requirements.toml, managed_config.toml ou no seu próprio config.toml, ou por allow_managed_hooks_only em requirements.toml sem o zn entre os hooks gerenciados. O Codex não dá nenhum sinal disso.

Qual é a correção de segurança?

O GHSA-rccq-h3xc-j9qj tem gravidade média e afeta o zn-gate 1.5.0 a 1.11.0. Nessas versões, a proteção de leitura dos hooks dos agentes podia deixar um arquivo protegido, como um arquivo .env com valores ou um arquivo de credenciais, ser lido sem ser recusado quando um comando chegava a ele de forma indireta, ou quando o comando era muito longo ou demorado de verificar. A 1.12.0 resolve essas formas antes de decidir, verifica todos os comandos de uma cadeia e recusa um comando que não consegue verificar dentro de um limite de tempo bem abaixo do timeout do hook do agente. Ela também recusa chaves privadas guardadas fora de ~/.ssh, por exemplo em um projeto.

A equipe do zn encontrou o problema em uma revisão interna. Descrevemos as classes de caminhos e o design da correção em um artigo à parte: como um agente de programação podia ler seu arquivo .env de forma indireta e como a 1.12.0 fecha esses caminhos.

O que fazer:

Atualize os pacotes e reinstale os hooks:

npm install -g zn-gate@1.12.0
pip install -U zn-gate
npx -y zn-gate@1.12.0 init

Em cada pasta que tenha um arquivo .env com valores, execute zn env shadow .env. Um arquivo com shadow contém apenas marcadores, então lê-lo por qualquer caminho não revela nenhum valor.
Execute zn-gate check para ver quais agentes têm os hooks instalados.

Se você usa o plugin do Claude Code, atualize-o pelo diretório de plugins assim que a 1.12.0 aparecer lá. As formas de cadeia longa e de timeout não têm solução alternativa nas versões antigas, então atualizar é a única correção para elas.

Perguntas frequentes

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

O zn-gate reach, um relatório somente leitura do que os agentes de programação da sua máquina conseguem acessar, também em SARIF para o code scanning. As releases são geradas e assinadas em um workflow separado (SLSA Build Level 3) e as tags de release são assinadas com gitsign. O zn audit oculta mais valores secretos, os hooks dos agentes voltam a recusar rapidamente patches longos de shell e uma correção de segurança fecha o GHSA-rccq-h3xc-j9qj.

Como atualizo para o zn-gate 1.12.0?

Execute npm install -g zn-gate@1.12.0 para o pacote Node e pip install -U zn-gate para o pacote Python. Para reinstalar os hooks dos agentes, execute npx -y zn-gate@1.12.0 init. Se você usa o plugin do Claude Code, atualize-o pelo diretório de plugins assim que a 1.12.0 aparecer lá.

O zn-gate reach envia meus segredos para algum lugar?

Não. Ele é somente leitura: nunca mostra um valor, não envia nada, não inicia nenhum hook e não grava nada, a menos que você passe --remember. Ele lista os nomes dos segredos dos seus arquivos .env, verifica se existem arquivos de credenciais como ~/.aws/credentials sem abri-los e mostra o que o zn audit encontra nos seus servidores MCP e nas configurações dos seus agentes.

Quais versões o GHSA-rccq-h3xc-j9qj afeta?

O zn-gate 1.5.0 a 1.11.0. Está corrigido na 1.12.0. O aviso tem gravidade média.

O que muda se eu verifico as releases do zn-gate?

A partir da 1.12.0, o workflow signatário das atestações do GitHub e das assinaturas do Sigstore é build-release.yml, e não release.yml. A página de verificação no repositório traz ambos e o jeito de verificar uma tag assinada.

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