zn-gate (local)

Configuração

Variáveis de ambiente, flags de linha de comando e regras personalizadas para o zn-gate.

Ver .md

O zn-gate funciona sem nenhuma configuração. Tudo abaixo é opcional.

Variáveis de ambiente

Variável Padrão Efeito
ZN_CLOUD off 1 faz com que a análise de prompts (analyze_prompt, zn-gate analyze, analyze() em Python) também consulte o modelo na nuvem para uma segunda opinião. Requer ZN_API_KEY.
ZN_API_KEY não definida Chave de API obtida no painel. Não tem efeito sem ZN_CLOUD=1.
ZN_LOCAL_ONLY não definida true força o modo somente local, mesmo com ZN_CLOUD=1.
ZN_STAGE v30 Endpoint da nuvem: v30 (API de produção atual) ou prod (endpoint legado).
ZN_API_URL não definida Substitui a URL do endpoint da nuvem. Tem precedência sobre ZN_STAGE.
ZN_VERBOSE não definida Qualquer valor ativa o log de depuração em stderr.

npx -y zn-gate status mostra o motor ativo e o que a sua configuração envia. Veja O que sai da sua máquina.

Ativar a nuvem para um único servidor MCP

Adicione as variáveis à entrada desse servidor na configuração do seu agente, por exemplo em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "zn-gate": {
      "command": "npx",
      "args": ["-y", "zn-gate", "mcp"],
      "env": { "ZN_CLOUD": "1", "ZN_API_KEY": "zn_live_your_key" }
    }
  }
}

Flags de linha de comando

Flag Efeito
--local-only Nunca usa a nuvem, mesmo que ZN_CLOUD=1 esteja definida
--key <api_key> Chave de API para a nuvem opcional (igual a ZN_API_KEY; ainda exige ZN_CLOUD=1)
--stage v30 ou --stage prod, --url <url> Seleção do endpoint da nuvem
--shadow Com init ou shield: registra detecções sem bloquear nem alterar o tráfego
--all, --include .rst,.xml, --exclude fixtures Controlam quais arquivos o scan lê
--verbose Log de depuração em stderr

Execute npx -y zn-gate --help para ver todas as opções.

Regras personalizadas

No pacote Node.js, adicione padrões proibidos e caminhos proibidos para o seu projeto em .znrules ou zn.config.json, no diretório de onde o zn-gate é executado:

# .znrules
path:.env.production
path:/etc/secrets
CONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+

Linhas que começam com path: bloqueiam qualquer entrada que contenha esse caminho. As demais linhas são expressões regulares sem distinção de maiúsculas e minúsculas, que bloqueiam qualquer entrada que correspondam. Linhas que começam com # são comentários. A forma em JSON:

{ "bannedPatterns": ["CONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+"], "forbiddenPaths": [".env.production", "/etc/secrets"] }

Bloqueios causados por regras personalizadas informam custom:banned_pattern ou custom:forbidden_path. O pacote Python não lê esses arquivos.

Arquivos que o zn-gate grava

Arquivo O que é
~/.zn/evidence.jsonl Log de auditoria local das decisões do shield (detalhes)
<config>.bak.<timestamp> Cópia de segurança de cada configuração de agente que o init altera; init --revert restaura a mais recente