| Name | pip-audit JSON |
| Version |
2.7.3
JSON |
| download |
| home_page | None |
| Summary | A tool for scanning Python environments for known vulnerabilities |
| upload_time | 2024-04-30 19:27:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
pip-audit
=========
<!--- BADGES: START --->
[](https://pypi.org/project/pip-audit)
[](https://repology.org/project/python:pip-audit/versions)
[](https://api.securityscorecards.dev/projects/github.com/pypa/pip-audit)
<!--- BADGES: END --->
`pip-audit` is a tool for scanning Python environments for packages
with known vulnerabilities. It uses the Python Packaging Advisory Database
(https://github.com/pypa/advisory-database) via the
[PyPI JSON API](https://warehouse.pypa.io/api-reference/json.html) as a source
of vulnerability reports.
This project is maintained in part by [Trail of Bits](https://www.trailofbits.com/)
with support from Google. This is not an official Google or Trail of Bits product.
## Index
* [Features](#features)
* [Installation](#installation)
* [Third-party packages](#third-party-packages)
* [GitHub Actions](#github-actions)
* [`pre-commit` support](#pre-commit-support)
* [Usage](#usage)
* [Exit codes](#exit-codes)
* [Dry runs](#dry-runs)
* [Examples](#examples)
* [Troubleshooting](#troubleshooting)
* [Tips and Tricks](#tips-and-tricks)
* [Security model](#security-model)
* [Licensing](#licensing)
* [Contributing](#contributing)
* [Code of Conduct](#code-of-conduct)
## Features
* Support for auditing local environments and requirements-style files
* Support for multiple vulnerability services
([PyPI](https://warehouse.pypa.io/api-reference/json.html#known-vulnerabilities),
[OSV](https://osv.dev/docs/))
* Support for emitting
[SBOMs](https://en.wikipedia.org/wiki/Software_bill_of_materials) in
[CycloneDX](https://cyclonedx.org/) XML or JSON
* Support for automatically fixing vulnerable dependencies (`--fix`)
* Human and machine-readable output formats (columnar, Markdown, JSON)
* Seamlessly reuses your existing local `pip` caches
## Installation
`pip-audit` requires Python 3.8 or newer, and can be installed directly via `pip`:
```bash
python -m pip install pip-audit
```
### Third-party packages
There are multiple **third-party** packages for `pip-audit`. The matrices and badges below
list some of them:
[](https://repology.org/project/python:pip-audit/versions)
[](https://repology.org/project/pip-audit/versions)
[][#conda-forge-package]
[][#conda-forge-package]
[#conda-forge-package]: https://anaconda.org/conda-forge/pip-audit
In particular, `pip-audit` can be installed via `conda`:
```bash
conda install -c conda-forge pip-audit
```
Third-party packages are **not** directly supported by this project. Please consult your package manager's
documentation for more detailed installation guidance.
### GitHub Actions
`pip-audit` has [an official GitHub Action](https://github.com/pypa/gh-action-pip-audit)!
You can install it from the
[GitHub Marketplace](https://github.com/marketplace/actions/gh-action-pip-audit), or
add it to your CI manually:
```yaml
jobs:
pip-audit:
steps:
- uses: pypa/gh-action-pip-audit@v1.0.0
with:
inputs: requirements.txt
```
See the
[action documentation](https://github.com/pypa/gh-action-pip-audit/blob/main/README.md)
for more details and usage examples.
### `pre-commit` support
`pip-audit` has [`pre-commit`](https://pre-commit.com/) support.
For example, using `pip-audit` via `pre-commit` to audit a requirements file:
```yaml
- repo: https://github.com/pypa/pip-audit
rev: v2.7.3
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]
```
Any `pip-audit` arguments documented below can be passed.
## Usage
You can run `pip-audit` as a standalone program, or via `python -m`:
```bash
pip-audit --help
python -m pip_audit --help
```
<!-- @begin-pip-audit-help@ -->
```
usage: pip-audit [-h] [-V] [-l] [-r REQUIREMENT] [-f FORMAT] [-s SERVICE] [-d]
[-S] [--desc [{on,off,auto}]] [--aliases [{on,off,auto}]]
[--cache-dir CACHE_DIR] [--progress-spinner {on,off}]
[--timeout TIMEOUT] [--path PATH] [-v] [--fix]
[--require-hashes] [--index-url INDEX_URL]
[--extra-index-url URL] [--skip-editable] [--no-deps]
[-o FILE] [--ignore-vuln ID] [--disable-pip]
[project_path]
audit the Python environment for dependencies with known vulnerabilities
positional arguments:
project_path audit a local Python project at the given path
(default: None)
optional arguments:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-l, --local show only results for dependencies in the local
environment (default: False)
-r REQUIREMENT, --requirement REQUIREMENT
audit the given requirements file; this option can be
used multiple times (default: None)
-f FORMAT, --format FORMAT
the format to emit audit results in (choices: columns,
json, cyclonedx-json, cyclonedx-xml, markdown)
(default: columns)
-s SERVICE, --vulnerability-service SERVICE
the vulnerability service to audit dependencies
against (choices: osv, pypi) (default: pypi)
-d, --dry-run without `--fix`: collect all dependencies but do not
perform the auditing step; with `--fix`: perform the
auditing step but do not perform any fixes (default:
False)
-S, --strict fail the entire audit if dependency collection fails
on any dependency (default: False)
--desc [{on,off,auto}]
include a description for each vulnerability; `auto`
defaults to `on` for the `json` format. This flag has
no effect on the `cyclonedx-json` or `cyclonedx-xml`
formats. (default: auto)
--aliases [{on,off,auto}]
includes alias IDs for each vulnerability; `auto`
defaults to `on` for the `json` format. This flag has
no effect on the `cyclonedx-json` or `cyclonedx-xml`
formats. (default: auto)
--cache-dir CACHE_DIR
the directory to use as an HTTP cache for PyPI; uses
the `pip` HTTP cache by default (default: None)
--progress-spinner {on,off}
display a progress spinner (default: on)
--timeout TIMEOUT set the socket timeout (default: 15)
--path PATH restrict to the specified installation path for
auditing packages; this option can be used multiple
times (default: [])
-v, --verbose run with additional debug logging; supply multiple
times to increase verbosity (default: 0)
--fix automatically upgrade dependencies with known
vulnerabilities (default: False)
--require-hashes require a hash to check each requirement against, for
repeatable audits; this option is implied when any
package in a requirements file has a `--hash` option.
(default: False)
--index-url INDEX_URL
base URL of the Python Package Index; this should
point to a repository compliant with PEP 503 (the
simple repository API); this will be resolved by pip
if not specified (default: None)
--extra-index-url URL
extra URLs of package indexes to use in addition to
`--index-url`; should follow the same rules as
`--index-url` (default: [])
--skip-editable don't audit packages that are marked as editable
(default: False)
--no-deps don't perform any dependency resolution; requires all
requirements are pinned to an exact version (default:
False)
-o FILE, --output FILE
output results to the given file (default: stdout)
--ignore-vuln ID ignore a specific vulnerability by its vulnerability
ID; this option can be used multiple times (default:
[])
--disable-pip don't use `pip` for dependency resolution; this can
only be used with hashed requirements files or if the
`--no-deps` flag has been provided (default: False)
```
<!-- @end-pip-audit-help@ -->
### Exit codes
On completion, `pip-audit` will exit with a code indicating its status.
The current codes are:
* `0`: No known vulnerabilities were detected.
* `1`: One or more known vulnerabilities were found.
`pip-audit`'s exit code cannot be suppressed.
See [Suppressing exit codes from `pip-audit`](#suppressing-exit-codes-from-pip-audit)
for supported alternatives.
### Dry runs
`pip-audit` supports the `--dry-run` flag, which can be used to control whether
an audit (or fix) step is actually performed.
* On its own, `pip-audit --dry-run` skips the auditing step and prints
the number of dependencies that *would have been* audited.
* In fix mode, `pip-audit --fix --dry-run` performs the auditing step and prints
out the fix behavior (i.e., which dependencies would be upgraded or skipped)
that *would have been performed*.
## Examples
Audit dependencies for the current Python environment:
```
$ pip-audit
No known vulnerabilities found
```
Audit dependencies for a given requirements file:
```
$ pip-audit -r ./requirements.txt
No known vulnerabilities found
```
Audit dependencies for a requirements file, excluding system packages:
```
$ pip-audit -r ./requirements.txt -l
No known vulnerabilities found
```
Audit dependencies for a local Python project:
```
$ pip-audit .
No known vulnerabilities found
```
`pip-audit` searches the provided path for various Python "project" files. At the moment, only `pyproject.toml` is supported.
Audit dependencies when there are vulnerabilities present:
```
$ pip-audit
Found 2 known vulnerabilities in 1 package
Name Version ID Fix Versions
---- ------- -------------- ------------
Flask 0.5 PYSEC-2019-179 1.0
Flask 0.5 PYSEC-2018-66 0.12.3
```
Audit dependencies including aliases:
```
$ pip-audit --aliases
Found 2 known vulnerabilities in 1 package
Name Version ID Fix Versions Aliases
---- ------- -------------- ------------ -------------------------------------
Flask 0.5 PYSEC-2019-179 1.0 CVE-2019-1010083, GHSA-5wv5-4vpf-pj6m
Flask 0.5 PYSEC-2018-66 0.12.3 CVE-2018-1000656, GHSA-562c-5r94-xh97
```
Audit dependencies including descriptions:
```
$ pip-audit --desc
Found 2 known vulnerabilities in 1 package
Name Version ID Fix Versions Description
---- ------- -------------- ------------ --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Flask 0.5 PYSEC-2019-179 1.0 The Pallets Project Flask before 1.0 is affected by: unexpected memory usage. The impact is: denial of service. The attack vector is: crafted encoded JSON data. The fixed version is: 1. NOTE: this may overlap CVE-2018-1000656.
Flask 0.5 PYSEC-2018-66 0.12.3 The Pallets Project flask version Before 0.12.3 contains a CWE-20: Improper Input Validation vulnerability in flask that can result in Large amount of memory usage possibly leading to denial of service. This attack appear to be exploitable via Attacker provides JSON data in incorrect encoding. This vulnerability appears to have been fixed in 0.12.3. NOTE: this may overlap CVE-2019-1010083.
```
Audit dependencies in JSON format:
```
$ pip-audit -f json | python -m json.tool
Found 2 known vulnerabilities in 1 package
[
{
"name": "flask",
"version": "0.5",
"vulns": [
{
"id": "PYSEC-2019-179",
"fix_versions": [
"1.0"
],
"aliases": [
"CVE-2019-1010083",
"GHSA-5wv5-4vpf-pj6m"
],
"description": "The Pallets Project Flask before 1.0 is affected by: unexpected memory usage. The impact is: denial of service. The attack vector is: crafted encoded JSON data. The fixed version is: 1. NOTE: this may overlap CVE-2018-1000656."
},
{
"id": "PYSEC-2018-66",
"fix_versions": [
"0.12.3"
],
"aliases": [
"CVE-2018-1000656",
"GHSA-562c-5r94-xh97"
],
"description": "The Pallets Project flask version Before 0.12.3 contains a CWE-20: Improper Input Validation vulnerability in flask that can result in Large amount of memory usage possibly leading to denial of service. This attack appear to be exploitable via Attacker provides JSON data in incorrect encoding. This vulnerability appears to have been fixed in 0.12.3. NOTE: this may overlap CVE-2019-1010083."
}
]
},
{
"name": "jinja2",
"version": "3.0.2",
"vulns": []
},
{
"name": "pip",
"version": "21.3.1",
"vulns": []
},
{
"name": "setuptools",
"version": "57.4.0",
"vulns": []
},
{
"name": "werkzeug",
"version": "2.0.2",
"vulns": []
},
{
"name": "markupsafe",
"version": "2.0.1",
"vulns": []
}
]
```
Audit and attempt to automatically upgrade vulnerable dependencies:
```
$ pip-audit --fix
Found 2 known vulnerabilities in 1 package and fixed 2 vulnerabilities in 1 package
Name Version ID Fix Versions Applied Fix
----- ------- -------------- ------------ ----------------------------------------
flask 0.5 PYSEC-2019-179 1.0 Successfully upgraded flask (0.5 => 1.0)
flask 0.5 PYSEC-2018-66 0.12.3 Successfully upgraded flask (0.5 => 1.0)
```
## Troubleshooting
Have you resolved a problem with `pip-audit`? Help us by contributing to this
section!
### `pip-audit` shows irrelevant vulnerability reports!
In a perfect world, vulnerability feeds would have an infinite signal-to-noise
ratio: every vulnerability report would be (1) correct, and (2) applicable to
every use of every dependency.
Unfortunately, neither of these is guaranteed: vulnerability feeds are not
immune to extraneous or spam reports, and not all uses of a particular
dependency map to all potential classes of vulnerabilities.
If your `pip-audit` runs produce vulnerability reports that aren't actionable
for your particular application or use case, you can use the `--ignore-vuln ID`
option to ignore specific vulnerability reports. `--ignore-vuln` supports
aliases, so you can use a `GHSA-xxx` or `CVE-xxx` ID instead of a `PYSEC-xxx`
ID if the report in question does not have a PYSEC ID.
For example, here is how you might ignore GHSA-w596-4wvx-j9j6, which is a
common source of noisy vulnerability reports and false positives for users of
[`pytest`](https://github.com/pytest-dev/pytest):
```console
# Run the audit as normal, but exclude any reports that match GHSA-w596-4wvx-j9j6
$ pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6
```
The `--ignore-vuln ID` option works with all other dependency resolution
and auditing options, meaning that it should function correctly with
requirements-style inputs, alternative vulnerability feeds, and so forth.
It can also be passed multiple times, to ignore multiple reports:
```console
# Run the audit as normal, but exclude any reports that match these IDs
$ pip-audit --ignore-vuln CVE-XXX-YYYY --ignore-vuln CVE-ZZZ-AAAA
```
### `pip-audit` takes longer than I expect!
Depending on how you're using it, `pip-audit` may have to perform its
own dependency resolution, which can take roughly as long as `pip install`
does for a project. See the [security model](#security-model) for an explanation.
You have two options for avoiding dependency resolution: *audit a pre-installed
environment*, or *ensure that your dependencies are already fully resolved*.
If you know that you've already fully configured an environment equivalent
to the one that `pip-audit -r requirements.txt` would audit, you can simply
reuse it:
```console
# Note the absence of any "input" arguments, indicating that the environment is used.
$ pip-audit
# Optionally filter out non-local packages, for virtual environments:
$ pip-audit --local
```
Alternatively, if your input is fully pinned (and optionally hashed), you
can tell `pip-audit` to skip dependency resolution with either `--no-deps`
(pinned without hashes) or `--require-hashes` (pinned including hashes).
The latter is equivalent to `pip`'s
[hash-checking mode](https://pip.pypa.io/en/stable/cli/pip_install/#hash-checking-mode)
and is preferred, since it offers additional integrity.
```console
# fails if any dependency is not fully pinned
$ pip-audit --no-deps -r requirements.txt
# fails if any dependency is not fully pinned *or* is missing hashes
$ pip-audit --require-hashes -r requirements.txt
```
### `pip-audit` can't authenticate to my third-party index!
### Authenticated third-party or private indices
`pip-audit` supports `--index-url` and `--extra-index-url` for configuring an alternate
or supplemental package indices, just like `pip`.
When *unauthenticated*, these indices should work as expected. However, when a third-party
index requires authentication, `pip-audit` has a few additional restrictions on top of
ordinary `pip`:
* Interactive authentication is **not** supported. In other words: `pip-audit` will **not**
prompt you for a username/password for the index.
* [`pip`'s `keyring` authentication](https://pip.pypa.io/en/stable/topics/authentication/#keyring-support)
**is** supported, but in a limited fashion: `pip-audit` uses the `subprocess` keyring provider,
since audits happen in isolated virtual environments. The `subprocess` provider in turn
is subject to additional restrictions (such as a required username);
[`pip`'s documentation](https://pip.pypa.io/en/stable/topics/authentication/#using-keyring-as-a-command-line-application)
explains these in depth.
In addition to the above, some third-party indices have required, hard-coded usernames.
For example, for Google Artifact registry, the hard-coded username is `oauth2accesstoken`.
See [#742](https://github.com/pypa/pip-audit/issues/742) and
[pip#11971](https://github.com/pypa/pip/issues/11971) for additional context.
## Tips and Tricks
### Running against a `pipenv` project
`pipenv` uses both a `Pipfile` and `Pipfile.lock` file to track and freeze dependencies
instead of a `requirements.txt` file. `pip-audit` cannot process the `Pipfile[.lock]`
files directly, however, these can be converted to a supported `requirements.txt` file
that `pip-audit` can run against. `pipenv` has a built-in command to convert dependencies
to a `requirements.txt` file (as of [`v2022.4.8`](https://pipenv.pypa.io/en/latest/changelog/#id206)):
```console
$ pipenv run pip-audit -r <(pipenv requirements)
```
### Suppressing exit codes from `pip-audit`
`pip-audit` intentionally does not support internally suppressing its own
exit codes.
Users who need to suppress a failing `pip-audit` invocation can use
one of the standard shell idioms for doing so:
```bash
pip-audit || true
```
or, to exit entirely:
```bash
pip-audit || exit 0
```
The exit code can also be captured and handled explicitly:
```bash
pip-audit
exitcode="${?}"
# do something with ${exitcode}
```
See [Exit codes](#exit-codes) for a list of potential codes that need handling.
### Reporting only fixable vulnerabilities
In development workflows, you may want to ignore the vulnerabilities that haven't been remediated yet and only investigate them in your release process. `pip-audit` does not support ignoring unfixed vulnerabilities. However, you can export its output in JSON format and externally process it. For example, if you want to exit with a non-zero code only when the detected vulnerabilities have known fix versions, you can process the output using [jq](https://github.com/jqlang/jq) as:
```shell
test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')"
```
A simple (and inefficient) example of using this method would be:
```shell
test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')" || pip-audit -r requirements.txt
```
which runs `pip-audit` as usual and exits with a non-zero code only if there are fixed versions for the known vulnerabilities.
## Security Model
This section exists to describe the security assumptions you **can** and **must not**
make when using `pip-audit`.
TL;DR: **If you wouldn't `pip install` it, you should not `pip audit` it.**
`pip-audit` is a tool for auditing Python environments for packages with
*known vulnerabilities*. A "known vulnerability" is a publicly reported flaw in
a package that, if uncorrected, *might* allow a malicious actor to perform
unintended actions.
`pip-audit` **can** protect you against known vulnerabilities by telling
you when you have them, and how you should upgrade them. For example,
if you have `somepackage==1.2.3` in your environment, `pip-audit` **can** tell
you that it needs to be upgraded to `1.2.4`.
You **can** assume that `pip-audit` will make a best effort to *fully resolve*
all of your Python dependencies and *either* fully audit each *or* explicitly
state which ones it has skipped, as well as why it has skipped them.
`pip-audit` is **not** a static code analyzer. It analyzes dependency trees,
not code, and it **cannot** guarantee that arbitrary dependency resolutions
occur statically. To understand why this is, refer to Dustin Ingram's
[excellent post on dependency resolution in Python](https://dustingram.com/articles/2018/03/05/why-pypi-doesnt-know-dependencies/).
As such: you **must not** assume that `pip-audit` will **defend** you against
malicious packages. In particular, it is **incorrect** to treat
`pip-audit -r INPUT` as a "more secure" variant of `pip-audit`. For all intents
and purposes, `pip-audit -r INPUT` is functionally equivalent to
`pip install -r INPUT`, with a small amount of **non-security isolation** to
avoid conflicts with any of your local environments.
`pip-audit` is first and foremost a auditing tool for *Python* packages.
You **must not** assume that `pip-audit` will detect or flag "transitive"
vulnerabilities that might be exposed through Python packages, but are not
actually part of the package itself. For example, `pip-audit`'s vulnerability
information sources are unlikely to include an advisory for a vulnerable shared
library that a popular Python package *might* use, since the Python package's
version is not strongly connected to the shared library's version.
## Licensing
`pip-audit` is licensed under the Apache 2.0 License.
`pip-audit` reuses and modifies examples from
[`resolvelib`](https://github.com/sarugaku/resolvelib), which is licensed under
the ISC license.
## Contributing
See [the contributing docs](CONTRIBUTING.md) for details.
## Code of Conduct
Everyone interacting with this project is expected to follow the
[PSF Code of Conduct](https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "pip-audit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Alex Cameron <alex.cameron@trailofbits.com>, Dustin Ingram <di@python.org>, William Woodruff <william@trailofbits.com>",
"download_url": "https://files.pythonhosted.org/packages/46/2f/d030d0d3a50b776f910dd87dc1d57dd4a27bfad176b85882f463632e4747/pip_audit-2.7.3.tar.gz",
"platform": null,
"description": "pip-audit\n=========\n\n<!--- BADGES: START --->\n\n[](https://pypi.org/project/pip-audit)\n[](https://repology.org/project/python:pip-audit/versions)\n[](https://api.securityscorecards.dev/projects/github.com/pypa/pip-audit)\n<!--- BADGES: END --->\n\n`pip-audit` is a tool for scanning Python environments for packages\nwith known vulnerabilities. It uses the Python Packaging Advisory Database\n(https://github.com/pypa/advisory-database) via the\n[PyPI JSON API](https://warehouse.pypa.io/api-reference/json.html) as a source\nof vulnerability reports.\n\nThis project is maintained in part by [Trail of Bits](https://www.trailofbits.com/)\nwith support from Google. This is not an official Google or Trail of Bits product.\n\n## Index\n\n* [Features](#features)\n* [Installation](#installation)\n * [Third-party packages](#third-party-packages)\n * [GitHub Actions](#github-actions)\n * [`pre-commit` support](#pre-commit-support)\n* [Usage](#usage)\n * [Exit codes](#exit-codes)\n * [Dry runs](#dry-runs)\n* [Examples](#examples)\n* [Troubleshooting](#troubleshooting)\n* [Tips and Tricks](#tips-and-tricks)\n* [Security model](#security-model)\n* [Licensing](#licensing)\n* [Contributing](#contributing)\n* [Code of Conduct](#code-of-conduct)\n\n## Features\n\n* Support for auditing local environments and requirements-style files\n* Support for multiple vulnerability services\n ([PyPI](https://warehouse.pypa.io/api-reference/json.html#known-vulnerabilities),\n [OSV](https://osv.dev/docs/))\n* Support for emitting\n [SBOMs](https://en.wikipedia.org/wiki/Software_bill_of_materials) in\n [CycloneDX](https://cyclonedx.org/) XML or JSON\n* Support for automatically fixing vulnerable dependencies (`--fix`)\n* Human and machine-readable output formats (columnar, Markdown, JSON)\n* Seamlessly reuses your existing local `pip` caches\n\n## Installation\n\n`pip-audit` requires Python 3.8 or newer, and can be installed directly via `pip`:\n\n```bash\npython -m pip install pip-audit\n```\n\n### Third-party packages\n\nThere are multiple **third-party** packages for `pip-audit`. The matrices and badges below\nlist some of them:\n\n[](https://repology.org/project/python:pip-audit/versions)\n[](https://repology.org/project/pip-audit/versions)\n[][#conda-forge-package]\n[][#conda-forge-package]\n\n[#conda-forge-package]: https://anaconda.org/conda-forge/pip-audit\n\nIn particular, `pip-audit` can be installed via `conda`:\n\n```bash\nconda install -c conda-forge pip-audit\n```\n\nThird-party packages are **not** directly supported by this project. Please consult your package manager's\ndocumentation for more detailed installation guidance.\n\n### GitHub Actions\n\n`pip-audit` has [an official GitHub Action](https://github.com/pypa/gh-action-pip-audit)!\n\nYou can install it from the\n[GitHub Marketplace](https://github.com/marketplace/actions/gh-action-pip-audit), or\nadd it to your CI manually:\n\n```yaml\njobs:\n pip-audit:\n steps:\n - uses: pypa/gh-action-pip-audit@v1.0.0\n with:\n inputs: requirements.txt\n```\n\nSee the\n[action documentation](https://github.com/pypa/gh-action-pip-audit/blob/main/README.md)\nfor more details and usage examples.\n\n### `pre-commit` support\n\n`pip-audit` has [`pre-commit`](https://pre-commit.com/) support.\n\nFor example, using `pip-audit` via `pre-commit` to audit a requirements file:\n\n```yaml\n - repo: https://github.com/pypa/pip-audit\n rev: v2.7.3\n hooks:\n - id: pip-audit\n args: [\"-r\", \"requirements.txt\"]\n\nci:\n # Leave pip-audit to only run locally and not in CI\n # pre-commit.ci does not allow network calls\n skip: [pip-audit]\n```\n\nAny `pip-audit` arguments documented below can be passed.\n\n## Usage\n\nYou can run `pip-audit` as a standalone program, or via `python -m`:\n\n```bash\npip-audit --help\npython -m pip_audit --help\n```\n\n<!-- @begin-pip-audit-help@ -->\n```\nusage: pip-audit [-h] [-V] [-l] [-r REQUIREMENT] [-f FORMAT] [-s SERVICE] [-d]\n [-S] [--desc [{on,off,auto}]] [--aliases [{on,off,auto}]]\n [--cache-dir CACHE_DIR] [--progress-spinner {on,off}]\n [--timeout TIMEOUT] [--path PATH] [-v] [--fix]\n [--require-hashes] [--index-url INDEX_URL]\n [--extra-index-url URL] [--skip-editable] [--no-deps]\n [-o FILE] [--ignore-vuln ID] [--disable-pip]\n [project_path]\n\naudit the Python environment for dependencies with known vulnerabilities\n\npositional arguments:\n project_path audit a local Python project at the given path\n (default: None)\n\noptional arguments:\n -h, --help show this help message and exit\n -V, --version show program's version number and exit\n -l, --local show only results for dependencies in the local\n environment (default: False)\n -r REQUIREMENT, --requirement REQUIREMENT\n audit the given requirements file; this option can be\n used multiple times (default: None)\n -f FORMAT, --format FORMAT\n the format to emit audit results in (choices: columns,\n json, cyclonedx-json, cyclonedx-xml, markdown)\n (default: columns)\n -s SERVICE, --vulnerability-service SERVICE\n the vulnerability service to audit dependencies\n against (choices: osv, pypi) (default: pypi)\n -d, --dry-run without `--fix`: collect all dependencies but do not\n perform the auditing step; with `--fix`: perform the\n auditing step but do not perform any fixes (default:\n False)\n -S, --strict fail the entire audit if dependency collection fails\n on any dependency (default: False)\n --desc [{on,off,auto}]\n include a description for each vulnerability; `auto`\n defaults to `on` for the `json` format. This flag has\n no effect on the `cyclonedx-json` or `cyclonedx-xml`\n formats. (default: auto)\n --aliases [{on,off,auto}]\n includes alias IDs for each vulnerability; `auto`\n defaults to `on` for the `json` format. This flag has\n no effect on the `cyclonedx-json` or `cyclonedx-xml`\n formats. (default: auto)\n --cache-dir CACHE_DIR\n the directory to use as an HTTP cache for PyPI; uses\n the `pip` HTTP cache by default (default: None)\n --progress-spinner {on,off}\n display a progress spinner (default: on)\n --timeout TIMEOUT set the socket timeout (default: 15)\n --path PATH restrict to the specified installation path for\n auditing packages; this option can be used multiple\n times (default: [])\n -v, --verbose run with additional debug logging; supply multiple\n times to increase verbosity (default: 0)\n --fix automatically upgrade dependencies with known\n vulnerabilities (default: False)\n --require-hashes require a hash to check each requirement against, for\n repeatable audits; this option is implied when any\n package in a requirements file has a `--hash` option.\n (default: False)\n --index-url INDEX_URL\n base URL of the Python Package Index; this should\n point to a repository compliant with PEP 503 (the\n simple repository API); this will be resolved by pip\n if not specified (default: None)\n --extra-index-url URL\n extra URLs of package indexes to use in addition to\n `--index-url`; should follow the same rules as\n `--index-url` (default: [])\n --skip-editable don't audit packages that are marked as editable\n (default: False)\n --no-deps don't perform any dependency resolution; requires all\n requirements are pinned to an exact version (default:\n False)\n -o FILE, --output FILE\n output results to the given file (default: stdout)\n --ignore-vuln ID ignore a specific vulnerability by its vulnerability\n ID; this option can be used multiple times (default:\n [])\n --disable-pip don't use `pip` for dependency resolution; this can\n only be used with hashed requirements files or if the\n `--no-deps` flag has been provided (default: False)\n```\n<!-- @end-pip-audit-help@ -->\n\n### Exit codes\n\nOn completion, `pip-audit` will exit with a code indicating its status.\n\nThe current codes are:\n\n* `0`: No known vulnerabilities were detected.\n* `1`: One or more known vulnerabilities were found.\n\n`pip-audit`'s exit code cannot be suppressed.\nSee [Suppressing exit codes from `pip-audit`](#suppressing-exit-codes-from-pip-audit)\nfor supported alternatives.\n\n### Dry runs\n\n`pip-audit` supports the `--dry-run` flag, which can be used to control whether\nan audit (or fix) step is actually performed.\n\n* On its own, `pip-audit --dry-run` skips the auditing step and prints\n the number of dependencies that *would have been* audited.\n* In fix mode, `pip-audit --fix --dry-run` performs the auditing step and prints\n out the fix behavior (i.e., which dependencies would be upgraded or skipped)\n that *would have been performed*.\n\n## Examples\n\nAudit dependencies for the current Python environment:\n```\n$ pip-audit\nNo known vulnerabilities found\n```\n\nAudit dependencies for a given requirements file:\n```\n$ pip-audit -r ./requirements.txt\nNo known vulnerabilities found\n```\n\nAudit dependencies for a requirements file, excluding system packages:\n```\n$ pip-audit -r ./requirements.txt -l\nNo known vulnerabilities found\n```\n\nAudit dependencies for a local Python project:\n```\n$ pip-audit .\nNo known vulnerabilities found\n```\n`pip-audit` searches the provided path for various Python \"project\" files. At the moment, only `pyproject.toml` is supported.\n\nAudit dependencies when there are vulnerabilities present:\n```\n$ pip-audit\nFound 2 known vulnerabilities in 1 package\nName Version ID Fix Versions\n---- ------- -------------- ------------\nFlask 0.5 PYSEC-2019-179 1.0\nFlask 0.5 PYSEC-2018-66 0.12.3\n```\n\nAudit dependencies including aliases:\n```\n$ pip-audit --aliases\nFound 2 known vulnerabilities in 1 package\nName Version ID Fix Versions Aliases\n---- ------- -------------- ------------ -------------------------------------\nFlask 0.5 PYSEC-2019-179 1.0 CVE-2019-1010083, GHSA-5wv5-4vpf-pj6m\nFlask 0.5 PYSEC-2018-66 0.12.3 CVE-2018-1000656, GHSA-562c-5r94-xh97\n```\n\nAudit dependencies including descriptions:\n```\n$ pip-audit --desc\nFound 2 known vulnerabilities in 1 package\nName Version ID Fix Versions Description\n---- ------- -------------- ------------ --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\nFlask 0.5 PYSEC-2019-179 1.0 The Pallets Project Flask before 1.0 is affected by: unexpected memory usage. The impact is: denial of service. The attack vector is: crafted encoded JSON data. The fixed version is: 1. NOTE: this may overlap CVE-2018-1000656.\nFlask 0.5 PYSEC-2018-66 0.12.3 The Pallets Project flask version Before 0.12.3 contains a CWE-20: Improper Input Validation vulnerability in flask that can result in Large amount of memory usage possibly leading to denial of service. This attack appear to be exploitable via Attacker provides JSON data in incorrect encoding. This vulnerability appears to have been fixed in 0.12.3. NOTE: this may overlap CVE-2019-1010083.\n```\n\nAudit dependencies in JSON format:\n```\n$ pip-audit -f json | python -m json.tool\nFound 2 known vulnerabilities in 1 package\n[\n {\n \"name\": \"flask\",\n \"version\": \"0.5\",\n \"vulns\": [\n {\n \"id\": \"PYSEC-2019-179\",\n \"fix_versions\": [\n \"1.0\"\n ],\n \"aliases\": [\n \"CVE-2019-1010083\",\n \"GHSA-5wv5-4vpf-pj6m\"\n ],\n \"description\": \"The Pallets Project Flask before 1.0 is affected by: unexpected memory usage. The impact is: denial of service. The attack vector is: crafted encoded JSON data. The fixed version is: 1. NOTE: this may overlap CVE-2018-1000656.\"\n },\n {\n \"id\": \"PYSEC-2018-66\",\n \"fix_versions\": [\n \"0.12.3\"\n ],\n \"aliases\": [\n \"CVE-2018-1000656\",\n \"GHSA-562c-5r94-xh97\"\n ],\n \"description\": \"The Pallets Project flask version Before 0.12.3 contains a CWE-20: Improper Input Validation vulnerability in flask that can result in Large amount of memory usage possibly leading to denial of service. This attack appear to be exploitable via Attacker provides JSON data in incorrect encoding. This vulnerability appears to have been fixed in 0.12.3. NOTE: this may overlap CVE-2019-1010083.\"\n }\n ]\n },\n {\n \"name\": \"jinja2\",\n \"version\": \"3.0.2\",\n \"vulns\": []\n },\n {\n \"name\": \"pip\",\n \"version\": \"21.3.1\",\n \"vulns\": []\n },\n {\n \"name\": \"setuptools\",\n \"version\": \"57.4.0\",\n \"vulns\": []\n },\n {\n \"name\": \"werkzeug\",\n \"version\": \"2.0.2\",\n \"vulns\": []\n },\n {\n \"name\": \"markupsafe\",\n \"version\": \"2.0.1\",\n \"vulns\": []\n }\n]\n```\n\nAudit and attempt to automatically upgrade vulnerable dependencies:\n```\n$ pip-audit --fix\nFound 2 known vulnerabilities in 1 package and fixed 2 vulnerabilities in 1 package\nName Version ID Fix Versions Applied Fix\n----- ------- -------------- ------------ ----------------------------------------\nflask 0.5 PYSEC-2019-179 1.0 Successfully upgraded flask (0.5 => 1.0)\nflask 0.5 PYSEC-2018-66 0.12.3 Successfully upgraded flask (0.5 => 1.0)\n```\n\n## Troubleshooting\n\nHave you resolved a problem with `pip-audit`? Help us by contributing to this\nsection!\n\n### `pip-audit` shows irrelevant vulnerability reports!\n\nIn a perfect world, vulnerability feeds would have an infinite signal-to-noise\nratio: every vulnerability report would be (1) correct, and (2) applicable to\nevery use of every dependency.\n\nUnfortunately, neither of these is guaranteed: vulnerability feeds are not\nimmune to extraneous or spam reports, and not all uses of a particular\ndependency map to all potential classes of vulnerabilities.\n\nIf your `pip-audit` runs produce vulnerability reports that aren't actionable\nfor your particular application or use case, you can use the `--ignore-vuln ID`\noption to ignore specific vulnerability reports. `--ignore-vuln` supports\naliases, so you can use a `GHSA-xxx` or `CVE-xxx` ID instead of a `PYSEC-xxx`\nID if the report in question does not have a PYSEC ID.\n\nFor example, here is how you might ignore GHSA-w596-4wvx-j9j6, which is a\ncommon source of noisy vulnerability reports and false positives for users of\n[`pytest`](https://github.com/pytest-dev/pytest):\n\n```console\n# Run the audit as normal, but exclude any reports that match GHSA-w596-4wvx-j9j6\n$ pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6\n```\n\nThe `--ignore-vuln ID` option works with all other dependency resolution\nand auditing options, meaning that it should function correctly with\nrequirements-style inputs, alternative vulnerability feeds, and so forth.\n\nIt can also be passed multiple times, to ignore multiple reports:\n\n```console\n# Run the audit as normal, but exclude any reports that match these IDs\n$ pip-audit --ignore-vuln CVE-XXX-YYYY --ignore-vuln CVE-ZZZ-AAAA\n```\n\n### `pip-audit` takes longer than I expect!\n\nDepending on how you're using it, `pip-audit` may have to perform its\nown dependency resolution, which can take roughly as long as `pip install`\ndoes for a project. See the [security model](#security-model) for an explanation.\n\nYou have two options for avoiding dependency resolution: *audit a pre-installed\nenvironment*, or *ensure that your dependencies are already fully resolved*.\n\nIf you know that you've already fully configured an environment equivalent\nto the one that `pip-audit -r requirements.txt` would audit, you can simply\nreuse it:\n\n```console\n# Note the absence of any \"input\" arguments, indicating that the environment is used.\n$ pip-audit\n\n# Optionally filter out non-local packages, for virtual environments:\n$ pip-audit --local\n```\n\nAlternatively, if your input is fully pinned (and optionally hashed), you\ncan tell `pip-audit` to skip dependency resolution with either `--no-deps`\n(pinned without hashes) or `--require-hashes` (pinned including hashes).\n\nThe latter is equivalent to `pip`'s\n[hash-checking mode](https://pip.pypa.io/en/stable/cli/pip_install/#hash-checking-mode)\nand is preferred, since it offers additional integrity.\n\n```console\n# fails if any dependency is not fully pinned\n$ pip-audit --no-deps -r requirements.txt\n\n# fails if any dependency is not fully pinned *or* is missing hashes\n$ pip-audit --require-hashes -r requirements.txt\n```\n\n### `pip-audit` can't authenticate to my third-party index!\n\n### Authenticated third-party or private indices\n\n`pip-audit` supports `--index-url` and `--extra-index-url` for configuring an alternate\nor supplemental package indices, just like `pip`.\n\nWhen *unauthenticated*, these indices should work as expected. However, when a third-party\nindex requires authentication, `pip-audit` has a few additional restrictions on top of\nordinary `pip`:\n\n* Interactive authentication is **not** supported. In other words: `pip-audit` will **not**\n prompt you for a username/password for the index.\n* [`pip`'s `keyring` authentication](https://pip.pypa.io/en/stable/topics/authentication/#keyring-support)\n **is** supported, but in a limited fashion: `pip-audit` uses the `subprocess` keyring provider,\n since audits happen in isolated virtual environments. The `subprocess` provider in turn\n is subject to additional restrictions (such as a required username);\n [`pip`'s documentation](https://pip.pypa.io/en/stable/topics/authentication/#using-keyring-as-a-command-line-application)\n explains these in depth.\n\nIn addition to the above, some third-party indices have required, hard-coded usernames.\nFor example, for Google Artifact registry, the hard-coded username is `oauth2accesstoken`.\nSee [#742](https://github.com/pypa/pip-audit/issues/742) and\n[pip#11971](https://github.com/pypa/pip/issues/11971) for additional context.\n\n## Tips and Tricks\n\n### Running against a `pipenv` project\n\n`pipenv` uses both a `Pipfile` and `Pipfile.lock` file to track and freeze dependencies\ninstead of a `requirements.txt` file. `pip-audit` cannot process the `Pipfile[.lock]`\nfiles directly, however, these can be converted to a supported `requirements.txt` file\nthat `pip-audit` can run against. `pipenv` has a built-in command to convert dependencies\nto a `requirements.txt` file (as of [`v2022.4.8`](https://pipenv.pypa.io/en/latest/changelog/#id206)):\n\n```console\n$ pipenv run pip-audit -r <(pipenv requirements)\n```\n\n### Suppressing exit codes from `pip-audit`\n\n`pip-audit` intentionally does not support internally suppressing its own\nexit codes.\n\nUsers who need to suppress a failing `pip-audit` invocation can use\none of the standard shell idioms for doing so:\n\n```bash\npip-audit || true\n```\n\nor, to exit entirely:\n\n```bash\npip-audit || exit 0\n```\n\nThe exit code can also be captured and handled explicitly:\n\n```bash\npip-audit\nexitcode=\"${?}\"\n# do something with ${exitcode}\n```\n\nSee [Exit codes](#exit-codes) for a list of potential codes that need handling.\n\n### Reporting only fixable vulnerabilities\n\nIn development workflows, you may want to ignore the vulnerabilities that haven't been remediated yet and only investigate them in your release process. `pip-audit` does not support ignoring unfixed vulnerabilities. However, you can export its output in JSON format and externally process it. For example, if you want to exit with a non-zero code only when the detected vulnerabilities have known fix versions, you can process the output using [jq](https://github.com/jqlang/jq) as:\n\n```shell\ntest -z \"$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')\"\n```\n\nA simple (and inefficient) example of using this method would be:\n\n```shell\ntest -z \"$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')\" || pip-audit -r requirements.txt\n```\n\nwhich runs `pip-audit` as usual and exits with a non-zero code only if there are fixed versions for the known vulnerabilities.\n\n## Security Model\n\nThis section exists to describe the security assumptions you **can** and **must not**\nmake when using `pip-audit`.\n\nTL;DR: **If you wouldn't `pip install` it, you should not `pip audit` it.**\n\n`pip-audit` is a tool for auditing Python environments for packages with\n*known vulnerabilities*. A \"known vulnerability\" is a publicly reported flaw in\na package that, if uncorrected, *might* allow a malicious actor to perform\nunintended actions.\n\n`pip-audit` **can** protect you against known vulnerabilities by telling\nyou when you have them, and how you should upgrade them. For example,\nif you have `somepackage==1.2.3` in your environment, `pip-audit` **can** tell\nyou that it needs to be upgraded to `1.2.4`.\n\nYou **can** assume that `pip-audit` will make a best effort to *fully resolve*\nall of your Python dependencies and *either* fully audit each *or* explicitly\nstate which ones it has skipped, as well as why it has skipped them.\n\n`pip-audit` is **not** a static code analyzer. It analyzes dependency trees,\nnot code, and it **cannot** guarantee that arbitrary dependency resolutions\noccur statically. To understand why this is, refer to Dustin Ingram's\n[excellent post on dependency resolution in Python](https://dustingram.com/articles/2018/03/05/why-pypi-doesnt-know-dependencies/).\n\nAs such: you **must not** assume that `pip-audit` will **defend** you against\nmalicious packages. In particular, it is **incorrect** to treat\n`pip-audit -r INPUT` as a \"more secure\" variant of `pip-audit`. For all intents\nand purposes, `pip-audit -r INPUT` is functionally equivalent to\n`pip install -r INPUT`, with a small amount of **non-security isolation** to\navoid conflicts with any of your local environments.\n\n`pip-audit` is first and foremost a auditing tool for *Python* packages.\nYou **must not** assume that `pip-audit` will detect or flag \"transitive\"\nvulnerabilities that might be exposed through Python packages, but are not\nactually part of the package itself. For example, `pip-audit`'s vulnerability\ninformation sources are unlikely to include an advisory for a vulnerable shared\nlibrary that a popular Python package *might* use, since the Python package's\nversion is not strongly connected to the shared library's version.\n\n## Licensing\n\n`pip-audit` is licensed under the Apache 2.0 License.\n\n`pip-audit` reuses and modifies examples from\n[`resolvelib`](https://github.com/sarugaku/resolvelib), which is licensed under\nthe ISC license.\n\n## Contributing\n\nSee [the contributing docs](CONTRIBUTING.md) for details.\n\n## Code of Conduct\n\nEveryone interacting with this project is expected to follow the\n[PSF Code of Conduct](https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A tool for scanning Python environments for known vulnerabilities",
"version": "2.7.3",
"project_urls": {
"Homepage": "https://pypi.org/project/pip-audit/",
"Issues": "https://github.com/pypa/pip-audit/issues",
"Source": "https://github.com/pypa/pip-audit"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4d4ac908ec8a527698a6539b431d70454e18aef04d4190ff48107ed4d3df99ff",
"md5": "cfcce1ab5431ee547e4a3b4da891da23",
"sha256": "46a11faee3323f76adf7987de8171daeb660e8f57d8088cc27fb1c1e5c7747b0"
},
"downloads": -1,
"filename": "pip_audit-2.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cfcce1ab5431ee547e4a3b4da891da23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 56266,
"upload_time": "2024-04-30T19:27:42",
"upload_time_iso_8601": "2024-04-30T19:27:42.177241Z",
"url": "https://files.pythonhosted.org/packages/4d/4a/c908ec8a527698a6539b431d70454e18aef04d4190ff48107ed4d3df99ff/pip_audit-2.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "462fd030d0d3a50b776f910dd87dc1d57dd4a27bfad176b85882f463632e4747",
"md5": "c90612859ab1faa206de61c8fe598d50",
"sha256": "08891bbf179bffe478521f150818112bae998424f58bf9285c0078965aef38bc"
},
"downloads": -1,
"filename": "pip_audit-2.7.3.tar.gz",
"has_sig": false,
"md5_digest": "c90612859ab1faa206de61c8fe598d50",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50365,
"upload_time": "2024-04-30T19:27:43",
"upload_time_iso_8601": "2024-04-30T19:27:43.967994Z",
"url": "https://files.pythonhosted.org/packages/46/2f/d030d0d3a50b776f910dd87dc1d57dd4a27bfad176b85882f463632e4747/pip_audit-2.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-30 19:27:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pypa",
"github_project": "pip-audit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pip-audit"
}
