actions: add lockfile-to-data-extension generator for unpinned-tag

Add a Go tool that parses a repository's Actions lockfile
(.github/workflows/actions.lock) with the canonical parser at
github.com/github/actions-lockfile/go and emits a CodeQL data extension
populating pinnedByLockfileDataModel, the predicate the actions/unpinned-tag
query already consumes to suppress lockfile-pinned refs.

The generator is transport-agnostic: it produces the same
[workflow_path, nwo, ref] rows whether they ship as a model pack applied via
--model-packs (as today, mirroring codeql/immutable-actions-list) or later feed
an extractor-native relation, so the parsing core is reusable without touching
the query.

Lockfiles record the resolved ref (e.g. v4.3.1) while workflows usually write a
shorter mutable tag (v4). Since the query matches the ref as written, the
generator expands every full-semver resolved ref into its major.minor and
major-only forms, so uses: owner/action@v4 is recognized as pinned by a
v4.3.1 lockfile entry. Verified end to end against a synthetic repo: the
lockfile-pinned short-tag ref is suppressed while unlocked refs still report.

actions-lockfile is not yet public, so go.mod carries a local replace directive
for building and testing; remove it once the module is published.

Author: nodeselector

actions/extractor/tools/lockfile-extension-generator/.gitignore

@@ -0,0 +1 @@
+/lockfile-extension-generator

actions/extractor/tools/lockfile-extension-generator/README.md

@@ -0,0 +1,75 @@
+# lockfile-extension-generator
+
+Turns a repository's GitHub Actions lockfile (`.github/workflows/actions.lock`)
+into a CodeQL data extension that populates the `pinnedByLockfileDataModel`
+extensible predicate consumed by the `actions/unpinned-tag`
+(`js/actions/actions-workflow-unpinned-tag`) query.
+
+## Why
+
+`actions/unpinned-tag` flags `uses:` references pinned to a mutable tag (e.g.
+`actions/checkout@v4`) rather than an immutable commit SHA. When a repository
+maintains an Actions lockfile, every such tag is already bound to a verified
+commit SHA at run time by the lockfile — which is exactly the pinning evidence
+the query otherwise lacks. Feeding the lockfile's bindings into
+`pinnedByLockfileDataModel` lets the query suppress those references while still
+flagging genuinely unpinned ones.
+
+The generator is deliberately **transport-agnostic**. It parses the lockfile
+with the canonical parser at `github.com/github/actions-lockfile/go` and emits
+the `[workflow_path, nwo, ref]` rows the query already matches on. Today those
+rows ship as a data-extension model pack applied at analysis time via
+`--model-packs` (the same mechanism as `codeql/immutable-actions-list`). The
+same parsing core can later feed an extractor-native relation without changing
+the query.
+
+## Ref normalization
+
+A lockfile records the *resolved* ref for each dependency — the CLI prefers a
+full semver tag such as `v4.3.1`. A workflow author, however, usually writes a
+shorter, mutable tag such as `v4` or `v4.3` in `uses:`, and the query matches on
+the ref exactly as written. For every full-semver resolved ref the generator
+therefore also emits its major.minor (`v4.3`) and major-only (`v4`) forms, so a
+`uses: owner/action@v4` is recognized as pinned by a lockfile entry that
+resolved to `v4.3.1`. Partial tags, pre-release tags, branches, and SHAs pass
+through unchanged.
+
+## Usage
+
+```
+lockfile-extension-generator <source-root> [output-file]
+```
+
+- `<source-root>`: repository root to scan; the lockfile is read from
+  `<source-root>/.github/workflows/actions.lock`.
+- `[output-file]`: destination for the extension YAML; defaults to stdout.
+
+If the repository has no lockfile the generator exits successfully without
+writing anything, so it is safe to run unconditionally.
+
+## Building and testing locally
+
+`github.com/github/actions-lockfile` is not yet public, so the module cannot be
+fetched by the module proxy. Point the `replace` directive in `go.mod` at a
+local clone before building or testing:
+
+```
+go mod edit -replace github.com/github/actions-lockfile/go=/path/to/actions-lockfile/go
+go test ./...
+```
+
+Remove the `replace` directive once actions-lockfile is published.
+
+## End-to-end check
+
+```
+# A repo whose workflow writes `uses: owner/action@v4` while the lockfile
+# resolves it to v4.3.1:
+lockfile-extension-generator /path/to/repo /tmp/pack/ext/pinned.yml
+codeql database analyze <db> \
+  codeql/actions-queries:Security/CWE-829/UnpinnedActionsTag.ql \
+  --additional-packs=/tmp/pack --model-packs=<your-pack-name>
+```
+
+The lockfile-pinned reference is suppressed; references not covered by the
+lockfile are still reported.

