zn-gate

zn-gate

A camada de segurança local para agentes de codificação.
zn-gate protege seus segredos, seus dados e seus sistemas enquanto você usa Claude Code, Codex CLI, Cursor ou OpenCode.
Uma camada de segurança de código aberto que roda na sua máquina, entre seu agente e as ferramentas e conteúdos que ele acessa.

Documentação · Pacote npm · Pacote Python · Segurança · Discord

Para: desenvolvedores que usam Claude Code, Codex CLI, Cursor, OpenCode ou qualquer cliente MCP, e equipes que constroem agentes com MCP, LangChain, CrewAI ou LlamaIndex.

O que faz: mantém valores secretos fora do que seu agente envia ao modelo, verifica o que seu agente lê e chama para injeção de prompt, e audita prompts, habilidades e configurações. Tudo roda na sua máquina, é licenciado sob MIT e não precisa de conta. O pacote Python não tem dependências em tempo de execução; a única dependência do pacote npm é age-encryption (com suas dependências @noble/@scure) para o cofre de segredos, incluída no pacote.

Instalação

Tudo roda na sua máquina; nenhuma conta ou chave de API é necessária. Você precisa do Node.js 18 ou posterior (a versão LTS do nodejs.org). Com um Node.js mais antigo, os comandos zn-gate e zn param e explicam como instalá-lo. O plugin do Claude Code precisa do Node.js 20.12 ou posterior.

Começando: quatro passos, um comando cada. Execute-os no seu próprio terminal.

1. npx -y zn-gate reach mostra o que seus agentes de codificação podem acessar nesta máquina: segredos nos seus arquivos .env (apenas por nome), arquivos de credenciais e servidores MCP. É somente leitura e não envia nada. Detalhes em docs/reach.md.
2. npx -y zn-gate init configura a proteção para os agentes de codificação que encontrar, um passo de cada vez, e pergunta antes de cada alteração.
3. npx -y zn-gate check testa essa proteção com um segredo falso em uma pasta temporária. init também o executa no final.
4. npx -y zn-gate env shadow .env move os valores reais dos seus .env para o cofre local e deixa marcadores no arquivo. Na primeira vez, execute npx -y zn-gate unlock para criar o cofre.

Um comando para os agentes de codificação na sua máquina:

npx -y zn-gate init

Ele encontra Claude Code, Codex CLI, Cursor e OpenCode, mostra a configuração para cada um que ainda não está protegido (o plugin zn-gate para Claude Code, os hooks do zn para os outros), executa cada passo após você confirmar, e termina com zn-gate check. Execute você mesmo no seu próprio terminal, sem argumentos: quando um agente de IA ou um script o executa, ele apenas imprime os passos.

Windows PowerShell: npm e npx podem falhar com "running scripts is disabled on this system", porque a política de execução padrão bloqueia npm.ps1. Use npm.cmd, npx.cmd e zn.cmd em vez disso (por exemplo, npm.cmd install -g zn-gate), execute os comandos do Prompt de Comando, ou permita scripts locais para sua conta com Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Depois, mantenha os valores dos seus .env no cofre. Com o plugin ou os hooks, o agente não pode ler arquivos .env com valores reais; mova-os para o cofre criptografado do zn-gate, e o arquivo mantém marcadores como __ZN_STRIPE_KEY__:

npx -y zn-gate unlock            # creates the vault the first time
npx -y zn-gate env shadow .env

Depois disso, seu próprio aplicativo também lê os marcadores em .env: inicie-o com o comando run do zn-gate assim que você permitir (docs/secrets.md). env shadow explica como desfazer.

Passo a passo de cinco minutos: docs/secrets.md. Limites: docs/threat-model.md.

claude plugin marketplace add usezn/zn
claude plugin install zn-gate@usezn

npm install -g zn-gate
zn hooks install codex           # or: cursor, opencode

python3 -m venv .venv
.venv/bin/pip install zn-gate      # Windows: .venv\Scripts\pip install zn-gate

