> ## 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.

# Repository Context vs. Custom Rules

> Two natural-language surfaces in ZeroPath — one teaches the scanner what is already true in your codebase, the other defines new policies it must enforce. Use them together.

ZeroPath gives you two natural-language surfaces for tuning scans: **[Repository Context](/platform/repo-context)** and **[Custom Rules](/platform/custom-rules)**. They sound similar but do different jobs, and most of the value comes from using them together. This page is a side-by-side reference for choosing between them.

<Columns cols={2}>
  <Card title="Repository Context" icon="book-open-cover" href="/platform/repo-context">
    A natural-language knowledge layer that tells ZeroPath things about your codebase it cannot
    infer from code alone. **Refines existing findings — reduces false positives.**
  </Card>

  <Card title="Custom Rules" icon="shield-check" href="/platform/custom-rules">
    Natural-language security policies ZeroPath evaluates during scans across your selected
    repositories. **Generates new findings when violated.**
  </Card>
</Columns>

<Tip>
  Declarative vs. imperative is the cleanest mental split. Context says *"X is already true in our
  stack."* Rules say *"X must always hold; flag any violation."*
</Tip>

## At a glance

| Dimension                   | Repository Context                                          | Custom Rules                                                      |
| --------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------- |
| **Purpose**                 | Reduce false positives, teach ZeroPath your architecture    | Enforce org-specific security policy, cover gaps in built-in SAST |
| **Phrasing**                | Declarative — facts about your stack                        | Imperative — policies that must hold                              |
| **Effect on findings**      | Refines existing findings; reduces noise                    | Generates new findings alongside SAST results                     |
| **Visibility to engineers** | Invisible improvement — fewer false alarms in PRs           | Visible findings with severity, confidence, file, and remediation |
| **Mental model**            | "Onboarding doc for ZeroPath"                               | "Linter for security policy"                                      |
| **Best entry point**        | One-click **Generate & Save Context** from a false positive | Browse **Rule Packs**, then author custom rules for gaps          |

## When to use each

<Tabs>
  <Tab title="Reach for Repository Context">
    Use Repository Context when ZeroPath is producing noise on patterns that are actually safe in
    your codebase — facts the code itself cannot reveal.

    **Trigger signals**

    * The same false positive keeps reappearing across scans
    * Findings on internal-only or dev-only paths that are not externally reachable
    * Code uses safe wrappers, sanitizers, or middleware that ZeroPath cannot recognize
    * Architectural facts hidden from the code (gateways, ingress, middleware, runtime sandboxes)

    **Typical examples**

    * *"All endpoints in this service sit behind a JWT gateway — anonymous access is not possible."*
    * *"The `eval()` call in `src/sandbox/` runs inside a restricted Docker container with no network access."*
    * *"Rate limiting is enforced at the load balancer for all public-facing routes."*

    <Warning>
      Do **not** use Repository Context to suppress a finding you simply do not want to fix, or to
      paper over missing detection. Over-broad context — e.g. asserting org-wide JWT enforcement
      when one repo allows anonymous endpoints — silently hides real findings.
    </Warning>
  </Tab>

  <Tab title="Reach for Custom Rules">
    Use Custom Rules when you have an organization-specific policy that built-in SAST does not
    enforce.

    **Trigger signals**

    * Your organization has security policies not covered by built-in SAST
    * Compliance frameworks (PCI, HIPAA, SOC 2) require code-level enforcement
    * You want internal coding standards enforced consistently across repos
    * Idiomatic patterns specific to your stack need a dedicated check

    **Typical examples**

    * *"Flag any API endpoint that returns user email addresses without the caller having admin scope."*
    * *"Find logging statements that include request bodies which may contain passwords or tokens."*
    * *"All database queries must use parameterized queries instead of string concatenation."*

    <Warning>
      Avoid duplicating built-in SAST checks, bundling multiple unrelated concerns into one rule,
      or writing vague rules like *"APIs should be secure."* Vague rules give ZeroPath nothing
      concrete to enforce.
    </Warning>
  </Tab>
</Tabs>

## Targeting and scope

Both features support the same three-level scope cascade and glob-based file scoping, but only Repository Context lets you target individual scan phases and input types.

### Shared: scope cascade

Both features follow the same **org → tag → repo** inheritance model as [scanner settings](/platform/scanner-settings).

| Scope            | Applies to                                                       |
| ---------------- | ---------------------------------------------------------------- |
| **Organization** | All repositories in the organization, including ones added later |
| **Tag**          | All repositories with the selected tag(s)                        |
| **Repository**   | Only the selected repository or repositories                     |

