Repository files navigation

A GitHub Action that usespip-auditto scan Python dependencies for known vulnerabilities.

This project is maintained in part byTrail of Bitswith support from Google. This is not an official Google or Trail of Bits product.

• Usage
• Configuration
  • ⚠️ Internal options⚠️
• Troubleshooting
• Tips and Tricks
• Licensing
• Code of Conduct

Simply addpypa/gh-action-pip-audit to one of your workflows:

jobs:selftest:runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v4      -name:installrun:python -m pip install .      -uses:pypa/gh-action-pip-audit@v1.1.0

Or, with a virtual environment:

jobs:selftest:runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v4      -name:installrun:|          python -m venv env/          source env/bin/activate          python -m pip install .      -uses:pypa/gh-action-pip-audit@v1.1.0with:virtual-environment:env/

By default,pip-audit will run in "pip list source" mode, meaning that it'llattempt to collect dependencies from the local environment. Seetheconfiguration documentation below for more inputand behavioral options.

gh-action-pip-audit takes a variety of configuration inputs, all of which areoptional.

Default: Empty, indicating "pip list source" mode

Theinputs setting controls what sourcespip-audit runs on.

To audit one or more requirements-style inputs:

-uses:pypa/gh-action-pip-audit@v1.1.0with:inputs:requirements.txt dev-requirements.txt

To audit a project that usespyproject.toml for its dependencies:

-uses:pypa/gh-action-pip-audit@v1.1.0with:# NOTE: this can be `.`, for the current directoryinputs:path/to/project/

Default: Empty, indicating no virtual environment

Thevirtual-environment setting controls thevirtual environment that thisaction loads to, if specified. The value is the top-level directory for thevirtual environment, which is conventionally namedenv orvenv.

Depending on your CI and project configuration, you may or may not need thissetting. Specifically, you only need it if you satisfyall of the followingconditions:

1. You are auditing anenvironment (not a requirements file or otherproject metadata)
2. Your environment is not already "active", i.e.python -m pip points to adifferentpip than the one that your environment uses

Example: use the virtual environment specified atenv/, relative to thecurrent directory:

-uses:pypa/gh-action-pip-audit@v1.1.0with:virtual-environment:env/# Note the absence of `input:`, since we're auditing the environment.

Default:false

Thelocal setting corresponds topip-audit's--local flag, which controlswhether non-local dependencies are included when auditing in "pip list source"mode.

By default all dependencies are included; withlocal: true, only dependenciesinstalled directly into the current environment are included.

Example:

-uses:pypa/gh-action-pip-audit@v1.1.0with:local:true

Default:PyPI

Options:PyPI,OSV (case insensitive)

Thevulnerability-service setting controls which vulnerability service is used for the audit.It's directly equivalent topip-audit --vulnerability-service=....

To audit with OSV instead of PyPI:

-uses:pypa/gh-action-pip-audit@v1.1.0with:vulnerability-service:osv

Default:false

Therequire-hashes setting controls whether strict hash checking is enabled.It's directly equivalent topip-audit --require-hashes ....

Example:

-uses:pypa/gh-action-pip-audit@v1.1.0with:# NOTE: only works with requirements-style inputsinputs:requirements.txtrequire-hashes:true

Default:false

Theno-deps setting controls whether dependency resolution is performed.It's directly equivalent topip-audit --no-deps ....

Example:

-uses:pypa/gh-action-pip-audit@v1.1.0with:# NOTE: only works with requirements-style inputsinputs:requirements.txtno-deps:true

Default:true

Thesummary setting controls whether a GitHubjob summaryis rendered at the end of the action.

Example:

-uses:pypa/gh-action-pip-audit@v1.1.0with:summary:false

Default: Empty, indicatingPyPI

Theindex-url setting specifies a base URL for an alternative PEP 503-compatiblepackage index.

This is probably not want you want. If your goal is to addcomplementaryindices to search (such as a corporate index with private packages), seeextra-index-urls.

Example:

-uses:pypa/gh-action-pip-audit@v1.1.0with:index-url:https://example.corporate.local/simple

Default: Empty (no extra indexes are searched by default)

Theextra-index-urls setting specifies one or moreextra PEP 503-compatible packagesindexes to search when resolving dependencies. Each URL is whitespace-separated.

Example:

-uses:pypa/gh-action-pip-audit@v1.1.0with:extra-index-urls:|      https://example.corporate.local/simple      https://prod.corporate.local/simple

Default: Empty (no vulnerabilities are ignored)

Theignore-vulns setting specifies one or more vulnerability IDs toignore (i.e., exclude from the results) if present. Each ID is whitespace-separated.

Example

-uses:pypa/gh-action-pip-audit@v1.1.0with:ignore-vulns:|      GHSA-XXXX-YYYYYY      PYSEC-AAAA-BBBBB

Default:false

Thedisable-pip setting disable the use ofpip for dependency resolution. This can only be used withhashed requirements files or if theno-deps setting has been provided.

Example

-uses:pypa/gh-action-pip-audit@v1.1.0with:inputs:requirements.lockdisable-pip:trueno-deps:true

Default:false

Thelocked setting enables audits of lock files (pylock.*.toml) from the local Python project.

Example

-uses:pypa/gh-action-pip-audit@v1.1.0with:inputs:path/to/project/locked:true

-uses:pypa/gh-action-pip-audit@v1.1.0with:internal-be-careful-allow-failure:true

-uses:pypa/gh-action-pip-audit@v1.1.0with:internal-be-careful-extra-flags:--not-a-real-pip-audit-flag

This section is still a work in progress. Please help us improve it!

If you're auditing a requirements file, consider settingno-deps: true orrequire-hashes: true:

-uses:pypa/gh-action-pip-audit@v1.1.0with:inputs:requirements.txtrequire-hashes:true

or:

-uses:pypa/gh-action-pip-audit@v1.1.0with:inputs:requirements.txtno-deps:true

See the"pip-audit takes longer than I expect!"troubleshooting for more details.

In the default ("pip list source") configuration,pip-audit collects alldependencies that are visible in the current environment.

Depending on the project or CI's configuration, this can include packages installedby 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/gh-action-pip-audit@v1.1.0with:# must be populated earlier in the CIvirtual-environment:env/

and, more aggressively, specify that only dependencies marked as "local"in the virtual environment should be included:

-uses:pypa/gh-action-pip-audit@v1.1.0with:# must be populated earlier in the CIvirtual-environment:env/local:true

The action prints debug information when theACTIONS_STEP_DEBUG secret is setto `true``. You should be able to enable this behavior byfollowing these instructions.

If you are addingpip-audit to a pipenv based project, you'll first needto convert thePipfile[.lock] to arequirements.txt file thatpip-auditcan ingest. Use a Python tool, such aspipfile-requirements, toconvert yourPipfile[.lock] to arequirements.txt file and then runpip-audit GitHub Action against the generated requirements file.

jobs:pip-audit:steps:      -uses:actions/setup-python@v5with: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/gh-action-pip-audit@v1.1.0with:inputs:requirements.txt

gh-action-pip-audit is licensed under the Apache 2.0 License.

Everyone interacting with this project is expected to follow thePSF Code of Conduct.