pypa/pip-auditАудитирует окружения Python, файлы требований и деревья зависимостей на предмет известных уязвимостей безопасности, и может автоматически их исправлять.
pip-audit — это инструмент для сканирования сред Python на наличие пакетов с известными уязвимостями. Он использует базу данных рекомендаций Python Packaging Advisory Database (https://github.com/pypa/advisory-database) через PyPI JSON API в качестве источника отчётов об уязвимостях.
Этот проект поддерживается при участии Trail of Bits при поддержке Google. Это не официальный продукт Google или Trail of Bits.
--fix)pippip-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 Actions!
Вы можете установить его из GitHub Marketplace или добавить его в ваш CI вручную:```yaml jobs: pip-audit: steps: - uses: pypa/[email protected] with: inputs: requirements.txt
См.
[документацию action](https://github.com/pypa/gh-action-pip-audit/blob/main/README.md)
для получения дополнительных сведений и примеров использования.
### Поддержка `pre-commit`
`pip-audit` имеет поддержку [`pre-commit`](https://pre-commit.com/).
Например, использование `pip-audit` через `pre-commit` для аудита файла зависимостей:```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 позволяет пользователям настраивать некоторые флаги с помощью переменных окружения:
| Флаг | Эквивалент в переменной окружения | Пример |
|---|---|---|
--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 |
По завершении 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
Аудит зависимостей для указанного файла requirements:```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
Аудит lockfiles для локального 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 поддерживает псевдонимы, поэтому вы можете использовать идентификатор GHSA-xxx или CVE-xxx вместо идентификатора PYSEC-xxx, если в соответствующем отчёте нет идентификатора PYSEC.
Например, вот как можно игнорировать 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
В качестве альтернативы, если ваш входной файл полностью зафиксирован (и, опционально, захэширован), вы можете указать `pip-audit` пропустить разрешение зависимостей, используя либо `--no-deps` (зафиксировано без хешей) или `--require-hashes` (зафиксировано с хешами).
Последнее эквивалентно `pip`'s [режиму проверки хешей](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's keyring authentication
поддерживается, но ограниченно: pip-audit использует провайдера keyring на основе subprocess,
поскольку аудиты выполняются в изолированных виртуальных окружениях. Провайдер subprocess в свою очередь
подчиняется дополнительным ограничениям (таким как требование имени пользователя);
документация pip
объясняет это подробно.В дополнение к вышесказанному, некоторые сторонние индексы имеют обязательные, жестко заданные имена пользователей.
Например, для Google Artifact Registry жестко заданное имя пользователя — oauth2accesstoken.
См. #742 и
pip#11971 для дополнительного контекста.
pipenvpipenv использует файлы Pipfile и Pipfile.lock для отслеживания и фиксации зависимостей
вместо файла requirements.txt. pip-audit не может обрабатывать файлы Pipfile[.lock]
напрямую, однако их можно преобразовать в поддерживаемый файл requirements.txt,
с которым может работать pip-audit. pipenv имеет встроенную команду для преобразования зависимостей
в файл requirements.txt (начиная с v2022.4.8):```console
$ pipenv run pip-audit -r <(pipenv requirements)
### Подавление кодов возврата из `pip-audit`
`pip-audit` намеренно не поддерживает внутреннее подавление своих собственных
кодов возврата.
Пользователи, которым необходимо подавить неудачный вызов `pip-audit`, могут использовать
один из стандартных идиом оболочки для этого:```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
which runs pip-audit as usual and exits with a non-zero code only if there are fixed versions for the known vulnerabilities.
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 environments for packages with
known vulnerabilities. A "known vulnerability" 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 vulnerabilities by telling
you when you have them, and how you should upgrade them. For example,
if you have somepackage==1.2.3 in your environment, 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" variant of pip-audit. For all intents
and purposes, pip-audit -r INPUT is functionally equivalent to
pip install -r INPUT, with a small amount of non-security isolation to
avoid conflicts with any of your local environments.
pip-audit is first and foremost an auditing tool for Python packages.
You must not assume that pip-audit will detect or flag "transitive"
vulnerabilities that might be exposed through Python packages, but are not
actually part of the package itself. For example, pip-audit's vulnerability
information sources are unlikely to include an advisory for a vulnerable shared
library that a popular Python package might use, since the Python package's
version is not strongly connected to the shared library's version.
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.
See the contributing docs for details.
Everyone interacting with this project is expected to follow the PSF Code of Conduct.