docs: security hardening info for actions untrusted content

content/actions/how-tos/security-for-github-actions/security-guides/security-hardening-for-github-actions.md

@@ -164,6 +164,34 @@ To help mitigate the risk of an exposed token, consider restricting the assigned
 
 {% ifversion custom-org-roles %}
 
+## Understanding the risks of untrusted code checkout
+
+Similar to script injection attacks, untrusted pull request content that automatically triggers Actions processing can also pose a security risk. The `pull_request_target` and `workflow_run` workflow triggers, when used with the checkout of an untrusted pull request, expose the repository to security compromises. These workflows are privileged (i.e. they share the same cache of the main branch with other privileged workflow triggers, may have repository write access and access to referenced secrets), which can be exploited to take over a repository.
+
+Review the [`pull_request_target` trigger documentation](/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target) and the [`workflow_run` trigger documentation](/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow-run) for more information on these triggers, how to use them, and the risks associated with them.
+
+For additional explanation, examples, and guidance on the risks of untrusted code checkout, see [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/) from GitHub Security Lab and the [Dangerous Workflow check documentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow) from OpenSSF Scorecard.
+
+## Good practices for mitigating untrusted code checkout risks
+
+There are a number of different approaches available to help you mitigate the risk of untrusted code checkout in Actions workflows:
+
+### Avoid potentially dangerous workflow triggers
+
+Avoid using the `pull_request_target` workflow trigger if not necessary. Prefer using `workflow_run` for privilege separation between workflows as described in [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests). Only use these workflow triggers when the workflow actually needs the privileged context.
+
+### Do not use the `pull_request_target` and `workflow_run` workflow triggers with untrusted content
+
+Avoid using the `pull_request_target` and `workflow_run` workflow triggers with untrusted pull requests or code content. Workflows that use these triggers must not explicitly checkout untrusted code, including from pull request forks or from repositories that are not under your control. Workflows triggered on `workflow_run` should treat artifacts uploaded from other workflows with caution (i.e. as untrusted).
+
+### Use CodeQL to detect potentially vulnerable workflows
+
+[CodeQL](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql) can scan and detect potentially vulnerable GitHub Actions workflows. [Configure the default setup for CodeQL](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) for the repository and ensure that GitHub Actions scanning is enabled.
+
+### Use OpenSSF Scorecards to detect potentially vulnerable workflows
+
+[OpenSSF Scorecards](#use-openssf-scorecards-to-detect-potentially-vulnerable-workflows) can help you identify potentially vulnerable workflows, along with other security risks when using GitHub Actions.
+
 ## Managing permissions for {% data variables.product.prodname_actions %} settings in your organization
 
 You can practice the principle of least privilege for your organization's CI/CD pipeline with {% data variables.product.prodname_actions %} by administering custom organization roles. A custom organization role is a way to grant an individual or team in your organization the ability to control certain subsets of settings without granting full administrative control of the organization and its repositories.

content/actions/reference/events-that-trigger-workflows.md

@@ -1222,6 +1222,8 @@ For more information, see the {% data variables.product.prodname_cli %} informat
 
 This event occurs when a workflow run is requested or completed. It allows you to execute a workflow based on execution or completion of another workflow. The workflow started by the `workflow_run` event is able to access secrets and write tokens, even if the previous workflow was not. This is useful in cases where the previous workflow is intentionally not privileged, but you need to take a privileged action in a later workflow.
 
+{% data reusables.actions.workflow-run-permissions-warning %}
+
 In this example, a workflow is configured to run after the separate "Run Tests" workflow completes.
 
 ```yaml

content/enterprise-onboarding/github-actions-for-your-enterprise/security-hardening-for-github-actions.md

@@ -139,7 +139,7 @@ In this example, the attempted script injection is unsuccessful, which is reflec
 PR title did not start with 'octocat'
 ```
 
-With this approach, the value of the {% raw %}`${{ github.event.issue.title }}`{% endraw %} expression is stored in memory and used as a variable, and doesn't interact with the script generation process. In addition, consider using double quote shell variables to avoid [word splitting](https://github.com/koalaman/shellcheck/wiki/SC2086), but this is [one of many](https://mywiki.wooledge.org/BashPitfalls) general recommendations for writing shell scripts, and is not specific to {% data variables.product.prodname_actions %}.
+With this approach, the value of the {% raw %}`${{ github.event.pull_request.title }}`{% endraw %} expression is stored in memory and used as a variable, and doesn't interact with the script generation process. In addition, consider using double quote shell variables to avoid [word splitting](https://github.com/koalaman/shellcheck/wiki/SC2086), but this is [one of many](https://mywiki.wooledge.org/BashPitfalls) general recommendations for writing shell scripts, and is not specific to {% data variables.product.prodname_actions %}.
 
 ### Using workflow templates for {% data variables.product.prodname_code_scanning %}
 
@@ -152,6 +152,34 @@ For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-
 
 To help mitigate the risk of an exposed token, consider restricting the assigned permissions. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token).
 
