A GitHub Action that uses pip-audit
to scan Python dependencies for known vulnerabilities.
This project is maintained in part by Trail of Bits with support from Google. This is not an official Google or Trail of Bits product.
Simply add pypa/gh-action-pip-audit to one of your workflows:
jobs:
selftest:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: install
run: python -m pip install .
- uses: pypa/[email protected]Or, with a virtual environment:
jobs:
selftest:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: install
run: |
python -m venv env/
source env/bin/activate
python -m pip install .
- uses: pypa/[email protected]
with:
virtual-environment: env/By default, pip-audit will run in "pip list source" mode, meaning that it'll
attempt to collect dependencies from the local environment. See
the configuration documentation below for more input
and behavioral options.
gh-action-pip-audit takes a variety of configuration inputs, all of which are
optional.
Default: Empty, indicating "pip list source" mode
The inputs setting controls what sources pip-audit runs on.
To audit one or more requirements-style inputs:
- uses: pypa/[email protected]
with:
inputs: requirements.txt dev-requirements.txtTo audit a project that uses pyproject.toml for its dependencies:
- uses: pypa/[email protected]
with:
# NOTE: this can be `.`, for the current directory
inputs: path/to/project/Default: Empty, indicating no virtual environment
The virtual-environment setting controls the
virtual environment that this
action loads to, if specified. The value is the top-level directory for the
virtual environment, which is conventionally named env or venv.
Depending on your CI and project configuration, you may or may not need this setting. Specifically, you only need it if you satisfy all of the following conditions:
- You are auditing an environment (not a requirements file or other project metadata)
- Your environment is not already "active", i.e.
python -m pippoints to a differentpipthan the one that your environment uses
Example: use the virtual environment specified at env/, relative to the
current directory:
- uses: pypa/[email protected]
with:
virtual-environment: env/
# Note the absence of `input:`, since we're auditing the environment.Default: false
The local setting corresponds to pip-audit's --local flag, which controls
whether non-local dependencies are included when auditing in "pip list source"
mode.
By default all dependencies are included; with local: true, only dependencies
installed directly into the current environment are included.
Example:
- uses: pypa/[email protected]
with:
local: trueDefault: PyPI
Options: PyPI, OSV (case insensitive)
The vulnerability-service setting controls which vulnerability service is used for the audit.
It's directly equivalent to pip-audit --vulnerability-service=....
To audit with OSV instead of PyPI:
- uses: pypa/[email protected]
with:
vulnerability-service: osvDefault: false
The require-hashes setting controls whether strict hash checking is enabled.
It's directly equivalent to pip-audit --require-hashes ....
Example:
- uses: pypa/[email protected]
with:
# NOTE: only works with requirements-style inputs
inputs: requirements.txt
require-hashes: trueDefault: false
The no-deps setting controls whether dependency resolution is performed.
It's directly equivalent to pip-audit --no-deps ....
Example:
- uses: pypa/[email protected]
with:
# NOTE: only works with requirements-style inputs
inputs: requirements.txt
no-deps: trueDefault: true
The summary setting controls whether a GitHub
job summary
is rendered at the end of the action.
Example:
- uses: pypa/[email protected]
with:
summary: falseDefault: Empty, indicating PyPI
The index-url setting specifies a base URL for an alternative PEP 503-compatible
package index.
This is probably not want you want. If your goal is to add complementary
indices to search (such as a corporate index with private packages), see
extra-index-urls.
Example:
- uses: pypa/[email protected]
with:
index-url: https://example.corporate.local/simpleDefault: Empty (no extra indexes are searched by default)
The extra-index-urls setting specifies one or more extra PEP 503-compatible packages
indexes to search when resolving dependencies. Each URL is whitespace-separated.
Example:
- uses: pypa/[email protected]
with:
extra-index-urls: |
https://example.corporate.local/simple
https://prod.corporate.local/simpleDefault: Empty (no vulnerabilities are ignored)
The ignore-vulns setting specifies one or more vulnerability IDs to
ignore (i.e., exclude from the results) if present. Each ID is whitespace-separated.
Example
- uses: pypa/[email protected]
with:
ignore-vulns: |
GHSA-XXXX-YYYYYY
PYSEC-AAAA-BBBBBDefault: false
The disable-pip setting disable the use of pip for dependency resolution. This can only be used with
hashed requirements files or if the no-deps setting has been provided.
Example
- uses: pypa/[email protected]
with:
inputs: requirements.lock
disable-pip: true
no-deps: true⚠️ Internal options ⚠️
Everything below is considered "internal," which means that it isn't part of the stable public settings and may be removed or changed at any point. You probably do not need these settings.
All internal options are prefixed with internal-be-careful-.
Default: false
The internal-be-careful-allow-failure setting allows the job to pass, even
if the underlying pip-audit run fails (e.g. due to vulnerabilities detected).
Be very careful with this setting! Using it unwittingly will prevent the action
from failing your CI when pip-audit fails, which is probably not what you want.
Example:
- uses: pypa/[email protected]
with:
internal-be-careful-allow-failure: trueDefault: ""
The internal-be-careful-extra-flags setting passes the specified flags
to pip-audit.
Example:
- uses: pypa/[email protected]
with:
internal-be-careful-extra-flags: --not-a-real-pip-audit-flagThis section is still a work in progress. Please help us improve it!
If you're auditing a requirements file, consider setting no-deps: true or
require-hashes: true:
- uses: pypa/[email protected]
with:
inputs: requirements.txt
require-hashes: trueor:
- uses: pypa/[email protected]
with:
inputs: requirements.txt
no-deps: trueSee the
"pip-audit takes longer than I expect!"
troubleshooting for more details.
In the default ("pip list source") configuration, pip-audit collects all
dependencies that are visible in the current environment.
Depending on the project or CI's configuration, this can include packages installed by the host system itself, or other Python projects that happen to be installed.
To minimize external dependencies, you can opt into a virtual environment:
- uses: pypa/[email protected]
with:
# must be populated earlier in the CI
virtual-environment: env/and, more aggressively, specify that only dependencies marked as "local" in the virtual environment should be included:
- uses: pypa/[email protected]
with:
# must be populated earlier in the CI
virtual-environment: env/
local: trueThe action prints debug information when the ACTIONS_STEP_DEBUG secret is set
to `true``. You should be able to enable this behavior by
following these instructions.
If you are adding pip-audit to a pipenv based project, you'll first need
to convert the Pipfile[.lock] to a requirements.txt file that pip-audit
can ingest. Use a Python tool, such as
pipfile-requirements, to
convert your Pipfile[.lock] to a requirements.txt file and then run
pip-audit GitHub Action against the generated requirements file.
jobs:
pip-audit:
steps:
- uses: actions/setup-python@v5
with:
python-version: 3.9 # change to your required version of Python
- name: 'Generate requirements.txt'
run: |
pipx run pipfile-requirements Pipfile.lock > requirements.txt
- uses: pypa/[email protected]
with:
inputs: requirements.txtgh-action-pip-audit is licensed under the Apache 2.0 License.
Everyone interacting with this project is expected to follow the PSF Code of Conduct.