How to Manage Policy Precedence and Exception Workflows
Understand first-match-wins evaluation, order policies by precedence, create time-bound exceptions, and balance security with developer productivity.
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)

Step 2: Design Your Policy Stack
A well-designed policy stack typically follows this pattern (highest to lowest precedence):
| Precedence | Policy Type | Purpose |
|---|---|---|
| 100 | Emergency allow | Specific packages needed urgently during incidents |
| 90 | Exception allows | Time-bound exceptions for approved risk acceptance |
| 80 | Critical blocks | Block confirmed malware (trust score = -100) |
| 70 | High-severity blocks | Block critical vulnerabilities (CVSS >= 9.0) |
| 60 | Typosquat blocks | Block suspected typosquats |
| 50 | License blocks | Block prohibited licenses (AGPL, GPL) |
| 40 | Freshness guards | Block packages < 14 days old |
| 30 | Trust score blocks | Block low trust score packages (< 30) |
| 20 | Quarantine rules | Quarantine moderate-risk packages for review |
| 10 | Default allow | Allow everything that passes all checks |

Step 3: Reorder Policies
Navigate to Policies. Drag and drop policies to adjust their precedence order.

Rules for Ordering
- Specific allows before general blocks — Exceptions need higher precedence than the rules they override
- Narrow scope before broad scope — A policy targeting a specific package should be above one targeting all packages
- Malware blocks at the top — Never let an exception override malware detection
- 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
- Find the violation in the violations list
- Click Create Exception
- 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

As a Policy
For more control, create the exception as an Allow policy:
- Name:
Exception: lodash@4.17.20 (JIRA-1234) - Action: Allow
- Conditions: Package =
lodash, Version =4.17.20 - Scope: Specific client or group
- Precedence: Above the blocking policy but below malware blocks

Step 5: Exception Lifecycle Management
Track Active Exceptions
Monitor active exceptions from the Overview dashboard. The exceptions KPI shows how many are currently active.

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:
| Trigger | When | Audience |
|---|---|---|
| T-7d | Seven days before expiry | The owner email on the exception (or the CODEOWNERS-resolved team if blank) |
| T-1d | One day before expiry | Same recipient list |
| T-0 | At expiry, when the exception transitions from active to expired | Same 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
| Scenario | Action |
|---|---|
| Patched version available | Remove exception, upgrade the package |
| No patch yet, risk accepted | Renew with new expiry and updated justification |
| Risk assessment changed | Remove exception, enforce the block |
| Package no longer needed | Remove 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)

Step 7: Testing Policy Changes
Before applying a new policy to production:
- Start with Monitor mode — The policy records
Flaggedaudit entries on every match but never returns a 403. See How to Enable Monitoring for a Single Policy. - Watch the violations view for a week — Check how many requests would be affected and which clients are hitting it.
- Review false positives — Create exceptions for legitimate packages before switching to Block.
- Switch to Block — Once you’re confident in the scope, change the policy’s mode to
block.
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") installslodash-esunder the folderlodash. The entry’snamefield 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 whoseresolvedURL is under the public registry or the reviewed repository on your Chainsaw proxy (setPROXYto 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 aresolvedfield 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 installandcomposer installget the package index with only the reviewed versions in it, so the resolver picks one of them. The response carriesX-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.post1and1.0.0rc1are not1.0.0.
Risks to plan for
| Risk | What happens | What to do |
|---|---|---|
| Exceptions expire | Bulk-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 dependencies | A 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 block | A 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 cost | Each 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-Pattern | Problem | Fix |
|---|---|---|
| Broad Allow at top | Overrides all blocks | Scope Allow policies to specific packages only |
| No default at bottom | Ambiguous behavior for unmatched requests | Add a catch-all Allow or Block at lowest precedence |
| Expired exceptions left active | Accumulating risk | Set expiry dates, review regularly |
| Copy-paste policies | Redundant rules, hard to maintain | Consolidate similar policies |
| Blocking without monitoring first | Developer disruption | Set mode: monitor on the policy first, measure impact, then flip to block |
| Flipping the global Blocking toggle off to test one policy | Disables enforcement on every Block policy | Use per-policy Monitor mode instead (tutorial 31) |
Changing a Block policy to allow to stop it blocking | Creates an explicit allow that bypasses other Block policies | Use monitor mode — it records matches without allowing anything through |
Next Steps
- How to Block Vulnerable Packages Using CVSS and EPSS — Create vulnerability blocking policies
- How to Monitor Violations and Respond to Blocked Packages — Handle violations from your policy stack
- How to Use Billy to Investigate and Draft Policies — Let Billy help design policies