actions/extractor/tools/lockfile-extension-generator/generator.go

@@ -0,0 +1,117 @@
+// Package main implements a generator that turns a repository's Actions lockfile
+// (`.github/workflows/actions.lock`) into a CodeQL data extension populating the
+// `pinnedByLockfileDataModel` extensible predicate consumed by the
+// `actions/unpinned-tag` query.
+//
+// The generator is deliberately transport-agnostic: it parses the lockfile with
+// the canonical parser at `github.com/github/actions-lockfile/go` and emits the
+// same `[workflow_path, nwo, ref]` rows the query already matches on. Today those
+// rows are shipped as a data-extension model pack (applied at analysis time via
+// `--model-packs`, exactly like `codeql/immutable-actions-list`). The same parsing
+// core can later feed an extractor-native TRAP relation without changing the query.
+package main
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/github/actions-lockfile/go/pkg/lockfile"
+)
+
+// row is a single `pinnedByLockfileDataModel` tuple: the reference
+// `nwo`@`ref` in the workflow or composite action file at `workflowPath` is
+// pinned by the repository's Actions lockfile.
+type row struct {
+	workflowPath string
+	nwo          string
+	ref          string
+}
+
+// rowsFromLockfile parses lockfile `contents` and returns the deduplicated,
+// sorted set of `pinnedByLockfileDataModel` rows it implies.
+//
+// A lockfile records the *resolved* ref for each dependency (the CLI prefers a
+// full semver tag such as `v4.3.1`), but a workflow author usually writes a
+// shorter, mutable tag such as `v4` or `v4.3` in `uses:`. The query matches on
+// the ref exactly as written, so for every full-semver resolved ref we also
+// emit its major-only (`v4`) and major.minor (`v4.3`) forms. This lets a
+// `uses: owner/action@v4` be recognised as pinned by a lockfile entry that
+// resolved to `v4.3.1`, which is the common real-world case.
+func rowsFromLockfile(contents []byte) ([]row, error) {
+	f, err := lockfile.Parse(contents)
+	if err != nil {
+		return nil, fmt.Errorf("parsing lockfile: %w", err)
+	}
+
+	seen := make(map[row]struct{})
+	for workflowPath, pinKeys := range f.Workflows {
+		for _, key := range pinKeys {
+			pin, ok := lockfile.ParsePin(key)
+			if !ok {
+				continue
+			}
+			// Prefer the resolved ref recorded in the dependency metadata; fall
+			// back to the ref embedded in the pin key.
+			ref := pin.Ref
+			if dep, ok := f.Dependencies[key]; ok && dep.Ref != "" {
+				ref = dep.Ref
+			}
+			for _, r := range refVariants(ref) {
+				seen[row{workflowPath: workflowPath, nwo: pin.NWO, ref: r}] = struct{}{}
+			}
+		}
+	}
+
+	rows := make([]row, 0, len(seen))
+	for r := range seen {
+		rows = append(rows, r)
+	}
+	sort.Slice(rows, func(i, j int) bool {
+		if rows[i].workflowPath != rows[j].workflowPath {
+			return rows[i].workflowPath < rows[j].workflowPath
+		}
+		if rows[i].nwo != rows[j].nwo {
+			return rows[i].nwo < rows[j].nwo
+		}
+		return rows[i].ref < rows[j].ref
+	})
+	return rows, nil
+}
+
+// refVariants returns every ref string a workflow author might have written in
+// `uses:` that the resolved `ref` covers. For a full semver tag (e.g. `v4.3.1`)
+// this is the tag itself plus its major.minor (`v4.3`) and major-only (`v4`)
+// forms; for anything else (a branch, a partial tag, a SHA) it is just the ref.
+func refVariants(ref string) []string {
+	sv, ok := lockfile.ParseSemVer(ref)
+	if !ok || !sv.IsFull() {
+		return []string{ref}
+	}
+	variants := []string{ref}
+	if minor := sv.MinorTag(); minor != ref {
+		variants = append(variants, minor)
+	}
+	if major := sv.MajorTag(); major != ref {
+		variants = append(variants, major)
+	}
+	return variants
+}
+
+// renderExtension serialises `rows` as a CodeQL data-extension YAML document that
+// adds to the `pinnedByLockfileDataModel` extensible predicate in
+// `codeql/actions-all`.
+func renderExtension(rows []row) string {
+	var b strings.Builder
+	b.WriteString("# Generated by lockfile-extension-generator from .github/workflows/actions.lock.\n")
+	b.WriteString("# Do not edit by hand; regenerate from the repository's Actions lockfile.\n")
+	b.WriteString("extensions:\n")
+	b.WriteString("  - addsTo:\n")
+	b.WriteString("      pack: codeql/actions-all\n")
+	b.WriteString("      extensible: pinnedByLockfileDataModel\n")
+	b.WriteString("    data:\n")
+	for _, r := range rows {
+		fmt.Fprintf(&b, "      - [%q, %q, %q]\n", r.workflowPath, r.nwo, r.ref)
+	}
+	return b.String()
+}

