> ## 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](/docs/platform/repo-context)** and **[Custom Rules](/docs/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="/docs/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="/docs/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](/docs/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:** [Settings → Repository context](https://zeropath.com/app/context) 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:** [Settings → Rules](https://zeropath.com/app/rules) → **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](/docs/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="/docs/platform/repo-context">
    Targeting axes, false-positive workflow, scope inheritance, and best practices.
  </Card>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.