pip-audit - Audits Python environments, requirements files and

项目说明

pip-audit
=========

<!--- BADGES: START --->
![CI]()
![PyPI ]()
![Packaging status]()
![OpenSSF Scorecard]()
![License]()
<!--- BADGES: END --->

pip-audit is a tool for scanning Python en for packages
with known . It uses the Python Packaging Ad Database
() via the
PyPI JSON API as a source
of reports.

This project was created by Trail of Bits
with support from Google, and is currently maintained under the
[Python Packaging Authority]. This is not an official Google or Trail of Bits product.

[Python Packaging Authority]:

Index

* Features
* Installation
* Third-party packages
* GitHub Actions
* pre-commit support
* Usage
* En
* Exit codes
* Dry runs
* Examples
* Troubleshooting
* Tips and Tricks
* Security model
* Licensing
* Contributing
* Code of Conduct

Features

* Support for auditing local en and requirements-style files
* Support for multiple services
(PyPI,
OSV)
* Support for emitting
SBOMs in
CycloneDX XML or JSON
* Support for automatically fixing dependencies (--fix)
* Human and machine-readable output formats (columnar, Markdown, JSON)
* Seamlessly reuses your existing local pip caches

Installation

pip-audit requires Python 3.10 or newer, and can be installed directly via pip:

Third-party packages

There are multiple third-party packages for pip-audit. The matrices and badges below
list some of them:

![Packaging status]()
![Packaging status]()
![Conda - Platform][#conda-forge-package]
![Conda (channel only)][#conda-forge-package]

[#conda-forge-package]:

In particular, pip-audit can be installed via conda:

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!

You can install it from the
GitHub Marketplace, or
add it to your CI manually:

See the
action documentation
for more details and usage examples.

pre-commit support

pip-audit has pre-commit support.

For example, using pip-audit via pre-commit to audit a requirements file:

Any pip-audit arguments documented below can be passed.

Usage

You can run pip-audit as a standalone program, or via python -m:

<!-- -pip-audit-help@ -->

<!-- @end-pip-audit-help@ -->

En

pip-audit allows users to configure some flags
instead:

| Flag | En equi | Example |
|---------------------------|-----------------------------------|---------------------------------------|
| --format | PIP_AUDIT_FORMAT | PIP_AUDIT_FORMAT=markdown |
| -- | PIP_AUDIT_ | PIP_AUDIT_=osv |
| --desc | PIP_AUDIT_DESC | PIP_AUDIT_DESC=off |
| --progress-spinner | PIP_AUDIT_PROGRESS_SPINNER | PIP_AUDIT_PROGRESS_SPINNER=off |
| --output | PIP_AUDIT_OUTPUT | PIP_AUDIT_OUTPUT=/tmp/example |

Exit codes

On completion, pip-audit will exit with a code indicating its status.

The current codes are:

* 0: No known were detected.
* 1: One or more known were found.

pip-audit's exit code cannot be suppressed.
See 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 en:

Audit dependencies for a gi file:

Audit dependencies for a requirements file, excluding system packages:

Audit dependencies for a local Python project:

Audit lockfiles for a local Python project:

pip-audit searches the provided path for Python "project" files.
At the moment, only pyproject.toml and pylock.*.toml are supported.

Audit dependencies when there are present:

Audit dependencies including aliases:

Audit dependencies including descriptions:

Audit dependencies in JSON format:

Audit and attempt to automatically upgrade dependencies:

Troubleshooting

Have you resolved a problem with pip-audit? Help us by contributing to this
section!

pip-audit shows irrelevant reports!

In a perfect world, feeds would have an infinite signal-to-noise
ratio: every report would be (1) correct, and (2) applicable to
every use of every dependency.

Unfortunately, neither of these is guaranteed: feeds are not
immune to extraneous or spam reports, and not all uses of a particular
dependency map to all potential classes of .

If your pip-audit runs produce reports that aren't actionable
for your particular application or use case, you can use the --ignore-vuln ID
option to ignore specific reports. --ignore-vuln supports
aliases, so you can use a GHSA-xxx or C 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-4w, which is a
common source of noisy reports and false positives for users of
pytest:

The --ignore-vuln ID option works with all other dependency resolution
and auditing options, meaning that it should function correctly with
requirements-style inputs, alternati feeds, and so forth.

It can also be passed multiple times, to ignore multiple reports:

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 for an explanation.

You have two options for a dependency resolution: *audit a pre-installed
en*, or *ensure that your dependencies are already fully resolved*.

If you know that you' fully configured an en equi
to the one that pip-audit -r requirements.txt would audit, you can simply
reuse it:

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 equi to pip's
hash-checking mode
and is preferred, since it offers additional integrity.

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:

* Interacti is not supported. In other words: pip-audit will not
prompt you for a username/password for the index.
* pip's keyring authentication
is supported, but in a limited fashion: pip-audit uses the subprocess keyring provider,
since audits happen in isolated en. The subprocess provider in turn
is subject to additional restrictions (such as a required username);
pip's documentation
explains these in depth.

In addition to the above, some third-party indices ha, hard-coded usernames.
For example, for Google Artifact registry, the hard-coded username is oauth2accesstoken.
See #742 and
pip#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 con 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):

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 in can use
one of the standard shell idioms for doing so:

or, to exit entirely:

The exit code can also be captured and handled explicitly:

See Exit codes for a list of potential codes that need handling.

Reporting only fixable

In de workflows, you may want to ignore the that haven't been remediated yet and only in them in your release process. pip-audit does not support ignoring unfixed . 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 ha fix , you can process the output using jq as:

A simple (and inefficient) example of using this method would be:

which runs pip-audit as usual and exits with a non-zero code only if there are fixed for the known .

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 en for packages with
*known *. A "known " 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 by telling
you when you have them, and how you should upgrade them. For example,
if you have somepackage==1.2.3 in your en, 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.

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" of pip-audit. For all intents
and purposes, pip-audit -r INPUT is functionally equi to
pip install -r INPUT, with a small amount of non-security isolation to
avoid conflicts with any of your local en.

pip-audit is first and foremost an auditing tool for *Python* packages.
You must not assume that pip-audit will detect or flag "transitive"
that might be exposed through Python packages, but are not
actually part of the package itself. For example, pip-audit's
information sources are unlikely to include an ad for a shared
library that a popular Python package *might* use, since the Python package's
is not strongly connected to the shared library's .

Licensing

pip-audit is licensed under the Apache 2.0 License.

pip-audit reuses and modifies examples from
resolvelib, which is licensed under
the ISC license.

Contributing

See the contributing docs for details.

Code of Conduct

E interacting with this project is expected to follow the
PSF Code of Conduct.

项目信息

开发语言：Python

Star 数：1378

技术要点

该项目属于漏洞知识库方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Audits Python environments, requirements files and dependency trees for known security vulnerabilities, and can automatically fix them展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。