How to Manage Policy Precedence and Exception Workflows

Advanced 25 minutes Security Engineers / DevOps Engineers Advanced Configuration Updated

Understand first-match-wins evaluation, order policies by precedence, create time-bound exceptions, and balance security with developer productivity.

Video: Retire the demo policies | Chainsaw tutorial 2.10
Video: Grant a policy exception that expires | Chainsaw tutorial 6.6
Video: Require a second approver | Chainsaw tutorial 6.7

Overview

Chainsaw evaluates policies in precedence order using a first-match-wins model. When a package request arrives, Chainsaw walks the policy list from highest to lowest precedence and applies the first policy whose conditions match. Understanding this model is essential for building a layered security posture that balances protection with developer productivity.

Prerequisites

  • Manager or Admin role in Chainsaw
  • Existing policies configured (see earlier tutorials)
  • Understanding of your organization’s security requirements

Step 1: Understand First-Match-Wins Evaluation

Policies are evaluated top to bottom. The first policy whose conditions match the request determines the outcome.

Request: npm install lodash@4.17.21

Policy 1 (Precedence: 100): Allow — package = "lodash"        → MATCH → ALLOW
Policy 2 (Precedence: 90):  Block — CVSS >= 7.0               → (never reached)
Policy 3 (Precedence: 80):  Block — trust_score < 30           → (never reached)
Policy precedence evaluation flow
Policies are evaluated from highest to lowest precedence — first match wins
A broad “Allow” policy at high precedence can silently override all blocking policies below it. Be very deliberate about what gets high precedence.

Step 2: Design Your Policy Stack

A well-designed policy stack typically follows this pattern (highest to lowest precedence):

PrecedencePolicy TypePurpose
100Emergency allowSpecific packages needed urgently during incidents
90Exception allowsTime-bound exceptions for approved risk acceptance
80Critical blocksBlock confirmed malware (trust score = -100)
70High-severity blocksBlock critical vulnerabilities (CVSS >= 9.0)
60Typosquat blocksBlock suspected typosquats
50License blocksBlock prohibited licenses (AGPL, GPL)
40Freshness guardsBlock packages < 14 days old
30Trust score blocksBlock low trust score packages (< 30)
20Quarantine rulesQuarantine moderate-risk packages for review
10Default allowAllow everything that passes all checks
Recommended policy stack layout
A layered policy stack from emergency overrides down to default behavior

Step 3: Reorder Policies

Navigate to Policies. Drag and drop policies to adjust their precedence order.

Dragging policies to reorder
Drag policies up or down to change their evaluation precedence

Rules for Ordering

  1. Specific allows before general blocks — Exceptions need higher precedence than the rules they override
  2. Narrow scope before broad scope — A policy targeting a specific package should be above one targeting all packages
  3. Malware blocks at the top — Never let an exception override malware detection
  4. Default behavior at the bottom — The catch-all policy goes last

Step 4: Create Time-Bound Exceptions

When a developer needs a blocked package, create a time-bound exception:

From the Violations Page

  1. Find the violation in the violations list
  2. Click Create Exception
  3. Set the details:
    • Package: Pre-filled from the violation
    • Version: One exact version. A range, a wildcard (1.x) or, for npm, Cargo, Go and NuGet, a partial version (4.17) is refused
    • Expiry: 30, 60, or 90 days
    • Reason: Document the business justification
Creating an exception from a violation
Create an exception directly from the violation detail

As a Policy

For more control, create the exception as an Allow policy:

  1. Name: Exception: lodash@4.17.20 (JIRA-1234)
  2. Action: Allow
  3. Conditions: Package = lodash, Version = 4.17.20
  4. Scope: Specific client or group
  5. Precedence: Above the blocking policy but below malware blocks
Exception created as an Allow policy
Create a specific Allow policy that overrides the blocking rule
Always include a ticket reference (JIRA, Linear, etc.) in the exception name so the approval is traceable.

Step 5: Exception Lifecycle Management

Track Active Exceptions

Monitor active exceptions from the Overview dashboard. The exceptions KPI shows how many are currently active.

Active exceptions count
Track the number of active exceptions across your organization

Review Expiring Exceptions

Set a regular cadence (weekly or biweekly) to review:

  • Exceptions approaching expiry
  • Whether the underlying issue has been resolved (patched version available)
  • Whether the exception should be renewed or removed

