📝 Add ‘Securing the release workflow’

* Git tags replaced by commit SHA values
* Beautify pyproject.toml files

Author: veit

.github/workflows/ci.yml

@@ -9,29 +9,29 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v6
-    - uses: actions/setup-python@v6
-    - uses: actions/cache@v5
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+    - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
       with:
         path: ~/.cache/pre-commit
         key: pre-commit|${{ env.pythonLocation }}|${{ hashFiles('.pre-commit-config.yaml') }}
-    - uses: pre-commit/action@v3.0.1
+    - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
 
   docs:
     name: Build docs and check links
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v6
-    - uses: pandoc/actions/setup@v1
-    - uses: actions/setup-python@v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - uses: pandoc/actions/setup@86321b6dd4675f5014c611e05088e10d4939e09e # v1.1.1
+    - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
       with:
         # Keep in sync with .readthedocs.yaml
         python-version-file: .python-version
     - name: Install plantuml
       run: |
         sudo apt install plantuml
     - name: Setup cached uv
-      uses: hynek/setup-cached-uv@v2
+      uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0
     - name: Create venv and install docs dependencies
       run: |
         uv venv

docs/document/sphinx/test.rst

@@ -121,13 +121,13 @@ You can then define the following jobs for GitHub, for example:
      runs-on: ubuntu-latest
      steps:
      - name: Download pre-built packages
-       uses: actions/download-artifact@v4
+       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: Packages
          path: dist
      - run: tar xf dist/*.tar.gz --strip-components=1
 
-     - uses: actions/setup-python@v5
+     - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          # Keep in sync with tox.ini/docs and .readthedocs.yaml
          python-version: "3.12"

docs/packs/.github/workflows/build_wheels.yml

@@ -16,12 +16,12 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-13, macos-14]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.21.3
+        uses: pypa/cibuildwheel@8d2b08b68458a16aeb24b64e68a09ab1c8e82084 # v3.4.1
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
           path: ./wheelhouse/*.whl

docs/packs/dataprep/pyproject.toml

@@ -25,7 +25,6 @@ dependencies = [
   "cython",
   "pandas",
 ]
-
 urls."Bug Tracker" = "https://github.com/veit/dataprep/issues"
 urls."Homepage" = "https://github.com/veit/dataprep"
 License-Expression = "BSD-3-Clause"

docs/packs/myapp/pyproject.toml

@@ -16,6 +16,5 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
 ]
-dependencies = [  ]
-
+dependencies = []
 scripts.myapp = "myapp:main"

docs/packs/mypack/pyproject.toml

@@ -16,6 +16,5 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
 ]
-dependencies = [  ]
-
+dependencies = []
 scripts.mypack = "mypack:main"

docs/packs/publish.rst

@@ -160,9 +160,9 @@ Finally, you can publish your package on PyPI:
 GitHub Action
 -------------
 
-You can also create a GitHub action, which creates a package and uploads it to
-PyPI at every time a release is created. Such a
-:file:`.github/workflows/pypi.yml` file could look like this:
+You can also create a `GitHub Action <https://github.com/features/actions>`_,
+which creates a package and uploads it to PyPI at every time a release is
+created. Such a :file:`.github/workflows/pypi.yml` file could look like this:
 
 .. code-block:: yaml
    :caption: .github/workflows/pypi.yml
@@ -183,16 +183,16 @@ PyPI at every time a release is created. Such a
        needs: [test]
        steps:
        - name: Checkout
-         uses: actions/checkout@v4
+         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
          with:
            fetch-depth: 0
        - name: Set up Python
-         uses: actions/setup-python@v5
+         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
          with:
            python-version-file: .python-version
            cache-dependency-path: '**/pyproject.toml'
        - name: Setup cached uv
-         uses: hynek/setup-cached-uv@v2
+         uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0
        - name: Create venv
          run: |
            uv venv
@@ -203,9 +203,9 @@ PyPI at every time a release is created. Such a
        - name: Retrieve and publish
          steps:
          - name: Retrieve release distributions
-           uses: actions/download-artifact@v4
+           uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
          - name: Publish package distributions to PyPI
