> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contexto de Repositório vs. Regras Personalizadas

> Duas superfícies de linguagem natural no ZeroPath — uma ensina ao scanner o que já é verdade no seu código, a outra define novas políticas que ele deve aplicar. Use as duas em conjunto.

O ZeroPath oferece duas superfícies de linguagem natural para ajustar os scans: **[Contexto de Repositório](/pt/platform/repo-context)** e **[Regras Personalizadas](/pt/platform/custom-rules)**. 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.

<Columns cols={2}>
  <Card title="Contexto de Repositório" icon="book-open-cover" href="/pt/platform/repo-context">
    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.**
  </Card>

  <Card title="Regras Personalizadas" icon="shield-check" href="/pt/platform/custom-rules">
    Políticas de segurança em linguagem natural que o ZeroPath avalia durante os scans nos
    repositórios selecionados. **Gera novos achados quando violadas.**
  </Card>
</Columns>

<Tip>
  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."*
</Tip>

<h2 id="at-a-glance">
  Visão rápida
</h2>

| Dimensão                          | Contexto de Repositório                                                | Regras Personalizadas                                                                       |
| --------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Propósito**                     | Reduzir falsos positivos, ensinar sua arquitetura ao ZeroPath          | Aplicar políticas de segurança específicas da organização, cobrir lacunas do SAST integrado |
| **Formulação**                    | Declarativa — fatos sobre o seu stack                                  | Imperativa — políticas que devem valer                                                      |
| **Efeito nos achados**            | Refina achados existentes; reduz o ruído                               | Gera novos achados junto aos resultados de SAST                                             |
| **Visibilidade para engenheiros** | Melhoria invisível — menos alarmes falsos em PRs                       | Achados visíveis com severidade, confiança, arquivo e remediação                            |
| **Modelo mental**                 | "Documento de onboarding para o ZeroPath"                              | "Linter para políticas de segurança"                                                        |
| **Melhor porta de entrada**       | **Generate & Save Context** em um clique a partir de um falso positivo | Explore os **Rule Packs** e depois escreva regras personalizadas para as lacunas            |

<h2 id="when-to-use-each">
  Quando usar cada uma
</h2>

<Tabs>
  <Tab title="Recorra ao Contexto de Repositório">
    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."*

    <Warning>
      **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.
    </Warning>
  </Tab>

  <Tab title="Recorra às Regras Personalizadas">
    Use Regras Personalizadas quando você tem uma política específica da organização que o SAST
    integrado não aplica.

    **Sinais de gatilho**

    * Sua organização tem políticas de segurança não cobertas pelo SAST integrado
    * Frameworks de conformidade (PCI, HIPAA, SOC 2) exigem aplicação no nível do código
    * Você quer padrões internos de codificação aplicados de forma consistente entre repositórios
    * Padrões idiomáticos específicos do seu stack precisam de uma verificação dedicada

    **Exemplos típicos**

    * *"Sinalize qualquer endpoint de API que retorne endereços de e-mail de usuários sem que o chamador tenha escopo de admin."*
    * *"Encontre instruções de log que incluam corpos de requisição que possam conter senhas ou tokens."*
    * *"Todas as consultas ao banco de dados devem usar consultas parametrizadas em vez de concatenação de strings."*

    <Warning>
      Evite duplicar verificações do SAST integrado, agrupar várias preocupações não relacionadas em
      uma única regra ou escrever regras vagas como *"APIs devem ser seguras."* Regras vagas não dão
      ao ZeroPath nada concreto para aplicar.
    </Warning>
  </Tab>
</Tabs>

<h2 id="targeting-and-scope">
  Direcionamento e escopo
</h2>

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.

<h3 id="shared-scope-cascade">
  Compartilhado: cascata de escopo
</h3>

Os dois recursos seguem o mesmo modelo de herança **org → tag → repo** das [configurações do scanner](/pt/platform/scanner-settings).

| Escopo           | Aplica-se a                                                           |
| ---------------- | --------------------------------------------------------------------- |
| **Organization** | Todos os repositórios da organização, incluindo os adicionados depois |
| **Tag**          | Todos os repositórios com a(s) tag(s) selecionada(s)                  |
| **Repository**   | Apenas o repositório ou os repositórios selecionados                  |

<Info>
  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.
</Info>

<h3 id="shared-file-level-glob">
  Compartilhado: glob no nível de arquivo
</h3>

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

| Padrão               | Corresponde a                                 |
| -------------------- | --------------------------------------------- |
| `**`                 | Todos os arquivos (padrão)                    |
| `src/api/**`         | Todos os arquivos sob `src/api/`              |
| `**/*.controller.ts` | Todos os arquivos de controller em TypeScript |
| `services/auth/**`   | Todos os arquivos no serviço de auth          |

<h3 id="context-only-scan-phases-and-input-types">
  Apenas Contexto: fases de scan e tipos de entrada
</h3>

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.

