Dependency Proxy Package Rules

Package rules decide which packages the dependency proxy serves. Each rule is a CEL (Common Expression Language) expression that is evaluated against the requested package. Rules are configured per organization, project or repository in the Dependency Proxy settings and apply to requests using the proxy URL of that scope.

The malicious package check always runs, independently of your rules — an allow rule can never let a known malicious package through.

Format

Rules are written in YAML:

FieldDescription
nameShown in the error message when the rule blocks a package.
actiondeny blocks a matching package, allow lets it through.
exprA CEL expression that evaluates to a boolean. true means the rule matches.

Evaluation

  • Rules are evaluated top to bottom and the last matching rule wins. Put general rules first and exceptions below them.
  • A package that matches no rule is allowed.
  • A configuration with invalid YAML, an unknown action or an expression that does not compile is rejected when saving.
  • If an expression fails at runtime — for example because it reads a field the package does not have — the package is blocked (fail closed).

A blocked download is answered with 403 Forbidden, the header X-Not-Allowed-Package: blocked and the name of the rule. Blocked versions are also hidden from the version lists, so version ranges resolve to an allowed version. npm, PyPI and Composer check every version; Go and Maven check from the newest version downwards until the first allowed one, because each check needs an extra request for the release time. For Debian, the proxy replaces blocked versions in the package list with the newest allowed older version and signs the list with its own key, see Setup Debian Proxy.

The pkg variable

FieldTypeDescription
pkg.namestringPackage name, e.g. lodash, @babel/core, github.com/gin-gonic/gin
pkg.versionstringRequested version
pkg.ecosystemstringnpm, go, pypi, maven, composer, deb, apk or oci
pkg.purlstringe.g. pkg:npm/lodash@4.17.21; OCI uses the image reference, e.g. docker.io/library/nginx:latest
pkg.registrystringUpstream registry, e.g. https://pypi.org
pkg.releasedAtstring (RFC 3339)Publish time of the version. Use timestamp(pkg.releasedAt) to compare it.
pkg.publisher.namestringUser who published this version (npm only)
pkg.publisher.changedSinceLastVersionboolThe publisher differs from the one of the previously published version (npm only)
pkg.suitestringDebian suite, e.g. trixie or trixie-security (Debian only)

Not every ecosystem provides every field:

EcosystemSource of releasedAtpublisher
npmtime field of the package metadata✓
Go modulesTime field of the .info file–
PyPIUpload time of the file–
Composertime field reported by Packagist–
MavenLast-Modified header from Maven Central–
DebianFirst appearance in the suite according to snapshot.debian.org and metasnap.debian.net, see Release times–
AlpineLast-Modified header from the Alpine mirror–
OCInot available–

Missing fields

Fields that are not available are absent, not empty. Reading an absent field makes the expression fail, which blocks the package. Use has() to decide explicitly what happens:

Expressions that start with ! must be quoted, otherwise YAML reads the ! as a tag.

Warning

OCI images never have a release time. A minimum age rule without has() or an pkg.ecosystem != "oci" check blocks every image.

Functions

FunctionExample
now()Current time as timestamp
timestamp(string)timestamp(pkg.releasedAt)
duration(string)duration("120h") — hours, minutes or seconds (h, m, s)
has(field)has(pkg.publisher)
startsWith, endsWith, contains, matchespkg.name.startsWith("@evil-scope/"), pkg.name.matches("^left-?pad$")
inpkg.ecosystem in ["npm", "pypi"]

All standard CEL operators (==, !=, <, &&, ||, !) are available.

Cookbook

Minimum release age

Exception for one package

Place it below the rule it overrides.

Block a whole npm scope

Block one exact version

Block versions published by a new maintainer

Account takeovers often publish a new version from a different account.

Allow only one ecosystem

Have feedback? We want to hear from you!

Fields marked with * are required