Merge pull request #19892 from owen-mc/fix-markdown-query-help-formatting

Fix markdown query help formatting

Author: owen-mc

actions/ql/src/Security/CWE-077/EnvPathInjectionCritical.md

@@ -1,6 +1,4 @@
-# Environment Path Injection
-
-## Description
+## Overview
 
 GitHub Actions allow to define the system PATH variable by writing to a file pointed to by the `GITHUB_PATH` environment variable. Writing to this file appends a directory to the system PATH variable and automatically makes it available to all subsequent actions in the current job.
 
@@ -12,11 +10,11 @@ echo "$HOME/.local/bin" >> $GITHUB_PATH
 
 If an attacker can control the contents of the system PATH, they are able to influence what commands are run in subsequent steps of the same job.
 
-## Recommendations
+## Recommendation
 
 Do not allow untrusted data to influence the system PATH: Avoid using untrusted data sources (e.g., artifact content) to define the system PATH.
 
-## Examples
+## Example
 
 ### Incorrect Usage
 
@@ -36,4 +34,4 @@ If an attacker can manipulate the value being set, such as through artifact down
 
 ## References
 
-- [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions)
+- GitHub Docs: [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions).

actions/ql/src/Security/CWE-077/EnvPathInjectionMedium.md

@@ -1,6 +1,4 @@
-# Environment Path Injection
-
-## Description
+## Overview
 
 GitHub Actions allow to define the system PATH variable by writing to a file pointed to by the `GITHUB_PATH` environment variable. Writing to this file appends a directory to the system PATH variable and automatically makes it available to all subsequent actions in the current job.
 
@@ -12,11 +10,11 @@ echo "$HOME/.local/bin" >> $GITHUB_PATH
 
 If an attacker can control the contents of the system PATH, they are able to influence what commands are run in subsequent steps of the same job.
 
-## Recommendations
+## Recommendation
 
 Do not allow untrusted data to influence the system PATH: Avoid using untrusted data sources (e.g., artifact content) to define the system PATH.
 
-## Examples
+## Example
 
 ### Incorrect Usage
 
@@ -36,4 +34,4 @@ If an attacker can manipulate the value being set, such as through artifact down
 
 ## References
 
-- [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions)
+- GitHub Docs: [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions).

actions/ql/src/Security/CWE-077/EnvVarInjectionCritical.md

@@ -1,6 +1,4 @@
-# Environment Variable Injection
-
-## Description
+## Overview
 
 GitHub Actions allow to define environment variables by writing to a file pointed to by the `GITHUB_ENV` environment variable:
 
@@ -37,7 +35,7 @@ steps:
 
 If an attacker can control the values assigned to environment variables and there is no sanitization in place, the attacker will be able to inject additional variables by injecting new lines or `{delimiters}`.
 
-## Recommendations
+## Recommendation
 
 1. **Do not allow untrusted data to influence environment variables**:
 
@@ -64,7 +62,7 @@ If an attacker can control the values assigned to environment variables and ther
           } >> "$GITHUB_ENV"
     ```
 
-## Examples
+## Example
 
 ### Example of Vulnerability
 
@@ -113,5 +111,5 @@ An attacker is be able to run arbitrary code by injecting environment variables
 
 ## References
 
-- [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions)
-- [GitHub Actions Exploitation: Repo Jacking and Environment Manipulation](https://www.synacktiv.com/publications/github-actions-exploitation-repo-jacking-and-environment-manipulation)
+- GitHub Docs: [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions).
+- Synacktiv: [GitHub Actions Exploitation: Repo Jacking and Environment Manipulation](https://www.synacktiv.com/publications/github-actions-exploitation-repo-jacking-and-environment-manipulation).

actions/ql/src/Security/CWE-077/EnvVarInjectionMedium.md

@@ -1,6 +1,4 @@
-# Environment Variable Injection
-
-## Description
+## Overview
 
 GitHub Actions allow to define environment variables by writing to a file pointed to by the `GITHUB_ENV` environment variable:
 
@@ -37,7 +35,7 @@ steps:
 
 If an attacker can control the values assigned to environment variables and there is no sanitization in place, the attacker will be able to inject additional variables by injecting new lines or `{delimiters}`.
 
-## Recommendations
+## Recommendation
 
 1. **Do not allow untrusted data to influence environment variables**:
 
@@ -64,7 +62,7 @@ If an attacker can control the values assigned to environment variables and ther
           } >> "$GITHUB_ENV"
     ```
 
-## Examples
+## Example
 
 ### Example of Vulnerability
 
@@ -113,5 +111,5 @@ An attacker would be able to run arbitrary code by injecting environment variabl
 
 ## References
 
