pypa/pip-auditPrüft Python-Umgebungen, Requirements-Dateien und Abhängigkeitsbäume auf bekannte Sicherheitsschwachstellen und kann diese automatisch beheben
pip-audit ist ein Tool zum Durchsuchen von Python-Umgebungen nach Paketen mit bekannten Sicherheitslücken. Es nutzt die Python Packaging Advisory Database (https://github.com/pypa/advisory-database) über die PyPI JSON API als Quelle für Schwachstellenberichte.
Dieses Projekt wird zum Teil von Trail of Bits mit Unterstützung von Google gepflegt. Es handelt sich nicht um ein offizielles Google- oder Trail-of-Bits-Produkt.
--fix)pip-Cachespip-audit erfordert Python 3.10 oder neuer und kann direkt über pip installiert werden:```bash
python -m pip install pip-audit
### Pakete von Drittanbietern
Es gibt mehrere **Pakete von Drittanbietern** für `pip-audit`. Die untenstehenden Matrizen und Badges listen einige davon auf:
[](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
Insbesondere kann `pip-audit` über `conda` installiert werden:```bash
conda install -c conda-forge pip-audit
Paketverwaltungen von Drittanbietern werden von diesem Projekt nicht direkt unterstützt. Bitte konsultieren Sie die Dokumentation Ihres Paketverwalters für detailliertere Installationsanleitungen.
pip-audit hat eine offizielle GitHub Action!
Sie können sie aus dem GitHub Marketplace installieren oder manuell zu Ihrer CI hinzufügen:```yaml jobs: pip-audit: steps: - uses: pypa/[email protected] with: inputs: requirements.txt
Siehe die
[Aktionsdokumentation](https://github.com/pypa/gh-action-pip-audit/blob/main/README.md)
für weitere Details und Nutzungsbeispiele.
### `pre-commit` Unterstützung
`pip-audit` hat [`pre-commit`](https://pre-commit.com/) Unterstützung.
Zum Beispiel die Verwendung von `pip-audit` über `pre-commit` zur Überprüfung einer Requirements-Datei:```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]
Alle unten dokumentierten pip-audit-Argumente können übergeben werden.
Sie können pip-audit als eigenständiges Programm ausführen oder über 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 erlaubt Benutzern, einige Flags über Umgebungsvariablen zu konfigurieren:
Nach Abschluss beendet sich pip-audit mit einem Code, der seinen Status angibt.
Die aktuellen Codes sind:
0: Es wurden keine bekannten Schwachstellen erkannt.1: Es wurden eine oder mehrere bekannte Schwachstellen gefunden.Der Exit-Code von pip-audit kann nicht unterdrückt werden.
Siehe Suppressing exit codes from pip-audit für unterstützte Alternativen.
pip-audit unterstützt das --dry-run Flag, mit dem gesteuert werden kann, ob ein Audit- (oder Fix-) Schritt tatsächlich durchgeführt wird.
pip-audit --dry-run den Audit-Schritt und gibt die Anzahl der Abhängigkeiten aus, die auditiert worden wären.pip-audit --fix --dry-run den Audit-Schritt durch und gibt das Fix-Verhalten aus (d.h., welche Abhängigkeiten aktualisiert oder übersprungen worden wären), das ausgeführt worden wäre.Abhängigkeiten für die aktuelle Python-Umgebung auditieren:```console $ pip-audit No known vulnerabilities found
Abhängigkeiten für eine bestimmte requirements-Datei prüfen:```console
$ pip-audit -r ./requirements.txt
No known vulnerabilities found
Abhängigkeiten für eine Requirements-Datei prüfen, Systempakete ausschließen:```console $ pip-audit -r ./requirements.txt -l No known vulnerabilities found
Abhängigkeiten für ein lokales Python-Projekt prüfen:```console
$ pip-audit .
No known vulnerabilities found
Prüfe Sperrdateien für ein lokales Python-Projekt:```console $ pip-audit --locked . No known vulnerabilities found
`pip-audit` durchsucht den angegebenen Pfad nach verschiedenen Python-"Projekt"-Dateien.
Derzeit werden nur `pyproject.toml` und `pylock.*.toml` unterstützt.
Überprüfe Abhängigkeiten, wenn Sicherheitslücken vorhanden sind:```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
Abhängigkeiten einschließlich Aliase prüfen:```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
Abhängigkeiten einschließlich Beschreibungen überprüfen:```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.
Abhängigkeiten im JSON-Format überprüfen:```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": [] } ]
Überprüfen und versuchen, verwundbare Abhängigkeiten automatisch zu aktualisieren:```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)
Hast du ein Problem mit pip-audit gelöst? Hilf uns, indem du zu diesem
Abschnitt beiträgst!
pip-audit zeigt irrelevante Schwachstellenmeldungen!In einer perfekten Welt hätten Schwachstellenquellen ein unendliches Signal-Rausch-Verhältnis: Jeder Schwachstellenbericht wäre (1) korrekt und (2) auf jede Verwendung jeder Abhängigkeit anwendbar.
Leider ist keines von beiden garantiert: Schwachstellenquellen sind nicht immun gegenüber überflüssigen oder Spam-Meldungen, und nicht alle Verwendungen einer bestimmten Abhängigkeit decken alle potenziellen Schwachstellenklassen ab.
Wenn deine pip-audit-Läufe Schwachstellenmeldungen erzeugen, die für deine
bestimmte Anwendung oder deinen Anwendungsfall nicht umsetzbar sind, kannst du
die Option --ignore-vuln ID verwenden, um bestimmte Schwachstellenmeldungen zu
ignorieren. --ignore-vuln unterstützt Aliase, sodass du eine GHSA-xxx- oder
CVE-xxx-ID anstelle einer PYSEC-xxx-ID verwenden kannst, falls die betreffende
Meldung keine PYSEC-ID hat.
Hier ist zum Beispiel, wie du GHSA-w596-4wvx-j9j6 ignorieren könntest, eine
häufige Quelle von verrauschten Schwachstellenmeldungen und Fehlalarmen für
Benutzer von pytest:```console
$ pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6
Die Option `--ignore-vuln ID` funktioniert mit allen anderen Abhängigkeitsauflösungs- und Prüfoptionen, was bedeutet, dass sie korrekt mit requirements-style Eingaben, alternativen Schwachstellenfeeds usw. funktionieren sollte.
Sie kann auch mehrmals übergeben werden, um mehrere Berichte zu ignorieren:```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 dauert länger als ich erwarte!Je nachdem, wie Sie es verwenden, muss pip-audit möglicherweise seine eigene Abhängigkeitsauflösung durchführen, die ungefähr so lange dauern kann wie pip install für ein Projekt. Siehe das Sicherheitsmodell für eine Erklärung.
Sie haben zwei Möglichkeiten, um die Abhängigkeitsauflösung zu vermeiden: Auditieren Sie eine vorinstallierte Umgebung oder stellen Sie sicher, dass Ihre Abhängigkeiten bereits vollständig aufgelöst sind.
Wenn Sie wissen, dass Sie bereits eine Umgebung konfiguriert haben, die derjenigen entspricht, die pip-audit -r requirements.txt auditieren würde, können Sie sie einfach wiederverwenden:```console
$ pip-audit
$ pip-audit --local
Alternativ, wenn Ihr Input vollständig gepinnt (und optional gehasht) ist, können Sie `pip-audit` anweisen, die Abhängigkeitsauflösung mit entweder `--no-deps` (gepinnt ohne Hashes) oder `--require-hashes` (gepinnt inklusive Hashes) zu überspringen.
Letzteres ist äquivalent zu dem [Hash-Überprüfungsmodus](https://pip.pypa.io/en/stable/cli/pip_install/#hash-checking-mode) von pip und wird bevorzugt, da es zusätzliche Integrität bietet.```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 kann sich nicht gegenüber meinem Drittanbieter-Index authentifizieren!pip-audit unterstützt --index-url und --extra-index-url zum Konfigurieren von alternativen oder ergänzenden Paketindizes, genau wie pip.
Bei nicht authentifizierten Indizes sollten diese wie erwartet funktionieren. Wenn jedoch ein Drittanbieter-Index eine Authentifizierung erfordert, hat pip-audit einige zusätzliche Einschränkungen gegenüber dem normalen pip:
pip-audit wird Sie nicht nach einem Benutzernamen/Passwort für den Index fragen.pip's keyring Authentifizierung wird unterstützt, jedoch in eingeschränkter Form: pip-audit verwendet den subprocess-Keyring-Anbieter, da Audits in isolierten virtuellen Umgebungen stattfinden. Der subprocess-Anbieter unterliegt wiederum zusätzlichen Einschränkungen (wie einem erforderlichen Benutzernamen); die pip-Dokumentation erklärt diese ausführlich.Zusätzlich zu den oben genannten Punkten haben einige Drittanbieter-Indizes erforderliche, fest codierte Benutzernamen. Beispielsweise ist für die Google Artifact Registry der fest codierte Benutzername oauth2accesstoken. Siehe #742 und pip#11971 für weitere Informationen.
pipenv-Projektpipenv verwendet sowohl eine Pipfile- als auch eine Pipfile.lock-Datei, um Abhängigkeiten zu verfolgen und einzufrieren, anstatt einer requirements.txt-Datei. pip-audit kann die Pipfile[.lock]-Dateien nicht direkt verarbeiten, diese können jedoch in eine unterstützte requirements.txt-Datei konvertiert werden, gegen die pip-audit ausgeführt werden kann. pipenv verfügt über einen integrierten Befehl zum Konvertieren von Abhängigkeiten in eine requirements.txt-Datei (ab v2022.4.8):```console
$ pipenv run pip-audit -r <(pipenv requirements)
### Unterdrücken von Exit-Codes von `pip-audit`
`pip-audit` unterstützt absichtlich keine interne Unterdrückung seiner eigenen Exit-Codes.
Benutzer, die einen fehlschlagenden `pip-audit`-Aufruf unterdrücken müssen, können einen der standardmäßigen Shell-Idiome dafür verwenden:
pip-audit ... || true```bash
pip-audit || true
oder, um vollständig zu beenden:```bash pip-audit || exit 0
Der Exit-Code kann auch explizit abgefangen und behandelt werden:```bash
pip-audit
exitcode="${?}"
# do something with ${exitcode}
Siehe Exit codes für eine Liste potenzieller Codes, die behandelt werden müssen.
In Entwicklungsworkflows möchten Sie möglicherweise die Schwachstellen ignorieren, die noch nicht behoben wurden, und diese nur in Ihrem Release-Prozess untersuchen. pip-audit unterstützt das Ignorieren von nicht behobenen Schwachstellen nicht. Sie können jedoch die Ausgabe im JSON-Format exportieren und extern verarbeiten. Wenn Sie beispielsweise nur dann mit einem von Null verschiedenen Code beenden möchten, wenn die erkannten Schwachstellen bekannte Fix-Versionen haben, können Sie die Ausgabe mit jq wie folgt verarbeiten:```shell
test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')"
Ein einfaches (und ineffizientes) Beispiel für die Verwendung dieser Methode wäre:```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.
Dieser Abschnitt beschreibt die Sicherheitsannahmen, die Sie bei der Verwendung von pip-audit treffen können und nicht treffen dürfen.
TL;DR: Wenn Sie es nicht mit pip install installieren würden, sollten Sie es auch nicht mit pip audit prüfen.
pip-audit ist ein Werkzeug zur Überprüfung von Python-Umgebungen auf Pakete mit bekannten Schwachstellen. Eine "bekannte Schwachstelle" ist ein öffentlich gemeldeter Fehler in einem Paket, der, wenn er nicht behoben wird, es einem böswilligen Akteur ermöglichen könnte, unbeabsichtigte Aktionen durchzuführen.
pip-audit kann Sie vor bekannten Schwachstellen schützen, indem es Ihnen mitteilt, wenn Sie solche haben und wie Sie sie aktualisieren sollten. Wenn Sie beispielsweise somepackage==1.2.3 in Ihrer Umgebung haben, kann pip-audit Ihnen sagen, dass es auf 1.2.4 aktualisiert werden muss.
Sie können davon ausgehen, dass pip-audit sein Bestes tun wird, um alle Ihre Python-Abhängigkeiten vollständig aufzulösen und entweder jede vollständig zu prüfen oder explizit anzugeben, welche es übersprungen hat und warum.
pip-audit ist kein statischer Code-Analysator. Es analysiert Abhängigkeitsbäume, nicht Code, und es kann nicht garantieren, dass beliebige Abhängigkeitsauflösungen statisch erfolgen. Um zu verstehen, warum das so ist, lesen Sie Dustin Ingrams exzellenten Beitrag zur Abhängigkeitsauflösung in Python.
Daher: Sie dürfen nicht davon ausgehen, dass pip-audit Sie gegen bösartige Pakete verteidigt. Insbesondere ist es falsch, pip-audit -r INPUT als eine "sicherere" Variante von pip-audit zu betrachten. Für alle praktischen Zwecke ist pip-audit -r INPUT funktional äquivalent zu pip install -r INPUT, mit einer geringen nicht-sicherheitsrelevanten Isolierung, um Konflikte mit Ihren lokalen Umgebungen zu vermeiden.
pip-audit ist in erster Linie ein Prüfwerkzeug für Python-Pakete. Sie dürfen nicht davon ausgehen, dass pip-audit "transitive" Schwachstellen erkennt oder kennzeichnet, die möglicherweise durch Python-Pakete offengelegt werden, aber nicht tatsächlich Teil des Pakets selbst sind. Beispielsweise ist es unwahrscheinlich, dass die Schwachstelleninformationsquellen von pip-audit eine Sicherheitswarnung für eine angreifbare gemeinsam genutzte Bibliothek enthalten, die ein beliebtes Python-Paket möglicherweise verwendet, da die Version des Python-Pakets nicht stark mit der Version der gemeinsam genutzten Bibliothek verbunden ist.
pip-audit ist unter der Apache 2.0 Lizenz lizenziert.
pip-audit verwendet und modifiziert Beispiele von resolvelib, das unter der ISC-Lizenz lizenziert ist.
Siehe die Mitwirkungsdokumentation für Details.
Jeder, der mit diesem Projekt interagiert, wird gebeten, den PSF Verhaltenskodex zu befolgen.
| Flag | Umgebungsäquivalent | Beispiel |
|---|
--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 |