pip-audit Documentation

Transitive Vulnerabilities

pip-audit is primarily an auditing tool for Python packages. It may not detect "transitive" vulnerabilities that are exposed through a Python package but are not part of the package itself.

For example, if a Python package uses a vulnerable shared system library, pip-audit is unlikely to flag it because the Python package version is not strongly coupled to the shared library's version in vulnerability databases. Use pip-audit to secure your Python dependency tree, but be aware of the underlying system dependencies.

pip-audit supports --index-url and --extra-index-url for package indices.

Important Authentication Notes:

• No Interactive Auth: pip-audit will not prompt you for a username or password.
• Keyring Support: It supports pip's keyring authentication via the subprocess provider, but this is subject to additional restrictions (e.g., requiring a username).
• Hard-coded Usernames: Some registries (like Google Artifact Registry) require specific hard-coded usernames (e.g., oauth2accesstoken).

You can integrate pip-audit into your pre-commit workflow to audit requirements files locally.

Important: Because pre-commit.ci does not allow network calls, you should configure pip-audit to skip running in CI environments to avoid failures.

Example .pre-commit-config.yaml snippet:

  - repo: https://github.com/pypa/pip-audit
    rev: v2.10.1
    hooks:
      -   id: pip-audit
          args: ["-r", "requirements.txt"]

ci:
  # Leave pip-audit to only run locally and not in CI
  # pre-commit.ci does not allow network calls
  skip: [pip-audit]

pip-audit requires Python 3.10 or newer. You can install it using pip or conda.

Using pip:

python -m pip install pip-audit

Using conda:

conda install -c conda-forge pip-audit

Note: Third-party packages for pip-audit are not directly supported by the project; please consult your package manager's documentation.

You can use the official pypa/gh-action-pip-audit GitHub Action to audit your dependencies in CI.

Example configuration:

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

pip-audit may perform dependency resolution, which can be slow. You can avoid this in two ways:

1. Audit a pre-installed environment: Run pip-audit without arguments to audit the current environment. Use --local to exclude non-local packages.
2. Use pinned dependencies: If your input is fully pinned, use --no-deps (pinned without hashes) or --require-hashes (pinned including hashes) to skip resolution. --require-hashes is preferred for better integrity.

pip-audit can be used to scan various Python dependency sources for known vulnerabilities.

Common usage patterns include:

• Current Environment: Audit the packages installed in your active Python environment.
• Requirements File: Audit dependencies listed in a requirements.txt file.
• Local Project: Audit a local directory by searching for supported project files like pyproject.toml or pylock.*.toml.
• Lockfiles: Audit a local project specifically using its lockfiles.

To see vulnerability aliases (like CVE or GHSA IDs) or detailed descriptions in the output, use the --aliases or --desc flags respectively.

You can configure several pip-audit flags using environment variables:

AuditState acts as a coordinator for one or more _StateActor objects. An _StateActor is an abstract base class that defines how an individual component (like a CLI spinner) should react to state changes.

When AuditState methods are called, they propagate the call to all registered members:

1. AuditState.initialize() $\rightarrow$ calls member.initialize() on all actors.
2. AuditState.update_state(msg, logs) $\rightarrow$ calls member.update_state(msg, logs) on all actors.
3. AuditState.finalize() $\rightarrow$ calls member.finalize() on all actors.

This pattern allows the core audit logic to remain decoupled from the specific UI implementation (e.g., a terminal spinner vs. a web-based progress bar).

The FixVersion class is an abstract base class for dependency fix results. You should not instantiate it directly. Instead, use the is_skipped() method to determine if the resolution attempt was successful or if it resulted in a SkippedFixVersion.

• If is_skipped() returns True, the object is a SkippedFixVersion and you can access the skip_reason attribute.
• If is_skipped() returns False, the object is a ResolvedFixVersion and you can access the version attribute.