feat: Add PURL (Package URL) builtin functions

Add two new built-in functions for working with Package URLs (PURLs):
- purl.is_valid(purl): Validates a PURL string
- purl.parse(purl): Parses a PURL string into its components

These functions help with software supply chain security by making it
easier to validate and parse package identifiers in policies.

Example usage:
  purl.is_valid("pkg:npm/[email protected]") # returns true
  purl.parse("pkg:npm/[email protected]") # returns {type: "npm", name: "express", version: "4.18.2"}

Fixes #6504

Signed-off-by: Anivar A Aravind <[email protected]>

Author: Anivar A Aravind

ast/builtins.go

@@ -324,6 +324,12 @@ var YAMLUnmarshal = v1.YAMLUnmarshal
 // YAMLIsValid verifies the input string is a valid YAML document.
 var YAMLIsValid = v1.YAMLIsValid
 
+// PurlIsValid validates that the input is a valid Package URL (PURL).
+var PurlIsValid = v1.PurlIsValid
+
+// PurlParse parses a Package URL (PURL) string into its components.
+var PurlParse = v1.PurlParse
+
 var HexEncode = v1.HexEncode
 
 var HexDecode = v1.HexDecode

builtin_metadata.json

@@ -62,6 +62,8 @@
       "json.marshal",
       "json.marshal_with_options",
       "json.unmarshal",
+      "purl.is_valid",
+      "purl.parse",
       "urlquery.decode",
       "urlquery.decode_object",
       "urlquery.encode",
@@ -17075,6 +17077,46 @@
     },
     "wasm": false
   },
+  "purl.is_valid": {
+    "args": [
+      {
+        "description": "Package URL string to validate",
+        "name": "purl",
+        "type": "string"
+      }
+    ],
+    "available": [
+      "edge"
+    ],
+    "description": "Validates that the input is a valid Package URL (PURL).",
+    "introduced": "edge",
+    "result": {
+      "description": "`true` if `purl` is a valid Package URL; `false` otherwise",
+      "name": "result",
+      "type": "boolean"
+    },
+    "wasm": false
+  },
+  "purl.parse": {
+    "args": [
+      {
+        "description": "Package URL string to parse",
+        "name": "purl",
+        "type": "string"
+      }
+    ],
+    "available": [
+      "edge"
+    ],
+    "description": "Parses a Package URL (PURL) string into its components.",
+    "introduced": "edge",
+    "result": {
+      "description": "object containing PURL components: type, namespace, name, version, qualifiers, subpath",
+      "name": "result",
+      "type": "object[string: any]"
+    },
+    "wasm": false
+  },
   "rand.intn": {
     "args": [
       {

capabilities.json

@@ -3460,6 +3460,42 @@
         "type": "function"
       }
     },
+    {
+      "name": "purl.is_valid",
+      "decl": {
+        "args": [
+          {
+            "type": "string"
+          }
+        ],
+        "result": {
+          "type": "boolean"
+        },
+        "type": "function"
+      }
+    },
+    {
+      "name": "purl.parse",
+      "decl": {
+        "args": [
+          {
+            "type": "string"
+          }
+        ],
+        "result": {
+          "dynamic": {
+            "key": {
+              "type": "string"
+            },
+            "value": {
+              "type": "any"
+            }
+          },
+          "type": "object"
+        },
+        "type": "function"
+      }
+    },
     {
       "name": "rand.intn",
       "decl": {

go.mod

@@ -83,6 +83,7 @@ require (
 	github.com/miekg/dns v1.1.57 // indirect
 	github.com/moby/locker v1.0.1 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/package-url/packageurl-go v0.1.3 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/prometheus/common v0.65.0 // indirect
 	github.com/prometheus/procfs v0.16.1 // indirect

go.sum

@@ -121,6 +121,8 @@ github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8
 github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
 github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
 github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
+github.com/package-url/packageurl-go v0.1.3 h1:4juMED3hHiz0set3Vq3KeQ75KD1avthoXLtmE3I0PLs=
+github.com/package-url/packageurl-go v0.1.3/go.mod h1:nKAWB8E6uk1MHqiS/lQb9pYBGH2+mdJ2PJc2s50dQY0=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/peterh/liner v1.2.2 h1:aJ4AOodmL+JxOZZEL2u9iJf8omNRpqHc/EbrK+3mAXw=

v1/ast/builtins.go

@@ -170,6 +170,8 @@ var DefaultBuiltins = [...]*Builtin{
 	YAMLMarshal,
 	YAMLUnmarshal,
 	YAMLIsValid,
+	PurlIsValid,
+	PurlParse,
 	HexEncode,
 	HexDecode,
 
@@ -2063,6 +2065,32 @@ var YAMLIsValid = &Builtin{
 	canSkipBctx: true,
 }
 
+var PurlIsValid = &Builtin{
+	Name:        "purl.is_valid",
+	Description: "Validates that the input is a valid Package URL (PURL).",
+	Decl: types.NewFunction(
+		types.Args(
+			types.Named("purl", types.S).Description("Package URL string to validate"),
+		),
+		types.Named("result", types.B).Description("`true` if `purl` is a valid Package URL; `false` otherwise"),
+	),
+	Categories:  encoding,
+	canSkipBctx: true,
+}
+
+var PurlParse = &Builtin{
+	Name:        "purl.parse",
+	Description: "Parses a Package URL (PURL) string into its components.",
+	Decl: types.NewFunction(
+		types.Args(
+			types.Named("purl", types.S).Description("Package URL string to parse"),
+		),
+		types.Named("result", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))).Description("object containing PURL components: type, namespace, name, version, qualifiers, subpath"),
+	),
+	Categories:  encoding,
+	canSkipBctx: true,
+}
+
 var HexEncode = &Builtin{
 	Name:        "hex.encode",
 	Description: "Serializes the input string using hex-encoding.",

v1/test/cases/testdata/v1/purlbuiltins/test-purl-is-valid.yaml

@@ -0,0 +1,45 @@
+---
+cases:
+  - note: purlbuiltins/is_valid_npm
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.is_valid("pkg:npm/[email protected]", x)
+        }
+    want_result:
+      - x: true
+
+  - note: purlbuiltins/is_valid_maven
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.is_valid("pkg:maven/org.apache.xmlgraphics/[email protected]", x)
+        }
+    want_result:
+      - x: true
+
+  - note: purlbuiltins/is_valid_invalid
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.is_valid("not-a-purl", x)
+        }
+    want_result:
+      - x: false
+
+  - note: purlbuiltins/is_valid_empty
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.is_valid("", x)
+        }
+    want_result:
+      - x: false

