Skip to main content
Versões

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.

Visão geral das novidades do zn-gate 1.16: um centro com cinco itens, em ordem. Uma verificação mais clara: check --hooks lista cada hook como OK, stale ou broken, o check simples termina com um resumo de hooks em uma linha e o tempo de decisão por chamada de ferramenta, e check --json entrega o resultado para scripts. zn why explica o último bloqueio em palavras simples. Segredos no histórico dos agentes: reach --history mostra quais tipos de segredo os seus agentes guardaram no histórico local de sessões e nunca imprime um valor. Auditoria antes de instalar: scan --package audita um servidor MCP ou skill do npm antes de você adicioná-lo, e uma verificação opcional analisa os pacotes que o seu agente instala. Mais difícil de burlar: a verificação de comandos destrutivos segue cd, env -C e sudo -D, e mais formas de ocultar um download-and-run ou uma leitura de .env são bloqueadas.

A verificação me diz mais agora?

Sim. Quatro adições, todas locais:

  • zn-gate check --hooks (também doctor --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 check e o doctor simples terminam com uma linha, por exemplo Hooks: 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. O zn-gate status també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 check termina 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.json apenas como números e mostra no data yet até o zn verificar uma chamada de ferramenta.
  • zn-gate check --json (também doctor --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. --json entrega 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ão node_modules, dist e build dentro do pacote também são analisados. Antes do resultado, o relatório lista o que o npm executaria se você o instalasse: seus scripts preinstall, install e postinstall com o respectivo comando, e seus comandos bin. Nada no pacote é instalado nem executado. O código de saída é 1 quando há achados, 3 quando parte do pacote não pôde ser lida e 2 quando 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 add e pipx install, e nunca bloqueia um comando. Defina hooks.packageInstallCheck como "offline" em ~/.zn/config.json (ou ZN_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 um npm install em 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 respeitam NODE_USE_ENV_PROXY. O fetch de 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 cd e pushd antes na linha, e env -C, env --chdir, sudo -D e sudo --chdir. cd ~ && rm -rf ., env -C ~ rm -rf . e sudo -D / rm -rf . são bloqueados como rm -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ém cd ~ && 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 ...) e curl URL | jq . continuam permitidos.
  • Grafias do .env. Um arquivo .env nomeado 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.example continuam permitidos, e .env.dist, .env.defaults e .env.schema sã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/, do package.json e do bin/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 check cita 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 --rules imprime 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 defina ZN_TEAM_JOIN_TOKEN). Um token passado como argumento continua funcionando.
  • zn audit. zn audit --approve registra 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 bloqueia audit --approve quando um agente o escreve. Uma nova regra, ZNA022, sinaliza um hook do tipo http que envia eventos de ferramenta a um endereço.
  • Claude Code. zn hooks install claude-code também registra os hooks ConfigChange e InstructionsLoaded. Execute-o de novo para adicioná-los.
  • O GitHub Copilot não é mais marcado como experimental. zn hooks install copilot configura 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_gate nã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, e python -m zn_gate executa o comando zn-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, scan e analyze saem com 2 diante 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ção security ou audit que 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 check disser que um hook está desatualizado, ou que um launcher registra só o runner, execute zn 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 no config.json e a lista de pedidos de segredo ficavam em ~/.zn quando ZN_HOME estava definido, enquanto estatísticas, pins, o cofre e a chave da nuvem o seguiam. Todo o estado do zn agora segue ZN_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.

Compartilhar