docs: improve gha vulnerabilities documentation (#645)

moe-ad · web-flow · commit 88bd523de96e · 2025-09-22T16:57:41.000+02:00
* docs: improve gha vulnerabilities documentation

* docs: fix code block

* docs: add content

* docs: review suggestions and vale errors
diff --git a/doc/Makefile b/doc/Makefile
@@ -19,10 +19,9 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 
-# customized clean due to examples gallery
+# customized clean
 clean:
-	rm -rf build
-	rm -rf source/examples/
+	rm -rf _build
 
 # customized pdf fov svg format images
 pdf:
diff --git a/doc/source/how-to/compatibility.rst b/doc/source/how-to/compatibility.rst
@@ -34,9 +34,9 @@ introduced in an earlier version are also supported in later versions. Suppressi
 a feature would lead to a backward compatibility issue.
 
 Because the same type of issues can happen with the PyAnsys servers wrapping
-Ansys products, creating a similar *maximum version* data structure is
-is necessary. While there are no such implementations yet, it should work
-in the same way as the minimum version data structure.
+Ansys products, creating a similar *maximum version* data structure is necessary.
+While there are no such implementations yet, it should work in the same way as the
+minimum version data structure.
 
 ``version_requires`` decorator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/source/how-to/vulnerabilities.rst b/doc/source/how-to/vulnerabilities.rst
@@ -144,7 +144,7 @@ action is up to date and that it is being used in all PyAnsys repositories consi
 that the action is implemented correctly and that the results are reviewed regularly.
 
 
-Addressing common vulnerabilities in python libraries and applications
+Addressing common vulnerabilities in Python libraries and applications
 ----------------------------------------------------------------------
 
 When developing Python applications, it is essential to be aware of common vulnerabilities that can
@@ -365,28 +365,34 @@ For additional examples of fixes, see the `zizmor trophy case`_.
 
 **artipacked**
 
+The vulnerability is that using ``actions/checkout`` in GitHub Actions can store repository credentials in ``.git/config``, 
+which may be unintentionally exposed through artifacts or workflow steps.
+
+Fixing is important because leaked credentials could grant attackers unauthorized access to your repositories,
+which can allow them push malicious code, among other things. See `artipacked audit rule`_ for more information.
+
 .. tab-set::
 
 
-  .. tab-item:: Before
+  .. tab-item:: Potential risk
 
     .. code:: yaml
 
       steps:
 
-      - name: "Checkout project"
+      - name: "Checkout project" # actions/checkout persists git credentials by default.
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
 
-  .. tab-item:: After
+  .. tab-item:: Remediation
 
     .. code:: yaml
 
       steps:
   
       - name: "Checkout project"
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
+        with: # Unless needed for git operations in subsequent steps, do not persist credentials.
           persist-credentials: false
 
 .. note::
@@ -396,50 +402,64 @@ For additional examples of fixes, see the `zizmor trophy case`_.
 
 **unpinned-uses**
 
+The vulnerability is that using unpinned ``uses:`` clauses in GitHub Actions allows workflows to pull in action
+code that can change at any time, including through branch or tag updates.
+
+Fixing it is important because unpinned actions could be modified by attackers or upstream maintainers, leading
+to unexpected or malicious code execution in your workflows. See `unpinned-uses audit rule`_ for more
+information.
+
 .. tab-set::
 
 
-  .. tab-item:: Before
+  .. tab-item:: Potential risk
 
     .. code:: yaml
 
       steps:
 
       - name: "Upload distribution artifacts to GitHub artifacts"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v4 # The commit a tag-pinned action points to can change due to various factors.
         with:
           name: ${{ env.LIBRARY_NAME }}-artifacts
           path: ~/${{ env.LIBRARY_NAME }}/dist/
 
 
-  .. tab-item:: After
+  .. tab-item:: Remediation
 
     .. code:: yaml
 
       steps:
 
       - name: "Upload distribution artifacts to GitHub artifacts"
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1 # Pinning with a SHA prevents this.
         with:
           name: ${{ env.LIBRARY_NAME }}-artifacts
           path: ~/${{ env.LIBRARY_NAME }}/dist/
 
+.. tip::
+
+  You can use the `pinact`_ tool to automatically pin versions of actions and reusable workflows.
+
 .. note::
 
   The ``ansys/actions/check-actions-security`` action has a ``trust-ansys-actions`` option that
   allows you to use tags for ``ansys/actions``.
   When this option is enabled, you only need to pin external actions.
 
-.. tip::
+**github-env**
 
-  You can use the `pinact`_ tool to automatically pin versions of actions and reusable workflows.
+Writing to ``GITHUB_ENV`` or ``GITHUB_PATH`` in workflows with dangerous triggers (such as ``pull_request_target`` and
+``workflow_run``) can let attackers inject arbitrary environment variables / variable contents.
 
-**github-env**
+A fix is required because this exposure could allow attackers to run malicious code in your GitHub Actions workflows
+either implictly in subsequent steps, or by shadowing ordinary system executables (such as ``ssh``). See
+`github-env audit rule`_ for more information.
 
 .. tab-set::
 
 
-  .. tab-item:: Before
+  .. tab-item:: Potential risk
 
     .. code:: yaml
 
@@ -449,10 +469,9 @@ For additional examples of fixes, see the `zizmor trophy case`_.
         shell: bash
         run: |
           if [[ ${{ github.ref_name }} =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            # Split the tag into its components
             IFS='.' read -ra PARTS <<< "${{ github.ref_name }}"
-            echo "V_AND_MAJOR=${PARTS[0]}" >> $GITHUB_ENV
-            echo "MINOR=${PARTS[1]}" >> $GITHUB_ENV
+            echo "V_AND_MAJOR=${PARTS[0]}" >> $GITHUB_ENV # When used in workflows with dangerous triggers, such as pull_request_target
+            echo "MINOR=${PARTS[1]}" >> $GITHUB_ENV # and workflow_run, GITHUB_ENV and GITHUB_PATH can be an arbitrary code execution risk.
             echo "PATCH=${PARTS[2]}" >> $GITHUB_ENV
           else
             echo "Invalid tag format. Expected vX.Y.Z but got ${{ github.ref_name }}"
@@ -462,7 +481,6 @@ For additional examples of fixes, see the `zizmor trophy case`_.
       - name: "Check tag is valid for current branch"
         shell: bash
         run: |
-          # Remove leading "v" from env.X
           V_AND_MAJOR=${{ env.V_AND_MAJOR }}
           MAJOR="${V_AND_MAJOR#v}"
           echo "MAJOR=${MAJOR}" >> $GITHUB_ENV
@@ -494,7 +512,7 @@ For additional examples of fixes, see the `zizmor trophy case`_.
           git push origin v${{ env.MAJOR }}
 
 
-  .. tab-item:: After
+  .. tab-item:: Remediation
 
     .. code:: yaml
 
@@ -505,11 +523,10 @@ For additional examples of fixes, see the `zizmor trophy case`_.
         shell: bash
         run: |
           if [[ ${{ github.ref_name }} =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            # Split the tag into its components
             IFS='.' read -ra PARTS <<< "${{ github.ref_name }}"
-            echo "V_AND_MAJOR=${PARTS[0]}" >> $GITHUB_OUTPUT
-            echo "MINOR=${PARTS[1]}" >> $GITHUB_OUTPUT
-            echo "PATCH=${PARTS[2]}" >> $GITHUB_OUTPUT
+            echo "V_AND_MAJOR=${PARTS[0]}" >> $GITHUB_OUTPUT # Writing to GITHUB_OUTPUT is safe.
+            echo "MINOR=${PARTS[1]}" >> $GITHUB_OUTPUT # Writing to GITHUB_OUTPUT is safe.
+            echo "PATCH=${PARTS[2]}" >> $GITHUB_OUTPUT # Writing to GITHUB_OUTPUT is safe.
           else
             echo "Invalid tag format. Expected vX.Y.Z but got ${{ github.ref_name }}"
             exit 1
@@ -519,10 +536,9 @@ For additional examples of fixes, see the `zizmor trophy case`_.
         id: current-branch-tag-validity
         shell: bash
         env:
-          V_AND_MAJOR: ${{ steps.tag-components.outputs.V_AND_MAJOR }}
-          MINOR: ${{ steps.tag-components.outputs.MINOR }}
+          V_AND_MAJOR: ${{ steps.tag-components.outputs.V_AND_MAJOR }} # Then share information between steps
+          MINOR: ${{ steps.tag-components.outputs.MINOR }} # through the env block.
         run: |
-          # Remove leading "v" from env.X
           MAJOR="${V_AND_MAJOR#v}"
           echo "MAJOR=${MAJOR}" >> $GITHUB_OUTPUT
           if [[ ${{ github.event.base_ref }} != "refs/heads/release/${MAJOR}.${MINOR}" ]]; then
@@ -567,10 +583,16 @@ For additional examples of fixes, see the `zizmor trophy case`_.
 
 **template-injection**
 
+The vulnerability is that template expansions (``${{ ... }}``) in GitHub Actions can allow code injection when used with
+attacker-controlled inputs, such as issue titles (``github.event.issue.title`` which the attacker can fully control by supplying a new issue title).
+
+Fixing it is important because malicious inputs could execute unintended commands, compromising the security of your workflows. See
+`template-injection audit rule`_ for more information.
+
 .. tab-set::
 
 
-  .. tab-item:: Before
+  .. tab-item:: Potential risk
 
     .. code:: yaml
 
@@ -598,12 +620,12 @@ For additional examples of fixes, see the `zizmor trophy case`_.
 
           - name: "Inspect context variables and workflow input"
             run: |
-              echo ${{ github.workspace }}
-              echo ${{ runner.temp }}
-              echo ${{ input.user-input }}
+              echo ${{ github.workspace }} # Template expansions are resolved before workflows and jobs run. These expansions
+              echo ${{ runner.temp }} # insert their results directly into the context, which can accidentally introduce shell injection risks.
+              echo ${{ input.user-input }} # This is especially through when such expansion is from a user input.
 
 
-  .. tab-item:: After
+  .. tab-item:: Remediation
 
     .. code:: yaml
 
@@ -631,27 +653,33 @@ For additional examples of fixes, see the `zizmor trophy case`_.
 
           - name: "Inspect context variables and workflow input"
             env:
-              USER_INPUT: ${{ inputs.user-input }}
+              USER_INPUT: ${{ inputs.user-input }} # Expand inputs and relevant context variables in the env block.
             run: |
-              echo ${USER_INPUT}
-              echo ${RUNNER_TEMP}
-              echo ${GITHUB_WORKSPACE}
+              echo ${USER_INPUT} # Then use that directly within the run block.
+              echo ${RUNNER_TEMP} # Also, most Github context variables have equivalent environment variables
+              echo ${GITHUB_WORKSPACE} # that can be directly used in place of template expansions.
 
 .. note::
 
   Notice that ``RUNNER_TEMP`` and ``GITHUB_WORKSPACE`` were not explicitly set in the ``env`` block.
   Some GitHub context variables automatically map to environment variables, such as
-  ``runner.temp`` to ``RUNNER_TEMP`` and ``github.workspace`` to ``GITHUB_WORKSPACE``
+  ``runner.temp`` to ``RUNNER_TEMP`` and ``github.workspace`` to ``GITHUB_WORKSPACE``.
   
   If a corresponding environment variable is not automatically available, you must set it in the ``env``
   block of the job or step where it is needed before you can use it.
 
 **excessive-permissions**
 
+The vulnerability is that workflows with excessive permissions grant more access than needed, either at the
+workflow or job level, including through the default ``GITHUB_TOKEN``.
+
+Fixing it is important because over-scoped permissions increase the risk that a compromised workflow could
+perform unauthorized actions on your repository. See `excessive-permissions audit rule`_ for more information.
+
 .. tab-set::
 
 
-  .. tab-item:: Before
+  .. tab-item:: Potential risk
 
     .. code:: yaml
 
@@ -669,6 +697,10 @@ For additional examples of fixes, see the `zizmor trophy case`_.
         MAIN_PYTHON_VERSION: '3.12'
         DOCUMENTATION_CNAME: 'actions.docs.ansys.com'
 
+      # When not specified, the default permission assigned to workflows might be too excessive
+      # for what the jobs need to do. Furthermore, all job steps automatically inherit this
+      # default permission
+
       concurrency:
         group: ${{ github.workflow }}-${{ github.ref }}
         cancel-in-progress: true
@@ -698,7 +730,7 @@ For additional examples of fixes, see the `zizmor trophy case`_.
                 bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
 
 
-  .. tab-item:: After
+  .. tab-item:: Remediation
 
     .. code:: yaml
 
@@ -716,7 +748,8 @@ For additional examples of fixes, see the `zizmor trophy case`_.
         MAIN_PYTHON_VERSION: '3.12'
         DOCUMENTATION_CNAME: 'actions.docs.ansys.com'
 
-      permissions: {}
+      permissions: {} # Zero permissions can be granted at the workflow level if not all jobs require permissions.
+                      # As a good rule of thumb, this normally includes jobs that don't use secrets.
 
       concurrency:
         group: ${{ github.workflow }}-${{ github.ref }}
@@ -739,7 +772,7 @@ For additional examples of fixes, see the `zizmor trophy case`_.
           runs-on: ubuntu-latest
           needs: [doc-build]
           permissions:
-            contents: write
+            contents: write # The specific permission type needed is set for a job that actually needs it.
           steps:
             - uses: ansys/actions/doc-deploy-dev@v10.1.0a0
               with:
@@ -750,14 +783,20 @@ For additional examples of fixes, see the `zizmor trophy case`_.
 
 **anonymous-definition**
 
+This issue is raised when workflows omit the ``name:`` field. When ``name:`` is omitted, the workflow is rendered
+anonymously in the Github Actions UI, making it harder to understand which definition is running.
+
+There is no security impact associated with this issue. However, it is good practice to always include the ``name:``
+field. See `anonymous-definition audit rule`_ for more information.
+
 .. tab-set::
 
 
-  .. tab-item:: Before
+  .. tab-item:: Potential risk
 
     .. code:: yaml
 
-      on: push
+      on: push # This workflow has no name.
 
       jobs:
         build:
@@ -766,11 +805,11 @@ For additional examples of fixes, see the `zizmor trophy case`_.
             - run: echo "Hello!"
 
 
-  .. tab-item:: After
+  .. tab-item:: Remediation
 
     .. code:: yaml
 
-      name: Echo Test
+      name: Echo Test # It is good practice to always name workflows.
       on: push
 
       jobs:
@@ -779,7 +818,6 @@ For additional examples of fixes, see the `zizmor trophy case`_.
           steps:
             - run: echo "Hello!"
 
-
 Ignoring ``zizmor`` findings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/source/links.rst b/doc/source/links.rst
@@ -124,6 +124,12 @@
 .. _zizmor audit rules: https://docs.zizmor.sh/audits/
 .. _zizmor trophy case: https://docs.zizmor.sh/trophy-case/
 .. _ignoring zizmor results: https://docs.zizmor.sh/usage/#ignoring-results
+.. _artipacked audit rule: https://docs.zizmor.sh/audits/#artipacked
+.. _unpinned-uses audit rule: https://docs.zizmor.sh/audits/#unpinned-uses
+.. _github-env audit rule: https://docs.zizmor.sh/audits/#github-env
+.. _template-injection audit rule: https://docs.zizmor.sh/audits/#template-injection
+.. _excessive-permissions audit rule: https://docs.zizmor.sh/audits/#excessive-permissions
+.. _anonymous-definition audit rule: https://docs.zizmor.sh/audits/#anonymous-definition
 .. _pinact: https://github.com/suzuki-shunsuke/pinact
 
 
diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt
diff --git a/requirements/requirements_doc.txt b/requirements/requirements_doc.txt