v1/test/cases/testdata/v1/purlbuiltins/test-purl-parse.yaml

@@ -0,0 +1,88 @@
+---
+cases:
+  - note: purlbuiltins/parse_simple
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.parse("pkg:npm/[email protected]", x)
+        }
+    want_result:
+      - x:
+          type: "npm"
+          name: "foobar"
+          version: "12.3.1"
+
+  - note: purlbuiltins/parse_with_namespace
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.parse("pkg:maven/org.apache.xmlgraphics/[email protected]", x)
+        }
+    want_result:
+      - x:
+          type: "maven"
+          namespace: "org.apache.xmlgraphics"
+          name: "batik-anim"
+          version: "1.9.1"
+
+  - note: purlbuiltins/parse_with_qualifiers
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.parse("pkg:rpm/fedora/[email protected]?arch=i386&distro=fedora-25", x)
+        }
+    want_result:
+      - x:
+          type: "rpm"
+          namespace: "fedora"
+          name: "curl"
+          version: "7.50.3-1.fc25"
+          qualifiers:
+            arch: "i386"
+            distro: "fedora-25"
+
+  - note: purlbuiltins/parse_with_subpath
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.parse("pkg:github/owner/[email protected]#path/to/file.js", x)
+        }
+    want_result:
+      - x:
+          type: "github"
+          namespace: "owner"
+          name: "repo"
+          version: "v1.0.0"
+          subpath: "path/to/file.js"
+
+  - note: purlbuiltins/parse_minimal
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.parse("pkg:npm/lodash", x)
+        }
+    want_result:
+      - x:
+          type: "npm"
+          name: "lodash"
+
+  - note: purlbuiltins/parse_invalid
+    query: data.generated.p = x
+    modules:
+      - |
+        package generated
+        p := x if {
+          purl.parse("not-a-purl", x)
+        }
+    want_error: 'purl.parse: invalid PURL'
+    strict_error: true

v1/topdown/purl.go

@@ -0,0 +1,69 @@
+// Copyright 2025 The OPA Authors.  All rights reserved.
+// Use of this source code is governed by an Apache2
+// license that can be found in the LICENSE file.
+
+package topdown
+
+import (
+	"fmt"
+
+	"github.com/package-url/packageurl-go"
+
+	"github.com/open-policy-agent/opa/v1/ast"
+	"github.com/open-policy-agent/opa/v1/topdown/builtins"
+)
+
+func builtinPurlIsValid(_ BuiltinContext, operands []*ast.Term, iter func(*ast.Term) error) error {
+	str, err := builtins.StringOperand(operands[0].Value, 1)
+	if err != nil {
+		return iter(ast.InternedTerm(false))
+	}
+
+	_, err = packageurl.FromString(string(str))
+	return iter(ast.InternedTerm(err == nil))
+}
+
+func builtinPurlParse(_ BuiltinContext, operands []*ast.Term, iter func(*ast.Term) error) error {
+	str, err := builtins.StringOperand(operands[0].Value, 1)
+	if err != nil {
+		return err
+	}
+
+	purl, err := packageurl.FromString(string(str))
+	if err != nil {
+		return fmt.Errorf("invalid PURL %q: %w", str, err)
+	}
+
+	// Create object with required fields
+	obj := ast.NewObject(
+		[2]*ast.Term{ast.InternedTerm("type"), ast.StringTerm(purl.Type)},
+		[2]*ast.Term{ast.InternedTerm("name"), ast.StringTerm(purl.Name)},
+	)
+
+	// Add optional fields only if present
+	if purl.Namespace != "" {
+		obj.Insert(ast.InternedTerm("namespace"), ast.StringTerm(purl.Namespace))
+	}
+	if purl.Version != "" {
+		obj.Insert(ast.InternedTerm("version"), ast.StringTerm(purl.Version))
+	}
+	if purl.Subpath != "" {
+		obj.Insert(ast.InternedTerm("subpath"), ast.StringTerm(purl.Subpath))
+	}
+
+	// Add qualifiers only if present
+	if len(purl.Qualifiers) > 0 {
+		qualifiers := ast.NewObject()
+		for _, q := range purl.Qualifiers {
+			qualifiers.Insert(ast.StringTerm(q.Key), ast.StringTerm(q.Value))
+		}
+		obj.Insert(ast.InternedTerm("qualifiers"), ast.NewTerm(qualifiers))
+	}
+
+	return iter(ast.NewTerm(obj))
+}
+
+func init() {
+	RegisterBuiltinFunc(ast.PurlIsValid.Name, builtinPurlIsValid)
+	RegisterBuiltinFunc(ast.PurlParse.Name, builtinPurlParse)
+}