A GitHub Action that uses pip-audit to scan Python dependencies for known vulnerabilities.

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

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

jobs:
  selftest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: install
        run: python -m pip install .
      - uses: trailofbits/[email protected]

Or, with a virtual environment:

jobs:
  selftest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: install
        run: |
          python -m venv env/
          source env/bin/activate
          python -m pip install .
      - uses: trailofbits/[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: trailofbits/[email protected]
  with:
    inputs: requirements.txt dev-requirements.txt

To audit a project that uses pyproject.toml for its dependencies:

- uses: trailofbits/[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:

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

Example: use the virtual environment specified at env/, relative to the current directory:

- uses: trailofbits/[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: trailofbits/[email protected]
  with:
    local: true

Default: 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: trailofbits/[email protected]
  with:
    vulnerability-service: osv

Default: false

The require-hashes setting controls whether strict hash checking is enabled. It's directly equivalent to pip-audit --require-hashes ....

Example:

- uses: trailofbits/[email protected]
  with:
    # NOTE: only works with requirements-style inputs
    inputs: requirements.txt
    require-hashes: true

Default: false

The no-deps setting controls whether dependency resolution is performed. It's directly equivalent to pip-audit --no-deps ....

Example:

- uses: trailofbits/[email protected]
  with:
    # NOTE: only works with requirements-style inputs
    inputs: requirements.txt
    no-deps: true

Default: true

The summary setting controls whether a GitHub job summary is rendered at the end of the action.

Example:

- uses: trailofbits/[email protected]
  with:
    summary: false

Default: 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: trailofbits/[email protected]
  with:
    index-url: https://example.corporate.local/simple

Default: 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: trailofbits/[email protected]
  with:
    extra-index-urls: |
      https://example.corporate.local/simple
      https://prod.corporate.local/simple

Default: 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: trailofbits/[email protected]
  with:
    ignore-vulns: |
      GHSA-XXXX-YYYYYY
      PYSEC-AAAA-BBBBB

- uses: trailofbits/[email protected]
  with:
    internal-be-careful-allow-failure: true

- uses: trailofbits/[email protected]
  with:
    internal-be-careful-debug: true

This 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: trailofbits/[email protected]
  with:
    inputs: requirements.txt
    require-hashes: true

or:

- uses: trailofbits/[email protected]
  with:
    inputs: requirements.txt
    no-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 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: trailofbits/[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: trailofbits/[email protected]
  with:
    # must be populated earlier in the CI
    virtual-environment: env/
    local: true

gh-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.