claude mcp add zn-gate -- npx -y zn-gate mcp     # Claude Code
codex mcp add zn-gate -- npx -y zn-gate mcp      # Codex CLI

npx -y zn-gate init --dry-run   # preview
npx -y zn-gate init --wrap-mcp  # wrap (backup first)
npx -y zn-gate init --revert    # undo

Verifique se funciona

npx -y zn-gate check

Para cada agente configurado para seu usuário, o zn-gate pede ao seu hook para permitir que o agente leia um arquivo .env com uma chave falsa e um arquivo comum, em uma pasta temporária. Ele mostra o que seu agente receberia, e uma linha que diz NOT protected explica como corrigir. Nada é enviado pela rede e nenhuma configuração é alterada. O que a saída significa.

npx -y zn-gate test

Isso executa o autoteste local (51 vetores curados: 26 ataques, 25 benignos) e mostra a latência por decisão na sua máquina. É um teste de fumaça, não uma taxa de detecção. Nada é enviado pela rede.

Para desenvolvedores: veja a redação manualmente. Envie uma saída de ferramenta com uma chave AWS falsa (o exemplo da documentação da AWS) e uma senha de banco de dados através do zn-gate, exatamente como seu agente faria, e procure por sanitized_content na saída; esse campo é o que o modelo veria:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_tool_result","arguments":{"tool_name":"read_file","content":"AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nDATABASE_URL=postgres://app:hunter2@db:5432/main"}}}' \
  | npx -y zn-gate@latest mcp

Equivalente em Python:

.venv/bin/python -c "from zn_gate import sanitize_tool_result as s; print(s('read_file', 'AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE')['sanitized_content'])"

O que cada parte faz

Onde o zn-gate se posiciona em uma chamada de ferramenta, como servidor MCP ou como proxy shield em torno de outros servidores:

Scrubber: segredos ficam fora do contexto do modelo

• Hoje, através do zn-gate: redige chaves AWS, chaves OpenAI e Anthropic, tokens GitHub, JWTs, chaves privadas e senhas em URLs de banco de dados em tudo que passa pelo zn-gate: saída de ferramenta verificada com check_tool_result, argumentos de ferramenta verificados com check_tool_call, e saída de servidores MCP envolvidos por zn-gate shield / init. Python: sanitize_tool_result, @guard(mask_secrets=True) e as integrações de framework.
• Hoje, hooks de agente e cofre (pacote npm): hooks para Claude Code, Codex CLI e OpenCode limpam a saída das ferramentas integradas dos agentes e bloqueiam segredos colados (no Cursor, apenas a saída de ferramentas MCP é limpa); um cofre criptografado local com marcadores estáveis (__ZN_AWS_KEY_1__); zn run preenche valores apenas em comandos que você aprovou; dados pessoais (cartões, IBAN, IDs nacionais, e-mail, telefone) também são detectados. O que cada agente permite difere: veja docs/compat.md.

Galvanize: detecção de injeção de prompt

• Hoje, local: um mecanismo de regras determinístico (assinaturas mais normalização contra homóglifos, caracteres de largura zero, overrides BiDi, splicing de comentários e Base64) verifica prompts, argumentos de ferramenta, saída de ferramenta e descrições de ferramentas MCP.
• Hoje, verificação opcional na nuvem: o classificador Galvanize 2 (pesos abertos no Hugging Face, Apache-2.0) também pode verificar prompts enviados a analyze_prompt, apenas se você definir ZN_CLOUD=1 e ZN_API_KEY. Os segredos que o zn-gate detecta são removidos do prompt na sua máquina antes do envio; dados pessoais não são removidos neste caminho.
• Roteiro: executar o Galvanize localmente dentro do zn-gate.

Scan: audite o que seu agente está prestes a confiar

