Index

• Fonctionnalités
• Installation
  • Paquets tiers
  • Actions GitHub
  • Support pre-commit
• Utilisation
  • Variables d'environnement
  • Codes de sortie
  • Exécutions à blanc
• Exemples
• Dépannage
• Astuces et conseils
• Modèle de sécurité
• Licence
• Contribution
• Code de conduite

Fonctionnalités

• Prise en charge de l'audit des environnements locaux et des fichiers de type requirements
• Prise en charge de multiples services de vulnérabilités (PyPI, OSV)
• Prise en charge de l'émission de SBOMs au format XML ou JSON CycloneDX
• Prise en charge de la correction automatique des dépendances vulnérables (--fix)
• Formats de sortie lisibles par l'humain et par machine (colonne, Markdown, JSON)
• Réutilisation transparente de vos caches pip locaux existants

Installation

pip-audit nécessite Python 3.10 ou plus récent, et peut être installé directement via pip :```bash python -m pip install pip-audit

Les paquets tiers ne sont pas directement supportés par ce projet. Veuillez consulter la documentation de votre gestionnaire de paquets pour des instructions d'installation plus détaillées.

GitHub Actions

pip-audit a une action GitHub officielle !

Vous pouvez l'installer depuis le GitHub Marketplace, ou l'ajouter manuellement à votre CI :```yaml jobs: pip-audit: steps: - uses: pypa/[email protected] with: inputs: requirements.txt

Tous les arguments pip-audit documentés ci-dessous peuvent être passés.

Utilisation

Vous pouvez exécuter pip-audit en tant que programme autonome, ou via python -m:```bash pip-audit --help python -m pip_audit --help

Variables d'environnement

pip-audit permet aux utilisateurs de configurer certains indicateurs via des variables d'environnement plutôt :

Codes de sortie

À la fin, pip-audit se termine avec un code indiquant son état.

Les codes actuels sont :

• 0 : Aucune vulnérabilité connue détectée.
• 1 : Une ou plusieurs vulnérabilités connues ont été trouvées.

Le code de sortie de pip-audit ne peut pas être supprimé. Voir Supprimer les codes de sortie de pip-audit pour des alternatives prises en charge.

Exécutions à blanc

pip-audit prend en charge l'option --dry-run, qui peut être utilisée pour contrôler si une étape d'audit (ou de correction) est réellement effectuée.

• Seul, pip-audit --dry-run ignore l'étape d'audit et affiche le nombre de dépendances qui auraient été auditées.
• En mode correction, pip-audit --fix --dry-run effectue l'étape d'audit et affiche le comportement de correction (c'est-à-dire quelles dépendances seraient mises à niveau ou ignorées) qui aurait été effectué.

Exemples

Auditer les dépendances pour l'environnement Python actuel :```console $ pip-audit No known vulnerabilities found

Auditer les dépendances pour un fichier requirements, à l'exclusion des paquets système :```console $ pip-audit -r ./requirements.txt -l No known vulnerabilities found

Auditer les lockfiles pour un projet Python local :```console $ pip-audit --locked . No known vulnerabilities found

Auditer les dépendances, y compris les alias :```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

Auditer les dépendances au format 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": [] } ]

Dépannage

Vous avez résolu un problème avec pip-audit ? Aidez-nous en contribuant à cette section !

pip-audit affiche des rapports de vulnérabilité non pertinents !

Dans un monde parfait, les flux de vulnérabilités auraient un rapport signal/bruit infini : chaque rapport de vulnérabilité serait (1) correct et (2) applicable à chaque utilisation de chaque dépendance.

Malheureusement, rien de tout cela n'est garanti : les flux de vulnérabilités ne sont pas à l'abri de rapports superflus ou de spam, et toutes les utilisations d'une dépendance particulière ne correspondent pas à toutes les classes potentielles de vulnérabilités.

Si vos exécutions de pip-audit produisent des rapports de vulnérabilité qui ne sont pas exploitables pour votre application ou cas d'utilisation particulier, vous pouvez utiliser l'option --ignore-vuln ID pour ignorer des rapports de vulnérabilité spécifiques. --ignore-vuln prend en charge les alias, vous pouvez donc utiliser un ID GHSA-xxx ou CVE-xxx au lieu d'un ID PYSEC-xxx si le rapport en question ne possède pas d'ID PYSEC.

