Vulnerability actions
=====================

Vulnerability actions verify that any safety advisories detected in a Python
library are properly identified and reported, both on the library itself
and third-party libraries (that is, dependencies).

.. _pyansys_check_vulnerabilities:

Check vulnerabilities action
----------------------------

.. note::

   Users can try out the ``ansys/check-vulnerabilities`` action on their local repository
   by doing the following:

   #. Download the ``check_vulnerabilities.py``, ``requirements.txt``, and ``.safety-ignore.yml`` files from
      the `ansys/check-vulnerabilities action folder <https://github.com/ansys/actions/tree/main/check-vulnerabilities>`_.
   #. Move the downloaded files to the root of the repository.

   #. Create a first virtual environment for the project and install the repository:

      .. code-block:: bash

         python -m venv .venv
         source .venv/bin/activate  # On Windows: .venv\Scripts\activate
         pip install -e .

   #. Dump the project dependencies to a file. **This step is required** to isolate the
      project dependencies from those of the security tools (``safety`` and ``bandit``),
      so that the tools' own packages are not included in the vulnerability scan:

      .. code-block:: bash

         pip freeze > requirements-for-safety.txt
         deactivate

   #. Create a second virtual environment dedicated to the security tools and install them:

      .. code-block:: bash

         python -m venv .venv_bandit_safety
         source .venv_bandit_safety/bin/activate  # On Windows: .venv_bandit_safety\Scripts\activate
         pip install -r requirements.txt

   #. Define the following environment variables:

      - ``DEPENDENCY_CHECK_TOKEN``: A GitHub token with the necessary permissions to access security advisories on the repository you are interested in.
      - ``DEPENDENCY_CHECK_PACKAGE_NAME``: The Python package name of your repository. This is the name of the package that you would use in a ``pip install`` command.
      - ``DEPENDENCY_CHECK_REPOSITORY``: The full name of the repository you are interested in. This is the name of the repository in the format ``<owner>/<repository>``.

   #. On **corporate networks with SSL inspection**, connections to external HTTPS
      endpoints is going to fail with an SSL certificate verification error because the
      ``requests`` library `uses ``certifi``'s CA bundle
      <https://requests.readthedocs.io/en/latest/user/advanced/#ca-certificates>`_
      and does not trust the corporate CA by default. Build a combined CA bundle
      that includes both your corporate root CA and the standard ``certifi``
      bundle, then point ``REQUESTS_CA_BUNDLE`` to it:

      .. code-block:: bash

         # Export the corporate root CA from the OS store as PEM,
         # then combine it with certifi's public CA bundle:
         CA_BUNDLE=$(python -c "import certifi; print(certifi.where())")
         cat "$CA_BUNDLE" /path/to/corporate-ca.pem > ~/combined-ca.pem
         export REQUESTS_CA_BUNDLE=~/combined-ca.pem

      .. note::

         Setting ``REQUESTS_CA_BUNDLE`` to the corporate CA file alone is not
         sufficient: it replaces ``certifi``'s bundle entirely, so public CAs
         (DigiCert, etc.) are no longer trusted. The combined bundle is required
         when the corporate proxy does not intercept all domains.

      .. note::

         Once you are done, you should delete the generated PEM files to keep
         your environment clean.

   #. Run the script by running ``python check_vulnerabilities.py --run-local``.

.. warning::

   The ``requirements-for-safety.txt`` file must be kept up to date for the
   vulnerability scan to reflect the actual state of your dependencies:

   - **If your dependencies are pinned** (for example, ``package==1.2.3``): regenerate
      the file whenever you modify the file defining your project dependencies
      (for example, ``pyproject.toml``).
   - **If your dependencies are not pinned** (for example, ``package>=1.2.0``):
      regenerate the file before each check as well, since the resolved versions
      may change over time even without any change to the dependency definitions.

   To regenerate, delete ``requirements-for-safety.txt``, then repeat steps 3
   and 4 above (reinstall the project in the first virtual environment and run
   ``pip freeze > requirements-for-safety.txt`` again).

.. warning::

   The ``ansys/check-vulnerabilities`` action needs to be performed on a public repository.
   If the repository is private, the action is going to fail due to denied access.


Documentation on how to address common vulnerabilities can be found in the
`PyAnsys developer's guide <https://dev.docs.pyansys.com/how-to/vulnerabilities.html#addressing-common-vulnerabilities-in-python-libraries-and-applications>`_.

.. jinja:: check-vulnerabilities
    :file: _templates/action.rst.jinja

Check actions security action
-----------------------------

.. note::

   ``zizmor`` is configurable with a ``zizmor.yml`` file. This action uses this behind the scenes for the ``trust-ansys-actions``
   option. If a custom ``zizmor.yml`` exists in the repository root, it takes precedence and the option is ignored. Refer to the
   `zizmor configuration settings <https://docs.zizmor.sh/configuration/#settings>`_ for details about setting up custom configuration.

   To audit locally for faster feedback when addressing vulnerabilities:

   #. Create a virtual environment with ``python -m venv .venv`` and activate it.
   #. Install zizmor: ``pip install zizmor==1.23.1``.
   #. If the repository doesn't use a custom ``zizmor.yml`` file, download the ``zizmor.yml`` file from the
      `ansys/action check-actions-security folder <https://github.com/ansys/actions/tree/main/check-actions-security>`_
      and move it to the root of the repository.

      #. If ``trust-ansys-actions`` has been set to false in the workflow (i.e., you pin ``ansys/actions`` with a SHA instead of a tag), you must edit the
         default policies in ``zizmor.yml`` as follows:

         .. tab-set::


            .. tab-item:: Before

               .. code:: yaml

                  rules:
                  unpinned-uses:
                     config:
                        policies:
                        ansys/*: ref-pin
                        actions/*: hash-pin


            .. tab-item:: After

               .. code:: yaml

                  rules:
                  unpinned-uses:
                     config:
                        policies:
                        ansys/*: hash-pin
                        actions/*: hash-pin

   #. Run ``zizmor --persona=pedantic .`` for a minimal audit (action's default) or ``zizmor --persona=auditor .`` for a stricter audit.
   #. To generate a summary table locally:

      - Download the ``zizmor-summary.py`` file from the
        `ansys/action python utilities folder <https://github.com/ansys/actions/tree/main/python-utils>`_ and
        move it to the root of the repository.
      - Set one of the following environment variables:

         - ``HIGH_AUDIT_LEVEL=--persona=pedantic`` for minimal audit.
         - ``STRICT_AUDIT_LEVEL=--persona=auditor`` for stricter audit.

      - Run the script: ``python zizmor-summary.py``.

For more details on addressing workflow vulnerabilities, see
`the relevant PyAnsys developer's guide section <https://dev.docs.pyansys.com/how-to/vulnerabilities.html#addressing-common-vulnerabilities-in-github-actions>`_.

.. jinja:: check-actions-security
    :file: _templates/action.rst.jinja