Automatic expiry reminders (T-7d / T-1d / T-0)

Chainsaw runs an idempotent reminder loop against the exceptions table. For every exception, three notifications fire automatically:

TriggerWhenAudience
T-7dSeven days before expiryThe owner email on the exception (or the CODEOWNERS-resolved team if blank)
T-1dOne day before expirySame recipient list
T-0At expiry, when the exception transitions from active to expiredSame recipient list, plus the policy admins group

The dispatch is idempotent on (exception_id, milestone) so a control-plane restart never double-sends. Delivery uses your configured outbound webhook destinations — the same channels as violation notifications. There is no opt-out at the exception level; if you do not want a reminder, do not create the exception (or set the expiry to a date that aligns with your review cadence).

The view at /reports/exceptions/expiring shows everything currently in the seven-day window in one screen, sorted by remaining days, so the weekly review can happen against a single page rather than per-exception.

Exception Renewal vs Removal

ScenarioAction
Patched version availableRemove exception, upgrade the package
No patch yet, risk acceptedRenew with new expiry and updated justification
Risk assessment changedRemove exception, enforce the block
Package no longer neededRemove exception, clean up BOM

Step 6: Scoping Policies for Different Environments

Use policy scoping to apply different rules to different contexts:

By Client Type

Production (service-token):  Block CVSS >= 7.0
Development (end-user):      Quarantine CVSS >= 9.0 (more permissive)

By Repository

npm:     Block trust score < 40 (high attack surface)
maven:   Block trust score < 20 (more stable ecosystem)

By Client Group

frontend-team:  Block all non-MIT/Apache licenses
backend-team:   Allow LGPL (linking is acceptable)
Policies with different scopes
Different policy stacks for different teams and environments

Step 7: Testing Policy Changes

Before applying a new policy to production:

  1. Start with Monitor mode — The policy records Flagged audit entries on every match but never returns a 403. See How to Enable Monitoring for a Single Policy.
  2. Watch the violations view for a week — Check how many requests would be affected and which clients are hitting it.
  3. Review false positives — Create exceptions for legitimate packages before switching to Block.
  4. Switch to Block — Once you’re confident in the scope, change the policy’s mode to block.
Use Billy to forecast impact: “How many packages would be blocked if we set a trust score threshold of 40?”

Recipe: Serve Only Reviewed Versions

Some teams want a repository that serves only the versions someone has reviewed, and refuses everything else. You build it from two pieces you already have: one block rule that covers the whole repository, and one exception per reviewed package@version. The exceptions are the reviewed list.

1. Block everything in the repository

Create a dedicated repository for this (for example npm-reviewed) so the rule never touches your other proxies, then block every package in it:

curl -X POST -H "Authorization: Bearer $CHAINSAW_TOKEN" \
     -H "Content-Type: application/json" \
     https://chain305.com/chainproxy/api/policies \
     -d '{"name":"Reviewed list only: npm-reviewed","precedence":500,"mode":"block","status":"enabled",
          "identifier":{"targetPackageRepo":"npm-reviewed","targetPackageName":"*"}}'

Leave your org-wide rules in place. The malware feed still refuses any version on the list once it lists that version: entries created through the bulk endpoint never cover a malware-listed version. Your other block rules (KEV, typosquats, CVSS, age) do not apply to a version on the list, because an exception overrides them for its exact version. Review the list with that in mind.

2. Seed the list from a lockfile

Take the list from the lockfile, not from package.json. The lockfile names every transitive dependency at its resolved version. A list without them refuses the first transitive install. This example reads an npm v2/v3 package-lock.json and sends it to the bulk endpoint in batches of 25, which is the most the endpoint accepts per request:

