Varnish Orca
← Varnish Orca Configuration

Artifact Firewall

Note: Orca Premium feature

Configuration for the Varnish Artifact Firewall.

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

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

address string

firewall:
  address: 0.0.0.0

Default: localhost

Address and/or port for the Artifact Firewall proxy to listen on. Defaults to localhost when behind Virtual Registry.

port integer

firewall:
  port: 6089

Default: 6089

Port for the Artifact Firewall proxy to listen on.

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.

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.

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.