• Hoje: zn-gate scan <path> audita modelos de prompt, arquivos AGENTS.md / SKILL.md e configurações para armadilhas de injeção e segredos vazados (código de saída 1 em achados, para CI). Um segredo vazado é relatado como Secret found, com o próximo passo: npx -y zn-gate env shadow <file> move os valores de um arquivo .env para o cofre local, npx -y zn-gate secret set NAME armazena qualquer outro. Ele encontra chaves e tokens de provedores, tokens opacos Authorization: Bearer, senhas em URLs e segredos passados como flags de linha de comando (--token=...) ou atribuídos a um nome como password ou api_key. A mesma verificação roda como uma GitHub Action. Servidores MCP podem ser verificados na web em usezn.com/scan.
• Roteiro: auditar servidores MCP e habilidades da CLI antes de adicioná-los.

O que a nuvem adiciona para equipes

Tudo acima roda localmente, gratuitamente, sem conta. A nuvem opcional em usezn.com é para equipes que precisam de um registro compartilhado do que seus agentes fizeram:

• Auditoria e rastreabilidade: um painel de evidências com os metadados de cada decisão na nuvem (veredito, regra, pontuação, latência), retenção de 90 dias e exportação CSV/JSONL.
• Um modelo de detecção maior para prompts, quando você optar por participar (ZN_CLOUD=1).
• Controles de equipe (políticas compartilhadas, auditoria em nível de organização): em andamento.

Por padrão, nada é enviado. Se você definir ZN_CLOUD=1 e uma chave de API (ou a opção de chave de API do plugin do Claude Code), analyze envia o texto do prompt após remover os segredos que o zn-gate detecta localmente: dados pessoais não são removidos neste caminho, e um segredo que ele não detecta seria enviado com o texto. O painel mantém os metadados de cada decisão na nuvem. Saída de ferramenta e argumentos de chamada de ferramenta nunca são enviados.

O que sai da sua máquina

Nada, por padrão.

ZN_API_KEY sozinho não habilita nada. ZN_LOCAL_ONLY=true substitui ZN_CLOUD=1. npx -y zn-gate status imprime o que sua configuração envia.

1.4.0 e anteriores: com ZN_API_KEY definido, o pacote Node enviava a saída da ferramenta e os argumentos de chamada da ferramenta para api.usezn.com sem redação. A versão 1.4.1 remove esse caminho. Detalhes no CHANGELOG.

Desempenho e precisão

Publicamos apenas números que podemos reproduzir, com o método ao lado deles.

• Latência do mecanismo local: uma tabela por tamanho de entrada, com hardware, data e o script para reproduzi-la (bench/bench_by_size.js), no README do pacote npm. Resumo curto dessa execução, com redação de segredos (p50): cerca de 0,045 ms para um prompt de 200 B, 0,3 ms para uma saída de ferramenta de 4 KB, cerca de 4 ms para 64 KB.
• Autoteste: 51 vetores selecionados passam. Isso é um teste de fumaça, não uma taxa de detecção ou de falsos positivos.
• Limitação conhecida: em arquivos de código-fonte inteiros, as regras podem sinalizar comentários de código comuns. A versão 1.5.0 reduz isso em código e documentação, ao custo de permitir que algumas tentativas de substituição com redação frouxa passem pelas regras locais. Para verificar em seus próprios arquivos de código-fonte, execute zn-gate scan --code <path>; para os servidores MCP que você envolve, --shadow registra detecções sem bloquear.
• Limitação conhecida: a detecção de credenciais sob nomes de variáveis com prefixo (por exemplo, OPENAI_API_KEY=) é parcial nesta versão.
• Taxas de detecção: em um conjunto privado retido de 3.309 exemplos, o Galvanize 2 tem recall de 83,4% com uma taxa de falsos positivos de 0,81% (limiar de serviço 0,662); esses números são para o classificador em nuvem, não para o mecanismo de regras local. Método, resultados por idioma, pontos fracos conhecidos e um benchmark reproduzível estão no model card e no anúncio. É uma camada de defesa, não uma garantia.

