Skip to content

docs: improve gha vulnerabilities documentation #645

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
moe-ad merged 4 commits into from
Sep 22, 2025
Merged

docs: improve gha vulnerabilities documentation #645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a61f5e4
docs: improve gha vulnerabilities documentation
moe-ad Sep 17, 2025
21e7ea6
docs: fix code block
moe-ad Sep 17, 2025
5168406
docs: add content
moe-ad Sep 17, 2025
7ba19e4
docs: review suggestions and vale errors
moe-ad Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
6 changes: 3 additions & 3 deletions doc/source/how-to/compatibility.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
126 changes: 82 additions & 44 deletions doc/source/how-to/vulnerabilities.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Comment thread
moe-ad marked this conversation as resolved.
persist-credentials: false

.. note::
Expand All @@ -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.
Comment thread
moe-ad marked this conversation as resolved.
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

Expand All @@ -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.
Comment thread
moe-ad marked this conversation as resolved.
echo "PATCH=${PARTS[2]}" >> $GITHUB_ENV
else
echo "Invalid tag format. Expected vX.Y.Z but got ${{ github.ref_name }}"
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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.
Comment thread
moe-ad marked this conversation as resolved.
else
echo "Invalid tag format. Expected vX.Y.Z but got ${{ github.ref_name }}"
exit 1
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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 }}
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -779,7 +818,6 @@ For additional examples of fixes, see the `zizmor trophy case`_.
steps:
- run: echo "Hello!"


Ignoring ``zizmor`` findings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
6 changes: 6 additions & 0 deletions doc/source/links.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down
Loading
Loading