<Info>
  Scopes **stack** — a repository receives its own entries plus tag-level and org-level entries
  that apply to it. More specific scopes never replace broader ones.
</Info>

### Shared: file-level glob

Both features accept a glob pattern to limit which files they apply to. The default is all files.

| Pattern              | Matches                         |
| -------------------- | ------------------------------- |
| `**`                 | All files (default)             |
| `src/api/**`         | All files under `src/api/`      |
| `**/*.controller.ts` | All TypeScript controller files |
| `services/auth/**`   | All files in the auth service   |

### Context-only: scan phases and input types

Repository Context has two extra targeting dimensions — useful when a fact is only relevant to a particular kind of analysis. Custom rules are always evaluated in the natural-language rule phase against identified sources, so they do not expose phase selection.

<AccordionGroup>
  <Accordion title="Scan phases (Context only)">
    Six phases are selectable under **Advanced Settings** when creating a context entry:

    | Phase                           | What ZeroPath is doing                                                    |
    | ------------------------------- | ------------------------------------------------------------------------- |
    | **Application identification**  | Understanding what your code does — services, modules, entry points       |
    | **Source identification**       | Finding where untrusted data enters your application                      |
    | **Sink identification**         | Finding where data flows to sensitive operations                          |
    | **Vulnerability investigation** | Evaluating whether potential issues are real, exploitable vulnerabilities |
    | **Logic analysis**              | Analyzing business logic for issues beyond typical code patterns          |
    | **Custom rule evaluation**      | Evaluating your custom rules against the codebase                         |

    If you are unsure which to select, leave all phases enabled — ZeroPath applies your context
    wherever it is relevant.
  </Accordion>

  <Accordion title="Input types (Context only)">
    Eight input types are selectable under **Advanced Settings**:

    | Input type        | Description                                             |
    | ----------------- | ------------------------------------------------------- |
    | **HTTP Handler**  | Web API endpoints and HTTP request handlers             |
    | **File Handler**  | File upload and file system input processing            |
    | **Stdin Handler** | Command-line stdin and pipe input                       |
    | **Browser Data**  | Client-side browser input (cookies, local storage, DOM) |
    | **WebSocket**     | WebSocket message handlers                              |
    | **Socket**        | Raw TCP/UDP socket connections                          |
    | **CLI Argument**  | Command-line arguments and flags                        |
    | **Mobile Inputs** | Mobile application user input                           |

    All input types are selected by default. Deselect the ones that are not relevant to narrow the
    scope.
  </Accordion>
</AccordionGroup>

## How they work together

Context and Custom Rules are most useful in combination. Without context, a rule that says *"must check auth"* has no idea what an auth check looks like in your stack. Without rules, context only reduces noise on built-in detections — it cannot enforce your own policies.

### Worked example: enforcing auth on PII endpoints

<Steps>
  <Step title="Org-level Repository Context">
    Define what *"authenticated"* means across the organization.

    > **Authentication =** a request that carries a valid JWT validated by the `requireAuth()`
    > middleware, **or** presents an mTLS client certificate at ingress.
  </Step>

  <Step title="Repo-level Repository Context (e.g. payments-api)">
    Define what *"PII"* means in this repository.

    > **PII fields include** `card_last4`, `billing_email`, `customer_phone`.
  </Step>

  <Step title="Org-scoped Custom Rule">
    State the policy.

    > *All endpoints exposing PII must require authentication.*
  </Step>

  <Step title="Result">
    ZeroPath now flags only endpoints that handle PII fields **and** bypass one of the two
    recognized auth mechanisms. Endpoints behind `requireAuth()` or mTLS are correctly treated as
    safe; everything else surfaces as a high-signal finding.
  </Step>
</Steps>

<Note>
  Without the context entries, the same rule would produce lower-confidence findings everywhere the
  model wasn't sure how your stack handles authentication or what counts as PII. Pairing rules with
  context is what makes findings actionable.
</Note>

## Lifecycle and management

