Artifact Firewall

Configuration for the Varnish Artifact Firewall.

To enable the firewall for a specific virtual registry, set enable_firewall on the registry.

Within Orca, the Supervisor always runs the firewall in integrated mode behind the Virtual Registry, which handles request routing. The firewall’s standalone deployment options (deployment, upstream registries, and their routes) therefore do not apply here.

Example:

virtual_registry:
  registries:
  - name: npmjs
    default: true
    enable_firewall: true
    remotes:
    - url: https://registry.npmjs.org

firewall:
  default_action: allow
  rulesets:
  - path: /path/to/custom/ruleset.yaml
  - git:
      name: npm-osv-rules
      url: https://github.com/varnish/osv-rules.git
      sub_path: rulesets/npm/all.yaml

address string#

firewall:
  address: 0.0.0.0

Default: 127.0.0.1

Address and/or port for the Artifact Firewall proxy to listen on. The Supervisor binds it to 127.0.0.1 when omitted in integrated mode.

port integer#

firewall:
  port: 6089

Default: 6089

Port for the Artifact Firewall proxy to listen on.

api_address string#

firewall:
  api_address: 127.0.0.1:6090

Default: 127.0.0.1:6090

Listen address for the firewall admin API (/api/eval, /api/update, /api/mode), in host:port form. In integrated mode the Virtual Registry calls this API to authorize per-version artifact downloads; the Supervisor binds it to 127.0.0.1:6090 when omitted.

log_level string#

firewall:
  log_level: info

Default: info

Log level for Artifact Firewall output.

Options:

• debug
• info
• warn
• error

log_output string#

firewall:
  log_output: stdout

Destination for Artifact Firewall logs.

Options:

• stdout
• stderr
• A file path (e.g. /var/log/artifact-firewall.log)

audit_log_output string#

firewall:
  audit_log_output: /var/log/artifact-firewall-audit.log

Default: stdout

Destination for the audit log, which records every decision made by the Artifact Firewall. When empty, audit logging is disabled.

Options:

• stdout
• stderr
• A file path (e.g. /var/log/artifact-firewall-audit.log)

default_action string#

firewall:
  default_action: deny

Default: allow

Action taken when a request does not match any rule in the configured rulesets.

Options:

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

mode string#

firewall:
  mode: report

Default: normal

Global mode that reshapes how matched rule actions are enforced, useful for testing rulesets before enforcing them.

Options:

• normal: Enforce rule actions as configured.
• hide: Downgrade deny actions to hide, so blocked versions are removed from “latest” consideration instead of being rejected outright.
• report: Downgrade all actions to allow, so nothing is blocked. Decisions are still recorded in the audit log via the effective_action field, making this a report-only mode for evaluating a ruleset’s impact.

default_quarantine_days integer#

firewall:
  default_quarantine_days: 2

Default: 0 (disabled)

When set to a positive integer, newly published packages within this many days of their release are blocked regardless of ruleset matches. This provides a quarantine window to guard against newly introduced malicious packages.

Set to 0 to disable quarantine.

severity_deny_threshold number#

firewall:
  severity_deny_threshold: 9.0

Default: 9

Severity score at or above which a matching rule resolves to deny. Rules with a severity score at or above this threshold override their configured action and deny the request.

severity_allow_threshold number#

firewall:
  severity_allow_threshold: 4.0

Default: 4

Severity score at or below which a matching rule resolves to allow. Rules with a severity score at or below this threshold override their configured action and allow the request.

rulesets list#

firewall:
  rulesets:
  - path: /etc/orca/rulesets

List of ruleset sources. Each entry can reference either a local path or a remote Git repository.

path string#

firewall:
  rulesets:
  - path: /etc/orca/rulesets

Path to a ruleset file or a directory containing ruleset files. All files with a .yaml extension are interpreted as rulesets. Directories are scanned non-recursively.

git#

firewall:
  rulesets:
  - git:
      name: npm-osv-rules
      url: https://github.com/varnish/osv-rules.git
      sub_path: rulesets/npm/all.yaml

