Saltar para o conteúdo principal
O ZeroPath oferece duas superfícies de linguagem natural para ajustar os scans: Contexto de Repositório e Regras Personalizadas. Elas parecem semelhantes, mas fazem trabalhos diferentes, e a maior parte do valor vem de usá-las em conjunto. Esta página é uma referência lado a lado para escolher entre elas.

Contexto de Repositório

Uma camada de conhecimento em linguagem natural que informa ao ZeroPath coisas sobre o seu código que ele não consegue inferir apenas do código. Refina achados existentes — reduz falsos positivos.

Regras Personalizadas

Políticas de segurança em linguagem natural que o ZeroPath avalia durante os scans nos repositórios selecionados. Gera novos achados quando violadas.
Declarativo vs. imperativo é a divisão mental mais limpa. O contexto diz “X já é verdade no nosso stack.” As regras dizem “X deve sempre valer; sinalize qualquer violação.”

​
Visão rápida

​
Quando usar cada uma

Use o Contexto de Repositório quando o ZeroPath estiver produzindo ruído sobre padrões que na verdade são seguros no seu código — fatos que o próprio código não consegue revelar.Sinais de gatilho
  • O mesmo falso positivo continua reaparecendo entre scans
  • Achados em caminhos exclusivamente internos ou de desenvolvimento que não são alcançáveis externamente
  • O código usa wrappers seguros, sanitizadores ou middleware que o ZeroPath não consegue reconhecer
  • Fatos arquiteturais ocultos do código (gateways, ingress, middleware, sandboxes de runtime)
Exemplos típicos
  • “Todos os endpoints deste serviço ficam atrás de um gateway JWT — acesso anônimo não é possível.”
  • “A chamada eval() em src/sandbox/ roda dentro de um contêiner Docker restrito, sem acesso à rede.”
  • “O rate limiting é aplicado no balanceador de carga para todas as rotas voltadas ao público.”
Não use o Contexto de Repositório para suprimir um achado que você simplesmente não quer corrigir, nem para encobrir uma detecção ausente. Contexto amplo demais — por exemplo, afirmar a aplicação de JWT em toda a organização quando um repositório permite endpoints anônimos — oculta achados reais silenciosamente.

​
Direcionamento e escopo

Os dois recursos suportam a mesma cascata de escopo em três níveis e o escopo de arquivos baseado em glob, mas apenas o Contexto de Repositório permite direcionar fases de scan e tipos de entrada individuais.

​
Compartilhado: cascata de escopo

Os dois recursos seguem o mesmo modelo de herança org → tag → repo das configurações do scanner.
Os escopos se acumulam — um repositório recebe suas próprias entradas mais as entradas de nível de tag e de organização que se aplicam a ele. Escopos mais específicos nunca substituem os mais amplos.

​
Compartilhado: glob no nível de arquivo

Os dois recursos aceitam um padrão glob para limitar a quais arquivos se aplicam. O padrão é todos os arquivos.

​
Apenas Contexto: fases de scan e tipos de entrada

O Contexto de Repositório tem duas dimensões extras de direcionamento — úteis quando um fato só é relevante para um tipo específico de análise. Regras personalizadas são sempre avaliadas na fase de regras em linguagem natural contra as fontes identificadas, então elas não expõem seleção de fase.
Seis fases são selecionáveis em Advanced Settings ao criar uma entrada de contexto:Se não tiver certeza de qual selecionar, deixe todas as fases habilitadas — o ZeroPath aplica seu contexto onde ele for relevante.
Oito tipos de entrada são selecionáveis em Advanced Settings:Todos os tipos de entrada vêm selecionados por padrão. Desmarque os que não forem relevantes para restringir o escopo.

​
Como funcionam em conjunto

Contexto e Regras Personalizadas são mais úteis em combinação. Sem contexto, uma regra que diz “deve verificar auth” não tem ideia de como é uma verificação de auth no seu stack. Sem regras, o contexto apenas reduz o ruído nas detecções integradas — ele não consegue aplicar as suas próprias políticas.

​
Exemplo prático: exigindo auth em endpoints com PII

1

Contexto de Repositório no nível da organização

Defina o que “autenticado” significa em toda a organização.
Autenticação = uma requisição que carrega um JWT válido validado pelo middleware requireAuth(), ou apresenta um certificado de cliente mTLS no ingress.
2

Contexto de Repositório no nível do repositório (ex.: payments-api)

Defina o que “PII” significa neste repositório.
Os campos de PII incluem card_last4, billing_email, customer_phone.
3

