Artifact Firewall Ruleset

Artifact Firewall Ruleset format.

Example:

- id: GHSA-8vvx-qvq9-5948
  match:
    - purl: pkg:npm/flowise
      version: vers:npm/<=2.2.7
  severity: 10
  reason: Flowise allows arbitrary file write to RCE

id string#

Unique identifier for the ruleset. Mandatory.

title string#

Human-readable title for the ruleset. Informational only. Optional.

date string#

Date the ruleset was authored. Informational only. Optional.

description string#

Description of the ruleset’s purpose. Informational only. Optional.

virtual_registries list#

id: my-ruleset
virtual_registries:
- npm-internal
rules: []

List of virtual registry names this ruleset applies to. When set, rules in this ruleset are only evaluated for requests routed through the listed registries. When empty, the ruleset applies to all registries.

rules list#

List of rules to evaluate. Rules are evaluated in order of priority value (higher priority takes precedence).

id: my-ruleset
rules:
- id: block-lodash
  match:
  - type: npm
    name: lodash
  action: deny
  reason: Unapproved package

id string#

Unique identifier for the rule within the ruleset. Mandatory.

aliases list#

rules:
- id: CVE-2021-44228
  aliases:
  - Log4Shell
  - GHSA-jfh8-c2jp-hdp

Alternative identifiers for the rule, such as CVE IDs or advisory references. Informational only.

priority integer#

rules:
- id: my-rule
  priority: 10

Default: 0

Priority for this rule. A higher numerical value means higher priority, and if multiple rules match at the highest priority level, the strongest rule applies: deny > hide > allow. The lowest possible priority is 0.

action string#

rules:
- id: my-rule
  action: deny

Action to take when the rule matches.

Options:

• allow: Pass the request through.
• hide: Remove version from “latest” consideration.
• deny: Return a 403 response.

severity number#

rules:
- id: my-rule
  severity: 8.5

Severity score for the rule, between 0.0 and 10.0. Used to determine the effective action when action is not set:

• At or above severity_deny_threshold (default 9): resolves to deny.
• At or below severity_allow_threshold (default 4): resolves to allow.
• Between the two thresholds: resolves to hide.

reason string#

rules:
- id: my-rule
  reason: Package has a known critical vulnerability

Informational. Human-readable explanation for the rule’s action. Included in audit log entries and denial responses.

quarantine_days integer#

rules:
- id: new-packages
  quarantine_days: 1

Overrides default_quarantine_days from the firewall configuration for packages matched by this rule.

match list#

rules:
- id: my-rule
  match:
  - type: npm
    name: lodash

List of selectors that must match for the rule to apply. A package must match at least one selector in the list.

exclude list#

rules:
- id: my-rule
  match:
  - type: npm
  exclude:
  - name: trusted-package

List of selectors that exempt a package from this rule. A package matching any exclude selector is not subject to the rule, even if it also matches a match selector.

Selectors#

Selectors are used in both match and exclude lists. All specified fields within a selector must match (AND logic). Multiple selectors in a list are combined with OR logic.

purl string#

- purl: pkg:npm/example@1.2.3

Match by Package URL (PURL). Package type and name are mandatory for PURLs, namespace and version are optional.

PURL only support exact versions. When a version range is needed, use the version field with VERS notation.

Mutually exclusive with type and name.

type string#

- type: npm
  name: example

Match by package ecosystem type (e.g. npm, pypi).

When type is used, name is also mandatory. Mutually exclusive with purl

namespace string#

- type: npm
  namespace: angular
  name: example

Match by package namespace (e.g. the npm scope). Simple glob patterns are supported.

name string#

- type: npm
  name: example

Match by package name. Simple glob patterns are supported.

When name is used, type is also mandatory. Mutually exclusive with purl

version string#

- purl: pkg:npm/example
  version: vers:npm/1.2.3|>=2.0.0|<5.0.0

Match by package version or version range.

Version ranges are supported with VERS notation.