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`` script and the ``requirements.txt`` file 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 virtual environment by running ``python -m venv .venv``.
   #. Activate the virtual environment.
   #. Install the required dependencies by running ``pip install -r requirements.txt``.
   #. Install your repository with the command ``pip install -e .``.
   #. 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>``.

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

.. warning::

   The ``ansys/check-vulnerabilities`` action needs to be performed on a public repository.
   If the repository is private, the action will 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.12.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

Check environment approval
--------------------------
This action is used to determine whether a manual approval step is needed in the
workflow. It evaluates the pull request workflow and determines the environment
name to be used in the workflow. The environment name should then be used in a
workflow job to trigger a manual approval step if needed.

.. jinja:: check-environment-approval
    :file: _templates/action.rst.jinja