Fetch rulesets from a remote Git repository. The repository is cloned locally and refreshed on the configured interval.

name string#

Unique name for this Git ruleset source. Used to identify the source in logs and as a subdirectory name under work_dir.

url string#

URL of the Git repository.

ref string#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      ref: main

Default: repository default branch HEAD

Branch, tag, or commit SHA to check out.

sub_path string#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      sub_path: policies/npm

Path within the repository to use as the ruleset root. When empty, the repository root is used.

interval string#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      interval: 30m

Default: 1h

How often to pull updates from the remote repository. Accepts duration strings such as 30m or 2h.

fetch_timeout string#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      fetch_timeout: 60s

Default: 30s

Timeout for each fetch operation. Accepts duration strings such as 30s or 2m.

auth#

firewall:
  rulesets:
  - git:
      url: https://github.com/example/rulesets.git
      auth:
        token_env: GITHUB_TOKEN

Credentials for authenticating with the Git remote.

token_env string#

Name of the environment variable that holds the authentication token. The token is passed as an HTTP Bearer token when fetching from the remote.

webhook#

firewall:
  webhook:
    url: https://example.com/hooks/ruleset-reloaded

Optional webhook called after rulesets are successfully reloaded. When url is not set, no webhook is sent.

Unavailable when using Artifact Firewall with Virtual Registry, as the webhook is used for manifest cache invalidation.

url string#

URL to send an HTTP request to when rulesets are reloaded.

method string#

firewall:
  webhook:
    url: https://example.com/hooks/ruleset-reloaded
    method: POST

Default: GET

HTTP method to use for the webhook request.

headers map#

firewall:
  webhook:
    url: https://example.com/hooks/ruleset-reloaded
    headers:
      Authorization: "Bearer my-secret-token"

Custom HTTP headers to include in the webhook request.

preserve_manifest boolean#

firewall:
  preserve_manifest: true

Default: false

Pass manifests through to the client without any transformation. When disabled, the firewall may rewrite manifest content.

max_manifest_size integer#

firewall:
  max_manifest_size: 67108864

Default: 67108864 (64 MiB)

Maximum manifest body size in bytes that the firewall will read and process. Manifests larger than this limit are rejected.

work_dir string#

firewall:
  work_dir: /var/cache/artifact-firewall

Working directory used to store cached data for remote ruleset sources (e.g., cloned Git repositories). Defaults to a temporary directory if not set.

storage#

firewall:
  storage:
    path: /var/lib/varnish-artifact-firewall/storage
    size: 10G

Persistent storage for the ruleset cache — cloned Git repositories and downloaded ruleset files. When path is set, it takes precedence over work_dir for these caches.

path string#

Directory where the ruleset cache (cloned Git repositories and downloaded ruleset files) is stored. Overrides work_dir for these caches when set.

size string#

Declared storage budget for the ruleset cache, such as 10G. When both path and size are set, the firewall enforces it as a growth limit: it stops growing cloned repositories once usage reaches size, preventing the cache from filling the disk over time. It also warns when usage reaches 80% of size, and warns at startup if the filesystem hosting path is significantly smaller than size.

Sizes follow Varnish conventions: a bare integer is bytes, while the suffixes K, M, G, and T (case-insensitive) are binary multipliers (for example 10G is 10 × 2^30 bytes).

metrics_address string#

firewall:
  metrics_address: :9090

Default: :9090

Address for the Prometheus metrics endpoint, in host:port form. When empty, the metrics server is disabled.

preserve_order boolean#

firewall:
  preserve_order: true

Default: false

Preserve the original JSON map key order in manifests. Enabling this is significantly slower and is primarily useful for debugging or diffing manifest transformations.

maven#

firewall:
  maven:
    solr_url: https://search.maven.org/solrsearch/select

Maven-specific configuration, used when a virtual registry proxying a Maven repository has the firewall enabled.

solr_url string#

Default: https://search.maven.org/solrsearch/select

Solr search endpoint used to look up Maven artifact publish timestamps for the quarantine window (see default_quarantine_days). When empty, Solr lookups are disabled and the firewall falls back to HEAD requests to determine timestamps.