How to Enable Monitoring for a Single Policy
Use per-policy Monitor mode to record audit-only matches on one policy without disabling enforcement on the rest of your policy stack.
Overview
Sometimes you want a policy to watch for matching package installs and record them in the audit log — without actually blocking the install and without touching any other policy. Common cases:
- Rolling out a new Block policy and wanting to measure impact before it starts returning 403s.
- Tracking a soft signal (e.g. “packages with no SLSA provenance”) that you are not ready to enforce organization-wide.
- Auditing a specific ecosystem or client group without disrupting developers.
Chainsaw supports this via Monitor mode on an individual policy. A policy with mode: monitor records an OutcomeFlagged audit entry on every match, never returns a 403 to the client, and dispatches an install.flagged webhook event (separate from install.blocked). It works independently of the global Settings → Blocking mode toggle.
allow mode as a workaround for audit-only monitoring. Allow is an explicit allow and bypasses every other Block policy on the same request. Use Monitor mode instead — it only records, never allows.Prerequisites
- Manager or Admin role in Chainsaw
- At least one existing policy (or the ability to create one) — see How to Block Vulnerable Packages Using CVSS and EPSS
How the four modes compare
| Mode | HTTP response | Audit entry | Affects other policies? |
|---|---|---|---|
allow | 200 (explicit allow) | Allowed (exception) | Short-circuits the stack — later Block policies never run |
block | 403 (or 200 + Flagged if the global Blocking toggle is off) | Blocked or Flagged | First match wins |
monitor | 200 (never blocks) | Flagged | First match wins, but does not short-circuit Block policies at lower precedence if you reorder |
quarantine | 202 (held for review) | Quarantined | Separate review queue |
The key distinction: monitor and the “Block policy with global Blocking toggle off” case both produce Flagged entries, but Monitor is scoped to one policy. The global toggle affects every Block policy at once.
Step 1: Open the policy editor
Navigate to Policies in the dashboard sidebar, find the policy you want to convert, and click Edit.
If you are creating a new policy specifically for monitoring, click New Policy and fill in the conditions normally — you will pick the mode in the next step.
Step 2: Set the mode to Monitor
In the policy editor, find the Mode selector at the top of the form. It offers four values:
allowblockmonitor← select this onequarantine
Save the policy. The change takes effect immediately — no restart required.
mode: monitor in a YAML-imported policy file. See How to Configure Chainsaw with YAML Imports for the import workflow.Step 3: Trigger a matching request
To verify the policy is recording matches, install a package that you know satisfies the policy’s conditions through a client that is configured to use Chainsaw. The install should succeed normally — no 403, no delay.
For example, if your Monitor policy blocks any package with a CVSS score ≥ 9.0, install a package with a known critical CVE:
# Through a Chainsaw-routed npm client
npm install --save some-known-cve-package@vulnerable-version
The install should complete successfully.
Step 4: Confirm the match in the violations view
Go to Monitoring → Violations (or the dashboard’s “Recent Activity” panel). You should see a new entry with:
- Outcome:
Flagged - Policy: the name of the policy you set to Monitor
- Reason: the match reason (e.g.
monitored by policy: high-cvss-block)
Unlike Blocked entries, Flagged entries do not have a “client impact” badge — no developer was interrupted.
Step 5: Subscribe to the install.flagged webhook event
Monitor-mode matches dispatch a webhook event named install.flagged. The payload is identical to install.blocked (same fields, same schema) — only the event field and the X-Chainsaw-Event header differ.
If you already have a handler for install.blocked, you can either:
- Subscribe to both events in your webhook endpoint configuration and route them to the same Slack channel or SIEM sink, or
- Keep them separated — e.g. send
install.blockedto your incident channel andinstall.flaggedto a lower-signal “audit” channel so Monitor matches never page someone.
Existing subscribers that listen only for install.blocked will not receive Monitor events. This is intentional so you can enable Monitor mode without noise in your existing alert pipeline.
Step 6: Promote to Block once you are confident
After observing Monitor entries for long enough to trust the policy’s scope:
- Return to the policy editor.
- Change Mode from
monitortoblock. - Save.
The next matching request will now return 403 and emit an install.blocked event. Anything recorded before the flip remains in the audit log as Flagged — those entries are not retroactively converted.
Common Pitfalls
| Pitfall | Why it happens | Fix |
|---|---|---|
| “Monitor mode is ignoring my global Blocking toggle” | That is correct behavior — Monitor is independent of the global toggle | No action needed |
| A Monitor policy shadows a lower-precedence Block policy | First-match-wins still applies | Put Block policies above Monitor policies when they overlap |
| Webhook subscriber not receiving Monitor events | The subscription is filtered to install.blocked only | Add install.flagged to the subscription’s event list |
| Rolling out a Block policy by flipping global Blocking toggle off | Disables enforcement across every Block policy | Use per-policy Monitor on just the new policy instead |
Next Steps
- How to Manage Policy Precedence and Exception Workflows — Order Monitor and Block policies correctly
- How to Monitor Violations and Respond to Blocked Packages — Investigate
FlaggedandBlockedentries in the violations view - How to Use Billy to Investigate and Draft Policies — Ask Billy to forecast how many matches a Monitor policy would record