Saltar para o conteúdo principal

Visão Geral

O contexto de repositório permite fornecer à ZeroPath informações sobre sua base de código que ela não consegue inferir apenas a partir do código. São descrições em linguagem natural que a ZeroPath leva em conta em sua análise durante os scans. Por exemplo, você pode informar à ZeroPath que um determinado endpoint fica atrás de um gateway de autenticação, que uma função aparentemente perigosa só é executada em desenvolvimento, ou que um módulo específico lida com entrada já sanitizada. Esse conhecimento adicional ajuda a tomar decisões mais precisas e reduz significativamente os falsos positivos.

Por Que Usar o Contexto de Repositório

Reduza falsos positivos

Elimine falsos alarmes recorrentes fornecendo à ZeroPath o conhecimento de domínio necessário para entender sua arquitetura.

Melhore a precisão

Contexto sobre camadas de autenticação, validação de entrada e fronteiras de implantação ajuda a ZeroPath a focar nos riscos reais.

Adapte ao seu stack

Direcione o contexto a arquivos, fases de scan e tipos de entrada específicos para que ele se aplique exatamente onde importa.

Criando Contexto de Repositório

Pelo Dashboard

  1. Navegue até Settings → Repository context, no grupo Scanner das configurações.
  2. Clique em Add Context. Você precisa de permissão para criar contexto no escopo selecionado.
  3. Opcionalmente, insira um título — um rótulo curto (até 120 caracteres) que identifica a regra de contexto na lista. Se você deixá-lo em branco, a lista de contextos exibe uma prévia do corpo do contexto.
  4. Escreva uma descrição em linguagem natural do que a ZeroPath deve saber. Por exemplo:
    • “Todos os endpoints deste serviço exigem autenticação JWT via API gateway — acesso não autenticado não é possível.”
    • “A chamada eval() em src/sandbox/ é executada dentro de um contêiner Docker restrito, sem acesso à rede.”
    • “O rate limiting é aplicado no nível do load balancer para todas as rotas voltadas ao público.”
  5. Opcionalmente, defina um escopo de arquivos usando um padrão glob (por exemplo, src/api/**, *.py) para limitar o contexto a arquivos específicos. O padrão é todos os arquivos.
  6. Em Repositories, escolha Apply to all repositories, Select specific repositories ou Apply to selected tags. O escopo para todos os repositórios ou por tags exige permissão em todos os repositórios.
  7. Opcionalmente, expanda Advanced Settings para configurar a quais fases de scan o contexto se aplica. Para configurar tipos de fonte, use a API ou o MCP. Consulte Direcionamento abaixo para mais detalhes.
  8. Expanda Tags para selecionar tags. O contexto também se aplica aos repositórios associados a elas. O escopo por tags exige pelo menos uma tag.
  9. Salve o contexto. As alterações entram em vigor no próximo scan.

A Partir de um Falso Positivo

Use a triagem para identificar fatos que o scanner deve considerar em scans futuros.
  1. Ao encerrar um achado como False positive, registre por que ele não se aplica. Sua equipe pode exigir um motivo.
  2. Se o mesmo fato for relevante para outros achados, abra Settings → Repository context e escolha Add Context.
  3. Descreva o fato que você verificou e limite o contexto aos repositórios, arquivos e fases de scan relevantes. O contexto passa a valer no próximo scan.

Direcionando o Contexto

O contexto de repositório suporta três eixos de direcionamento que controlam quando e onde ele é aplicado. Quanto mais preciso o direcionamento, mais eficaz é o contexto.

Padrões de Arquivo

Use padrões glob para limitar a quais arquivos o contexto se aplica. O padrão é **, que corresponde a todos os arquivos.

Fases de Scan

Escolha quais estágios da análise da ZeroPath devem ver este contexto. Por padrão, todas as fases estão selecionadas. Selecione fases específicas quando seu contexto for relevante apenas para um tipo particular de análise. No dashboard, elas aparecem como caixas de seleção em Advanced Settings. O pipeline de scan da ZeroPath passa por várias fases. Ao criar um contexto, você pode selecionar uma ou mais delas para controlar quando seu contexto é aplicado:
Se você não tem certeza de qual fase selecionar, deixe todas as fases habilitadas. A ZeroPath aplicará seu contexto onde ele for relevante.

Tipos de Entrada

Limite o contexto a tipos específicos de pontos de entrada de dados. Isso é útil quando seu contexto se aplica apenas a certos tipos de tratamento de entrada. No dashboard, eles aparecem como caixas de seleção em Advanced Settings: Ao criar uma nova entrada de contexto, todos os tipos de entrada estão selecionados por padrão. Desmarque os que não forem relevantes para restringir o escopo.

Escopo do Contexto

O contexto pode ter escopo em três níveis, seguindo o mesmo modelo de herança das configurações do scanner: O contexto com escopo de organização se aplica automaticamente a repositórios recém-adicionados, sem nenhuma atualização manual. As regras de contexto se acumulam entre os níveis — um repositório recebe seu próprio contexto mais qualquer contexto de nível de tag e de organização que se aplique a ele. Escopos mais específicos não substituem os mais amplos.

Gerenciando o Contexto

Na página Repository context você pode:
  • Visualizar todas as regras de contexto da sua organização em uma tabela que mostra o título (ou uma prévia do corpo do contexto, se nenhum título foi definido), o padrão de arquivos, as tags atribuídas e o escopo de repositórios. Regras de contexto que se aplicam a todos os repositórios exibem “All Repositories” em vez de uma contagem.
  • Editar qualquer regra de contexto clicando na sua linha — atualize o texto, o direcionamento ou o escopo.
  • Excluir regras de contexto individualmente ou em massa. Excluir uma entrada de contexto exige confirmação para evitar remoções acidentais.

Boas Práticas

  1. Seja específico e factual — “Os endpoints /admin exigem certificados de cliente mTLS aplicados pelo ingress Nginx” é melhor que “admin é seguro”. Quanto mais concreto o seu contexto, melhor a ZeroPath consegue usá-lo.
  2. Registre fatos da triagem que podem ser reutilizados. Se vários achados partirem da mesma premissa incorreta, adicione como contexto o detalhe de arquitetura ou implantação que você verificou.
  3. Direcione de forma restrita — aplique o contexto a padrões de arquivo, fases de scan e tipos de entrada específicos em vez de deixar tudo no padrão. Um direcionamento restrito evita que contexto irrelevante adicione ruído.
  4. Use tags para arquitetura compartilhada — se vários repositórios compartilham o mesmo gateway de autenticação ou padrão de infraestrutura, crie uma única regra de contexto com escopo de tag em vez de duplicá-la por repositório.
  5. Revise periodicamente — à medida que sua base de código evolui, revisite as regras de contexto para garantir que ainda refletem a realidade. Contexto desatualizado pode fazer a ZeroPath deixar passar problemas reais.