actions/unpinned-tag: normalize lockfile action identity

Author: nodeselector

actions/ql/lib/change-notes/2026-07-09-pinned-by-lockfile.md

@@ -1,4 +1,4 @@
 ---
 category: minorAnalysis
 ---
-* Added a new extensible predicate `pinnedByLockfileDataModel(workflow_path, nwo, ref)`, which records `uses:` references that are pinned by a repository's Actions lockfile (`.github/workflows/actions.lock`). The CodeQL Actions extractor generates this data at database-creation time into a database-local model pack (`codeql/actions-lockfile-pins`); it has no effect unless that pack is supplied to analysis (for example via `--model-packs`), so behavior is unchanged for repositories without a lockfile or analyses that do not opt in.
+* Added a new extensible predicate `pinnedByLockfileDataModel(workflow_path, nwo, ref)`, which lets model packs record `uses:` references pinned by a repository's Actions lockfile (`.github/workflows/actions.lock`).

actions/ql/lib/codeql/actions/config/Config.qll

@@ -137,15 +137,22 @@ predicate trustedActionsOwnerDataModel(string owner) {
 
 /**
  * MaD models for `uses` references pinned by the repository's Actions lockfile
- * (`.github/workflows/actions.lock`). Populated by the CodeQL Actions extractor; see
- * `pinnedByLockfileDataModel` in `ConfigExtensions.qll`.
+ * (`.github/workflows/actions.lock`).
  * Fields:
  *    - workflow_path: repo-relative path of the file containing the `uses:` reference
- *    - nwo: owner and name of the referenced action (e.g. `actions/checkout`)
+ *    - nwo: referenced action, optionally including a sub-action path (e.g. `actions/cache/save`)
  *    - ref: the ref as written in `uses:` (e.g. `v4`)
  */
+bindingset[nwo]
 predicate pinnedByLockfileDataModel(string workflow_path, string nwo, string ref) {
-  Extensions::pinnedByLockfileDataModel(workflow_path, nwo, ref)
+  exists(string pinnedNwo |
+    Extensions::pinnedByLockfileDataModel(workflow_path, pinnedNwo, ref) and
+    (
+      nwo.toLowerCase() = pinnedNwo
+      or
+      nwo.toLowerCase().prefix(pinnedNwo.length() + 1) = pinnedNwo + "/"
+    )
+  )
 }
 
 /**

actions/ql/lib/codeql/actions/config/ConfigExtensions.qll

@@ -73,17 +73,14 @@ extensible predicate trustedActionsOwnerDataModel(string owner);
  * `workflow_path` is pinned by an entry in the repository's Actions lockfile
  * (`.github/workflows/actions.lock`).
  *
- * This predicate is intended to be populated by the CodeQL Actions extractor, which parses
- * `actions.lock` at database-creation time using the canonical lockfile parser at
- * `github.com/github/actions-lockfile/go`. Each lockfile entry binds an `nwo`@`ref` to a
- * verified commit SHA, which is exactly the pinning evidence the `actions/unpinned-tag` query
- * otherwise lacks. Until the extractor populates this predicate it is empty, so any clause that
- * consumes it is a clean no-op and behavior is unchanged for repositories without a lockfile.
+ * Supply rows from a model pack generated with the canonical parser at
+ * `github.com/github/actions-lockfile/go/pkg/lockfile`. Each lockfile entry binds an `nwo`@`ref`
+ * to a verified commit SHA. Without such a model pack this predicate is empty.
  *
  * Fields:
  *  - `workflow_path`: repo-relative path of the file containing the `uses:` reference,
  *    e.g. `.github/workflows/ci.yml`.
- *  - `nwo`: owner and name of the referenced action, e.g. `actions/checkout`.
+ *  - `nwo`: canonical owner and repository from the lockfile pin, e.g. `actions/cache`.
  *  - `ref`: the ref (tag or branch) as written in `uses:`, e.g. `v4`.
  */
 extensible predicate pinnedByLockfileDataModel(string workflow_path, string nwo, string ref);

actions/ql/lib/ext/config/pinned_by_lockfile.yml

@@ -39,21 +39,6 @@ private predicate isContainerImage(string nwo) { nwo.regexpMatch("^docker://.+")
 bindingset[nwo]
 private predicate isSelfRepository(string nwo) { nwo.matches("$/%") }
 
-// Holds if `uses` (calling action `nwo` at `version`) is pinned by an entry in the repository's
-// Actions lockfile (`.github/workflows/actions.lock`). The underlying `pinnedByLockfileDataModel`
-// predicate is populated by the CodeQL Actions extractor when it parses the lockfile at
-// database-creation time; until then this is a clean no-op and no lockfile-pinned refs are
-// suppressed. See `pinnedByLockfileDataModel` in `ConfigExtensions.qll` for the intended shape.
-bindingset[nwo]
-private predicate pinnedByLockfile(UsesStep uses, string nwo, string version) {
-  // The extractor populates this predicate with lower-cased owner/repo (GitHub treats
-  // them case-insensitively) but preserves the ref, so match `nwo` case-insensitively
-  // and `version` exactly. `nwo` keeps its source casing everywhere else (e.g. the
-  // alert message) so authors still see the ref as written.
-  pinnedByLockfileDataModel(uses.getLocation().getFile().getRelativePath(), nwo.toLowerCase(),
-    version)
-}
-
 private predicate getStepContainerName(UsesStep uses, string name) {
   exists(Workflow workflow |
     uses.getEnclosingWorkflow() = workflow and
@@ -77,7 +62,7 @@ where
   uses.getVersion() = version and
   not isTrustedOwner(nwo) and
   not isSelfRepository(nwo) and
-  not pinnedByLockfile(uses, nwo, version) and
+  not pinnedByLockfileDataModel(uses.getLocation().getFile().getRelativePath(), nwo, version) and
   not (if isContainerImage(nwo) then isPinnedContainer(version) else isPinnedCommit(version)) and
   not isImmutableAction(uses, nwo)
 select uses.getCalleeNode(),

actions/ql/src/Security/CWE-829/UnpinnedActionsTag.ql

@@ -1,4 +1,4 @@
 ---
 category: minorAnalysis
 ---
-* The `actions/unpinned-tag` query no longer reports `uses:` references that are recorded as pinned by a repository's Actions lockfile (`.github/workflows/actions.lock`) via the new `pinnedByLockfileDataModel` extensible predicate. The CodeQL Actions extractor generates this data at database-creation time into a database-local model pack (`codeql/actions-lockfile-pins`); references are suppressed only when that pack is supplied to analysis (for example via `--model-packs`), so behavior is unchanged for repositories without a lockfile or analyses that do not opt in. Because the lockfile keys its pins transitively by workflow path, a stale lockfile could in rare cases suppress a directly-written unpinned tag that shares an action and major version with a transitively-pinned dependency of the same workflow; keeping the lockfile current avoids this.
+* The `actions/unpinned-tag` query no longer reports `uses:` references recorded by the new `pinnedByLockfileDataModel` extensible predicate. Lockfile pins match repository sub-actions while preserving ref casing.

actions/ql/src/change-notes/2026-07-09-unpinned-tag-lockfile-aware.md

@@ -9,17 +9,21 @@ jobs:
     # `some-owner/pinned-action@v1` is a tag ref that would normally be reported as an unpinned
     # tag. The test data extension `pinned_by_lockfile.model.yml` records it as pinned by the
     # repository's Actions lockfile, so the `not pinnedByLockfile(...)` clause suppresses it (this
-    # fixture is expected to produce no findings). This mirrors what the CodeQL Actions extractor
-    # will do by parsing `.github/workflows/actions.lock`.
+    # fixture is expected to produce no findings). This mirrors data supplied by an external
+    # model pack generated from `.github/workflows/actions.lock`.
     #
     # Negative control is provided for free by the many other fixtures in this directory whose tag
     # refs are NOT recorded in the data extension and therefore remain reported.
     - uses: some-owner/pinned-action@v1
     # `Mixed-Owner/Pinned-Action@v1` is pinned by the lockfile too, but written with the mixed-case
-    # owner/repo that authors commonly use (Azure, GoogleCloudPlatform, ...). The extractor emits
-    # the lockfile nwo lower-cased, so the query must match owner/repo case-insensitively; this ref
-    # is therefore expected to be suppressed (no finding).
+    # owner/repo that authors commonly use (Azure, GoogleCloudPlatform, ...).
+    # Lockfile pins canonicalize owner/repo, so this ref is also expected to be suppressed (no
+    # finding).
     - uses: Mixed-Owner/Pinned-Action@v1
     # Negative control: a mixed-case ref that is NOT recorded in the lockfile data must still be
     # reported, guarding against over-suppression of every mixed-case ref.
     - uses: Mixed-Owner/Unpinned-Action@v2
+    # A repository-scoped pin also covers its sub-actions.
+    - uses: some-owner/pinned-action/save@v1
+    # Ref casing must match the canonical lockfile pin exactly.
+    - uses: some-owner/pinned-action@V1

actions/ql/test/query-tests/Security/CWE-829/.github/workflows/lockfile_pinned.yml

@@ -17,7 +17,8 @@
 | .github/workflows/label_trusted_checkout2.yml:21:13:21:36 | completely/fakeaction@v2 | Unpinned 3rd party Action 'label_trusted_checkout2.yml' step $@ uses 'completely/fakeaction' with ref 'v2', not a pinned commit hash | .github/workflows/label_trusted_checkout2.yml:21:7:25:4 | Uses Step | Uses Step |
 | .github/workflows/label_trusted_checkout2.yml:25:13:25:37 | fakerepo/comment-on-pr@v1 | Unpinned 3rd party Action 'label_trusted_checkout2.yml' step $@ uses 'fakerepo/comment-on-pr' with ref 'v1', not a pinned commit hash | .github/workflows/label_trusted_checkout2.yml:25:7:28:21 | Uses Step | Uses Step |
 | .github/workflows/level0.yml:36:15:36:47 | rlespinasse/github-slug-action@v4 | Unpinned 3rd party Action 'Poutine Level 0' step $@ uses 'rlespinasse/github-slug-action' with ref 'v4', not a pinned commit hash | .github/workflows/level0.yml:36:9:39:6 | Uses Step | Uses Step |
-| .github/workflows/lockfile_pinned.yml:25:13:25:42 | Mixed-Owner/Unpinned-Action@v2 | Unpinned 3rd party Action 'lockfile_pinned.yml' step $@ uses 'Mixed-Owner/Unpinned-Action' with ref 'v2', not a pinned commit hash | .github/workflows/lockfile_pinned.yml:25:7:25:43 | Uses Step | Uses Step |
+| .github/workflows/lockfile_pinned.yml:25:13:25:42 | Mixed-Owner/Unpinned-Action@v2 | Unpinned 3rd party Action 'lockfile_pinned.yml' step $@ uses 'Mixed-Owner/Unpinned-Action' with ref 'v2', not a pinned commit hash | .github/workflows/lockfile_pinned.yml:25:7:27:4 | Uses Step | Uses Step |
+| .github/workflows/lockfile_pinned.yml:29:13:29:39 | some-owner/pinned-action@V1 | Unpinned 3rd party Action 'lockfile_pinned.yml' step $@ uses 'some-owner/pinned-action' with ref 'V1', not a pinned commit hash | .github/workflows/lockfile_pinned.yml:29:7:29:40 | Uses Step | Uses Step |
 | .github/workflows/mend.yml:31:15:31:34 | ruby/setup-ruby@v1 | Unpinned 3rd party Action 'Test' step $@ uses 'ruby/setup-ruby' with ref 'v1', not a pinned commit hash | .github/workflows/mend.yml:29:9:33:28 | Uses Step | Uses Step |
 | .github/workflows/pr-workflow.yml:60:15:60:52 | amannn/action-semantic-pull-request@v5 | Unpinned 3rd party Action 'pr-workflow' step $@ uses 'amannn/action-semantic-pull-request' with ref 'v5', not a pinned commit hash | .github/workflows/pr-workflow.yml:60:9:70:6 | Uses Step | Uses Step |
 | .github/workflows/pr-workflow.yml:109:15:109:42 | actionsdesk/lfs-warning@v3.2 | Unpinned 3rd party Action 'pr-workflow' step $@ uses 'actionsdesk/lfs-warning' with ref 'v3.2', not a pinned commit hash | .github/workflows/pr-workflow.yml:109:9:124:6 | Uses Step | Uses Step |

actions/ql/test/query-tests/Security/CWE-829/UnpinnedActionsTag.expected

@@ -139,7 +139,9 @@ edges
 | .github/workflows/level0.yml:125:9:129:6 | Uses Step | .github/workflows/level0.yml:129:9:133:6 | Uses Step |
 | .github/workflows/level0.yml:129:9:133:6 | Uses Step | .github/workflows/level0.yml:133:9:135:23 | Run Step |
 | .github/workflows/lockfile_pinned.yml:17:7:22:4 | Uses Step | .github/workflows/lockfile_pinned.yml:22:7:25:4 | Uses Step |
-| .github/workflows/lockfile_pinned.yml:22:7:25:4 | Uses Step | .github/workflows/lockfile_pinned.yml:25:7:25:43 | Uses Step |
+| .github/workflows/lockfile_pinned.yml:22:7:25:4 | Uses Step | .github/workflows/lockfile_pinned.yml:25:7:27:4 | Uses Step |
+| .github/workflows/lockfile_pinned.yml:25:7:27:4 | Uses Step | .github/workflows/lockfile_pinned.yml:27:7:29:4 | Uses Step |
+| .github/workflows/lockfile_pinned.yml:27:7:29:4 | Uses Step | .github/workflows/lockfile_pinned.yml:29:7:29:40 | Uses Step |
 | .github/workflows/mend.yml:13:9:22:6 | Run Step: set_ref | .github/workflows/mend.yml:22:9:29:6 | Uses Step |
 | .github/workflows/mend.yml:22:9:29:6 | Uses Step | .github/workflows/mend.yml:29:9:33:28 | Uses Step |
 | .github/workflows/poc2.yml:28:9:37:6 | Uses Step: branch-deploy | .github/workflows/poc2.yml:37:9:42:6 | Uses Step |

actions/ql/test/query-tests/Security/CWE-829/UntrustedCheckoutCritical.expected

@@ -2,12 +2,8 @@ extensions:
   - addsTo:
       pack: codeql/actions-all
       extensible: pinnedByLockfileDataModel
-    # Test data standing in for what the CodeQL Actions extractor will emit from
-    # `.github/workflows/actions.lock`. Records `some-owner/pinned-action@v1` in
-    # `lockfile_pinned.yml` as pinned by the lockfile so the `actions/unpinned-tag`
-    # query suppresses it.
+    # Canonical lockfile pin rows supplied by an external model pack.
     data:
       - [".github/workflows/lockfile_pinned.yml", "some-owner/pinned-action", "v1"]
-      # Lower-cased form of `Mixed-Owner/Pinned-Action@v1`, as the extractor emits it. Exercises the
-      # case-insensitive owner/repo match in the `actions/unpinned-tag` query.
+      # Owner/repo is canonicalized; ref casing is preserved.
       - [".github/workflows/lockfile_pinned.yml", "mixed-owner/pinned-action", "v1"]