PackageUrl Policy

The PackageUrl policy enforces constraints on resolved package URLs (pURLs). It evaluates against Resolved Dependencies attestations (predicate type https://gradle.com/attestation/resolved-dependencies/v1).

Spec Fields

purls

A list of package URL patterns to match against resolved dependencies.

matchingStrategy

must-match requires that all resolved dependencies match one of the specified patterns. none-match requires that no dependency matches any specified pattern.

Package URL Pattern Syntax

Wildcards (*) may appear in namespace, artifact name, and version components. Matching is case-insensitive.

Pattern Matches Example

pkg:maven/org.example/artifact

Exact package, any version

pkg:maven/org.example/artifact@1.0.0

pkg:maven/org.example/artifact@1.0.0

Exact package and version

Only pkg:maven/org.example/artifact@1.0.0

pkg:maven/org.example/artifact@1.0.*

Wildcard patch version

pkg:maven/org.example/artifact@1.0.0, @1.0.5

pkg:maven/org.example/*

All artifacts in namespace

pkg:maven/org.example/foo, pkg:maven/org.example/bar

pkg:maven/org.example/\*@1.0.0

Namespace with specific version

pkg:maven/org.example/foo@1.0.0, pkg:maven/org.example/bar@1.0.0

pkg:maven/*/*

All Maven artifacts

Any Maven package

pkg:npm/@scope/*

All packages in npm scope

pkg:npm/@scope/package-a, pkg:npm/@scope/package-b

Examples

Disallow a Specific Dependency

apiVersion: policy.gradle.com/v1
kind: PackageUrl
metadata:
  name: none-match-purl-lombok
  labels:
    policy.my-corp.com/gate: build
spec:
  resultsLabels:
    policy.my-corp.com/gate: build
  description: Disallow lombok dependency
  remediation: Remove lombok dependency from project
  matchingStrategy: none-match
  purls:
    - pkg:maven/org.projectlombok/lombok

Find Usages of a Specific Version

apiVersion: policy.gradle.com/v1
kind: PackageUrl
metadata:
  name: none-match-purl-spring-beans-6.2.7
  labels:
    policy.my-corp.com/gate: build
spec:
  resultsLabels:
    policy.my-corp.com/gate: build
  description: Find usages of spring 6.2.7
  remediation: Upgrade dependency to spring 6.2.7
  matchingStrategy: none-match
  purls:
    - pkg:maven/org.springframework/*@6.2.7

Require Approved Patch Versions

apiVersion: policy.gradle.com/v1
kind: PackageUrl
metadata:
  name: must-match-approved-spring-versions
  labels:
    policy.my-corp.com/gate: build
spec:
  resultsLabels:
    policy.my-corp.com/gate: build
  description: Ensure only approved patch versions of Spring Framework are used
  remediation: Upgrade or downgrade to approved patch version (e.g., 6.0.10, 6.1.5)
  matchingStrategy: must-match
  purls:
    - pkg:maven/org.springframework/spring-core@6.0.10
    - pkg:maven/org.springframework/spring-beans@6.0.10
    - pkg:maven/org.springframework/spring-web@6.0.10
    - pkg:maven/org.springframework/spring-core@6.1.5
    - pkg:maven/org.springframework/spring-beans@6.1.5
    - pkg:maven/org.springframework/spring-web@6.1.5