REGISTRY=https://registry.npmjs.org/
PROXY=https://chain305.com/chainproxy/repository/@your-org/npm-reviewed/   # use your org slug
jq -c --arg registry "$REGISTRY" --arg proxy "$PROXY" '[.packages | to_entries[]
         | select((.key | test("(^|/)node_modules/")) and .value.version != null and (.value.link | not))
         | select((.value.resolved // "") as $r | ($r | startswith($registry)) or ($r | startswith($proxy)))
         | {repository:"npm-reviewed", package:(.value.name // (.key | sub("^.*node_modules/"; ""))), version:.value.version,
            note:"reviewed list: seeded from package-lock.json"}]
       | unique | . as $all | range(0; length; 25) | $all[.:(. + 25)]' package-lock.json |
while read -r batch; do
  curl -sS --fail-with-body -X POST -H "Authorization: Bearer $CHAINSAW_TOKEN" \
       -H "Content-Type: application/json" \
       -H "X-Chainsaw-Action-Source: bulk_action" \
       https://chain305.com/chainproxy/api/actions/bulk \
       -d "{\"action_type\":\"exception\",\"items\":$batch}" || { echo "batch failed; stopping" >&2; exit 1; }
done

Three things in that filter matter:

  • The real package name. An npm alias ("lodash": "npm:lodash-es@4.17.21") installs lodash-es under the folder lodash. The entry’s name field holds the real name, so the filter uses it and falls back to the folder name.
  • Only public-registry entries. A git, file: or private-registry dependency has the same name as some package on the public registry, which belongs to somebody else. Seeding that name would allow the public namesake: the dependency-confusion shape. The filter keeps only entries whose resolved URL is under the public registry or the reviewed repository on your Chainsaw proxy (set PROXY to that one repository’s URL, ending in its name and a slash). Do not widen it to the whole proxy: a private package served from a hosted repository on the same proxy also resolves under it, and seeding its name would allow the public namesake. Entries without a resolved field are skipped too; add them by hand after checking where they come from.
  • Stop on the first failure. --fail-with-body (curl 7.76 or later) makes curl exit non-zero on an error response and still print it, and the loop stops there.

A batch is all-or-nothing: if one item fails, the batch’s rows are rolled back and the response says which item failed. Each entry must be one exact version; a range, a wildcard (1.x) or, for npm, Cargo, Go and NuGet, a partial version (4.17) fails the batch. If your org requires a second approver for exceptions, every row is created as pending_approval and refuses installs until someone approves it.

3. What a client sees

  • npm install, pip install and composer install get the package index with only the reviewed versions in it, so the resolver picks one of them. The response carries X-Chainsaw-Exception-Listing: hidden=N.
  • A package with no reviewed version gets a 403 on its index.
  • A download of any version not on the list is refused, whatever the index said. That includes a PyPI post-release or pre-release of a reviewed version: 1.0.0.post1 and 1.0.0rc1 are not 1.0.0.

Risks to plan for

RiskWhat happensWhat to do
Exceptions expireBulk-created exceptions carry no expiry of their own, so they lapse after the org’s exception age (Settings, exception_age, 1 to 365 days, default 30). The reviewed list then stops installing all at once. In an org that requires approval, each row is created with an expiry of the exception age counted from the request, and the approver can change it.Raise exception_age, which applies to every exception in the org. Or create each entry with chainsaw exception create --days N, and renew before expiry (POST /api/exceptions/{id}/renew).
Transitive dependenciesA dependency missing from the list is refused, and the install fails.Seed from the lockfile, and re-seed when it changes.
An exception overrides every other blockA bulk-created exception never covers a version the malware feed lists, but it overrides every other block on its exact version: KEV, typosquat, CVSS, age. A single exception created from the API or the CLI overrides malware too.Review the list before you seed it. Seed through the bulk endpoint, as above, rather than one exception at a time.
Evaluation costEach request walks the policy list in order, and exceptions sort first. An index request evaluates every listed version against that list, so the cost grows with versions times exceptions.Measure index latency on your own list before you rely on this at thousands of exceptions. We have not benchmarked it at that size.

Common Anti-Patterns

Anti-PatternProblemFix
Broad Allow at topOverrides all blocksScope Allow policies to specific packages only
No default at bottomAmbiguous behavior for unmatched requestsAdd a catch-all Allow or Block at lowest precedence
Expired exceptions left activeAccumulating riskSet expiry dates, review regularly
Copy-paste policiesRedundant rules, hard to maintainConsolidate similar policies
Blocking without monitoring firstDeveloper disruptionSet mode: monitor on the policy first, measure impact, then flip to block
Flipping the global Blocking toggle off to test one policyDisables enforcement on every Block policyUse per-policy Monitor mode instead (tutorial 31)
Changing a Block policy to allow to stop it blockingCreates an explicit allow that bypasses other Block policiesUse monitor mode — it records matches without allowing anything through

Next Steps