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

# Custom Rules

> Create and manage custom SAST rules using natural language to enforce organization-specific security policies

## Overview

Custom rules let you define security policies in natural language that ZeroPath evaluates during full scans across your selected repositories. Instead of writing complex pattern-matching rules, describe what you want to check and ZeroPath's AI applies it across your codebase.

## Creating Rules

### From the Dashboard

1. Navigate to [**Settings → Rules**](https://zeropath.com/app/rules) (under **Scanner** in the Settings menu) and select the **Custom rules** tab.
2. Click **"Add Rule"**.
3. Give the rule a descriptive **name**.
4. Write your rule in natural language. For example:

   * *"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"*
   * *"Check that all database queries use parameterized queries instead of string concatenation"*

   The rule editor includes clickable example rules you can use as a starting point.
5. Optionally set a **file scope** using a glob pattern (e.g., `src/api/**`, `*.py`) to limit the rule to specific files. The default is all files.
6. Choose the **repository scope**: apply the rule to **all repositories** (including any added in the future) or select **specific repositories**. You can also assign **tags** to organize your rules.
7. Save the rule.

### From the API

Rules can be managed via the v2 API:

```bash theme={null}
# Create a rule scoped to specific repositories
curl -X POST https://zeropath.com/api/v2/rules/create \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: your-token-id" \
  -H "X-ZeroPath-API-Token-Secret: your-token-secret" \
  -d '{
    "organizationId": "your-org-id",
    "name": "Require Auth on API Endpoints",
    "description": "All API endpoints must require authentication",
    "rule": "All API endpoints must require authentication before processing requests",
    "repositoryIds": ["repo-id-1", "repo-id-2"]
  }'
```

To apply a rule to all repositories in the organization, pass `allRepositories: true` instead of `repositoryIds`:

```bash theme={null}
# Create a rule that applies to all repositories
curl -X POST https://zeropath.com/api/v2/rules/create \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: your-token-id" \
  -H "X-ZeroPath-API-Token-Secret: your-token-secret" \
  -d '{
    "organizationId": "your-org-id",
    "name": "No Hardcoded Secrets",
    "rule": "No hardcoded credentials or API keys in source code",
    "allRepositories": true
  }'
```

To scope a rule to all repositories with specific tags, use `scope: "tags"` with `tagIds`:

```bash theme={null}
# Create a rule scoped to repositories with specific tags
curl -X POST https://zeropath.com/api/v2/rules/create \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: your-token-id" \
  -H "X-ZeroPath-API-Token-Secret: your-token-secret" \
  -d '{
    "organizationId": "your-org-id",
    "name": "Require Auth on Internal APIs",
    "rule": "All internal API endpoints must require authentication",
    "scope": "tags",
    "tagIds": ["tag-id-1", "tag-id-2"]
  }'
```

You can also use the explicit `scope` parameter (`"allRepositories"`, `"repositories"`, or `"tags"`) on any create or update request to make the intended scope unambiguous:

```bash theme={null}
# Explicitly set scope to all repositories
curl -X POST https://zeropath.com/api/v2/rules/create \
  -d '{ "scope": "allRepositories", ... }'

# Explicitly set scope to specific repositories
curl -X POST https://zeropath.com/api/v2/rules/create \
  -d '{ "scope": "repositories", "repositoryIds": ["repo-id-1"], ... }'
```

<Info>
  You cannot combine `allRepositories` and `repositoryIds` in the same request. Use one or the other when creating or updating a rule. When using `scope: "tags"`, do not pass `repositoryIds` or `allRepositories`.
</Info>

## How Rules Are Evaluated

During each scan, ZeroPath:

1. **Identifies applications** in your repository (services, modules, entry points).
2. **Evaluates each custom rule** against every application in context.
3. **Reports violations** as findings alongside SAST, SCA, and other results.

Custom rule violations appear in the same findings stream as other scan results — with severity, confidence, affected file, and remediation guidance.

## Rule Scope

Rules can be scoped at different levels:

| Scope | Applies To |
| - | - |
| **Organization** | All repositories in the organization |
| **Tag** | All repositories with a specific tag |
| **Repository** | A single repository |

Organization-scoped rules automatically apply to newly added repositories without any manual update. Tag-scoped rules automatically apply to every repository that belongs to the selected tags, and access updates dynamically as repositories join or leave a tag. When you list rules via the API, each rule includes a `scope` field (`"allRepositories"`, `"repositories"`, or `"tags"`) indicating how it is scoped.

Rules follow the same **org → tag → repo** inheritance cascade as scanner settings. Repository-level rules supplement (not replace) org and tag-level rules.

## Managing Rules

From the dashboard or API, you can:

* **List** all rules for your organization — rules that apply to all repositories display **"All Repositories"**, and tag-scoped rules display the number of assigned tags (e.g., **"2 Tags"**) instead of a numeric repository count. Each rule displays who created it and how it was created (manually by a user, via the API, or auto-generated by an integration). Rules created from a rule pack template also show the originating template name and pack name, so you can trace the rule back to the pack it came from. The rules table supports sorting by name, creator, pattern, tags, and repositories, and columns can be resized to fit your workflow. You can also search rules by creator name in addition to rule name, pattern, and tags
* **View** a rule's definition, scope, and metadata. Each rule includes a `source` field indicating its origin: rules you create manually have the source `USER`, while rules auto-generated by the [Security Compass integration](/docs/integrations/security-compass) have the source `SECURITY_COMPASS`
* **Update** a rule's name, description, natural language definition, or scope (pass `allRepositories: true` to apply to all repos, or `repositoryIds` to scope to specific repos)
* **Delete** rules that are no longer needed. If a rule is deleted while a scan is in progress,
  findings from that rule are preserved — the association to the deleted rule is cleared, but the
  findings themselves remain in your results

## Custom Rules Only Mode

For organizations or repositories that want to run **only** their custom rules, enable the **Custom rules only** toggle in your scanner settings. When enabled, ZeroPath disables all built-in scanning modules, including SAST, SCA, IaC, Secrets, and EOL, and evaluates only your custom natural-language rules against identified sources. This setting can be configured at the organization, tag, or individual repository level, following the standard settings inheritance cascade. Custom rules only cannot be combined with the Lightweight [full scan mode](/docs/platform/scanner-settings#full-scan-settings).

## Rule Packs

In addition to custom rules, ZeroPath offers **Rule Packs**: curated bundles of pre-built rules published by ZeroPath that target common security patterns and compliance requirements. You can browse available rule packs from the **Rule packs** tab on the [Rules](https://zeropath.com/app/rules?tab=packs) page and enable the ones relevant to your organization. The Rule packs tab is only visible to users who have permission to edit organization metadata. Users without this permission see only the Custom rules tab (and the Security Compass tab, if enabled).

Rule packs supplement your custom rules. When a rule pack is enabled, its rules are evaluated during scans alongside any custom rules you have defined. Rule pack activation requires a user account — agent sessions (such as the AI assistant or MCP-driven automation) cannot activate rule packs and will receive a permission error if they attempt to do so.

## Security Compass Rules

If your organization has the [Security Compass integration](/docs/integrations/security-compass) enabled, a **Security Compass** tab appears on the [Rules](https://zeropath.com/app/rules?tab=compass) page. This tab lists all rules that were automatically generated from SD Elements countermeasures during a rule sync — distinct from rules you create manually.

Within the **Custom rules** tab, any rule sourced from the Security Compass integration displays a badge next to its name so you can identify auto-generated rules at a glance. You can open, view, and edit these rules the same way as any other custom rule.

To manage the Security Compass integration or trigger a rule sync, go to **Settings → Integrations → Security Compass**. See [Security Compass / SD Elements](/docs/integrations/security-compass) for the full workflow.

## Best Practices

1. **Be specific** — "All API endpoints must validate the user's session token before processing" is better than "APIs should be secure".
2. **One policy per rule** — create separate rules for separate concerns so violations are actionable.
3. **Start broad, then refine** — begin with high-level policies and add detail based on the violations you see.
4. **Use tags for team-specific rules** — different teams may have different security requirements; scope rules using tags.


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