actions/extractor/tools/lockfile-extension-generator/generator_test.go

@@ -0,0 +1,91 @@
+package main
+
+import (
+	"os"
+	"testing"
+)
+
+func TestRowsFromLockfile(t *testing.T) {
+	contents, err := os.ReadFile("testdata/actions.lock")
+	if err != nil {
+		t.Fatalf("reading fixture: %v", err)
+	}
+
+	rows, err := rowsFromLockfile(contents)
+	if err != nil {
+		t.Fatalf("rowsFromLockfile: %v", err)
+	}
+
+	// Every full-semver resolved ref expands to {raw, minor, major} so a
+	// workflow that writes a shorter tag in `uses:` still matches. Rows are
+	// sorted by (workflowPath, nwo, ref).
+	want := []row{
+		{".github/workflows/ci.yml", "actions/checkout", "v4"},
+		{".github/workflows/ci.yml", "actions/checkout", "v4.3"},
+		{".github/workflows/ci.yml", "actions/checkout", "v4.3.1"},
+		{".github/workflows/ci.yml", "some-owner/pinned-action", "v1"},
+		{".github/workflows/ci.yml", "some-owner/pinned-action", "v1.2"},
+		{".github/workflows/ci.yml", "some-owner/pinned-action", "v1.2.0"},
+		{".github/workflows/release.yml", "actions/checkout", "v4"},
+		{".github/workflows/release.yml", "actions/checkout", "v4.3"},
+		{".github/workflows/release.yml", "actions/checkout", "v4.3.1"},
+	}
+
+	if len(rows) != len(want) {
+		t.Fatalf("got %d rows, want %d:\n%#v", len(rows), len(want), rows)
+	}
+	for i := range want {
+		if rows[i] != want[i] {
+			t.Errorf("row %d: got %+v, want %+v", i, rows[i], want[i])
+		}
+	}
+}
+
+func TestRefVariants(t *testing.T) {
+	cases := []struct {
+		ref  string
+		want []string
+	}{
+		{"v4.3.1", []string{"v4.3.1", "v4.3", "v4"}},
+		{"v1.0.0", []string{"v1.0.0", "v1.0", "v1"}},
+		// Partial tags are already their own broadest form.
+		{"v4", []string{"v4"}},
+		{"v4.3", []string{"v4.3"}},
+		// Pre-release and non-semver refs pass through untouched.
+		{"v2.0.0-beta.1", []string{"v2.0.0-beta.1"}},
+		{"main", []string{"main"}},
+	}
+	for _, c := range cases {
+		got := refVariants(c.ref)
+		if len(got) != len(c.want) {
+			t.Errorf("refVariants(%q) = %v, want %v", c.ref, got, c.want)
+			continue
+		}
+		for i := range c.want {
+			if got[i] != c.want[i] {
+				t.Errorf("refVariants(%q) = %v, want %v", c.ref, got, c.want)
+				break
+			}
+		}
+	}
+}
+
+func TestRenderExtensionMatchesGolden(t *testing.T) {
+	contents, err := os.ReadFile("testdata/actions.lock")
+	if err != nil {
+		t.Fatalf("reading fixture: %v", err)
+	}
+	rows, err := rowsFromLockfile(contents)
+	if err != nil {
+		t.Fatalf("rowsFromLockfile: %v", err)
+	}
+	got := renderExtension(rows)
+
+	want, err := os.ReadFile("testdata/expected.yml")
+	if err != nil {
+		t.Fatalf("reading golden: %v", err)
+	}
+	if got != string(want) {
+		t.Errorf("rendered extension does not match testdata/expected.yml:\n--- got ---\n%s", got)
+	}
+}

