Auditoria

npx -y zn-gate audit ./some-repo

(ou zn audit se você instalou com npm i -g zn-gate; zn-gate audit é o mesmo comando).

Os agentes de código leem configuração do repositório em que trabalham. Vários desses arquivos executam comandos, iniciam servidores MCP, mudam para onde o agente envia suas requisições à API ou ampliam o que ele pode fazer sem perguntar. Atualizar o agente corrige os bugs conhecidos, mas os arquivos continuam no repositório, e o próximo agente, um colega com uma versão mais antiga ou um job de CI ainda pode agir com base neles.

O zn audit lê esses arquivos, sem executar nada, e diz o que seria executado, para onde iriam as requisições e quais instruções um agente seguiria. Ele roda localmente e não envia nada a lugar nenhum. Execute-o antes de abrir um repositório que você acabou de clonar, e no CI.

Opções

zn audit [path] [--format text|json|sarif] [--output <file>]
         [--fail-on low|medium|high|critical|none]
         [--agents claude,codex,cursor,opencode,amazonq,copilot,gemini,all] [--include-home]

Exemplos:

# Antes de abrir um repositório que você acabou de clonar
npx -y zn-gate audit ./some-repo

# No CI: grava um arquivo SARIF para o code scanning do GitHub e nunca falha
zn audit --format sarif --output zn-audit.sarif --fail-on none

# Só o que o Claude Code e o Codex leem; falha apenas em critical
zn audit --agents claude,codex --fail-on critical

Na 1.5, o zn audit mostrava o registro local de uso de segredos. Esse registro agora é zn vault log (também zn secret log). zn audit log e zn audit --since DATE terminam com código 2 e dizem para usar zn vault log.

Códigos de saída

O que ele lê

Arquivos do projeto em qualquer profundidade, porque a configuração de um subdiretório vale quando um agente inicia ali. As pastas de agentes (.claude, .codex, .cursor, .github, skills e semelhantes) são lidas primeiro. Fora delas, node_modules, vendor e as pastas de build e de ambientes virtuais são ignoradas. O .git nunca é lido.

Nada do que o repositório controla pode fazer um arquivo sumir do relatório em silêncio:

• Um link simbólico que sai do repositório é reportado (ZNA020), não seguido.
• Um arquivo de agente maior que 1 MB é reportado (ZNA020) em vez de ignorado.
• A verificação para após 50.000 entradas de diretório ou 120 segundos, e avisa com um achado ZNA020 de gravidade alta, então a execução falha no limite padrão.
• Um .env na raiz, commitado, que aponta CODEX_HOME ou CLAUDE_CONFIG_DIR para uma pasta dentro do repositório faz o zn audit ler também as configurações dessa pasta.
• Um .env na raiz é auditado mesmo que o .gitignore o liste, porque num clone novo ele só existe se foi commitado. Os achados dele ficam um nível abaixo e dizem que não se aplicam ao seu .env local.

Com --include-home, ele lê também ~/.claude/settings.json, ~/.claude.json, ~/.codex/config.toml, ~/.cursor/mcp.json, ~/.cursor/hooks.json, ~/.aws/amazonq/mcp.json, ~/.config/opencode/opencode.json[c] e ~/.gemini/settings.json. Ele respeita CODEX_HOME e XDG_CONFIG_HOME como os agentes. Os comandos que você mesmo configurou são esperados ali, então só as variantes mais arriscadas são reportadas: código baixado e executado, pacotes sem versão fixa, mudanças de endpoint, segredos e permissões amplas. Os achados de endpoint, ambiente e permissões ficam limitados a medium.

Regras

Os ids das regras são estáveis: uma regra pode melhorar, mas o id nunca muda de significado. As gravidades são critical, high, medium e low; quando uma regra lista várias, o achado recebe a que corresponde ao caso.

Saída

Texto

zn audit  ./some-repo  (zn-gate 1.12.0 ou posterior)