+## Understanding the risks of untrusted code checkout
+
+Similar to script injection attacks, untrusted pull request content that automatically triggers Actions processing can also pose a security risk. The `pull_request_target` and `workflow_run` workflow triggers, when used with the checkout of an untrusted pull request, expose the repository to security compromises. These workflows are privileged (i.e. they share the same cache of the main branch with other privileged workflow triggers, may have repository write access and access to referenced secrets), which can be exploited to take over a repository.
+
+Review the [`pull_request_target` trigger documentation](/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target) and the [`workflow_run` trigger documentation](/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow-run) for more information on these triggers, how to use them, and the risks associated with them.
+
+For additional explanation, examples, and guidance on the risks of untrusted code checkout, see [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/) from GitHub Security Lab and the [Dangerous Workflow check documentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow) from OpenSSF Scorecard.
+
+## Good practices for mitigating untrusted code checkout risks
+
+There are a number of different approaches available to help you mitigate the risk of untrusted code checkout in Actions workflows:
+
+### Avoid potentially dangerous workflow triggers
+
+Avoid using the `pull_request_target` workflow trigger if not necessary. Prefer using `workflow_run` for privilege separation between workflows as described in [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests). Only use these workflow triggers when the workflow actually needs the privileged context.
+
+### Do not use the `pull_request_target` and `workflow_run` workflow triggers with untrusted content
+
+Avoid using the `pull_request_target` and `workflow_run` workflow triggers with untrusted pull requests or code content. Workflows that use these triggers must not explicitly checkout untrusted code, including from pull request forks or from repositories that are not under your control. Workflows triggered on `workflow_run` should treat artifacts uploaded from other workflows with caution (i.e. as untrusted).
+
+### Use CodeQL to detect potentially vulnerable workflows
+
+[CodeQL](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql) can scan and detect potentially vulnerable GitHub Actions workflows. [Configure the default setup for CodeQL](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) for the repository and ensure that GitHub Actions scanning is enabled.
+
+### Use OpenSSF Scorecards to detect potentially vulnerable workflows
+
+[OpenSSF Scorecards](#use-openssf-scorecards-to-detect-potentially-vulnerable-workflows) can help you identify potentially vulnerable workflows, along with other security risks when using GitHub Actions.
+
 ## Managing permissions for {% data variables.product.prodname_actions %} settings in your organization
 
 You can practice the principle of least privilege for your organization's CI/CD pipeline with {% data variables.product.prodname_actions %} by administering custom organization roles. A custom organization role is a way to grant an individual or team in your organization the ability to control certain subsets of settings without granting full administrative control of the organization and its repositories.

data/reusables/actions/pull-request-target-permissions-warning.md

@@ -1,2 +1,2 @@
 > [!WARNING]
-> For workflows that are triggered by the `pull_request_target` event, the `GITHUB_TOKEN` is granted read/write repository permission unless the `permissions` key is specified and the workflow can access secrets, even when it is triggered from a fork. Although the workflow runs in the context of the base of the pull request, you should make sure that you do not check out, build, or run untrusted code from the pull request with this event. Additionally, any caches share the same scope as the base branch. To help prevent cache poisoning, you should not save the cache if there is a possibility that the cache contents were altered. For more information, see [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests) on the GitHub Security Lab website.
+> For workflows that are triggered by the `pull_request_target` event, the `GITHUB_TOKEN` may be granted read/write repository permission (unless the `permissions` key is explicitly specified in the workflow or repository/organization default permission are set to Read-Only) and the workflow can access referenced secrets, even when it is triggered from a fork. Although the workflow runs in the context of the base of the pull request, you should be cautious if checking out untrusted code from the pull request with this event. Make sure that you do not build, or run untrusted code from the pull request. When `pull_request_target` is triggered against the main branch it shares the same cache as the other privileged workflows running in the context of the main branch. Running untrusted code on this trigger may lead to to cache poisoning. For more information, see [Understanding the risks of untrusted code checkout](/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risks-of-untrusted-code-checkout) in the Security Hardening for GitHub Actions documentation and [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests) on the GitHub Security Lab website.

data/reusables/actions/workflow-run-permissions-warning.md

@@ -0,0 +1,2 @@
+> [!WARNING]
+> Workflows triggered by the `workflow_run` event are privileged (i.e. they share the same cache of the main branch with other privileged workflow triggers, may have repository write access and access to referenced secrets). You should make sure that you do not check out, build, or run untrusted code from the pull request or other untrusted sources with this event. The workflow shares the same cache as the other privileged workflows running in the context of the main branch. Running untrusted code on this trigger may lead to to cache poisoning. For more information, see [Understanding the risks of untrusted code checkout](/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risks-of-untrusted-code-checkout) in the Security Hardening for GitHub Actions documentation and [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests) on the GitHub Security Lab website.