Configuração

zn Team: zn team join <token> conecta uma máquina à política de segredos assinada da sua organização e envia seu log de auditoria (somente metadados). O que a organização pode e não pode alterar na máquina, comportamento offline e a exportação OpenTelemetry (zn vault log export --otlp): docs/team.md.

Regras personalizadas: adicione padrões proibidos e caminhos bloqueados em .znrules ou zn.config.json na raiz do seu projeto (exemplo).

Log de auditoria: zn-gate shield anexa cada decisão a ~/.zn/evidence.jsonl como um registro com hash encadeado (SHA-256) com uma prévia redigida. Ele detecta edições acidentais ou parciais; não é à prova de adulteração contra alguém com acesso de gravação ao arquivo. Verifique com npx -y zn-gate evidence --verify.

GitHub Action

A action instala os pacotes publicados do zn-gate em uma versão exata e executa apenas no runner; não envia nada para lugar nenhum. Ela tem duas verificações, escolhidas com mode:

• scan (padrão): zn-gate scan procura armadilhas de injeção de prompt e segredos vazados em prompts, definições de ferramentas e arquivos de configuração (pacote Python do PyPI). Isso é o que versões anteriores da action faziam.
• audit: zn audit revisa o que seus agentes de codificação estão configurados para confiar: .claude/, .mcp.json, .codex/, .cursor/, hooks, AGENTS.md / CLAUDE.md, plugins e habilidades (pacote npm; requer versão 1.6.0 ou posterior).
• both: executa os dois. Com um version anterior a 1.6.0, ou uma versão .post apenas PyPI, ele executa apenas a verificação e imprime um aviso.

Verifique prompts em pull requests:

name: AI agent security scan

on:
  pull_request:
    paths:
      - 'prompts/**'
      - '**/*.prompt'
      - '**/AGENTS.md'
      - '**/SKILL.md'

permissions:
  contents: read

jobs:
  zn-gate-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Scan AI agent prompts and tools
        # Pin the action to a full commit SHA; the comment names the release.
        uses: usezn/zn@003a95ae7ef63c22b969496422131a49fa107f8d # v1.12.0
        with:
          version: '1.12.0'
          package-sha256: '9e7b7ac4a43722249c10623dcb5817c1cd956b6100d6ca02faa8b6451dd72dbf'
          path: '.'
          fail-on-threat: 'true'
          format: 'github'

Audite configurações de agentes e plugins em cada pull request e mostre os resultados no code scanning. A auditoria leva segundos, então o exemplo não tem filtro paths:: um filtro pularia as configurações de agentes que ele não lista.

name: AI agent config audit

on:
  pull_request:

permissions:
  contents: read

jobs:
  zn-gate-audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # only for the SARIF upload
      actions: read            # private repositories only, for upload-sarif
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Audit agent configs
        id: zn
        # Pin to the full commit SHA of the first Action release that has the
        # mode input. The zn-gate package version is set by version below.
        uses: usezn/zn@<commit-sha> # <first Action release with mode>
        with:
          version: '1.12.0'
          mode: 'both'
          format: 'sarif'
          severity-threshold: 'medium'   # stricter than the default (high)
      - name: Upload SARIF
        if: ${{ !cancelled() && steps.zn.outputs.sarif-file != '' }}
        uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
        with:
          sarif_file: ${{ steps.zn.outputs.sarif-file }}

A verificação encontra mais tipos de segredos a cada versão (1.9.1 adicionou segredos passados como flags de linha de comando e atribuídos a nomes como password ou api_key), então um job que falha em descobertas pode começar a falhar em arquivos que passavam antes: fixe version e leia as descobertas antes de atualizá-lo.

Versões mais antigas da action ignoram as entradas que não possuem, com apenas um aviso: com uma delas, mode: audit executa a verificação em vez disso.