Par exemple, voici comment ignorer GHSA-w596-4wvx-j9j6, qui est une source courante de rapports de vulnérabilité bruyants et de faux positifs pour les utilisateurs de pytest :```console

Run the audit as normal, but exclude any reports that match GHSA-w596-4wvx-j9j6

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

pip-audit prend plus de temps que prévu !

Selon la façon dont vous l'utilisez, pip-audit peut devoir effectuer sa propre résolution des dépendances, ce qui peut prendre à peu près autant de temps que pip install pour un projet. Voir le modèle de sécurité pour une explication.

Vous avez deux options pour éviter la résolution des dépendances : auditer un environnement préinstallé, ou s'assurer que vos dépendances sont déjà entièrement résolues.

Si vous savez que vous avez déjà entièrement configuré un environnement équivalent à celui que pip-audit -r requirements.txt auditerait, vous pouvez simplement le réutiliser :```console

Note the absence of any "input" arguments, indicating that the environment is used.

$ pip-audit

Optionally filter out non-local packages, for virtual environments:

$ pip-audit --local

pip-audit ne peut pas s'authentifier à mon index tiers !

Index tiers authentifiés ou index privés

pip-audit prend en charge --index-url et --extra-index-url pour configurer des index de paquets alternatifs ou supplémentaires, tout comme pip.

Lorsqu'ils sont non authentifiés, ces indices devraient fonctionner comme prévu. Cependant, lorsqu'un index tiers nécessite une authentification, pip-audit a quelques restrictions supplémentaires par rapport à pip normal :

• L'authentification interactive n'est pas prise en charge. En d'autres termes : pip-audit ne vous demandera pas de nom d'utilisateur/mot de passe pour l'index.
• L'authentification par keyring de pip est prise en charge, mais de manière limitée : pip-audit utilise le fournisseur de keyring subprocess, car les audits ont lieu dans des environnements virtuels isolés. Le fournisseur subprocess est lui-même soumis à des restrictions supplémentaires (comme un nom d'utilisateur obligatoire) ; la documentation de pip les explique en détail.

En plus de ce qui précède, certains index tiers ont des noms d'utilisateur obligatoires et codés en dur. Par exemple, pour Google Artifact Registry, le nom d'utilisateur codé en dur est oauth2accesstoken. Voir #742 et pip#11971 pour plus de contexte.

Trucs et astuces

Exécution sur un projet pipenv

pipenv utilise à la fois un fichier Pipfile et Pipfile.lock pour suivre et figer les dépendances au lieu d'un fichier requirements.txt. pip-audit ne peut pas traiter directement les fichiers Pipfile[.lock], mais ceux-ci peuvent être convertis en un fichier requirements.txt pris en charge que pip-audit peut analyser. pipenv dispose d'une commande intégrée pour convertir les dépendances en fichier requirements.txt (depuis la v2022.4.8) :```console $ pipenv run pip-audit -r <(pipenv requirements)

ou, pour quitter complètement :```bash pip-audit || exit 0

Consultez Codes de sortie pour une liste des codes potentiels qui nécessitent une gestion.

Signaler uniquement les vulnérabilités corrigibles

Dans les workflows de développement, vous pouvez souhaiter ignorer les vulnérabilités qui n'ont pas encore été corrigées et ne les examiner que lors de votre processus de publication. pip-audit ne prend pas en charge l'ignorance des vulnérabilités non corrigées. Cependant, vous pouvez exporter sa sortie au format JSON et la traiter en externe. Par exemple, si vous voulez quitter avec un code non nul uniquement lorsque les vulnérabilités détectées ont des versions de correctif connues, vous pouvez traiter la sortie en utilisant jq comme suit :```shell test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')"

which runs pip-audit as usual and exits with a non-zero code only if there are fixed versions for the known vulnerabilities.

Security Model

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.

Licensing

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.

Contributing

See the contributing docs for details.

Code of Conduct

Everyone interacting with this project is expected to follow the PSF Code of Conduct.