pip-audit は、既知の脆弱性を持つパッケージをスキャンするためのPython環境向けツールです。脆弱性レポートのソースとして、PyPI JSON APIを介してPython Packaging Advisory Database (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` を使用して要件ファイルを監査する場合：```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: 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
requirementsファイルの依存関係を監査し、システムパッケージを除外する:```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
The `--ignore-vuln ID` オプションは、他のすべての依存関係解決および監査オプションと連携して動作します。つまり、requirements形式の入力、代替の脆弱性フィードなどでも正しく機能するはずです。
また、このオプションは複数回指定することで、複数のレポートを無視することもできます：
``````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 とほぼ同じ時間がかかる可能性があります。詳細はセキュリティモデルを参照してください。
依存関係解決を回避するには、2つのオプションがあります：事前にインストールされた環境を監査する か、依存関係がすでに完全に解決されていることを確認する です。
すでに 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 Registry の場合、ハードコードされたユーザー名は oauth2accesstoken です。詳細は #742 および pip#11971 を参照してください。
pipenv プロジェクトに対して実行するpipenv は requirements.txt ファイルの代わりに Pipfile と Pipfile.lock ファイルを使用して依存関係を追跡・固定します。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` の呼び出しを抑制する必要があるユーザーは、標準的なシェルのイディオムのいずれかを使用できます:
pip-audit ... || true
pip-audit || true
```
または、完全に終了するには:```bash
pip-audit || exit 0
```
終了コードを明示的にキャプチャして処理することもできます。```bash
pip-audit
exitcode="${?}"
# do something with ${exitcode}
```
「終了コード」のリストについては、[終了コード](#exit-codes)を参照してください。
### 修正可能な脆弱性のみを報告する
開発ワークフローでは、まだ修正されていない脆弱性を無視し、リリースプロセスでのみ調査したい場合があります。`pip-audit` は未修正の脆弱性を無視する機能をサポートしていません。ただし、出力をJSON形式でエクスポートし、外部で処理することができます。例えば、検出された脆弱性に既知の修正バージョンがある場合にのみ非ゼロの終了コードで終了したい場合は、[jq](https://github.com/jqlang/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` を使用する際に**できる**と**してはいけない**セキュリティ上の前提について説明します。
TL;DR: **`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 における依存関係解決に関する優れた記事](https://dustingram.com/articles/2018/03/05/why-pypi-doesnt-know-dependencies/) を参照してください。
したがって、`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` は、ISC ライセンスの下でライセンスされている [`resolvelib`](https://github.com/sarugaku/resolvelib) のサンプルを再利用および修正しています。
## コントリビューション
詳細は [コントリビューションガイド](https://github.com/pypa/pip-audit/blob/HEAD/CONTRIBUTING.md) を参照してください。
## 行動規範
このプロジェクトに関わるすべての人は、[PSF 行動規範](https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md) に従うことが期待されています。
| フラグ | 環境変数相当 | 例 |
|---|
--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 |