Quais descobertas de auditoria falham o passo: fail-on se estiver definido; caso contrário, nenhuma quando fail-on-threat é false; caso contrário, severity-threshold. Para a verificação, apenas fail-on-threat se aplica.

Com mode: both e format: sarif, o arquivo contém uma execução SARIF por verificação (zn-gate scan e a própria execução da auditoria), cada uma com sua própria categoria, então o code scanning rastreia seus alertas separadamente. O passo falha com o pior dos dois resultados: um erro supera descobertas.

Permissões: a action em si precisa apenas de contents: read; adicione security-events: write ao job somente quando você enviar SARIF (e, em repositórios privados, actions: read, que upload-sarif precisa). Os pacotes são instalados sem executar scripts de instalação ou etapas de build (--only-binary=:all: --no-deps para a wheel, --ignore-scripts para o tarball npm, cujas dependências são empacotadas) em diretórios privados sob o diretório temporário do runner. O pip ainda lê as configurações do próprio runner (variáveis de ambiente PIP_* e pip.conf), então um espelho ou proxy que você configurar lá é usado; defina package-sha256 para que a wheel seja verificada independentemente do índice de onde vier (e npm-integrity para o tarball npm). Execute em pull_request, nunca em pull_request_target: não faça checkout de código de pull request não confiável em um workflow pull_request_target. Com mode: audit ou both, a action também configura Node.js 22 para o resto do job.

Estrutura do repositório

• packages/zn-gate: CLI Node.js, servidor MCP e proxy shield (npm).
• packages/zn-gate-py: SDK e CLI Python (PyPI).
• src/: gateway Rust legado, não publicado (docs/rust-core.md).
• bench/: scripts de benchmark e resultados.
• assets/brand/: arquivos de logotipo (SVG mestre e variantes claro/escuro, PNG lockup e banners).

FAQ

Preciso de uma conta ou chave de API? Não. Tudo local funciona sem uma. Uma conta é necessária apenas para a nuvem opcional (auditoria de equipe e o modelo de detecção maior).

O zn-gate deixa meu agente mais lento? A verificação local adiciona menos de um milissegundo para prompts e saídas de ferramentas típicos (p99 0,8 ms a 4 KB no nosso host de teste). Veja a tabela medida acima. Isso vai bloquear conteúdo legítimo? Às vezes. Use init --shadow ou shield --shadow para registrar detecções sem bloquear enquanto você avalia.

Quais agentes são suportados? Qualquer cliente MCP. init pode reescrever configurações para os agentes listados em Instalação.

Como faço para remover? npx -y zn-gate init --revert restaura suas configurações a partir do backup. Para um servidor autônomo, remova a entrada zn-gate da configuração do seu agente.

Segurança

Reporte vulnerabilidades para security@usezn.com. Política, escopo e porto seguro: SECURITY.md. Hall da Fama: usezn.com/security.

As versões publicadas pelo fluxo de trabalho de lançamento, começando pela primeira após 1.5.0-beta.1, são assinadas e possuem proveniência de build. As versões 1.5.0-beta.1 e anteriores foram publicadas manualmente e não possuem assinaturas nem proveniência. Para verificar um download: docs/verify-release.md.

Comunidade e suporte

• Discussões: perguntas sobre configuração e uso, ideias e demonstrações. Comece aqui se você não tiver certeza de onde sua pergunta se encaixa.
• Issues: bugs reproduzíveis e solicitações concretas de funcionalidades.
• Vulnerabilidades de segurança: não as publique em Discussões ou Issues. Reporte-as de forma privada conforme descrito em SECURITY.md.

Contribuindo

Issues e pull requests são bem-vindos. Veja CONTRIBUTING.md.

Licença

MIT. Copyright (c) 2026 usezn (usezn.com). Os pesos Galvanize 2 e Galvanize-60M são Apache-2.0. O conjunto de dados zn-prompt-injection-bench é CC-BY-4.0. O pacote npm inclui código de terceiros listado em THIRD_PARTY_NOTICES.md.