Merge pull request #21715 from knewbury01/knewbury01/adjust-actions-queries-untrusted-checkout

Improve actions/ql/src/Security/CWE-829/UntrustedCheckoutX queries

actions/ql/lib/change-notes/2026-04-15-poisonable-steps-additions-alterations.md

@@ -0,0 +1,4 @@
+---
+category: minorAnalysis
+---
+* Altered 2 patterns in the `poisonable_steps` modelling. Extra sinks are detected in the following cases: scripts executed via python modules and `go run` in directories are detected as potential mechanisms of injection. For the go execution pattern, the pattern is updated to now ignore flags that occur between go and the specific command. This change may lead to more results being detected by the following queries: `actions/untrusted-checkout/high`, `actions/untrusted-checkout/critical`, `actions/untrusted-checkout-toctou/high`, `actions/untrusted-checkout-toctou/critical`, `actions/cache-poisoning/poisonable-step`, `actions/cache-poisoning/direct-cache` and `actions/artifact-poisoning/path-traversal`.

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

@@ -70,7 +70,7 @@ extensions:
       - ["(source|sh|bash|zsh|fish)\\s+([^\\s]+)\\b", 2]
       - ["(node)\\s+([^\\s]+)(\\.js|\\.ts)\\b", 2]
       - ["(python[\\d\\.]*)\\s+([^\\s]+)\\.py\\b", 2]
+      - ["(python[\\d\\.]*)\\s+-m\\s+([A-Za-z_][\\w\\.]*)\\b", 2] # eg: pythonX -m anything(dir or file)
       - ["(ruby)\\s+([^\\s]+)\\.rb\\b", 2]
-      - ["(go)\\s+(generate|run)\\s+([^\\s]+)\\.go\\b", 3]
+      - ["(go)\\s+(generate|run)(?:\\s+-[^\\s]+)*\\s+([^\\s]+)", 3]
       - ["(dotnet)\\s+([^\\s]+)\\.csproj\\b", 2]
-

actions/ql/src/Security/CWE-829/UntrustedCheckoutCritical.md

@@ -1,6 +1,35 @@
 ## Overview
 
