pypa/gh-action-pip-audit
GitHub: pypa/gh-action-pip-audit
一个用于 GitHub Actions 的 Python 依赖漏洞扫描工具，可在 CI 流程中自动检测并拦截存在已知安全风险的第三方包。
Stars: 84 | Forks: 14
# gh-action-pip-audit
[](https://github.com/pypa/gh-action-pip-audit/actions/workflows/ci.yml)
[](https://github.com/pypa/gh-action-pip-audit/actions/workflows/selftest.yml)
一个使用 [`pip-audit`](https://github.com/pypa/pip-audit) 的 GitHub Action
用于扫描 Python 依赖项中的已知漏洞。
该项目由 [Trail of Bits](https://www.trailofbits.com/) 在 Google 的支持下维护。
这不是 Google 或 Trail of Bits 的官方产品。
## 目录
* [用法](#usage)
* [配置](#configuration)
* [⚠️ 内部选项 ⚠️](#internal-options)
* [故障排除](#troubleshooting)
* [技巧与诀窍](#tips-and-tricks)
* [许可](#licensing)
* [行为准则](#code-of-conduct)
## 用法
只需将 `pypa/gh-action-pip-audit` 添加到您的一个 workflow 中：
```
jobs:
selftest:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: install
run: python -m pip install .
- uses: pypa/gh-action-pip-audit@v1.1.0
```
或者，使用虚拟环境：
```
jobs:
selftest:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: install
run: |
python -m venv env/
source env/bin/activate
python -m pip install .
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
virtual-environment: env/
```
默认情况下，`pip-audit` 将以“`pip list` 源”模式运行，这意味着它将尝试从本地环境中收集依赖项。请参阅下面的[配置](#configuration)文档以了解更多输入和行为选项。
## 配置
`gh-action-pip-audit` 接受多种配置输入，所有这些都是可选的。
### `inputs`
**默认值**：空，表示“`pip list` 源”模式
`inputs` 设置控制 `pip-audit` 运行的源。
要审计一个或多个 requirements 风格的输入：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
inputs: requirements.txt dev-requirements.txt
```
要审计一个使用 `pyproject.toml` 管理依赖项的项目：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
# NOTE: this can be `.`, for the current directory
inputs: path/to/project/
```
### `virtual-environment`
**默认值**：空，表示无虚拟环境
`virtual-environment` 设置控制此 Action 加载的[虚拟环境](https://docs.python.org/3/tutorial/venv.html)（如果指定）。该值是虚拟环境的顶层目录，通常命名为 `env` 或 `venv`。
根据您的 CI 和项目配置，您可能需要也可能不需要此设置。具体而言，只有在满足以下*所有*条件时才需要它：
1. 您正在审计一个*环境*（**而非** requirements 文件或其他项目元数据）
2. 您的环境尚未“激活”，即 `python -m pip` 指向的 `pip` 与您的环境使用的 `pip` 不同
示例：使用相对于当前目录的 `env/` 指定的虚拟环境：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
virtual-environment: env/
# Note the absence of `input:`, since we're auditing the environment.
```
### `local`
**默认值**：`false`
`local` 设置对应于 `pip-audit` 的 `--local` 标志，该标志控制在“`pip list` 源”模式下审计时是否包含非本地依赖项。
默认情况下，包含所有依赖项；设置 `local: true` 时，仅包含直接安装到当前环境中的依赖项。
示例：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
local: true
```
### `vulnerability-service`
**默认值**：`PyPI`
**选项**：`PyPI`、`OSV`（不区分大小写）
`vulnerability-service` 设置控制审计使用哪个漏洞服务。
它直接等同于 `pip-audit --vulnerability-service=...`。
要使用 OSV 而不是 PyPI 进行审计：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
vulnerability-service: osv
```
### `require-hashes`
**默认值**：`false`
`require-hashes` 设置控制是否启用严格的哈希检查。
它直接等同于 `pip-audit --require-hashes ...`。
示例：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
# NOTE: only works with requirements-style inputs
inputs: requirements.txt
require-hashes: true
```
### `no-deps`
**默认值**：`false`
`no-deps` 设置控制是否执行依赖项解析。
它直接等同于 `pip-audit --no-deps ...`。
示例：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
# NOTE: only works with requirements-style inputs
inputs: requirements.txt
no-deps: true
```
### `summary`
**默认值**：`true`
`summary` 设置控制是否在 Action 结束时渲染 GitHub [Job 摘要](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/)。
示例：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
summary: false
```
### `index-url`
**默认值**：空，表示 [PyPI](https://pypi.org)
`index-url` 设置指定兼容 PEP 503 的备用包索引的基础 URL。
**这可能不是您想要的。** 如果您的目标是添加要搜索的*补充*索引（例如包含私有包的企业索引），请参阅 [`extra-index-urls`](#extra-index-urls)。
示例：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
index-url: https://example.corporate.local/simple
```
### `extra-index-urls`
**默认值**：空（默认情况下不搜索额外的索引）
`extra-index-urls` 设置指定一个或多个*额外的*兼容 PEP 503 的包索引，以便在解析依赖项时进行搜索。每个 URL 以空格分隔。
示例：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
extra-index-urls: |
https://example.corporate.local/simple
https://prod.corporate.local/simple
```
### `ignore-vulns`
**默认值**：空（不忽略任何漏洞）
`ignore-vulns` 设置指定一个或多个要忽略（即从结果中排除）的漏洞 ID（如果存在）。每个 ID 以空格分隔。
示例
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
ignore-vulns: |
GHSA-XXXX-YYYYYY
PYSEC-AAAA-BBBBB
```
### `disable-pip`
**默认值**：`false`
`disable-pip` 设置禁用使用 `pip` 进行依赖项解析。这仅可用于带有哈希的 requirements 文件，或者如果已提供 `no-deps` 设置。
示例
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
inputs: requirements.lock
disable-pip: true
no-deps: true
```
### `locked`
**默认值**：`false`
`locked` 设置启用对本地 Python 项目中锁文件 (`pylock.*.toml`) 的审计。
示例
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
inputs: path/to/project/
locked: true
```
### 内部选项
## 故障排除
本节仍在编写中。请帮助我们改进它！
### Action 运行时间比预期的要长！
如果您正在审计 requirements 文件，请考虑设置 `no-deps: true` 或 `require-hashes: true`：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
inputs: requirements.txt
require-hashes: true
```
或者：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
inputs: requirements.txt
no-deps: true
```
有关更多详细信息，请参阅
[“`pip-audit` 运行时间比预期的要长！”](https://github.com/pypa/pip-audit#pip-audit-takes-longer-than-i-expect)
故障排除说明。
### Action 显示了不在我的环境中的依赖项！
在默认（“`pip list` 源”）配置中，`pip-audit` 会收集当前环境中可见的所有依赖项。
根据项目或 CI 的配置，这可能包括主机系统本身安装的包，或者恰好安装的其他 Python 项目。
为了最大限度地减少外部依赖项，您可以选择使用虚拟环境：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
# must be populated earlier in the CI
virtual-environment: env/
```
并且，更激进地指定仅包含虚拟环境中标记为“local”的依赖项：
```
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
# must be populated earlier in the CI
virtual-environment: env/
local: true
```
### Action 出现问题，我想启用调试日志记录！
当 `ACTIONS_STEP_DEBUG` secret 设置为 `true` 时，Action 会打印调试信息。
您应该能够通过[按照这些说明操作](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs#re-running-all-the-jobs-in-a-workflow)来启用此行为。
## 技巧与诀窍
### 针对 pipenv 项目运行
如果您要将 `pip-audit` 添加到基于 pipenv 的项目中，首先需要将 `Pipfile[.lock]` 转换为 `pip-audit` 可以使用的 `requirements.txt` 文件。使用 Python 工具（例如 [`pipfile-requirements`](https://github.com/frostming/pipfile-requirements)）将您的 `Pipfile[.lock]` 转换为 `requirements.txt` 文件，然后针对生成的 requirements 文件运行 `pip-audit` GitHub Action。
```
jobs:
pip-audit:
steps:
- uses: actions/setup-python@v5
with:
python-version: 3.9 # change to your required version of Python
- name: 'Generate requirements.txt'
run: |
pipx run pipfile-requirements Pipfile.lock > requirements.txt
- uses: pypa/gh-action-pip-audit@v1.1.0
with:
inputs: requirements.txt
```
## 许可
`gh-action-pip-audit` 根据 Apache 2.0 许可证授权。
## 行为准则
与该项目交互的所有人员都应遵守 [PSF 行为准则](https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md)。
⚠️ 内部选项 ⚠️
以下所有内容均被视为“内部”选项，这意味着它们不属于稳定的公共设置，可能会随时被删除或更改。**您可能不需要这些设置。** 所有内部选项都以 `internal-be-careful-` 为前缀。 #### `internal-be-careful-allow-failure` **默认值**：`false` `internal-be-careful-allow-failure` 设置允许 Job 通过，即使底层的 `pip-audit` 运行失败（例如，由于检测到漏洞）。 请务必小心使用此设置！在不了解情况的情况下使用它将导致当 `pip-audit` 失败时，Action 不会让您的 CI 失败，这可能不是您想要的。 示例： ``` - uses: pypa/gh-action-pip-audit@v1.1.0 with: internal-be-careful-allow-failure: true ``` #### `internal-be-careful-extra-flags` **默认值**：`""` `internal-be-careful-extra-flags` 设置将指定的标志传递给 `pip-audit`。 示例： ``` - uses: pypa/gh-action-pip-audit@v1.1.0 with: internal-be-careful-extra-flags: --not-a-real-pip-audit-flag ```标签：CI/CD 安全, DevSecOps, GitHub Action, LNA, pip-audit, PyPI, Python, SBOM, YAML, 上游代理, 云安全监控, 依赖扫描, 安全库, 对称加密, 数据投毒防御, 文档安全, 无后门, 模型提供商, 硬件无关, 组件安全, 自动化审计, 软件开发工具包, 逆向工具, 静态分析