From e26dc912d9a2739778448e1cebb7868d71a9af71 Mon Sep 17 00:00:00 2001 From: Muhammed Adedigba Date: Wed, 3 Sep 2025 17:46:00 +0200 Subject: [PATCH 1/6] docs: update documentation --- doc/source/how-to/vulnerabilities.rst | 32 ++++++++++++++++++++++----- doc/source/links.rst | 2 ++ 2 files changed, 29 insertions(+), 5 deletions(-) diff --git a/doc/source/how-to/vulnerabilities.rst b/doc/source/how-to/vulnerabilities.rst index 9768584f3..23be81a55 100644 --- a/doc/source/how-to/vulnerabilities.rst +++ b/doc/source/how-to/vulnerabilities.rst @@ -144,8 +144,8 @@ 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 ---------------------------------- +Addressing common vulnerabilities in python libraries and applications +---------------------------------------------------------------------- When developing Python applications, it is essential to be aware of common vulnerabilities that can occur in the codebase. These vulnerabilities can lead to security risks, data breaches, and other @@ -295,10 +295,10 @@ provides a secure way to generate random numbers. Ignore Bandit warnings ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ In-line comment -~~~~~~~~~~~~~~~ ++++++++++++++++ When using Bandit, you may encounter warnings that you believe are not relevant to your codebase or that you have already addressed. In such cases, you can ignore specific Bandit warnings by @@ -326,9 +326,31 @@ For example, to ignore the B404 warning, you would add `# nosec B404` to the end Security considerations file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++ In addition to ignoring specific Bandit warnings, it is a good practice to document the ignored advisories in a dedicated file. You can find an example of such a file in the `PyACP security considerations`_ documentation page. This way, you can provide to the users a clear overview of the vulnerabilities that need to be taken into account when using the library. + +Addressing common vulnerabilities in Github Actions +--------------------------------------------------- +Vulnerabilities can exist in continuous integration pipelines the same way can exist in the codebase. +Therefore, it is important to secure your actions / workflows against known vulnerabilities to prevent +security breaches and supply chain attacks. + +`zizmor`_ is a static analysis tool that can help audit Github Actions CI/CD setups. It provides functionality +for detecting common vulnerabilities and in some cases, fixing them. Refer to `zizmor audit rules`_ for detailed +information about the rules `zizmor` applies when auditing workflows. + +Auditing CI/CD setups in the PyAnsys ecosystem +++++++++++++++++++++++++++++++++++++++++++++++ +The recommended process for workflow audits by PyAnsys ecosystem projects is using the ``ansys/actions/check-actions-security`` +action. The action is wraps ``zizmor`` lightly to provide additional functionalities and configurations sensible for projects +within the ecosystem. Refer to the action's documentation for information on how to set it up. + +How to fix common issues detected by ``zizmor`` ++++++++++++++++++++++++++++++++++++++++++++++++ + +How to ignore ``zizmor`` warnings ++++++++++++++++++++++++++++++++++ diff --git a/doc/source/links.rst b/doc/source/links.rst index e0e49cc92..798cbd212 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -120,6 +120,8 @@ .. _Test Driven Development (TDD): https://en.wikipedia.org/wiki/Test-driven_development .. _bandit documentation: https://bandit.readthedocs.io/en/latest/ .. _blacklists bandit documentation: https://bandit.readthedocs.io/en/latest/blacklists/blacklist_calls.html +.. _zizmor: https://docs.zizmor.sh/ +.. _zizmor audit rules: https://docs.zizmor.sh/audits/#remediation_1 .. #Sphinx-related links .. _PyData_Sphinx_theme: https://github.com/pydata/pydata-sphinx-theme From dfe3726aa3fd4ac3882184a9ef5176076a66ae54 Mon Sep 17 00:00:00 2001 From: Muhammed Adedigba Date: Thu, 4 Sep 2025 05:17:08 +0200 Subject: [PATCH 2/6] docs: update documentation --- doc/source/how-to/vulnerabilities.rst | 445 +++++++++++++++++- doc/source/links.rst | 13 +- .../config/vocabularies/ANSYS/accept.txt | 3 +- 3 files changed, 450 insertions(+), 11 deletions(-) diff --git a/doc/source/how-to/vulnerabilities.rst b/doc/source/how-to/vulnerabilities.rst index 23be81a55..0342a3409 100644 --- a/doc/source/how-to/vulnerabilities.rst +++ b/doc/source/how-to/vulnerabilities.rst @@ -54,7 +54,7 @@ have been integrated into the ``ansys/actions/check-vulnerabilities`` action. For third-party packages, the PyAnsys Core team has listed a set of excluded advisories so that the action does not fail. This is done to avoid false positives and to ensure that the action does not block the CI/CD pipeline unnecessarily. You can find the list of excluded advisories in -`the action's documentation`_. +`the check-vulnerabilities-action documentation`_. For potential vulnerabilities in the codebase, repositories can configure Bandit to ignore specific advisories. This can be due to the code not being ready yet to be fixed or that the @@ -72,7 +72,7 @@ and ensure that they are regularly reviewed to determine if they can be addresse .. warning:: Testing the action locally before enabling it in the CI/CD workflow is recommended. Information - on how to do this can be found in `the action's documentation`_. + on how to do this can be found in `the check-vulnerabilities-action documentation`_. Vulnerability remediation and reporting ---------------------------------------- @@ -344,13 +344,442 @@ for detecting common vulnerabilities and in some cases, fixing them. Refer to `z information about the rules `zizmor` applies when auditing workflows. Auditing CI/CD setups in the PyAnsys ecosystem -++++++++++++++++++++++++++++++++++++++++++++++ -The recommended process for workflow audits by PyAnsys ecosystem projects is using the ``ansys/actions/check-actions-security`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The recommended workflow auditing process for PyAnsys ecosystem projects is using the ``ansys/actions/check-actions-security`` action. The action is wraps ``zizmor`` lightly to provide additional functionalities and configurations sensible for projects -within the ecosystem. Refer to the action's documentation for information on how to set it up. +within the ecosystem. Refer to `the check-actions-security-action documentation`_ for information on how to set it up. How to fix common issues detected by ``zizmor`` -+++++++++++++++++++++++++++++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This section provides information on fixing common workflow vulnerabilities. Project maintainers can also consult the +following pull requests for examples of workflows / actions already fixed within the PyAnsys ecosystem: -How to ignore ``zizmor`` warnings -+++++++++++++++++++++++++++++++++ +- `Ansys actions security fixes 1`_ +- `Ansys actions security fixes 2`_ +- `Ansys actions security fixes 3`_ +- `PyConverter-XML2Py security fixes`_ + +For vulnerabilities not list here, refer to `zizmor audit rules`_ for remediation steps. For more examples on fixing +issues detected by zizmor, consult `zizmor trophy case`_. + +**artipacked** + +.. tab-set:: + + + .. tab-item:: Before + + .. code:: yaml + + steps: + + - name: "Checkout project" + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + + .. tab-item:: After + + .. code:: yaml + + steps: + + - name: "Checkout project" + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + persist-credentials: false + +.. note:: + + When ``git`` commands requiring credentials to be persisted are executed in subsequent steps + within the same job, this vulnerability can be ignored. See `ignoring zizmor results`_ + +**unpinned-uses** + +.. tab-set:: + + + .. tab-item:: Before + + .. code:: yaml + + steps: + + - name: "Upload distribution artifacts to GitHub artifacts" + uses: actions/upload-artifact@v4 + with: + name: ${{ env.LIBRARY_NAME }}-artifacts + path: ~/${{ env.LIBRARY_NAME }}/dist/ + + + .. tab-item:: After + + .. code:: yaml + + steps: + + - name: "Upload distribution artifacts to GitHub artifacts" + uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1 + with: + name: ${{ env.LIBRARY_NAME }}-artifacts + path: ~/${{ env.LIBRARY_NAME }}/dist/ + +.. note:: + + ``ansys/actions/check-actions-security`` has a ``trust-ansys-actions`` option that allows using tags + for ``ansys/actions``. With this option, only external actions need to be pinned. + +.. tip:: + + The `pinact`_ tool can be used to automatically pin versions of actions and reusable workflows. + +**github-env** + +.. tab-set:: + + + .. tab-item:: Before + + .. code:: yaml + + steps: + + - name: "Decompose tag into components" + 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 "PATCH=${PARTS[2]}" >> $GITHUB_ENV + else + echo "Invalid tag format. Expected vX.Y.Z but got ${{ github.ref_name }}" + exit 1 + fi + + - 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 + if [[ ${{ github.event.base_ref }} != "refs/heads/release/$MAJOR.${{ env.MINOR }}" ]]; then + echo "::error::Tag ${{ github.ref_name }} does not match branch version. wrong branch." + exit 1 + fi + + - name: "Remove v${{ env.MAJOR }} tag" + shell: bash + run: | + git push --delete origin v${{ env.MAJOR }} && \ + echo "Deleted v${{ env.MAJOR }} tag" || \ + echo "Tag v${{ env.MAJOR }} not found" + + - name: "Remove v${{ env.MAJOR }}.${{ env.MINOR }} tag" + shell: bash + run: | + git push --delete origin v${{ env.MAJOR }}.${{ env.MINOR }} && \ + echo "Deleted v${{ env.MAJOR }}.${{ env.MINOR }} tag" || \ + echo "Tag v${{ env.MAJOR }}.${{ env.MINOR }} not found" + + - name: "Create new tags" + shell: bash + run: | + git tag v${{ env.MAJOR }}.${{ env.MINOR }} + git tag v${{ env.MAJOR }} + git push origin v${{ env.MAJOR }}.${{ env.MINOR }} + git push origin v${{ env.MAJOR }} + + + .. tab-item:: After + + .. code:: yaml + + steps: + + - name: "Decompose tag into components" + id: tag-components + 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 + else + echo "Invalid tag format. Expected vX.Y.Z but got ${{ github.ref_name }}" + exit 1 + fi + + - name: "Check tag is valid for current branch" + id: current-branch-tag-validity + shell: bash + env: + V_AND_MAJOR: ${{ steps.tag-components.outputs.V_AND_MAJOR }} + MINOR: ${{ steps.tag-components.outputs.MINOR }} + 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 + echo "::error::Tag ${{ github.ref_name }} does not match branch version. wrong branch." + exit 1 + fi + + - name: "Remove v${{ steps.current-branch-tag-validity.outputs.MAJOR }} tag" + shell: bash + env: + MAJOR: ${{ steps.current-branch-tag-validity.outputs.MAJOR }} + run: | + git push --delete origin v${MAJOR} && \ + echo "Deleted v${MAJOR} tag" || \ + echo "Tag v${MAJOR} not found" + + - name: "Remove v${{ steps.current-branch-tag-validity.outputs.MAJOR }}.${{ steps.tag-components.outputs.MINOR }} tag" + shell: bash + env: + MAJOR: ${{ steps.current-branch-tag-validity.outputs.MAJOR }} + MINOR: ${{ steps.tag-components.outputs.MINOR }} + run: | + git push --delete origin v${MAJOR}.${MINOR} && \ + echo "Deleted v${MAJOR}.${MINOR} tag" || \ + echo "Tag v${MAJOR}.${MINOR} not found" + + - name: "Create new tags" + shell: bash + env: + MAJOR: ${{ steps.current-branch-tag-validity.outputs.MAJOR }} + MINOR: ${{ steps.tag-components.outputs.MINOR }} + run: | + git tag v${MAJOR}.${MINOR} + git tag v${MAJOR} + git push origin v${MAJOR}.${MINOR} + git push origin v${MAJOR} + +.. note:: + + The trick is to pass state between steps using ``GITHUB_OUTPUT`` instead of ``GITHUB_ENV`` or ``GITHUB_PATH``. + For commands expected to run on ``cmd`` or ``pwsh`` on windows runners, the principle is the same, only the + syntax changes. + +**template-injection** + +.. tab-set:: + + + .. tab-item:: Before + + .. code:: yaml + + name: Example reusable workflow + + on: + workflow_call: + inputs: + user-input: + required: false + type: string + default: "user input" + + workflow_dispatch: + inputs: + required: false + type: string + default: "user input" + + jobs: + example-job: + name: "Example job" + runs-on: ubuntu-latest + steps: + + - name: "Inspect context variables and workflow input" + run: | + echo ${{ github.workspace }} + echo ${{ runner.temp }} + echo ${{ input.user-input }} + + + .. tab-item:: After + + .. code:: yaml + + name: Example reusable workflow + + on: + workflow_call: + inputs: + user-input: + required: false + type: string + default: "user input" + + workflow_dispatch: + inputs: + required: false + type: string + default: "user input" + + jobs: + example-job: + name: "Example job" + runs-on: ubuntu-latest + steps: + + - name: "Inspect context variables and workflow input" + env: + USER_INPUT: ${{ inputs.user-input }} + run: | + echo ${USER_INPUT} + echo ${RUNNER_TEMP} + echo ${GITHUB_WORKSPACE} + +.. note:: + + Notice that RUNNER_TEMP and GITHUB_WORKSPACE were not explicitly set in the ``env`` block. This + is because some github context variables have corresponding environment variables, such as ``runner.temp`` + and ``github.workspace`` in this case. + + When corresponding environment variables are not automatically available, they must be set in the + ``env`` block of the job or step where they are needed before they can be used. + +**excessive-permissions** + +.. tab-set:: + + + .. tab-item:: Before + + .. code:: yaml + + name: Github CI + + on: + pull_request: + push: + tags: + - "*" + branches: + - main + + env: + MAIN_PYTHON_VERSION: '3.12' + DOCUMENTATION_CNAME: 'actions.docs.ansys.com' + + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + + jobs: + doc-build: + name: "Doc build" + runs-on: ubuntu-latest + steps: + - uses: ansys/actions/doc-build@v10.1.0a0 + with: + skip-install: true + python-version: ${{ env.MAIN_PYTHON_VERSION }} + use-python-cache: false + needs-quarto: true + + doc-deploy-dev: + name: "Deploy development documentation" + runs-on: ubuntu-latest + needs: [doc-build] + steps: + - uses: ansys/actions/doc-deploy-dev@v10.1.0a0 + with: + cname: ${{ env.DOCUMENTATION_CNAME }} + token: ${{ secrets.GITHUB_TOKEN }} + bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }} + bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }} + + + .. tab-item:: After + + .. code:: yaml + + name: Github CI + + on: + pull_request: + push: + tags: + - "*" + branches: + - main + + env: + MAIN_PYTHON_VERSION: '3.12' + DOCUMENTATION_CNAME: 'actions.docs.ansys.com' + + permissions: {} + + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + + jobs: + doc-build: + name: "Doc build" + runs-on: ubuntu-latest + steps: + - uses: ansys/actions/doc-build@v10.1.0a0 + with: + skip-install: true + python-version: ${{ env.MAIN_PYTHON_VERSION }} + use-python-cache: false + needs-quarto: true + + doc-deploy-dev: + name: "Deploy development documentation" + runs-on: ubuntu-latest + needs: [doc-build] + permissions: + contents: write + steps: + - uses: ansys/actions/doc-deploy-dev@v10.1.0a0 + with: + cname: ${{ env.DOCUMENTATION_CNAME }} + token: ${{ secrets.GITHUB_TOKEN }} + bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }} + bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }} + +**anonymous-definition** + +.. tab-set:: + + + .. tab-item:: Before + + .. code:: yaml + + on: push + + jobs: + build: + runs-on: ubuntu-latest + steps: + - run: echo "Hello!" + + + .. tab-item:: After + + .. code:: yaml + + name: Echo Test + on: push + + jobs: + build: + runs-on: ubuntu-latest + steps: + - run: echo "Hello!" + + +Ignoring ``zizmor`` findings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To add content about ignoring zizmor findings \ No newline at end of file diff --git a/doc/source/links.rst b/doc/source/links.rst index 798cbd212..557b65494 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -121,7 +121,11 @@ .. _bandit documentation: https://bandit.readthedocs.io/en/latest/ .. _blacklists bandit documentation: https://bandit.readthedocs.io/en/latest/blacklists/blacklist_calls.html .. _zizmor: https://docs.zizmor.sh/ -.. _zizmor audit rules: https://docs.zizmor.sh/audits/#remediation_1 +.. _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 +.. _pinact: https://github.com/suzuki-shunsuke/pinact + .. #Sphinx-related links .. _PyData_Sphinx_theme: https://github.com/pydata/pydata-sphinx-theme @@ -220,10 +224,15 @@ .. _CVE: https://www.cve.org/ .. _Safety: https://pyup.io/safety/ .. _Bandit: https://bandit.readthedocs.io/en/latest/ -.. _the action's documentation: https://actions.docs.ansys.com/version/stable/vulnerability-actions/index.html#check-vulnerabilities-action +.. _the check-vulnerability-action documentation: https://actions.docs.ansys.com/version/stable/vulnerability-actions/index.html#check-vulnerabilities-action +.. _the check-actions-security-action documentation: https://actions.docs.ansys.com/version/stable/vulnerability-actions/index.html#check-actions-security-action .. _PyACP security considerations: https://acp.docs.pyansys.com/version/dev/user_guide/security_considerations.html .. _Github's documentation: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability .. _PyAnsys Geometry subprocess advisory: https://github.com/ansys/pyansys-geometry/security/advisories/GHSA-38jr-29fh-w9vm +.. _Ansys actions security fixes 1: https://github.com/ansys/actions/pull/739 +.. _Ansys actions security fixes 2: https://github.com/ansys/actions/pull/725 +.. _Ansys actions security fixes 3: https://github.com/ansys/actions/pull/967 +.. _PyConverter-XML2Py security fixes: https://github.com/ansys/pyconverter-xml2py/pull/452 .. #Deprecation .. _PyAdditive Widgets README: https://github.com/ansys/pyadditive-widgets/blob/main/README.rst diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 9f777831b..b3398b2aa 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -126,4 +126,5 @@ WSL2 Sphinx-Gallery snyk README -CSV \ No newline at end of file +CSV +zizmor \ No newline at end of file From 18f6f4773410a6e7aae366d73fd8d1e7aa8e225e Mon Sep 17 00:00:00 2001 From: Muhammed Adedigba Date: Thu, 4 Sep 2025 05:18:40 +0200 Subject: [PATCH 3/6] fix: vale error --- doc/styles/config/vocabularies/ANSYS/accept.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index b3398b2aa..80e79293a 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -127,4 +127,5 @@ Sphinx-Gallery snyk README CSV -zizmor \ No newline at end of file +zizmor +artipacked \ No newline at end of file From 57ab5ac583886c5d01191df87a3bb6e28fa05e2c Mon Sep 17 00:00:00 2001 From: Muhammed Adedigba Date: Thu, 4 Sep 2025 11:45:33 +0200 Subject: [PATCH 4/6] docs: update documentation --- doc/source/how-to/vulnerabilities.rst | 43 ++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/doc/source/how-to/vulnerabilities.rst b/doc/source/how-to/vulnerabilities.rst index 0342a3409..459125453 100644 --- a/doc/source/how-to/vulnerabilities.rst +++ b/doc/source/how-to/vulnerabilities.rst @@ -782,4 +782,45 @@ issues detected by zizmor, consult `zizmor trophy case`_. Ignoring ``zizmor`` findings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To add content about ignoring zizmor findings \ No newline at end of file +One-off comments +++++++++++++++++ +While auditing workflows with zizmor, you may have to ignore audit findings that are not relevant +to your workflows. zizmor audits are ignored by adding a comment to any line within the span where +the audit finding is located, so long as it can be identified as a YAML comment. + +The comment should be in the format ``# zizmor: ignore[rulename]``, where ```` is audit rule type. +To ignore ``artipacked`` for example, ``# zizmor: ignore[artipacked]`` would be added. Ignoring +multiple audits within the same span is achieved by separating each rule with a comma, e.g. +``zizmor: ignore[github-env,template-injection]``. + +For more information, refer to `ignoring zizmor results`_. + +``zizmor.yml`` configuration file ++++++++++++++++++++++++++++++++++ +A ``zizmor.yml`` configuration file is easier to maintain than one-off comments when ignoring multiple +findings or entire files. + +A ``zizmor.yml`` may look like the following: + +.. code:: yaml + + rules: + unpinned-uses: + config: + policies: + ansys/*: ref-pin + actions/*: hash-pin + template-injection: + ignore: + - safe.yml + - somewhat-safe.yml:123 + - one-exact-spot.yml:123:456 + +This configuration file achieves the following: + +- Declares that ``ansys/actions`` can be pinned with tags but ``actions/*`` must be pinned with a SHA. +- Ignores all ``template-injection`` findings in safe.yml, regardless of line/column location. +- Ignores any ``template-injection`` findings in somewhat-safe.yml that occur on line 123 +- Ignores one ``template-injection`` finding in one-exact-spot.yml that occurs on line 123, column 456 + +For more information, refer to `ignoring zizmor results`_. \ No newline at end of file From 4c10d96b0862f86b0aa85e41fae865c8973c1c4c Mon Sep 17 00:00:00 2001 From: Muhammed Adedigba Date: Thu, 4 Sep 2025 13:46:33 +0200 Subject: [PATCH 5/6] doc: update documentation --- doc/source/how-to/vulnerabilities.rst | 98 +++++++++++++++------------ 1 file changed, 55 insertions(+), 43 deletions(-) diff --git a/doc/source/how-to/vulnerabilities.rst b/doc/source/how-to/vulnerabilities.rst index 459125453..612d0c7cd 100644 --- a/doc/source/how-to/vulnerabilities.rst +++ b/doc/source/how-to/vulnerabilities.rst @@ -335,32 +335,33 @@ the vulnerabilities that need to be taken into account when using the library. Addressing common vulnerabilities in Github Actions --------------------------------------------------- -Vulnerabilities can exist in continuous integration pipelines the same way can exist in the codebase. -Therefore, it is important to secure your actions / workflows against known vulnerabilities to prevent -security breaches and supply chain attacks. +Vulnerabilities can exist in continuous integration (CI) pipelines just as they can in a codebase. +To reduce the risk of security breaches and supply chain attacks, it is important to secure your +GitHub Actions workflows against known vulnerabilities. -`zizmor`_ is a static analysis tool that can help audit Github Actions CI/CD setups. It provides functionality -for detecting common vulnerabilities and in some cases, fixing them. Refer to `zizmor audit rules`_ for detailed -information about the rules `zizmor` applies when auditing workflows. +`zizmor`_ is a static analysis tool that audits GitHub Actions CI/CD setups. It detects common +vulnerabilities and, in some cases, can automatically fix them. For detailed information about +the rules that zizmor applies when auditing workflows, see `zizmor audit rules`_. Auditing CI/CD setups in the PyAnsys ecosystem ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The recommended workflow auditing process for PyAnsys ecosystem projects is using the ``ansys/actions/check-actions-security`` -action. The action is wraps ``zizmor`` lightly to provide additional functionalities and configurations sensible for projects -within the ecosystem. Refer to `the check-actions-security-action documentation`_ for information on how to set it up. +For PyAnsys ecosystem projects, the recommended way to audit workflows is to use the +``ansys/actions/check-actions-security`` action. The action wraps ``zizmor`` and provides +additional functionality and configuration tailored to PyAnsys projects. For setup instructions, +see `the check-actions-security-action documentation`_. -How to fix common issues detected by ``zizmor`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section provides information on fixing common workflow vulnerabilities. Project maintainers can also consult the -following pull requests for examples of workflows / actions already fixed within the PyAnsys ecosystem: +Fixing common issues detected by ``zizmor`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This section describes how to fix common workflow vulnerabilities. +For practical examples, see these pull requests with fixes already applied in the PyAnsys ecosystem: - `Ansys actions security fixes 1`_ - `Ansys actions security fixes 2`_ - `Ansys actions security fixes 3`_ - `PyConverter-XML2Py security fixes`_ -For vulnerabilities not list here, refer to `zizmor audit rules`_ for remediation steps. For more examples on fixing -issues detected by zizmor, consult `zizmor trophy case`_. +For vulnerabilities not listed here, refer to `zizmor audit rules`_ for remediation steps. +For additional examples of fixes, see the `zizmor trophy case`_. **artipacked** @@ -390,8 +391,8 @@ issues detected by zizmor, consult `zizmor trophy case`_. .. note:: - When ``git`` commands requiring credentials to be persisted are executed in subsequent steps - within the same job, this vulnerability can be ignored. See `ignoring zizmor results`_ + When you run git commands that require persisted credentials in subsequent steps within the same job, + you can ignore this audit finding. For details, see `ignoring zizmor results`_ **unpinned-uses** @@ -425,12 +426,13 @@ issues detected by zizmor, consult `zizmor trophy case`_. .. note:: - ``ansys/actions/check-actions-security`` has a ``trust-ansys-actions`` option that allows using tags - for ``ansys/actions``. With this option, only external actions need to be pinned. + 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:: - The `pinact`_ tool can be used to automatically pin versions of actions and reusable workflows. + You can use the `pinact`_ tool to automatically pin versions of actions and reusable workflows. **github-env** @@ -561,8 +563,7 @@ issues detected by zizmor, consult `zizmor trophy case`_. .. note:: The trick is to pass state between steps using ``GITHUB_OUTPUT`` instead of ``GITHUB_ENV`` or ``GITHUB_PATH``. - For commands expected to run on ``cmd`` or ``pwsh`` on windows runners, the principle is the same, only the - syntax changes. + On Windows runners, the same principle applies when running commands in ``cmd`` or ``pwsh``; only the syntax differs. **template-injection** @@ -638,12 +639,12 @@ issues detected by zizmor, consult `zizmor trophy case`_. .. note:: - Notice that RUNNER_TEMP and GITHUB_WORKSPACE were not explicitly set in the ``env`` block. This - is because some github context variables have corresponding environment variables, such as ``runner.temp`` - and ``github.workspace`` in this case. + 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`` - When corresponding environment variables are not automatically available, they must be set in the - ``env`` block of the job or step where they are needed before they can be used. + 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** @@ -784,23 +785,34 @@ Ignoring ``zizmor`` findings One-off comments ++++++++++++++++ -While auditing workflows with zizmor, you may have to ignore audit findings that are not relevant -to your workflows. zizmor audits are ignored by adding a comment to any line within the span where -the audit finding is located, so long as it can be identified as a YAML comment. +While auditing workflows with ``zizmor``, you might need to ignore findings that are not relevant to your workflows. +You can ignore ``zizmor`` audits by adding a YAML comment on any line within the span of the finding. -The comment should be in the format ``# zizmor: ignore[rulename]``, where ```` is audit rule type. -To ignore ``artipacked`` for example, ``# zizmor: ignore[artipacked]`` would be added. Ignoring -multiple audits within the same span is achieved by separating each rule with a comma, e.g. -``zizmor: ignore[github-env,template-injection]``. +Use the following format: -For more information, refer to `ignoring zizmor results`_. +.. code:: yaml + + # zizmor: ignore[] + +For example, to ignore the ``artipacked`` rule: + +.. code:: yaml + + # zizmor: ignore[artipacked] + +To ignore multiple rules in the same span, separate them with commas: + +.. code:: yaml + # zizmor: ignore[github-env,template-injection] + +For more information, see `ignoring zizmor results`_. ``zizmor.yml`` configuration file +++++++++++++++++++++++++++++++++ -A ``zizmor.yml`` configuration file is easier to maintain than one-off comments when ignoring multiple -findings or entire files. +If you need to ignore multiple findings or entire files, a ``zizmor.yml`` configuration file is +easier to maintain than one-off comments. -A ``zizmor.yml`` may look like the following: +A ``zizmor.yml`` file might look like this: .. code:: yaml @@ -818,9 +830,9 @@ A ``zizmor.yml`` may look like the following: This configuration file achieves the following: -- Declares that ``ansys/actions`` can be pinned with tags but ``actions/*`` must be pinned with a SHA. -- Ignores all ``template-injection`` findings in safe.yml, regardless of line/column location. -- Ignores any ``template-injection`` findings in somewhat-safe.yml that occur on line 123 -- Ignores one ``template-injection`` finding in one-exact-spot.yml that occurs on line 123, column 456 +- Declares that ``ansys/actions`` can be pinned with tags, but ``actions/*`` must be pinned with a SHA. +- Ignores all ``template-injection`` findings in ``safe.yml``, regardless of line or column location. +- Ignores any ``template-injection`` findings in ``somewhat-safe.yml`` that occur on line 123. +- Ignores one ``template-injection`` finding in ``one-exact-spot.yml`` that occurs on line 123, column 456. -For more information, refer to `ignoring zizmor results`_. \ No newline at end of file +For more information, see `ignoring zizmor results`_. \ No newline at end of file From 4b2d3f9de68c1d22760424000243792e366dd35b Mon Sep 17 00:00:00 2001 From: Muhammed Adedigba Date: Thu, 4 Sep 2025 13:55:20 +0200 Subject: [PATCH 6/6] doc: update documentation --- doc/source/how-to/vulnerabilities.rst | 7 ++++--- doc/source/links.rst | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/source/how-to/vulnerabilities.rst b/doc/source/how-to/vulnerabilities.rst index 612d0c7cd..2e187fdee 100644 --- a/doc/source/how-to/vulnerabilities.rst +++ b/doc/source/how-to/vulnerabilities.rst @@ -54,7 +54,7 @@ have been integrated into the ``ansys/actions/check-vulnerabilities`` action. For third-party packages, the PyAnsys Core team has listed a set of excluded advisories so that the action does not fail. This is done to avoid false positives and to ensure that the action does not block the CI/CD pipeline unnecessarily. You can find the list of excluded advisories in -`the check-vulnerabilities-action documentation`_. +`the check-vulnerabilities action documentation`_. For potential vulnerabilities in the codebase, repositories can configure Bandit to ignore specific advisories. This can be due to the code not being ready yet to be fixed or that the @@ -72,7 +72,7 @@ and ensure that they are regularly reviewed to determine if they can be addresse .. warning:: Testing the action locally before enabling it in the CI/CD workflow is recommended. Information - on how to do this can be found in `the check-vulnerabilities-action documentation`_. + on how to do this can be found in `the check-vulnerabilities action documentation`_. Vulnerability remediation and reporting ---------------------------------------- @@ -348,7 +348,7 @@ Auditing CI/CD setups in the PyAnsys ecosystem For PyAnsys ecosystem projects, the recommended way to audit workflows is to use the ``ansys/actions/check-actions-security`` action. The action wraps ``zizmor`` and provides additional functionality and configuration tailored to PyAnsys projects. For setup instructions, -see `the check-actions-security-action documentation`_. +see `the check-actions-security action documentation`_. Fixing common issues detected by ``zizmor`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -803,6 +803,7 @@ For example, to ignore the ``artipacked`` rule: To ignore multiple rules in the same span, separate them with commas: .. code:: yaml + # zizmor: ignore[github-env,template-injection] For more information, see `ignoring zizmor results`_. diff --git a/doc/source/links.rst b/doc/source/links.rst index 557b65494..ba33e5adb 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -224,8 +224,8 @@ .. _CVE: https://www.cve.org/ .. _Safety: https://pyup.io/safety/ .. _Bandit: https://bandit.readthedocs.io/en/latest/ -.. _the check-vulnerability-action documentation: https://actions.docs.ansys.com/version/stable/vulnerability-actions/index.html#check-vulnerabilities-action -.. _the check-actions-security-action documentation: https://actions.docs.ansys.com/version/stable/vulnerability-actions/index.html#check-actions-security-action +.. _the check-vulnerabilities action documentation: https://actions.docs.ansys.com/version/stable/vulnerability-actions/index.html#check-vulnerabilities-action +.. _the check-actions-security action documentation: https://actions.docs.ansys.com/version/stable/vulnerability-actions/index.html#check-actions-security-action .. _PyACP security considerations: https://acp.docs.pyansys.com/version/dev/user_guide/security_considerations.html .. _Github's documentation: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability .. _PyAnsys Geometry subprocess advisory: https://github.com/ansys/pyansys-geometry/security/advisories/GHSA-38jr-29fh-w9vm