CRITICAL  ZNA007  .claude/settings.json:4  [claude]
          Model API endpoint overridden by the project
          ANTHROPIC_BASE_URL points to https://agent-proxy.example.invalid
          evidence: "ANTHROPIC_BASE_URL": "https://agent-proxy.example.invalid"
          fix: Remove the override; set it in your user settings if you need a gateway.

1 finding (1 critical, 0 high, 0 medium, 0 low) in 3 files. Failing: severity >= high.

As cores só são usadas num terminal e nunca com NO_COLOR definido. Caracteres de controle e sequências de escape vindos do repositório são impressos como \x1b, nunca enviados ao seu terminal.

JSON

--format json imprime um objeto com os findings e um summary:

{
  "version": 1,
  "tool": "zn-gate",
  "toolVersion": "1.12.0",
  "root": "/home/me/some-repo",
  "findings": [
    {
      "id": "ZNA007",
      "severity": "critical",
      "agent": "claude",
      "file": ".claude/settings.json",
      "line": 4,
      "title": "Model API endpoint overridden by the project",
      "detail": "ANTHROPIC_BASE_URL points to https://agent-proxy.example.invalid ...",
      "evidence": "\"ANTHROPIC_BASE_URL\": \"https://agent-proxy.example.invalid\"",
      "fix": "Remove the override ...",
      "references": []
    }
  ],
  "summary": {
    "files": 3,
    "findings": 1,
    "bySeverity": { "critical": 1, "high": 0, "medium": 0, "low": 0 },
    "failOn": "high",
    "failed": true,
    "agents": ["claude", "codex", "cursor", "opencode", "amazonq", "copilot", "gemini"]
  }
}

file é relativo a root, com barras normais; os arquivos de --include-home começam com ~/. agent é o agente que lê o arquivo, ou any quando vários o leem. evidence é a linha correspondente, cortada em 160 caracteres, com os segredos trocados por [REDACTED:<TYPE>]. As URLs perdem usuário, senha, query string e fragmento.

SARIF

--format sarif grava SARIF 2.1.0 para o code scanning do GitHub: uma regra por id ZNA com texto de ajuda e uma pontuação de gravidade, e resultados localizados em relação à raiz do repositório. Cada resultado tem uma impressão digital, então os alertas sobrevivem a mudanças de linha. Os achados de --include-home são marcados como vindos da pasta pessoal e o GitHub os ignora, então não use essa opção no CI.

Use no CI

O mais simples é a GitHub Action do zn-gate com mode: audit. Veja GitHub Actions.

Para rodar a CLI você mesmo, grave um arquivo SARIF e envie-o ao code scanning:

- run: npx -y zn-gate@1.12.0 audit --format sarif --output zn-audit.sarif --fail-on none
- uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: zn-audit.sarif

Retire --fail-on none (o padrão é high) se quiser que o job falhe em achados high e critical. Adicione security-events: write ao job só quando enviar SARIF.

Limites

• Ele lê arquivos; não os executa, não inicia servidores nem resolve pacotes. Um pacote com versão fixa ainda pode ser malicioso, e um hook que chama um script local é reportado como hook, sem julgar o que o script faz.
• As regras de instruções procuram padrões linha a linha. Um autor determinado pode redigir uma instrução que nenhum padrão detecte, e a documentação que cita um comando perigoso também é reportada, por exemplo um guia de instalação com curl ... | sh. Revise a evidência antes de agir.
• A regra de workflows lê o YAML linha a linha. Ela conhece as actions de agentes comuns e as chaves de gatilhos e permissões, não workflows reutilizáveis nem actions compostas.
• A configuração do Git (.git/config, filtros do .gitattributes) e as extensões de editor não são verificadas.
• Os agentes mudam seus formatos de configuração com frequência. Chaves desconhecidas são ignoradas, não reportadas.
• Os segredos são encontrados por formato e por nome de chave sensível. Um segredo sem formato conhecido sob um nome de chave inocente não é encontrado, e senhas escritas em prosa não são ocultadas na evidência.