Arquitetura

Como o zn-gate é construído. Três pontos de controle em torno de cada ação do agente e os princípios por trás deles.

O zn-gate é um pequeno ponto de controle que roda na sua máquina, entre o seu agente de código e tudo o que ele lê e executa. Ele olha três momentos de cada ação e não atrapalha no resto do tempo. Esta página explica a estrutura e os princípios por trás dela. Para ver as peças em detalhe, consulte Como o zn-gate funciona.

Três pontos de controle

Etapa	Ponto de controle	Quando	O que faz
1	`analyze_prompt`	Antes de o agente agir sobre um prompt ou um conteúdo	Procura injeção de prompt, jailbreaks e segredos colados no texto
2	`check_tool_call`	Antes de uma ferramenta rodar	Verifica os argumentos em busca de injeção, padrões de exfiltração e caminhos sensíveis. Uma chamada bloqueada nunca chega à ferramenta. Os segredos nos argumentos são mascarados
3	`check_tool_result`	Depois que a ferramenta roda e antes de o modelo ler a saída	Oculta os segredos e neutraliza a injeção de prompt indireta. Um resultado que traz uma injeção é substituído por um aviso curto

Cada ponto de controle responde allow ou block e informa a rule e o reason que decidiram. As mesmas três verificações funcionam em cada forma de configurar o zn-gate: hooks do agente, o servidor MCP ou zn-gate shield na frente dos seus outros servidores MCP. As configurações e o que cada uma cobre estão em Como o zn-gate funciona.

Princípios

Poucas dependências. O pacote Python usa apenas a biblioteca padrão. O pacote npm tem uma única dependência em tempo de execução, age-encryption (com as bibliotecas @noble e @scure), que criptografa o cofre de segredos. Ela vem embutida no pacote nas versões fixadas em package-lock.json, e nada é compilado na sua máquina.
Primeiro local e previsível. As verificações rodam na sua máquina com regras fixas: correspondência de padrões mais normalização de caracteres parecidos, caracteres de largura zero e texto codificado. A mesma entrada dá a mesma resposta, e cada resposta informa a sua regra. Os últimos 2.048 resultados ficam em cache, então um texto repetido é verificado uma só vez. Os tempos medidos estão na página de Desempenho.
Uma segunda opinião opcional da nuvem. Só a análise de prompts pode consultar o classificador na nuvem, e só depois que você ativa: defina ZN_API_KEY e ZN_CLOUD=1, ou rode zn-gate connect. ZN_LOCAL_ONLY=true desativa de novo. O texto que as regras locais já bloqueiam nunca é enviado, e os segredos do texto são removidos na sua máquina antes de enviar qualquer coisa (dados pessoais não). Argumentos de ferramentas, saída de ferramentas e descrições de ferramentas nunca saem da sua máquina, em nenhuma configuração. Detalhes: O que sai da sua máquina.
Um registro local que revela alterações. Cada decisão registrada pelo zn-gate shield e pelos SDKs é adicionada a ~/.zn/evidence.jsonl com um hash SHA-256 que a liga à anterior, com uma prévia ocultada e nunca o segredo. zn-gate evidence --verify confere a cadeia. Ela detecta edições acidentais ou parciais, mas não protege contra quem consegue escrever no arquivo, porque essa pessoa pode recalculá-la. Veja Evidências.

O que esta estrutura não faz

É uma fronteira, não todo o seu modelo de segurança. Mantenha escopos mínimos nas ferramentas e revisão humana para ações de alto impacto.
O que os pontos de controle enxergam depende de como o zn-gate está configurado e do agente. Um servidor MCP sozinho só vê as chamadas que o seu agente decide enviar a ele. Os hooks cobrem também as ferramentas internas do agente, na medida em que cada agente permite. Veja o Modelo de ameaças.
As regras locais não são um classificador semântico: ataques reescritos com outras palavras podem passar.