Manage exceptions

Create scoped, documented, expiring waivers when a rule blocks a package you need.

Rules are general; reality has edge cases. An exception lets a specific package through a specific rule without changing the rule itself. Every exception carries a reason and, ideally, an expiry date, so waivers stay visible and temporary instead of accumulating as silent policy holes.

Create an exception from a log entry

The fastest path starts from the block itself:

Open Logs on the firewall and find the blocked request.
Create an exception from the log entry. The rule, package name, and version are prefilled.
Pick a Reason and set Expiration.
Save, then retry the install.

Create an exception manually

Open Exceptions on the firewall and add one:

Rule. The rule to except from. An exception belongs to exactly one rule.
Selector. Which packages the exception covers: package name and version, matched the same way a rule selector matches them.
Reason. One of the dashboard reasons below. Exported JSON stores its corresponding snake-case config value.
Expires. Optional, recommended.
Log. Whether matching requests still produce a log entry. Keep this on; allowed-by-exception is exactly what you want visible in an audit.

As JSON:

{
  "rule": "block-critical-vulns",
  "selector": { "packageName": "lodash", "version": "4.17.20" },
  "log": true,
  "expires": "2026-08-01T00:00:00Z",
  "reason": "not_exploitable",
  "notes": "Vulnerable function not reachable from our code. Tracked in JIRA-1234."
}

To apply the JSON without the dashboard: export the config with bsfw firewall export, add the exception to the exceptions array, and import it back. See firewall import.

Scope narrowly

An exception selector with only a package name covers every version of that package, including versions published after you wrote it, against that rule. Prefer pinning the exact version. Wildcards work (lodash@4.17.*) but widen the hole. The narrower the exception, the less it erodes the rule.

An exception applies to one rule. It does not exempt the package from your other rules, so a package excepted from a license rule is still checked for malware.

If the rule comes through inheritance, adding an exception needs fw:update:exception on both this firewall and the source firewall that owns the rule. The source may be any ancestor in the chain. Without both permissions, the dashboard greys out Add exception and its tooltip identifies the missing permission.

Let vulnerability fixes skip a delay

For a versions- or download-phase rule on an npm, Go, Maven, PyPI, or NuGet firewall, the dashboard offers Vulnerability Fixes under Condition. It matches versions identified in current advisory data as published fixes. On a delay rule, this lets a security-fix release through the age window without allowing unrelated new releases.

Keep exception logging on. This makes each automatic bypass visible. The vulnerability-fix reference documents the matching behavior and JSON shape.

Reasons

Reason	Meaning
`acknowledged_violation`	We know, we accept it for now
`evaluating_component`	Under assessment, temporary access
`mitigated_externally`	Risk handled outside the package, for example WAF or config
`no_upgrade_path`	No fixed version available yet
`not_exploitable`	Vulnerability cannot be triggered in our usage
`not_reachable`	Vulnerable code path not reachable
`other`	Explain in notes

Expiry

An expired exception stops matching. The next install of that package is blocked again, and the returning block is what tells you the date passed, so pick a date you are prepared to act on. That is the point of expiry: no_upgrade_path gets re-checked when it expires instead of surviving three years past the fix.

Review existing exceptions

List them per firewall in the dashboard, or with the CLI:

bsfw firewall exceptions <firewall-id> -o json

Ask for JSON here rather than the default table: the table is a compact view, and reason, expiry, and notes are exactly the fields a review turns on. The dashboard shows the same three with names resolved instead of IDs.

Worth a periodic review: exceptions without expiry and exceptions with reason other and empty notes are the ones that turn into permanent policy by accident.

Concept: Rule evaluation, including when exceptions are checked
How-to: Share configuration across firewalls, for exceptions on inherited rules
Reference: Rules and selectors, Permissions

Manage exceptions

On this page