-           uses: pypa/gh-action-pypi-publish@release/v1
+           uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
            with:
              username: __token__
              password: ${{ secrets.PYPI_TOKEN }}
@@ -218,26 +218,86 @@ Line 12
 Line 31
     Here :samp:`{mypack}` should be replaced by your package name.
 Line 36
-    The GitHub action ``actions/download-artifact`` provides the built
+    The GitHub action `actions/download-artifact
+    <https://github.com/actions/download-artifact>`_ provides the built
     distribution packages.
 Lines 38–41
-    The GitHub action ``pypa/gh-action-pypi-publish`` publishes the packages
+    The GitHub action `pypa/gh-action-pypi-publish
+    <https://github.com/pypa/gh-action-pypi-publish>`_ publishes the packages
     with the upload token on :term:`PyPI`.
 
 .. seealso::
 
    * `GitHub Actions <https://docs.github.com/en/actions>`_
+   * :doc:`cibuildwheel`
+
+Securing the release workflow
+-----------------------------
+
+Continuous deployment systems used to publish Python packages are a popular
+target for attacks. You can avoid many of these risks by following a few
+security recommendations:
+
+Avoid insecure triggers
+    Workflows that can be triggered by an attacker, particularly those that rely
+    on inputs controlled by the attacker (such as :ref:`pull request
+    <merge-pull-requests>` or :doc:`branch
+    <Python4DataScience:productive/git/branch>` titles), have been used in the
+    past to inject commands. In particular, the `pull_request_target
+    <https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target>`_
+    trigger in :ref:`github-actions` should be avoided.
+
+    .. seealso::
+       * `Keeping your GitHub Actions and workflows secure Part 2: Untrusted
+         input
+         <https://securitylab.github.com/resources/github-actions-untrusted-input/>`_
+       * `Mitigating Attack Vectors in GitHub Workflows: Workflow triggers
+         <https://openssf.org/blog/2024/08/12/mitigating-attack-vectors-in-github-workflows/>`_
+       * `Misuse of pull_request_target trigger
+         <https://securitylab.github.com/resources/github-actions-new-patterns-and-mitigations/#misuse-of-pull_request_target-trigger>`_
+
+Sanitise parameters and inputs
+    Any workflow parameter or input that can be expanded into an executable
+    command has the potential to be exploited in attacks. Sanitise values by
+    passing them to commands as environment variables to prevent
+    `template injection <https://docs.zizmor.sh/audits/#template-injection>`_
+    attacks.
+Avoid mutable references
+    Fix your dependencies in workflows.
+
+    * Prefer Git commit `SHA
+      <https://en.wikipedia.org/wiki/Secure_Hash_Algorithms>`_ values over
+      :doc:`Git tags <Python4DataScience:productive/git/tag>`, as tags are
+      mutable.
+
+      .. tip::
+         * Für die Aktualisierung der GitHub Actions und `Dependency Cooldowns
+           <https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns>`_
+           könnt ihr `pinact <https://github.com/suzuki-shunsuke/pinact>`_
+           verwenden, also :abbr:`z. B. (zum Beispiel)`:
+
+           .. code-block:: console
+
+              $ pinact run -u --min-age 7
+
+    * Use a :ref:`uv_lock` file for PyPI dependencies used in workflows.
+
+Use verifiable deployments
+    With :ref:`trusted_publishers`, you can use verifiable GitHub environments
+    to build your Python packages. If you use GitHub Actions for continuous
+    delivery, you should use :ref:`zizmorcore` to detect and fix insecure
+    workflows.
 
 .. _trusted_publishers:
 
 Trusted Publishers
-------------------
+~~~~~~~~~~~~~~~~~~
 
 `Trusted Publishers <https://docs.pypi.org/trusted-publishers/>`_ is a procedure
 for publishing packages on the :term:`PyPI`. It is based on OpenID Connect and
 requires neither a password nor a token. Only the following steps are required:
 
-#. Add a *Trusted Publishers* on PyPI
+#. Add a *Trusted Publisher* on PyPI
 
    Depending on whether you want to publish a new package or update an existing
    one, the process is slightly different:
@@ -276,7 +336,7 @@ requires neither a password nor a token. Only the following steps are required:
    .. code-block:: diff
       :caption: .github/workflows/pypi.yml
       :lineno-start: 10
-      :emphasize-lines: 3, 4-5
+      :emphasize-lines: 3-5
 
           package-and-deploy:
             runs-on: ubuntu-latest
@@ -292,24 +352,19 @@ requires neither a password nor a token. Only the following steps are required:
    Lines 13–14
        The ``write`` authorisation is required for *Trusted Publishing*.
 
-   Zeilen 42–44
+   Zeilen 40–44
        ``username`` and ``password`` are no longer required for the GitHub
        action ``pypa/gh-action-pypi-publish``.
 
-       .. code-block:: diff
+       .. code-block:: yaml
           :lineno-start: 40
           :emphasize-lines: 3-
 
-             - name: Publish package distributions to PyPI
-               uses: pypa/gh-action-pypi-publish@release/v1
-          -    with:
-          -      username: __token__
-          -      password: ${{ secrets.PYPI_TOKEN }}
-
-.. _digital-attestations:
-
-Digital Attestations
---------------------
+          - name: Publish package distributions to PyPI
+            uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+            with:
+              username: __token__
+              password: ${{ secrets.PYPI_TOKEN }}
 
 Since 14 November 2024, :term:`PyPI` also supports :pep:`740` with `Digital
 Attestations <https://docs.pypi.org/attestations/>`_. PyPI uses the
@@ -337,7 +392,7 @@ are used for publishing:
          id-token: write
        steps:
        - name: Publish package distributions to PyPI
-         uses: pypa/gh-action-pypi-publish@release/v1
+         uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
 
 .. note::
    Support for the automatic creation of digital attestations and publishing
@@ -346,3 +401,57 @@ are used for publishing:
 .. seealso::
    `PyPI now supports digital attestations
    <https://blog.pypi.org/posts/2024-11-14-pypi-now-supports-digital-attestations/>`_
+
+.. _zizmorcore:
+
+zizmor
+~~~~~~
+
+`zizmor <https://docs.zizmor.sh>`_ can detect and resolve many security issues
+in typical GitHub Actions CI/CD configurations. zizmor is designed to integrate
+with GitHub Actions. A typical GitHub Action we use for zizmor looks like this:
+
+.. code-block:: yaml
+   :caption: .github/workflows/zizmor.yml
+
+   # https://github.com/woodruffw/zizmor
+   name: Zizmor
+
+   on:
+     push:
+       branches: ["main"]
+     pull_request:
+       branches: ["**"]
+
+   concurrency:
+     group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+     cancel-in-progress: true
+
+   permissions: {}
+
+   jobs:
+     zizmor:
+       name: Run zizmor
+       runs-on: ubuntu-latest
+       permissions:
+         security-events: write # Required for upload-sarif (used by zizmor-action) to upload SARIF files.
+       steps:
+         - name: Checkout repository
+           uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+           with:
+             persist-credentials: false
+         - name: Run zizmor
+           uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2
+           with:
+             persona: pedantic
+
+.. _add_2fa:
+
+2FA for all development accounts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You should use two-factor authentication for all your accounts related to
+development – not just for :term:`PyPI`. Remember your version control accounts
+(`GitHub <https://github.com/>`_, `GitLab <https://about.gitlab.com/>`_,
+`Codeberg <https://codeberg.org/>`_, `Forgejo <https://forgejo.org/>`_) and
+email.

docs/packs/pyproject.toml

@@ -2,8 +2,6 @@
 test-requires = "pytest"
 test-command = "pytest {project}/tests"
 build-verbosity = 1
-
 # support Universal2 for Apple Silicon:
-[tool.cibuildwheel.macos]
-archs = [ "auto", "universal2" ]
-test-skip = [ "*universal2:arm64" ]
+macos.archs = [ "auto", "universal2" ]
+macos.test-skip = [ "*universal2:arm64" ]