Saltar para o conteúdo principal
O ZeroPath se integra a agentes de codificação com IA para que o código passe por revisão de segurança no ponto de geração, antes mesmo de chegar a um commit, a um PR ou à produção. Agentes suportados:

​
Instalação

Um único instalador, do repositório ZeroPathAI/agent_install, detecta quais agentes estão presentes e configura todos eles:
O instalador solicita um token de API (crie um em Settings → API Tokens no dashboard do ZeroPath), ou você pode passá-lo de forma não interativa:
Flags úteis (após bash -s --): --agents claude,codex,cursor, --org-id, --base-url (ambientes self-hosted / de branch), --no-hooks, --no-mcp, --no-rules. Para desinstalar, execute o uninstall.sh do repositório da mesma forma. O que o instalador faz:
  1. Instala a CLI zeropath em ~/.zeropath/bin/ e armazena as credenciais em ~/.config/zeropath/credentials.json.
  2. Registra o servidor MCP do ZeroPath em cada agente detectado (executado via uvx; o instalador avisa se o uv estiver ausente).
  3. Instala os scripts de stop hook em ~/.zeropath/hooks/ e os registra nos agentes que suportam hooks.
  4. Adiciona os blocos de regras/orientação descritos abaixo.
  5. Grava as configurações padrão em ~/.zeropath/config.env (veja Configuração).

​
Como a integração funciona

A integração usa dois mecanismos deliberadamente diferentes.

​
  1. Ferramentas MCP — iniciadas pelo agente, ricas em contexto

Cada agente é configurado com o servidor MCP do ZeroPath, que expõe a API do ZeroPath como ferramentas que o próprio agente pode chamar — consultas a issues, gerenciamento de varreduras e, principalmente, as ferramentas de Varredura de Código Sob Demanda: O que torna essa superfície valiosa é o contexto: o agente sabe o que lhe foi pedido para construir, quais entradas são controladas por atacantes e quais suposições ele fez. O campo additionalContext da ferramenta submit (até 20 KiB) leva esse conhecimento para a varredura, onde o ZeroPath o trata como informação de contexto não confiável — não como instruções para o scanner. O instalador adiciona orientações para que os agentes realmente usem essas ferramentas (os arquivos de regras na tabela acima): escanear após mudanças não triviais, corrigir achados críticos/altos antes de declarar uma tarefa concluída e apresentar o restante ao usuário. A limitação é inerente: chamadas MCP acontecem a critério do modelo. Um agente sob um prompt enganoso — ou simplesmente preguiçoso — pode pular a varredura. É para isso que serve a segunda superfície.

​
  1. Stop hooks — determinísticos, aplicados pelo harness

Harnesses de agentes com hooks de ciclo de vida executam o stop hook do ZeroPath toda vez que o agente termina um turno, independentemente do que o modelo decidir. O hook (~/.zeropath/hooks/zeropath_hook.py):
Propriedades que vale a pena conhecer:
  • Fail open. Erros de rede, problemas de autenticação e timeouts de varredura nunca bloqueiam o agente; eles aparecem como um aviso e são registrados em log.
  • Sem varreduras redundantes. O SHA-256 do diff é armazenado em cache por workspace; um turno que não produziu mudanças de código não custa nada.
  • Loops de remediação limitados. O modo de bloqueio gasta um orçamento por sessão (padrão: 3 bloqueios). Um agente que não consegue corrigir um achado eventualmente para, e os achados são repassados ao usuário em vez de entrar em loop para sempre.
  • Controlados por severidade. Apenas achados no limiar configurado ou acima dele (padrão high) bloqueiam; tudo o que for encontrado ainda é reportado e registrado em log.
O suporte a hooks varia por agente: os Stop hooks do Claude Code podem bloquear (loop completo de remediação); os stop hooks do Cursor são observacionais; o Codex não tem mecanismo de hooks multiplataforma e depende inteiramente da superfície MCP mais a orientação do AGENTS.md.
As varreduras disparadas por essas integrações são Varreduras de Código Sob Demanda: elas analisam apenas o diff/arquivos enviados (limites: 256 KiB de código, 20 arquivos/trechos, 20 KiB de contexto adicional), executam de forma assíncrona (tipicamente dezenas de segundos) e os resultados expiram após 7 dias. Com target.kind: "auto" e uma URL de remote Git, o ZeroPath resolve o workspace para um repositório vinculado e enriquece a análise com o contexto persistido de repositório, aplicação e modelo de ameaças. Elas complementam — não substituem — as varreduras completas de repositório e a varredura de PRs.

​
Verificando a configuração

  • Claude Code: execute /mcp — um servidor zeropath deve aparecer listado e conectado. claude --debug mostra o Stop hook disparando ao final de um turno.
  • Codex: execute /mcp na TUI do Codex, ou verifique se há um bloco [mcp_servers.zeropath] em ~/.codex/config.toml.
  • Cursor: abra Settings → MCP — zeropath deve aparecer listado com suas ferramentas.
  • De ponta a ponta: peça ao agente para “escanear minhas alterações não commitadas com o ZeroPath”, ou execute a mesma varredura que o hook executa:

​
Telemetria: o caller agent

As varreduras enviadas por essas integrações são marcadas com metadata.caller = "agent" (hooks) ou "mcp" (chamadas MCP iniciadas pelo agente), para que você possa distinguir varreduras no ponto de geração do uso via CLI, IDE e pre-commit ao revisar a atividade de varredura.