<Tabs>
  <Tab title="Repository Context">
    **Where to manage:** [Context](https://zeropath.com/app/context) page in the dashboard. Table
    view with title (or body preview), file pattern, tags, and repository scope.

    **Creation paths**

    * Manual creation in the dashboard
    * One-click **Generate & Save Context** from any false positive — no review step, takes effect
      on the next scan

    **Editing and deletion**

    * Click a row to edit text, targeting, or scope
    * Individual or bulk delete with confirmation
    * Changes take effect on the next scan

    **Review cadence:** quarterly. Architecture drifts; stale context can hide real issues. Delete
    entries that no longer reflect reality.
  </Tab>

  <Tab title="Custom Rules">
    **Where to manage:** [Rules](https://zeropath.com/app/rules) page → **Custom Rules** tab. The
    sibling **Rule Packs** tab exposes curated bundles published by ZeroPath that you can enable
    without authoring.

    **Creation paths**

    * Manual creation in the dashboard
    * Enable **Rule Packs** — no authoring needed
    * v2 API for programmatic management

    **Editing and deletion**

    * Update name, description, rule text, or scope
    * Switch between `allRepositories` and specific `repositoryIds` (mutually exclusive in the same
      request)
    * Delete rules that are no longer needed

    **Review cadence:** quarterly, or after major architectural change. Refine rules as you see
    which findings are actionable vs. noise.
  </Tab>
</Tabs>

<Warning>
  **Custom Rules Only mode** — the **Custom rules only** toggle in [scanner
  settings](/platform/scanner-settings) disables every built-in scanning module (SAST, SCA, IaC,
  Secrets, EOL) and evaluates only your natural-language rules. This is rarely the right choice;
  enable it only when you intentionally want ZeroPath to run as a pure custom-rule engine.
</Warning>

## Pitfalls to avoid

<AccordionGroup>
  <Accordion title="Over-broad context that silently suppresses findings">
    The single most dangerous mistake. Saying *"all endpoints require JWT"* at org scope is fine
    only if it is **literally true everywhere**. One legacy service with an anonymous endpoint and
    you have just taught ZeroPath to ignore a real finding. Start narrow; widen only when the
    statement is provably true across the broader scope.
  </Accordion>

  <Accordion title="Vague rules that produce noise">
    *"APIs should be secure"* is not enforceable. Rules need a concrete, testable assertion: a
    specific behavior that either holds or doesn't. If you cannot describe how a reviewer would
    check the rule by hand, ZeroPath cannot enforce it consistently either.
  </Accordion>

  <Accordion title="Using context to mask findings instead of stating facts">
    Context is for facts that are true in your codebase, not for hiding findings you don't want
    to triage. If the underlying claim isn't true, the entry will eventually hide a real bug.
  </Accordion>

  <Accordion title="Rules without supporting context">
    Standalone rules produce findings, but ZeroPath has to guess what *"auth check"* or
    *"sanitized input"* means in your stack. Pair every non-trivial rule with the context it needs
    to recognize the safe pattern.
  </Accordion>

  <Accordion title="Leaving all input types and phases enabled by default">
    Default targeting is intentionally permissive. When you know a context entry only applies to
    HTTP handlers during source identification, narrow it. Over-broad targeting makes irrelevant
    context bleed into unrelated analysis.
  </Accordion>
</AccordionGroup>

## Suggested rollout

<Steps>
  <Step title="Week 1 — Baseline">
    Connect repos, run full scans, and enable the relevant [**Rule
    Packs**](https://zeropath.com/app/rules?tab=packs). No custom work yet — let the baseline
    surface where the noise is.
  </Step>

  <Step title="Week 2 — Triage into context">
    For every false positive, use the one-click **Generate & Save Context** workflow. Aim to
    convert roughly 80% of FPs into context entries. This is the highest-ROI step.
  </Step>

  <Step title="Week 3 — Author rules for policy gaps">
    Identify org-specific policies not covered by built-in SAST or Rule Packs. Write 3–5 custom
    rules. For each, add the supporting context entries that describe the safe patterns the rule
    must recognize.
  </Step>

  <Step title="Week 4 — Tag, review, and own">
    Tag rules and context entries by team or compliance framework. Assign a quarterly review owner
    so entries don't go stale as the codebase evolves.
  </Step>
</Steps>

## Quick reference

| Situation                                                            | Use                |
| -------------------------------------------------------------------- | ------------------ |
| Same false positive keeps appearing                                  | Repository Context |
| Internal-only service flagged as public                              | Repository Context |
| Safe wrapper or helper not recognized                                | Repository Context |
| Architectural fact every engineer knows but the code doesn't show    | Repository Context |
| Compliance policy needs code-level enforcement                       | Custom Rule        |
| Org-wide coding standard to enforce                                  | Custom Rule        |
| Built-in SAST misses a pattern specific to your stack                | Custom Rule        |
| Need to enforce a policy **and** teach ZeroPath what safe looks like | Both, paired       |

<Columns cols={2}>
  <Card title="Repository Context docs" icon="arrow-right" href="/platform/repo-context">
    Targeting axes, false-positive workflow, scope inheritance, and best practices.
  </Card>

  <Card title="Custom Rules docs" icon="arrow-right" href="/platform/custom-rules">
    Authoring rules, the v2 API, Rule Packs, and Custom Rules Only mode.
  </Card>
</Columns>