Rules and selectors

A firewall's policy consists of rules and exceptions inside its configuration. This page documents every field. For the mental model, see Rule evaluation.

Rule

{
  "id": "delay-new-versions",
  "disabled": false,
  "executionPhase": "versions",
  "selector": { "maxAgeHours": 168 },
  "ruleEffect": { "block": true, "log": true },
  "description": "Block versions younger than 7 days"
}

Evaluation order

Rules are not evaluated in configuration order. A request is evaluated against the cheaper rules first, so it pays for an expensive check only once every cheaper rule has allowed it. Rules of equal cost keep their configuration order, inherited rules before the firewall's own.

The first matching rule with block: true ends evaluation. Two things follow. The block a client sees, and the rule recorded in the log entry, is not necessarily the first rule you configured. And rules after it are never evaluated, never log, and cost the request nothing: a package stopped by a maxAgeHours rule is never scanned for malware.

Treat the order as an implementation detail that can change. If you need a rule to be evaluated regardless of what else matches, do not rely on ordering; give it a selector that cannot overlap with the others.

Selector

All set fields must match (AND). Empty fields match everything.

Wildcards

packageName and version accept at most one *, at the start or the end:

Package name matching

packageName is matched in the naming form the ecosystem itself considers canonical, so a selector written the way the package appears on the registry works:

NuGet and PyPI have their own naming rules, and the firewall follows them. Everywhere else the name is matched as written, so a rule selects only the package it names.

Write the name the way the registry shows it. Most npm names are lowercase, but older ones such as JSONStream are not, and a rule written jsonstream does not match.

Wildcards are normalized the same way, so a NuGet selector Microsoft.* matches microsoft.extensions.logging. version is always compared exactly and is never normalized.

Exceptions use the same matching, which matters most there: an exception meant to unblock a package has to select it to take effect.

Version ranges

version and versionRange answer different questions. version compares text, so 1.* selects anything whose version string starts with 1.. versionRange parses both sides and compares them as versions, so >=1.2.0 <2.0.0 knows that 1.10.0 is newer than 1.9.0. Use version to match a naming shape, versionRange to match a real interval.

The two are independent fields. Set both and a version has to satisfy both.

Each ecosystem keeps its own range notation:

Semver ranges support || for alternatives, X - Y for an inclusive span, x, X, or * as a wildcard component, and the operators =, !=, >, <, >=, <=, ~, ^. As in npm itself, a prerelease only matches a range that mentions a prerelease: 1.2.0-beta.1 does not satisfy ^1.2.0.

NuGet ranges go through the semver parser, deliberately, so that range syntax is the same across ecosystems that can share it. NuGet's own bracket intervals are therefore not accepted, and [1.0.0,2.0.0) is rejected when you save the rule. NuGet versions keep their own rules, so a four-part version such as 1.5.0.3 still parses and compares correctly.

Saving a rule whose range the ecosystem cannot parse fails with an error. At request time, a package version the ecosystem cannot parse does not match the range.

Selector functions

Full semantics, options, and dashboard availability per function: Selector functions.

The API rejects rules and exceptions whose function does not support the firewall's ecosystem. Full config imports and rollbacks apply the same validation.

Effect

{ "block": false, "log": true } is a dry-run rule, the standard way to trial a policy.

Exceptions

An exception waives one rule for requests matching its own selector, with an expiry and a reason. Field-level reference: Exceptions.

Related

• Concept: Rule evaluation
• Reference: Selector functions, Exceptions, Firewall config
• How-to: Delay new versions, Block vulnerable packages, Manage exceptions