python-pip-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python pip-audit Dependency Security Scanning

Python pip-audit 依赖项安全扫描

pip-audit scans Python environments and requirements files for packages with known vulnerabilities. It queries the Python Packaging Advisory Database via the PyPI JSON API and the OSV database, reporting CVEs, GHSA IDs, and fix versions.

pip-audit可扫描Python环境和requirements文件，检测存在已知漏洞的包。它通过PyPI JSON API和OSV数据库查询Python包安全咨询数据库，报告CVE、GHSA ID以及修复版本。

Installation

安装

Install pip-audit into the project's virtual environment or as a standalone tool:

bash

undefined

将pip-audit安装到项目的虚拟环境中，或作为独立工具安装：

bash

undefined

Into active virtual environment

安装到激活的虚拟环境

pip install pip-audit

Isolated global install (preferred for CI)

独立全局安装（CI环境推荐）

pipx install pip-audit

Via conda

通过conda安装

conda install -c conda-forge pip-audit


pip-audit requires Python 3.10 or newer.

conda install -c conda-forge pip-audit


pip-audit要求Python 3.10或更高版本。

Core Usage

核心用法

Audit the current environment:

bash

pip-audit

Audit a requirements file:

bash

pip-audit -r requirements.txt

Audit a local Python project (reads
pyproject.toml
or
pylock.*.toml
):

bash

pip-audit .

Audit lock files only:

bash

pip-audit --locked .

Exclude system packages (useful inside virtual environments):

bash

pip-audit -r requirements.txt -l

审计当前环境：

bash

pip-audit

审计requirements文件：

bash

pip-audit -r requirements.txt

审计本地Python项目（读取
pyproject.toml
或
pylock.*.toml
）：

bash

pip-audit .

仅审计锁文件：

bash

pip-audit --locked .

排除系统包（虚拟环境中适用）：

bash

pip-audit -r requirements.txt -l

Vulnerability Services

漏洞数据源

pip-audit supports two vulnerability data sources:

Service	Flag	Default
PyPI JSON API	`-s pypi`	Yes
OSV (Open Source Vulnerabilities)	`-s osv`	No

Use OSV for broader advisory coverage across multiple ecosystems:

bash

pip-audit -r requirements.txt -s osv

Switch the OSV API endpoint (e.g., for self-hosted instances):

bash

pip-audit -r requirements.txt -s osv --osv-url https://api.osv.dev/v1/query

pip-audit支持两种漏洞数据源：

服务	参数	默认状态
PyPI JSON API	`-s pypi`	启用
OSV（开源漏洞数据库）	`-s osv`	禁用

使用OSV可获取跨多个生态系统的更全面的安全咨询信息：

bash

pip-audit -r requirements.txt -s osv

切换OSV API端点（例如自托管实例）：

bash

pip-audit -r requirements.txt -s osv --osv-url https://api.osv.dev/v1/query

Output Formats

输出格式

bash

pip-audit -f columns          # Default columnar output
pip-audit -f json             # Machine-readable JSON
pip-audit -f markdown         # Markdown table
pip-audit -f cyclonedx-json   # CycloneDX SBOM (JSON)
pip-audit -f cyclonedx-xml    # CycloneDX SBOM (XML)

Save output to a file:

bash

pip-audit -f json -o audit-report.json

Include vulnerability descriptions and alias IDs (CVE/GHSA) in output:

bash

pip-audit --desc --aliases

For JSON format, descriptions and aliases are included automatically.

bash

pip-audit -f columns          # 默认列格式输出
pip-audit -f json             # 机器可读的JSON格式
pip-audit -f markdown         # Markdown表格格式
pip-audit -f cyclonedx-json   # CycloneDX SBOM（JSON格式）
pip-audit -f cyclonedx-xml    # CycloneDX SBOM（XML格式）

将输出保存到文件：

bash

pip-audit -f json -o audit-report.json

在输出中包含漏洞描述和别名ID（CVE/GHSA）：

bash

pip-audit --desc --aliases

对于JSON格式，描述和别名会自动包含在内。

Automatic Fix

自动修复

Upgrade vulnerable packages automatically:

bash

pip-audit --fix

Preview what would be upgraded without applying changes:

bash

pip-audit --fix --dry-run

Dry run without the

--fix

flag reports how many dependencies would be audited:

bash

pip-audit --dry-run

自动升级存在漏洞的包：

bash

pip-audit --fix

预览将升级的内容但不实际应用更改：

bash

pip-audit --fix --dry-run

不带

--fix

参数的试运行会报告将审计的依赖项数量：

bash

pip-audit --dry-run

Ignoring Specific Vulnerabilities

忽略特定漏洞

Suppress known false positives or accepted risks using the vulnerability ID, CVE, or GHSA alias:

bash

undefined

使用漏洞ID、CVE或GHSA别名，屏蔽已知误报或已接受风险的漏洞：

bash

undefined

Ignore by PYSEC ID

通过PYSEC ID忽略

pip-audit --ignore-vuln PYSEC-2021-666

Ignore by CVE

通过CVE忽略

pip-audit --ignore-vuln CVE-2019-1010083

Ignore by GHSA

通过GHSA忽略

pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6

Ignore multiple

忽略多个漏洞

pip-audit --ignore-vuln CVE-XXX-YYYY --ignore-vuln GHSA-abc-def-ghij


Document every suppressed ID in a comment or issue tracker entry explaining why it is not applicable.

pip-audit --ignore-vuln CVE-XXX-YYYY --ignore-vuln GHSA-abc-def-ghij