<AccordionGroup>
  <Accordion title="Fases de scan (apenas Contexto)">
    Seis fases são selecionáveis em **Advanced Settings** ao criar uma entrada de contexto:

    | Fase                            | O que o ZeroPath está fazendo                                                           |
    | ------------------------------- | --------------------------------------------------------------------------------------- |
    | **Application identification**  | Entendendo o que seu código faz — serviços, módulos, pontos de entrada                  |
    | **Source identification**       | Encontrando onde dados não confiáveis entram na sua aplicação                           |
    | **Sink identification**         | Encontrando para onde os dados fluem em operações sensíveis                             |
    | **Vulnerability investigation** | Avaliando se problemas potenciais são vulnerabilidades reais e exploráveis              |
    | **Logic analysis**              | Analisando a lógica de negócio em busca de problemas além dos padrões de código típicos |
    | **Custom rule evaluation**      | Avaliando suas regras personalizadas contra o código                                    |

    Se não tiver certeza de qual selecionar, deixe todas as fases habilitadas — o ZeroPath aplica seu
    contexto onde ele for relevante.
  </Accordion>

  <Accordion title="Tipos de entrada (apenas Contexto)">
    Oito tipos de entrada são selecionáveis em **Advanced Settings**:

    | Tipo de entrada   | Descrição                                                             |
    | ----------------- | --------------------------------------------------------------------- |
    | **HTTP Handler**  | Endpoints de API web e handlers de requisições HTTP                   |
    | **File Handler**  | Upload de arquivos e processamento de entrada do sistema de arquivos  |
    | **Stdin Handler** | Entrada por stdin e pipes na linha de comando                         |
    | **Browser Data**  | Entrada do navegador no lado do cliente (cookies, local storage, DOM) |
    | **WebSocket**     | Handlers de mensagens WebSocket                                       |
    | **Socket**        | Conexões brutas de socket TCP/UDP                                     |
    | **CLI Argument**  | Argumentos e flags de linha de comando                                |
    | **Mobile Inputs** | Entrada de usuário em aplicações móveis                               |

    Todos os tipos de entrada vêm selecionados por padrão. Desmarque os que não forem relevantes para
    restringir o escopo.
  </Accordion>
</AccordionGroup>

<h2 id="how-they-work-together">
  Como funcionam em conjunto
</h2>

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.

<h3 id="worked-example-enforcing-auth-on-pii-endpoints">
  Exemplo prático: exigindo auth em endpoints com PII
</h3>

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Regra Personalizada com escopo de organização">
    Declare a política.

    > *Todos os endpoints que expõem PII devem exigir autenticação.*
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

<h2 id="lifecycle-and-management">
  Ciclo de vida e gerenciamento
</h2>

<Tabs>
  <Tab title="Contexto de Repositório">
    **Onde gerenciar:** página [Context](https://zeropath.com/app/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.
  </Tab>

  <Tab title="Regras Personalizadas">
    **Onde gerenciar:** página [Rules](https://zeropath.com/app/rules) → aba **Custom Rules**. A aba
    irmã **Rule Packs** expõe pacotes curados publicados pelo ZeroPath que você pode habilitar sem
    precisar escrever nada.

    **Formas de criação**

    * Criação manual no painel
    * Habilitar **Rule Packs** — sem necessidade de autoria
    * API v2 para gerenciamento programático

    **Edição e exclusão**

    * Atualize o nome, a descrição, o texto da regra ou o escopo
    * Alterne entre `allRepositories` e `repositoryIds` específicos (mutuamente exclusivos na mesma
      requisição)
    * Exclua regras que não são mais necessárias

    **Cadência de revisão:** trimestral, ou após mudanças arquiteturais importantes. Refine as
    regras à medida que você observa quais achados são acionáveis vs. ruído.
  </Tab>
</Tabs>

<Warning>
  **Modo Custom Rules Only** — o toggle **Custom rules only** nas [configurações do
  scanner](/pt/platform/scanner-settings) 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.
</Warning>

<h2 id="pitfalls-to-avoid">
  Armadilhas a evitar
</h2>

<AccordionGroup>
  <Accordion title="Contexto amplo demais que suprime achados silenciosamente">
    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.
  </Accordion>

  <Accordion title="Regras vagas que produzem ruído">
    *"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.
  </Accordion>

  <Accordion title="Usar contexto para mascarar achados em vez de declarar fatos">
    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.
  </Accordion>

  <Accordion title="Regras sem contexto de apoio">
    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.
  </Accordion>

  <Accordion title="Deixar todos os tipos de entrada e fases habilitados por padrão">
    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.
  </Accordion>
</AccordionGroup>

<h2 id="suggested-rollout">
  Implantação sugerida
</h2>

<Steps>
  <Step title="Semana 1 — Linha de base">
    Conecte os repositórios, execute scans completos e habilite os [**Rule
    Packs**](https://zeropath.com/app/rules?tab=packs) relevantes. Nenhum trabalho personalizado
    ainda — deixe a linha de base revelar onde está o ruído.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<h2 id="quick-reference">
  Referência rápida
</h2>

| Situação                                                               | Use                     |
| ---------------------------------------------------------------------- | ----------------------- |
| O mesmo falso positivo continua aparecendo                             | Contexto de Repositório |
| Serviço exclusivamente interno sinalizado como público                 | Contexto de Repositório |
| Wrapper ou helper seguro não reconhecido                               | Contexto de Repositório |
| Fato arquitetural que todo engenheiro conhece, mas o código não mostra | Contexto de Repositório |
| Política de conformidade precisa de aplicação no nível do código       | Regra Personalizada     |
| Padrão de codificação da organização a ser aplicado                    | Regra Personalizada     |
| O SAST integrado não detecta um padrão específico do seu stack         | Regra Personalizada     |
| Precisa aplicar uma política **e** ensinar ao ZeroPath como é o seguro | Ambos, em conjunto      |

<Columns cols={2}>
  <Card title="Documentação de Contexto de Repositório" icon="arrow-right" href="/pt/platform/repo-context">
    Eixos de direcionamento, fluxo de falsos positivos, herança de escopo e boas práticas.
  </Card>

  <Card title="Documentação de Regras Personalizadas" icon="arrow-right" href="/pt/platform/custom-rules">
    Autoria de regras, a API v2, os Rule Packs e o modo Custom Rules Only.
  </Card>
</Columns>