pip-audit 是一个用于扫描 Python 环境中已知漏洞包的工具。它通过 PyPI JSON API 使用 Python 打包咨询数据库 (https://github.com/pypa/advisory-database) 作为漏洞报告的来源。
该项目由 Trail of Bits 部分维护，并得到 Google 的支持。这不是 Google 或 Trail of Bits 的官方产品。
--fix)pip 缓存pip-audit 需要 Python 3.10 或更新版本，并可通过 pip 直接安装：```bash
python -m pip install pip-audit
### 第三方包
`pip-audit` 有多个 **第三方** 包。以下矩阵和徽章列举了其中一些：
[](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
特别是，`pip-audit` 可以通过 `conda` 安装：```bash
conda install -c conda-forge pip-audit
第三方软件包不受本项目直接支持。请查阅您的包管理器文档以获取更详细的安装指南。
pip-audit 有一个官方 GitHub Action！
您可以从 GitHub Marketplace 安装它，或者手动添加到您的 CI：```yaml jobs: pip-audit: steps: - uses: pypa/[email protected] with: inputs: requirements.txt
查阅
[操作文档](https://github.com/pypa/gh-action-pip-audit/blob/main/README.md)
获取更多详情和使用示例。
### `pre-commit` 支持
`pip-audit` 支持 [`pre-commit`](https://pre-commit.com/)。
例如，通过 `pre-commit` 使用 `pip-audit` 审计 requirements 文件：```yaml
- 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 参数都可以传递。
你可以将 pip-audit 作为独立程序运行，或者通过 python -m 运行：```bash
pip-audit --help
python -m pip_audit --help
<!-- @begin-pip-audit-help@ -->```
usage: pip-audit [-h] [-V] [-l] [-r REQUIREMENT] [--locked] [-f FORMAT]
[-s SERVICE] [--osv-url OSV_URL] [-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)
options:
-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)
--locked audit lock files from the local Python project. This
flag only applies to auditing from project paths
(default: False)
-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, esms) (default: pypi)
--osv-url OSV_URL URL to use for the OSV API instead of the default
(default: https://api.osv.dev/v1/query)
-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)
pip-audit 允许用户通过环境变量配置部分选项，而不是直接使用命令行标志：
执行完成后，pip-audit 会返回一个表示其状态的退出码。
当前定义的退出码如下：
0：未检测到已知漏洞。1：发现一个或多个已知漏洞。pip-audit 的退出码无法被取消。
请参阅pip-audit 退出码的抑制
了解支持的替代方案。
pip-audit 支持 --dry-run 标志，用于控制是否实际执行审计（或修复）步骤。
pip-audit --dry-run 会跳过审计步骤，并打印出 本应 被审计的依赖项数量。pip-audit --fix --dry-run 会执行审计步骤，并打印出修复行为（即哪些依赖项会被升级或跳过）本应 执行的操作。审计当前 Python 环境中的依赖项：```console $ pip-audit No known vulnerabilities found
审计给定需求文件的依赖项：```console
$ pip-audit -r ./requirements.txt
No known vulnerabilities found
审计需求文件中的依赖项，排除系统软件包：```console $ pip-audit -r ./requirements.txt -l No known vulnerabilities found
审计本地 Python 项目的依赖项：```console
$ pip-audit .
No known vulnerabilities found
审计本地Python项目的锁定文件：```console $ pip-audit --locked . No known vulnerabilities found
`pip-audit` 会在指定路径中搜索各类 Python“项目”文件。
目前，仅支持 `pyproject.toml` 和 `pylock.*.toml`。
在存在漏洞时审计依赖项：```console
$ 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
审计依赖项，包括别名：```console $ 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
审计依赖项，包括描述：```console
$ 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.
以JSON格式审计依赖项：```console $ 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": [] } ]
审计并尝试自动升级存在漏洞的依赖项：```console
$ 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)
您是否解决了 pip-audit 的问题？欢迎通过贡献内容帮助我们丰富本节！
pip-audit 显示了不相关的漏洞报告！在理想世界中，漏洞源应具有无限的信噪比：每条漏洞报告都应（1）正确，且（2）适用于每个依赖项的每一种使用场景。
不幸的是，这两点都无法保证：漏洞源无法避免无关或垃圾报告，且特定依赖项的不同使用场景并不对应所有潜在漏洞类型。
如果您的 pip-audit 运行产生的漏洞报告对您的特定应用或用例没有实际帮助，您可以使用 --ignore-vuln ID 选项忽略特定漏洞报告。--ignore-vuln 支持别名，因此如果相关报告没有 PYSEC ID，您可以使用 GHSA-xxx 或 CVE-xxx ID 代替 PYSEC-xxx ID。
例如，以下是如何忽略 GHSA-w596-4wvx-j9j6，这是 pytest 用户常见的嘈杂漏洞报告和误报来源：```console
$ pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6
`--ignore-vuln ID` 选项可与所有其他依赖解析和审计选项配合使用，这意味着它能够正确处理需求格式的输入、替代漏洞源等场景。
该选项还可以多次传递，以忽略多个报告：```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 花费的时间比我预期的要长！根据使用方式的不同，pip-audit 可能需要执行自己的依赖解析，其耗时大致相当于 pip install 对一个项目进行依赖解析的时间。详情请参见安全模型中的说明。
你有两种方式可以避免依赖解析：审计一个已安装的环境，或确保你的依赖关系已经完全解析。
如果你知道自己已经完整配置了一个与 pip-audit -r requirements.txt 将要审计的环境等价的环境，你可以直接复用它：```console
$ pip-audit
$ pip-audit --local
或者，如果你的输入是完全锁定（并且可选地进行了哈希处理）的，你可以使用 `--no-deps`（无哈希的锁定）或 `--require-hashes`（包含哈希的锁定）来告诉 `pip-audit` 跳过依赖解析。
后者等同于 `pip` 的[哈希验证模式](https://pip.pypa.io/en/stable/cli/pip_install/#hash-checking-mode)，并且是首选方案，因为它提供了额外的完整性保障。```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 无法验证我的第三方索引！pip-audit 支持 --index-url 和 --extra-index-url 用于配置替代或补充的包索引，就像 pip 一样。
当未进行身份验证时，这些索引应能正常工作。然而，当第三方索引需要身份验证时，pip-audit 在普通 pip 的基础上增加了一些额外限制：
pip-audit 不会提示你输入该索引的用户名/密码。pip 的 keyring 身份验证 是支持的，但支持程度有限：pip-audit 使用 subprocess keyring 提供程序，因为审计发生在隔离的虚拟环境中。而 subprocess 提供程序本身又受到额外限制（例如需要用户名）；pip 的文档 对此进行了深入解释。除此之外，一些第三方索引需要硬编码的用户名。例如，对于 Google Artifact 注册表，硬编码的用户名是 oauth2accesstoken。详情请参阅 #742 和 pip#11971。
pipenv 项目运行pipenv 使用 Pipfile 和 Pipfile.lock 文件来跟踪和冻结依赖项，而不是使用 requirements.txt 文件。pip-audit 无法直接处理 Pipfile[.lock] 文件，但是这些文件可以转换为 pip-audit 支持的 requirements.txt 文件。pipenv 有一个内置命令可以将依赖项转换为 requirements.txt 文件（自 v2022.4.8 起）：```console
$ pipenv run pip-audit -r <(pipenv requirements)
### 抑制来自 `pip-audit` 的退出码
`pip-audit` 故意不支持内部抑制其自身的退出码。
需要抑制失败 `pip-audit` 调用的用户可以使用标准 shell 惯用法之一来实现：```bash
pip-audit || true
或者，完全退出：```bash pip-audit || exit 0
退出码也可以被显式捕获和处理：```bash
pip-audit
exitcode="${?}"
# do something with ${exitcode}
请参阅退出码了解需要处理的潜在代码列表。
在开发工作流中，您可能希望忽略尚未修复的漏洞，仅在发布流程中对其进行调查。pip-audit 不支持忽略未修复的漏洞。不过，您可以将其输出导出为 JSON 格式并进行外部处理。例如，如果您只想在检测到的漏洞具有已知的修复版本时才以非零退出码退出，可以使用 jq 处理输出，如下所示：```shell
test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')"
使用此方法的一个简单（且低效）的示例如下：```shell
test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')" || pip-audit -r requirements.txt
pip-audit 正常运行，并且仅在已知漏洞存在已修复版本时以非零代码退出。
本节旨在描述使用 pip-audit 时可以和不得做出的安全假设。
简单总结：如果你不会 pip install 它，你也不应该 pip audit 它。
pip-audit 是一个用于审计 Python 环境中存在已知漏洞的包的工具。“已知漏洞”是指一个公开报告的程序缺陷，如果不加修正，可能允许恶意行为者执行非预期的操作。
pip-audit 可以通过告知你是否存在已知漏洞以及如何升级来保护你。例如，如果你的环境中存在 somepackage==1.2.3，pip-audit 可以告诉你需要升级到 1.2.4。
你可以假设 pip-audit 会尽最大努力完全解析你所有的 Python 依赖，要么完全审计每个依赖，要么明确说明哪些被跳过及跳过的原因。
pip-audit 不是静态代码分析器。它分析的是依赖树，而非代码，并且它不能保证任意依赖解析是静态发生的。要理解原因，请参考 Dustin Ingram 的关于 Python 依赖解析的优秀文章。
因此：你不得假设 pip-audit 能够防御恶意包。特别是，将 pip-audit -r INPUT 视为 pip-audit 的“更安全”变体是错误的。无论从哪个角度看，pip-audit -r INPUT 在功能上都等同于 pip install -r INPUT，仅有微小的非安全隔离以避免与你本地环境的冲突。
pip-audit 首先是一个针对 Python 包的审计工具。你不得假设 pip-audit 能够检测或标记通过 Python 包暴露但并非包本身的“传递性”漏洞。例如，pip-audit 的漏洞信息来源不太可能包含针对流行 Python 包可能使用的易受攻击的共享库的公告，因为 Python 包的版本与该共享库的版本没有强关联。
pip-audit 采用 Apache 2.0 许可证。
pip-audit 重用并修改了来自 resolvelib 的示例，后者采用 ISC 许可证。
详情请参阅贡献文档。
所有与本项目互动的人员应遵循 PSF 行为准则。
| 标志 | 对应的环境变量 | 示例 |
|---|
--format | PIP_AUDIT_FORMAT | PIP_AUDIT_FORMAT=markdown |
--vulnerability-service | PIP_AUDIT_VULNERABILITY_SERVICE | PIP_AUDIT_VULNERABILITY_SERVICE=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 |