-- [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions)
-- [GitHub Actions Exploitation: Repo Jacking and Environment Manipulation](https://www.synacktiv.com/publications/github-actions-exploitation-repo-jacking-and-environment-manipulation)
+- GitHub Docs: [Workflow commands for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions).
+- Synacktiv: [GitHub Actions Exploitation: Repo Jacking and Environment Manipulation](https://www.synacktiv.com/publications/github-actions-exploitation-repo-jacking-and-environment-manipulation).

actions/ql/src/Security/CWE-094/CodeInjectionCritical.md

@@ -1,18 +1,16 @@
-# Code Injection in GitHub Actions
-
-## Description
+## Overview
 
 Using user-controlled input in GitHub Actions may lead to code injection in contexts like _run:_ or _script:_.
 
 Code injection in GitHub Actions may allow an attacker to exfiltrate any secrets used in the workflow and the temporary GitHub repository authorization token. The token may have write access to the repository, allowing an attacker to make changes to the repository.
 
-## Recommendations
+## Recommendation
 
 The best practice to avoid code injection vulnerabilities in GitHub workflows is to set the untrusted input value of the expression to an intermediate environment variable and then use the environment variable using the native syntax of the shell/script interpreter (that is, not _${{ env.VAR }}_).
 
 It is also recommended to limit the permissions of any tokens used by a workflow such as the GITHUB_TOKEN.
 
-## Examples
+## Example
 
 ### Incorrect Usage
 

actions/ql/src/Security/CWE-094/CodeInjectionMedium.md

@@ -1,18 +1,16 @@
-# Code Injection in GitHub Actions
-
-## Description
+## Overview
 
 Using user-controlled input in GitHub Actions may lead to code injection in contexts like _run:_ or _script:_.
 
 Code injection in GitHub Actions may allow an attacker to exfiltrate any secrets used in the workflow and the temporary GitHub repository authorization token. The token may have write access to the repository, allowing an attacker to make changes to the repository.
 
-## Recommendations
+## Recommendation
 
 The best practice to avoid code injection vulnerabilities in GitHub workflows is to set the untrusted input value of the expression to an intermediate environment variable and then use the environment variable using the native syntax of the shell/script interpreter (that is, not _${{ env.VAR }}_).
 
 It is also recommended to limit the permissions of any tokens used by a workflow such as the GITHUB_TOKEN.
 
-## Examples
+## Example
 
 ### Incorrect Usage
 

actions/ql/src/Security/CWE-1395/UseOfKnownVulnerableAction.md

@@ -1,13 +1,11 @@
-# Use of Actions with known vulnerabilities
-
-## Description
+## Overview
 
 The security of the workflow and the repository could be compromised by GitHub Actions workflows that utilize GitHub Actions with known vulnerabilities.
 
-## Recommendations
+## Recommendation
 
 Either remove the component from the workflow or upgrade it to a version that is not vulnerable.
 
 ## References
 
-- [GitHub Docs: Keeping your actions up to date with Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot)
+- GitHub Docs: [Keeping your actions up to date with Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot).

actions/ql/src/Security/CWE-275/MissingActionsPermissions.md

@@ -1,12 +1,21 @@
-# Actions Job and Workflow Permissions are not set
-
-## Description
+## Overview
 
 If a GitHub Actions job or workflow has no explicit permissions set, then the repository permissions are used. Repositories created under organizations inherit the organization permissions. The organizations or repositories created before February 2023 have the default permissions set to read-write. Often these permissions do not adhere to the principle of least privilege and can be reduced to read-only, leaving the `write` permission only to a specific types as `issues: write` or `pull-requests: write`.
 
-## Recommendations
+## Recommendation
+
+Add the `permissions` key to the job or the root of workflow (in this case it is applied to all jobs in the workflow that do not have their own `permissions` key) and assign the least privileges required to complete the task.
+
+## Example
+
+### Incorrect Usage
+
+```yaml
+name: "My workflow"
+# No permissions block
+```
 
-Add the `permissions` key to the job or the root of workflow (in this case it is applied to all jobs in the workflow that do not have their own `permissions` key) and assign the least privileges required to complete the task:
+### Correct Usage
 
 ```yaml
 name: "My workflow"
@@ -27,4 +36,4 @@ jobs:
 
 ## References
 
-- [Assigning permissions to jobs](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/assigning-permissions-to-jobs)
+- GitHub Docs: [Assigning permissions to jobs](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/assigning-permissions-to-jobs).

actions/ql/src/Security/CWE-285/ImproperAccessControl.md

@@ -1,14 +1,12 @@
-# Improper Access Control
-
-## Description
+## Overview
 
 Sometimes labels are used to approve GitHub Actions. An authorization check may not be properly implemented, allowing an attacker to mutate the code after it has been reviewed and approved by label.
 
-## Recommendations
+## Recommendation
 
 When using labels, make sure that the code cannot be modified after it has been reviewed and the label has been set.
 
-## Examples
+## Example
 
 ### Incorrect Usage
 
@@ -57,4 +55,4 @@ jobs:
 
 ## References
 
-- [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target)
+- GitHub Docs: [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target).

actions/ql/src/Security/CWE-312/ExcessiveSecretsExposure.md

@@ -1,14 +1,12 @@
-# Excessive Secrets Exposure
-
-## Description
+## Overview
 
 When the workflow runner cannot determine what secrets are needed to run the workflow, it will pass all the available secrets to the runner including organization and repository secrets. This violates the least privileged principle and increases the impact of a potential vulnerability affecting the workflow.
 
-## Recommendations
+## Recommendation
 
 Only pass those secrets that are needed by the workflow. Avoid using expressions such as `toJSON(secrets)` or dynamically accessed secrets such as `secrets[format('GH_PAT_%s', matrix.env)]` since the workflow will need to receive all secrets to decide at runtime which one needs to be used.
 
-## Examples
+## Example
 
 ### Incorrect Usage
 
@@ -48,5 +46,5 @@ env:
 
 ## References
 
-- [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#using-encrypted-secrets-in-a-workflow)
-- [Job uses all secrets](https://github.com/boostsecurityio/poutine/blob/main/docs/content/en/rules/job_all_secrets.md)
+- GitHub Docs: [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#using-encrypted-secrets-in-a-workflow).
+- poutine: [Job uses all secrets](https://github.com/boostsecurityio/poutine/blob/main/docs/content/en/rules/job_all_secrets.md).