Regra Personalizada com escopo de organização

Declare a política.
Todos os endpoints que expõem PII devem exigir autenticação.
4

Resultado

O ZeroPath agora sinaliza apenas endpoints que lidam com campos de PII e contornam um dos dois mecanismos de auth reconhecidos. Endpoints atrás de requireAuth() ou mTLS são corretamente tratados como seguros; todo o resto aparece como um achado de alto sinal.
Sem as entradas de contexto, a mesma regra produziria achados de menor confiança em todos os lugares em que o modelo não tivesse certeza de como seu stack lida com autenticação ou do que conta como PII. Parear regras com contexto é o que torna os achados acionáveis.

​
Ciclo de vida e gerenciamento

Onde gerenciar: página Context no painel. Visão em tabela com título (ou prévia do corpo), padrão de arquivo, tags e escopo de repositório.Formas de criação
  • Criação manual no painel
  • Generate & Save Context em um clique a partir de qualquer falso positivo — sem etapa de revisão, tem efeito no próximo scan
Edição e exclusão
  • Clique em uma linha para editar o texto, o direcionamento ou o escopo
  • Exclusão individual ou em massa, com confirmação
  • As alterações têm efeito no próximo scan
Cadência de revisão: trimestral. A arquitetura muda; contexto desatualizado pode ocultar problemas reais. Exclua entradas que não refletem mais a realidade.
Modo Custom Rules Only — o toggle Custom rules only nas configurações do scanner desabilita todos os módulos de scan integrados (SAST, SCA, IaC, Secrets, EOL) e avalia apenas as suas regras em linguagem natural. Raramente é a escolha certa; habilite apenas quando você intencionalmente quiser que o ZeroPath rode como um motor puro de regras personalizadas.

​
Armadilhas a evitar

O erro mais perigoso de todos. Dizer “todos os endpoints exigem JWT” no escopo da organização só é aceitável se for literalmente verdade em todos os lugares. Basta um serviço legado com um endpoint anônimo e você acabou de ensinar o ZeroPath a ignorar um achado real. Comece restrito; amplie apenas quando a afirmação for comprovadamente verdadeira no escopo mais amplo.
“APIs devem ser seguras” não é aplicável. Regras precisam de uma asserção concreta e testável: um comportamento específico que vale ou não vale. Se você não consegue descrever como um revisor verificaria a regra manualmente, o ZeroPath também não consegue aplicá-la de forma consistente.
Contexto é para fatos que são verdadeiros no seu código, não para esconder achados que você não quer triar. Se a afirmação subjacente não for verdadeira, a entrada acabará ocultando um bug real.
Regras isoladas produzem achados, mas o ZeroPath precisa adivinhar o que “verificação de auth” ou “entrada sanitizada” significa no seu stack. Paree toda regra não trivial com o contexto de que ela precisa para reconhecer o padrão seguro.
O direcionamento padrão é intencionalmente permissivo. Quando você sabe que uma entrada de contexto se aplica apenas a handlers HTTP durante a identificação de fontes, restrinja-a. Direcionamento amplo demais faz contexto irrelevante vazar para análises não relacionadas.

​
Implantação sugerida

1

Semana 1 — Linha de base

Conecte os repositórios, execute scans completos e habilite os Rule Packs relevantes. Nenhum trabalho personalizado ainda — deixe a linha de base revelar onde está o ruído.
2

Semana 2 — Converta a triagem em contexto

Para cada falso positivo, use o fluxo de um clique Generate & Save Context. Busque converter cerca de 80% dos FPs em entradas de contexto. Esta é a etapa de maior ROI.
3

Semana 3 — Escreva regras para as lacunas de política

Identifique políticas específicas da organização não cobertas pelo SAST integrado nem pelos Rule Packs. Escreva de 3 a 5 regras personalizadas. Para cada uma, adicione as entradas de contexto de apoio que descrevem os padrões seguros que a regra deve reconhecer.
4

Semana 4 — Marque, revise e assuma a responsabilidade

Marque regras e entradas de contexto por equipe ou framework de conformidade. Atribua um responsável pela revisão trimestral para que as entradas não fiquem obsoletas conforme o código evolui.

​
Referência rápida

Documentação de Contexto de Repositório

Eixos de direcionamento, fluxo de falsos positivos, herança de escopo e boas práticas.

Documentação de Regras Personalizadas

Autoria de regras, a API v2, os Rule Packs e o modo Custom Rules Only.