Novidades do zn-gate 1.16.0: uma verificação mais clara, zn why, segredos no histórico do agente, uma auditoria de pacote, verificações de comando mais rigorosas
John Silver12 min de leitura
O zn-gate 1.16.0 deixa a verificação mais fácil de ler e de automatizar. zn-gate check --hooks lista cada hook instalado e diz se ele está OK, desatualizado ou quebrado, o check simples termina com um resumo de uma linha dos hooks e o tempo de decisão por chamada de ferramenta, e check --json entrega o mesmo resultado para scripts e CI. zn why explica o último bloqueio em palavras simples. Ele também traz quatro recursos que ficam desativados até você pedir, faz as verificações de comando lerem mais do que um shell realmente executa e verifica todos os arquivos do zn-gate que o hook carrega. O zn-gate continua sem exigir conta e não envia nada por padrão. Atualize com npm install -g zn-gate@1.16.0 e pip install -U zn-gate.
A verificação me diz mais agora?
Sim. Quatro adições, todas locais:
zn-gate check --hooks(tambémdoctor --hooks) lista cada hook do zn instalado com seu agente, seu arquivo de configurações, seu evento e o comando que ele executa. Cada hook está OK, desatualizado (escrito por um zn-gate mais antigo) ou quebrado (não consegue executar, está desativado, está escrito duas vezes ou está em um arquivo de configurações que o zn não consegue ler), e uma linha de hook desatualizado ou quebrado vem com o comando que o corrige. Ele só lê arquivos: nada é executado, alterado ou enviado.- Um resumo dos hooks. O
checke odoctorsimples terminam com uma linha, por exemploHooks: 3 OK, 1 stale, 0 broken. Run zn-gate check --hooks for details.Ela aparece só quando há um hook instalado e não muda o código de saída. Ozn-gate statustambém avisa quando um hook foi escrito por um zn-gate mais antigo, cita cada agente e dá o comando que o renova. - Tempo de decisão. O
checktermina com o p50 e o p95 das últimas 100 chamadas de ferramenta, medidos na sua máquina. Ele deixa de fora a inicialização do processo, a escrita da resposta e o salvamento de estatísticas e evidências. É guardado em~/.zn/stats.jsonapenas como números e mostrano data yetaté o zn verificar uma chamada de ferramenta. zn-gate check --json(tambémdoctor --json) imprime um objeto JSON para scripts, CI e pedidos de suporte: o estado da proteção e o motivo para cada agente, as versões e o código de saída. Os códigos de saída são os mesmos da forma em texto, e sua pasta pessoal aparece como~.
O que o zn why faz?
zn why explica o último bloqueio no seu registro de decisões, ou o registro com o id que você informar (zn why <id>), em palavras simples: o que foi interrompido (apenas a prévia curta que o registro já guarda), qual regra foi acionada, por que isso importa e o comando que você pode executar no seu próprio terminal para continuar, quando há um. Ele só lê o registro e nunca usa a rede. Está no pacote npm.
Seis mensagens de bloqueio agora seguem o mesmo padrão: citam a regra, dizem por que ela importa e dizem quem pode liberar, com o único comando a executar quando possível. Elas cobrem um comando destrutivo, um arquivo .env e outros arquivos de segredo, uma requisição que enviaria dados pessoais, um comando longo demais para verificar e um cofre que não está disponível. As mensagens começam com as mesmas palavras de antes. Quando um curinga como ls * ou cat * é interrompido porque também corresponderia a um arquivo .env, a mensagem agora diz isso sobre o padrão e pede que você indique os arquivos de que precisa.
O que há de novo e fica desativado, a menos que eu peça?
- Segredos no histórico do agente:
zn-gate reach --history. Ele lê os arquivos de histórico do Claude Code e do Codex na sua pasta pessoal, linha por linha, e imprime o agente, o arquivo, o tipo de segredo, quantas vezes aparece e o que fazer (trocar a chave, apagar a sessão). Ele nunca imprime um valor.--jsonentrega o mesmo para scripts. Não escreve nada, não envia nada e não segue nenhum link, e, quando seu limite de tempo (--max-seconds, 120 por padrão) é atingido, diz quais arquivos não terminou. Ele não consegue ver o que já foi enviado ao provedor do seu modelo. O pacote Python também o tem, com o mesmo relatório, as mesmas opções e os mesmos códigos de saída. - Auditar um pacote antes de adicioná-lo:
zn-gate scan --package <name>[@version]. O zn-gate baixa um servidor MCP ou uma skill do npm a partir do registro, confere com o checksum, descompacta em uma pasta temporária e lê seus arquivos com extensão analisada, junto com a auditoria da configuração do agente. Nenhuma pasta é ignorada pelo nome, entãonode_modules,distebuilddentro do pacote também são analisados. Antes do resultado, o relatório lista o que o npm executaria se você o instalasse: seus scriptspreinstall,installepostinstallcom o respectivo comando, e seus comandosbin. Nada no pacote é instalado nem executado. O código de saída é1quando há achados,3quando parte do pacote não pôde ser lida e2quando o pacote não pode ser obtido ou é recusado (por exemplo, o checksum não confere). Ele não analisa os pacotes dos quais o pacote depende. - Uma verificação dos pacotes que seu agente instala. Ela cobre
npm install,pnpm add,yarn add,bun add,pip install,uv addepipx install, e nunca bloqueia um comando. Definahooks.packageInstallCheckcomo"offline"em~/.zn/config.json(ouZN_PACKAGE_CHECK=offline) e seu agente pergunta antes de instalar um nome parecido com o de um pacote conhecido (uma letra de diferença, duas letras trocadas, um caractere parecido, outros separadores ou um escopo npm que imita um conhecido). Com"online"(apenas no arquivo de configuração), o zn-gate também consulta o registro público do npm ou do PyPI, para uma instalação simples, para saber se o nome existe, enviando apenas o nome do pacote, e pergunta quando ele não existe ou foi publicado pela primeira vez há menos de 14 dias. Agentes que não conseguem exibir uma pergunta (Codex CLI, OpenCode, Gemini CLI) executam o comando, e todo achado vai para o registro de decisões. Avisos sobre uma versão publicada há menos de 72 horas, e sobre umnpm installem um projeto que pode atualizar o lockfile, são uma ativação separada (hooks.packageInstallNotices). - Limitar os hosts que um comando acessa:
zn run --egress-allow HOST[:PORT],.... O zn configura um proxy local em 127.0.0.1 para o comando, e requisições para outros hosts recebem um 403. Cobre programas que leem as variáveis de proxy (curl, gh, requests, axios) e, no Node, apenas versões que respeitamNODE_USE_ENV_PROXY. Ofetchde um Node mais antigo, programas que ignoram as variáveis, sockets brutos e DNS não são cobertos.
Quais comandos a verificação lê agora?
A verificação de comandos destrutivos bloqueia uma exclusão recursiva da sua pasta pessoal, da raiz do sistema de arquivos ou de uma pasta do sistema. O 1.16.0 lê mais do que um shell realmente executa antes de decidir:
- Mudanças de pasta. Ele segue
cdepushdantes na linha, eenv -C,env --chdir,sudo -Desudo --chdir.cd ~ && rm -rf .,env -C ~ rm -rf .esudo -D / rm -rf .são bloqueados comorm -rf ~, e um shell aninhado começa na pasta que a linha alcançou. Os mesmos comandos em uma pasta de projeto (cd build && rm -rf .,env -C ~/projects/app rm -rf .) continuam permitidos, e tambémcd ~ && rm -rf .cache. - Palavras-chave do shell e crases.
{ rm -rf ~; },if true; then rm -rf ~; fi,while ...; do ...; done,! rm -rf ~e um comando dentro de crases são lidos como o mesmo comando isolado. - Baixar e executar. A verificação agora também bloqueia um shell que lê seu programa de uma substituição na entrada (
bash < <(curl URL),sh <<< "$(curl URL)"), um downloader ou shell escrito de outra forma (/bin/sh -c "$(curl ...)",bash <(\curl ...)), um download encaminhado para um grupo ou para a linha seguinte (curl URL | (sh)) e variáveis literais atribuídas antes na mesma linha (X=curl; $X URL | sh).bash < <(echo hi),diff <(curl ...) <(curl ...)ecurl URL | jq .continuam permitidos. - Grafias do
.env. Um arquivo.envnomeado com prefixo de caminho (./.env,app/.env,/srv/app/.env), em uma lista do PowerShell (cat .env.example,.env), com um parâmetro do PowerShell (Get-Content -Path:.env) ou escrito via cmd.exe (type .e^nv, unidades%NAME%) ou por uma expansão do shell que poderia completar o nome é bloqueado. Arquivos de exemplo como.env.examplecontinuam permitidos, e.env.dist,.env.defaultse.env.schemasão bloqueados. - O launcher verifica todos os arquivos. Na instalação, o launcher do hook registra o SHA-256 do código e dos dados em
lib/, dopackage.jsone dobin/cli.js. Cada um desses arquivos é verificado quando o hook o carrega, e um arquivo que foi editado, não consta da lista, é um link ou fica fora do pacote interrompe o hook.zn-gate checkcita um arquivo alterado. O próprio script do launcher, o binário do Node.js, arquivos lidos como dados e os hooks inline do PowerShell no Windows (Codex CLI, Cursor, Gemini CLI, Antigravity) não são cobertos.
Veja Comandos destrutivos para a lista completa.
O que mudou para equipes, zn audit e Python?
- Equipes.
zn team status --rulesimprime em palavras simples as regras da política assinada ativa da sua organização: a versão, o id da chave, quando expira e cada regra com o que ela bloqueia, avisa ou restringe, e o motivo. Não faz nenhuma chamada de rede e não mostra regras de uma cópia que não é verificada ou que expirou.zn team join -lê o token de entrada da entrada padrão, então ele fica fora do histórico do seu shell e da lista de processos (printf %s "$TOKEN" | zn team join -, ou definaZN_TEAM_JOIN_TOKEN). Um token passado como argumento continua funcionando. zn audit.zn audit --approveregistra a configuração executável de um projeto (servidores MCP, hooks, permissões, comandos auxiliares, scripts de instalação e mais). Auditorias posteriores relatam uma entrada alterada, adicionada ou removida como ZNA023, apenas pelo nome. A aprovação é sua: o comando só roda em um terminal, e o zn bloqueiaaudit --approvequando um agente o escreve. Uma nova regra, ZNA022, sinaliza um hook do tipohttpque envia eventos de ferramenta a um endereço.- Claude Code.
zn hooks install claude-codetambém registra os hooksConfigChangeeInstructionsLoaded. Execute-o de novo para adicioná-los. - O GitHub Copilot não é mais marcado como experimental.
zn hooks install copilotconfigura os hooks que o VS Code, o app GitHub Copilot e o Copilot CLI compartilham. Os hooks foram executados de ponta a ponta apenas com o Copilot CLI, e a parte do VS Code está documentada, não testada no app. - Python. Uma verificação local inicia em menos da metade do tempo que levava, porque
import zn_gatenão compila mais todas as regras de antemão. O pacote Python também oculta os mesmos formatos de segredo que o pacote Node.js, epython -m zn_gateexecuta o comandozn-gate.
Algo quebra?
Não para a maioria das pessoas. Estas são as mudanças que podem interromper algo que funcionava antes:
- Opções desconhecidas são erros.
check,doctor,status,version,test,evidence,logs,export,team status,scaneanalyzesaem com2diante de uma opção que não conhecem, e a mensagem lista as opções que o comando aceita. Antes, a opção era ignorada. - Configurações com erro de digitação no
zn.json. Uma configuração na seçãosecurityouauditque o zn não conhece agora é um erro que cita a configuração e a válida mais próxima. Em outras seções, continua sendo um aviso. - Hooks desatualizados. Se o
checkdisser que um hook está desatualizado, ou que um launcher registra só o runner, executezn hooks install <agent>de novo. - Um evento de hook desconhecido (um nome ou um formato que esta versão não conhece) agora é bloqueado nos hooks que podem bloquear, no Claude Code, Codex CLI, ZCode e Cursor, com uma mensagem que pede para atualizar. Execute
zn hooks install <agent>para obter o novo launcher. - Se você definiu
ZN_HOME. Até agora, o registro de decisões, as configurações de hooks noconfig.jsone a lista de pedidos de segredo ficavam em~/.znquandoZN_HOMEestava definido, enquanto estatísticas, pins, o cofre e a chave da nuvem o seguiam. Todo o estado do zn agora segueZN_HOME. Com a variável não definida, nada muda.
Como atualizo?
npm install -g zn-gate@1.16.0
pip install -U zn-gate
npx -y zn-gate@1.16.0 check
A atualização renova os launchers de hook que ela escreveu. Se o seu gerenciador de pacotes ignora scripts de instalação (npm install --ignore-scripts, pnpm ou bun), ou você atualizou com sudo, execute zn hooks install <agent> de novo para cada agente que você usa. O check diz quais agentes precisam disso. Se você usa o plugin do Claude Code, execute claude plugin update zn-gate@usezn e inicie uma nova sessão.
Se você já definiu ZN_HOME, mova evidence.jsonl e requests.jsonl de ~/.zn para essa pasta e copie para lá também a parte de hooks do config.json. Esses três ficavam em ~/.zn, e o zn agora os procura na pasta de ZN_HOME.
A lista completa está no changelog.