请在注释或问题跟踪条目中记录每个被屏蔽的ID，并说明不适用于当前场景的原因。

Performance: Skipping Dependency Resolution

性能优化：跳过依赖解析

pip-audit performs its own dependency resolution by default, which can be slow. Skip resolution when inputs are already fully pinned:

Pinned without hashes (faster):

bash

pip-audit --no-deps -r requirements.txt

Pinned with hashes (fastest, most secure):

bash

pip-audit --require-hashes -r requirements.txt

--require-hashes

is equivalent to pip's hash-checking mode. It fails if any package is missing a hash, providing additional supply-chain integrity.

Audit a pre-installed environment directly (no resolution needed):

bash

pip-audit
pip-audit --local   # only local packages, skip globally installed

pip-audit默认会自行执行依赖解析，这可能较慢。当输入已完全固定版本时，可跳过解析：

固定版本但无哈希（速度较快）：

bash

pip-audit --no-deps -r requirements.txt

固定版本且带哈希（速度最快，安全性最高）：

bash

pip-audit --require-hashes -r requirements.txt

--require-hashes

与pip的哈希检查模式等效。如果任何包缺少哈希值，该命令会执行失败，从而提供额外的供应链完整性保障。

直接审计已安装的环境（无需解析）：

bash

pip-audit
pip-audit --local   # 仅审计本地包，跳过全局安装的包

Exit Codes

退出码

Code	Meaning
`0`	No known vulnerabilities found
`1`	One or more vulnerabilities found

Exit codes cannot be suppressed internally. Use shell idioms when needed:

bash

undefined

代码	含义
`0`	未发现已知漏洞
`1`	发现一个或多个漏洞

无法在内部屏蔽退出码。必要时可使用shell语句处理：

bash

undefined

Continue even if vulnerabilities found

即使发现漏洞也继续执行

pip-audit || true

Capture for custom handling

捕获退出码以便自定义处理

pip-audit exitcode="${?}"

undefined

pip-audit exitcode="${?}"

undefined

Environment Variables

环境变量

Configure pip-audit without flags for CI pipelines:

Variable	Equivalent flag	Example value
`PIP_AUDIT_FORMAT`	`--format`	json
`PIP_AUDIT_VULNERABILITY_SERVICE`	`--vulnerability-service`	osv
`PIP_AUDIT_DESC`	`--desc`	off
`PIP_AUDIT_PROGRESS_SPINNER`	`--progress-spinner`	off
`PIP_AUDIT_OUTPUT`	`--output`	audit-report.json

在CI流水线中，可通过环境变量而非命令行参数配置pip-audit：

变量	等效参数	示例值
`PIP_AUDIT_FORMAT`	`--format`	json
`PIP_AUDIT_VULNERABILITY_SERVICE`	`--vulnerability-service`	osv
`PIP_AUDIT_DESC`	`--desc`	off
`PIP_AUDIT_PROGRESS_SPINNER`	`--progress-spinner`	off
`PIP_AUDIT_OUTPUT`	`--output`	audit-report.json

Reporting Only Fixable Vulnerabilities

仅报告可修复的漏洞

Filter to only fail when vulnerabilities have known fix versions using

jq

bash

test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null \
  | jq '.dependencies[].vulns[].fix_versions[]')"

This exits non-zero only when at least one fixable vulnerability exists.

使用

jq

过滤结果，仅当存在已知修复版本的漏洞时才执行失败：

bash

test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null \
  | jq '.dependencies[].vulns[].fix_versions[]')"

仅当至少存在一个可修复的漏洞时，该命令才会返回非零退出码。

pipenv Projects

pipenv 项目

Convert

Pipfile.lock

to a requirements format and pipe directly:

bash

pipenv run pip-audit -r <(pipenv requirements)

将

Pipfile.lock

转换为requirements格式并直接传入：

bash

pipenv run pip-audit -r <(pipenv requirements)

Private Package Indices

私有包索引

Use

--index-url

and

--extra-index-url

to point at internal registries:

bash

pip-audit -r requirements.txt \
  --index-url https://pypi.example.com/simple/ \
  --extra-index-url https://pypi.org/simple/

Interactive authentication is not supported. Use keyring via the subprocess provider or set credentials in the URL or environment.

使用

--index-url

和

--extra-index-url

指向内部仓库：

bash

pip-audit -r requirements.txt \
  --index-url https://pypi.example.com/simple/ \
  --extra-index-url https://pypi.org/simple/

不支持交互式认证。可通过子进程提供程序使用密钥环，或在URL或环境变量中设置凭据。

Security Model

安全模型

pip-audit detects known vulnerabilities in direct and transitive Python dependencies. It does not:

Perform static code analysis
Detect vulnerabilities in native shared libraries linked by Python packages
Protect against malicious packages not yet in any advisory database

Treat

pip-audit -r INPUT

as equivalent to

pip install -r INPUT

— it resolves and downloads packages. Only audit inputs from trusted sources.

pip-audit可检测直接和间接Python依赖项中的已知漏洞。但它无法：

执行静态代码分析
检测Python包所链接的原生共享库中的漏洞
防范尚未纳入任何安全咨询数据库的恶意包

请将

pip-audit -r INPUT

视为与

pip install -r INPUT

等效的操作——它会解析并下载包。仅对受信任来源的输入执行审计。

Additional Resources

额外资源

references/ci-integration.md
— GitHub Actions workflow, pre-commit hook, and baseline automation patterns

references/ci-integration.md
— GitHub Actions工作流、pre-commit钩子以及基线自动化模式