-GitHub workflows can be triggered through various repository events, including incoming pull requests (PRs) or comments on Issues/PRs. A potentially dangerous misuse of the triggers such as `pull_request_target` or `issue_comment` followed by an explicit checkout of untrusted code (Pull Request HEAD) may lead to repository compromise if untrusted code gets executed (e.g., due to a modified build script) in a privileged job.
+GitHub workflows can be triggered through various repository events, including incoming pull requests (PRs) or comments on Issues/PRs. Under certain conditions described below, attackers can take over a repository by opening malicious PRs from forks. The attacks can result in malicious code execution causing unauthorized changes to the repository or exfiltration of repository secrets and a compromise of connected systems.
+
+## Workflow Security Model
+
+In GitHub Actions, there is a distinction between unprivileged and privileged workflows. For example, a workflow with a `pull_request` trigger is unprivileged while a workflow with `pull_request_target` is privileged.
+
+This is relevant especially for PRs from forks. Normal PRs can only be submitted by people who have write access to a repository, while PRs from forks can be submitted by anyone.
+
+On a PR from a fork, an unprivileged `pull_request` workflow has only limited capabilities but a privileged `pull_request_target` workflow is much more dangerous. A privileged workflow:
+
+  * Runs in the context of the base repository
+  * Has access to organization and repository secrets (e.g., API keys, deployment tokens)
+  * Has a read/write `GITHUB_TOKEN` by default
+  * Can access private resources
+
+Certain triggers automatically grant a workflow elevated privileges:
+
+  * `pull_request_target` as described above
+  * `workflow_run`: Triggered when another workflow completes.
+  * `issue_comment`: Triggered when a comment is made on an issue or PR.
+
+## Attack Details
+
+  * A repository has a privileged workflow
+  * An attacker forks the repository and adds malicious code (e.g., in the build script)
+  * The attacker opens a PR from the fork, and, if needed, comments on the PR
+  * The workflow in the base repository checks out the forked code
+  * The workflow runs, (e.g. the build script etc.), which contains the malicious code
+
+Please note that not only build scripts can be malicious code vectors. There is a large number of other possibilities. Some of them are listed in the [LOTP](https://boostsecurityio.github.io/lotp/) catalog.
 
 ## Recommendation
 
@@ -133,3 +162,5 @@ jobs:
 ## References
 
 - GitHub Security Lab Research: [Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/).
+- Mitigating risks of untrusted checkout: [GitHub Docs](https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/secure-use#mitigating-the-risks-of-untrusted-code-checkout).
+- Living Off the Pipeline: [LOTP](https://boostsecurityio.github.io/lotp/).

actions/ql/src/Security/CWE-829/UntrustedCheckoutHigh.md

@@ -1,6 +1,35 @@
 ## Overview
 
-GitHub workflows can be triggered through various repository events, including incoming pull requests (PRs) or comments on Issues/PRs. A potentially dangerous misuse of the triggers such as `pull_request_target` or `issue_comment` followed by an explicit checkout of untrusted code (Pull Request HEAD) may lead to repository compromise if untrusted code gets executed (e.g., due to a modified build script) in a privileged job.
+GitHub workflows can be triggered through various repository events, including incoming pull requests (PRs) or comments on Issues/PRs. Under certain conditions described below, attackers can take over a repository by opening malicious PRs from forks. The attacks can result in malicious code execution causing unauthorized changes to the repository or exfiltration of repository secrets and a compromise of connected systems.
+
+## Workflow Security Model
+
+In GitHub Actions, there is a distinction between unprivileged and privileged workflows. For example, a workflow with a `pull_request` trigger is unprivileged while a workflow with `pull_request_target` is privileged.
+
+This is relevant especially for PRs from forks. Normal PRs can only be submitted by people who have write access to a repository, while PRs from forks can be submitted by anyone.
+
+On a PR from a fork, an unprivileged `pull_request` workflow has only limited capabilities but a privileged `pull_request_target` workflow is much more dangerous. A privileged workflow:
+
+  * Runs in the context of the base repository
+  * Has access to organization and repository secrets (e.g., API keys, deployment tokens)
+  * Has a read/write `GITHUB_TOKEN` by default
+  * Can access private resources
+
+Certain triggers automatically grant a workflow elevated privileges:
+
+  * `pull_request_target` as described above
+  * `workflow_run`: Triggered when another workflow completes.
+  * `issue_comment`: Triggered when a comment is made on an issue or PR.
+
+## Attack Details
+
+  * A repository has a privileged workflow
+  * An attacker forks the repository and adds malicious code (e.g., in the build script)
+  * The attacker opens a PR from the fork, and, if needed, comments on the PR
+  * The workflow in the base repository checks out the forked code
+  * The workflow runs, (e.g. the build script etc.), which contains the malicious code
+
+Please note that not only build scripts can be malicious code vectors. There is a large number of other possibilities. Some of them are listed in the [LOTP](https://boostsecurityio.github.io/lotp/) catalog.
 
 ## Recommendation
 
@@ -133,3 +162,5 @@ jobs:
 ## References
 
 - GitHub Security Lab Research: [Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/).
+- Mitigating risks of untrusted checkout: [GitHub Docs](https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/secure-use#mitigating-the-risks-of-untrusted-code-checkout).
+- Living Off the Pipeline: [LOTP](https://boostsecurityio.github.io/lotp/).

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

@@ -1,5 +1,5 @@
 /**
- * @name Checkout of untrusted code in trusted context
+ * @name Checkout of untrusted code in privileged context without privileged context use
  * @description Privileged workflows have read/write access to the base repository and access to secrets.
  *              By explicitly checking out and running the build script from a fork the untrusted code is running in an environment
  *              that is able to push to the base repository and to access secrets.

actions/ql/src/Security/CWE-829/UntrustedCheckoutMedium.md

@@ -1,6 +1,35 @@
 ## Overview
 
-GitHub workflows can be triggered through various repository events, including incoming pull requests (PRs) or comments on Issues/PRs. A potentially dangerous misuse of the triggers such as `pull_request_target` or `issue_comment` followed by an explicit checkout of untrusted code (Pull Request HEAD) may lead to repository compromise if untrusted code gets executed (e.g., due to a modified build script) in a privileged job.
+GitHub workflows can be triggered through various repository events, including incoming pull requests (PRs) or comments on Issues/PRs. Under certain conditions described below, attackers can take over a repository by opening malicious PRs from forks. The attacks can result in malicious code execution causing unauthorized changes to the repository or exfiltration of repository secrets and a compromise of connected systems.
+
+## Workflow Security Model
+
+In GitHub Actions, there is a distinction between unprivileged and privileged workflows. For example, a workflow with a `pull_request` trigger is unprivileged while a workflow with `pull_request_target` is privileged.
+
+This is relevant especially for PRs from forks. Normal PRs can only be submitted by people who have write access to a repository, while PRs from forks can be submitted by anyone.
+
+On a PR from a fork, an unprivileged `pull_request` workflow has only limited capabilities but a privileged `pull_request_target` workflow is much more dangerous. A privileged workflow:
+
+  * Runs in the context of the base repository
+  * Has access to organization and repository secrets (e.g., API keys, deployment tokens)
+  * Has a read/write `GITHUB_TOKEN` by default
+  * Can access private resources
+
+Certain triggers automatically grant a workflow elevated privileges:
+
+  * `pull_request_target` as described above
+  * `workflow_run`: Triggered when another workflow completes.
+  * `issue_comment`: Triggered when a comment is made on an issue or PR.
+
+## Attack Details
+
+  * A repository has a privileged workflow
+  * An attacker forks the repository and adds malicious code (e.g., in the build script)
+  * The attacker opens a PR from the fork, and, if needed, comments on the PR
+  * The workflow in the base repository checks out the forked code
+  * The workflow runs, (e.g. the build script etc.), which contains the malicious code
+
+Please note that not only build scripts can be malicious code vectors. There is a large number of other possibilities. Some of them are listed in the [LOTP](https://boostsecurityio.github.io/lotp/) catalog.
 
 ## Recommendation
 
@@ -133,3 +162,5 @@ jobs:
 ## References
 
 - GitHub Security Lab Research: [Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/).
+- Mitigating risks of untrusted checkout: [GitHub Docs](https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/secure-use#mitigating-the-risks-of-untrusted-code-checkout).
+- Living Off the Pipeline: [LOTP](https://boostsecurityio.github.io/lotp/).

actions/ql/src/change-notes/2026-04-15-untrusted-checkout-improvements-helpfile.md

@@ -0,0 +1,4 @@
+---
+category: fix
+---
+* Fixed help file descriptions for queries: `actions/untrusted-checkout/critical`, `actions/untrusted-checkout/high`, `actions/untrusted-checkout/medium`. Previously the messages were unclear as to why and how the vulnerabilities could occur. 

actions/ql/src/change-notes/2026-04-15-untrusted-checkout-improvements-metadata.md

@@ -0,0 +1,4 @@
+---
+category: queryMetadata
+---
+* Adjusted the name of `actions/untrusted-checkout/high` to more clearly describe which parts of the scenario are in a privileged context.