actions/extractor/tools/lockfile-extension-generator/go.mod

@@ -0,0 +1,16 @@
+module github.com/github/codeql/actions/extractor/tools/lockfile-extension-generator
+
+go 1.23
+
+require github.com/github/actions-lockfile/go v0.0.0-00010101000000-000000000000
+
+require gopkg.in/yaml.v3 v3.0.1 // indirect
+
+// LOCAL TESTING ONLY: github.com/github/actions-lockfile is not yet public, so it
+// cannot be fetched by the module proxy. Point this at a local clone of the
+// repository to build and test the generator:
+//
+//   go mod edit -replace github.com/github/actions-lockfile/go=/path/to/actions-lockfile/go
+//
+// Remove this replace directive once actions-lockfile is published.
+replace github.com/github/actions-lockfile/go => /Users/nodeselector/ghq/github.com/github/actions-lockfile/go

actions/extractor/tools/lockfile-extension-generator/go.sum

@@ -0,0 +1,10 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

actions/extractor/tools/lockfile-extension-generator/main.go

@@ -0,0 +1,57 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/github/actions-lockfile/go/pkg/lockfile"
+)
+
+// main reads a repository's Actions lockfile and writes the corresponding
+// `pinnedByLockfileDataModel` data extension.
+//
+// Usage:
+//
+//	lockfile-extension-generator <source-root> [output-file]
+//
+// `<source-root>` is the root of the repository to scan; the lockfile is read
+// from `<source-root>/.github/workflows/actions.lock`. When `[output-file]` is
+// omitted the extension is written to stdout. If the repository has no lockfile
+// the generator exits successfully without writing anything, so it is safe to
+// run unconditionally.
+func main() {
+	if len(os.Args) < 2 || len(os.Args) > 3 {
+		fmt.Fprintf(os.Stderr, "usage: %s <source-root> [output-file]\n", filepath.Base(os.Args[0]))
+		os.Exit(2)
+	}
+	sourceRoot := os.Args[1]
+
+	lockPath := filepath.Join(sourceRoot, filepath.FromSlash(lockfile.Path))
+	contents, err := os.ReadFile(lockPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			// No lockfile: nothing to pin. A clean no-op keeps this safe to run
+			// against every repository.
+			return
+		}
+		fmt.Fprintf(os.Stderr, "error: reading %s: %v\n", lockPath, err)
+		os.Exit(1)
+	}
+
+	rows, err := rowsFromLockfile(contents)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
+	out := renderExtension(rows)
+	if len(os.Args) == 3 {
+		if err := os.WriteFile(os.Args[2], []byte(out), 0o644); err != nil {
+			fmt.Fprintf(os.Stderr, "error: writing %s: %v\n", os.Args[2], err)
+			os.Exit(1)
+		}
+		return
+	}
+	fmt.Print(out)
+}

actions/extractor/tools/lockfile-extension-generator/testdata/actions.lock

@@ -0,0 +1,19 @@
+# Machine-generated by `gh actions-lock`; used here as a test fixture.
+version: 'v0.0.2'
+workflows:
+    '.github/workflows/ci.yml':
+        - 'actions/checkout@v4.3.1'
+        - 'some-owner/pinned-action@v1.2.0'
+    '.github/workflows/release.yml':
+        - 'actions/checkout@v4.3.1'
+dependencies:
+    'actions/checkout@v4.3.1':
+        ref: 'v4.3.1'
+        commit: 'sha1-34e114876b0b11c390a56381ad16ebd13914f8d5'
+        owner_id: 44036562
+        repo_id: 197814629
+    'some-owner/pinned-action@v1.2.0':
+        ref: 'v1.2.0'
+        commit: 'sha1-1111111111111111111111111111111111111111'
+        owner_id: 12345
+        repo_id: 67890