pypa/pip-auditAudita entornos Python, archivos de requisitos y árboles de dependencias en busca de vulnerabilidades de seguridad conocidas, y puede corregirlas automáticamente.
pip-audit es una herramienta para escanear entornos Python en busca de paquetes
con vulnerabilidades conocidas. Utiliza la Base de Datos de Asesoramiento de Empaquetado de Python
(https://github.com/pypa/advisory-database) a través de la
API JSON de PyPI como fuente
de informes de vulnerabilidades.
Este proyecto es mantenido en parte por Trail of Bits con el apoyo de Google. Esto no es un producto oficial de Google ni de Trail of Bits.
--fix)pippip-audit requiere Python 3.10 o superior, y se puede instalar directamente mediante pip:```bash
python -m pip install pip-audit
### Paquetes de terceros
Existen múltiples paquetes **de terceros** para `pip-audit`. Las matrices e insignias a continuación listan algunos de ellos:
[](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
En particular, `pip-audit` puede instalarse mediante `conda`:```bash
conda install -c conda-forge pip-audit
Los paquetes de terceros no son compatibles directamente con este proyecto. Consulte la documentación de su gestor de paquetes para obtener instrucciones de instalación más detalladas.
pip-audit tiene una Acción de GitHub oficial!
Puede instalarla desde el Marketplace de GitHub, o agregarla manualmente a su CI:```yaml jobs: pip-audit: steps: - uses: pypa/[email protected] with: inputs: requirements.txt
Consulte la
[documentación de la acción](https://github.com/pypa/gh-action-pip-audit/blob/main/README.md)
para más detalles y ejemplos de uso.
### Soporte de `pre-commit`
`pip-audit` tiene soporte para [`pre-commit`](https://pre-commit.com/).
Por ejemplo, usando `pip-audit` a través de `pre-commit` para auditar un archivo de requisitos:```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]
Cualquier argumento de pip-audit documentado a continuación puede ser pasado.
Puede ejecutar pip-audit como un programa independiente, o mediante 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 permite a los usuarios configurar algunas opciones mediante variables de entorno
en su lugar:
Al finalizar, pip-audit saldrá con un código indicando su estado.
Los códigos actuales son:
0: No se detectaron vulnerabilidades conocidas.1: Se encontraron una o más vulnerabilidades conocidas.El código de salida de pip-audit no se puede suprimir.
Vea Supresión de códigos de salida de pip-audit
para alternativas compatibles.
pip-audit admite la bandera --dry-run, que se puede usar para controlar si
se realiza realmente un paso de auditoría (o corrección).
pip-audit --dry-run omite el paso de auditoría e imprime
el número de dependencias que habrían sido auditadas.pip-audit --fix --dry-run realiza el paso de auditoría e imprime
el comportamiento de corrección (es decir, qué dependencias se actualizarían o saltarían)
que se habría realizado.Auditar dependencias para el entorno actual de Python:```console $ pip-audit No known vulnerabilities found
Auditar dependencias para un archivo de requisitos dado:```console
$ pip-audit -r ./requirements.txt
No known vulnerabilities found
Auditar dependencias para un archivo de requirements, excluyendo paquetes del sistema:```console $ pip-audit -r ./requirements.txt -l No known vulnerabilities found
Auditar dependencias para un proyecto local de Python:```console
$ pip-audit .
No known vulnerabilities found
Auditar archivos de bloqueo para un proyecto local de Python:```console $ pip-audit --locked . No known vulnerabilities found
`pip-audit` busca en la ruta proporcionada varios archivos de "proyecto" de Python.
Por el momento, solo se admiten `pyproject.toml` y `pylock.*.toml`.
Auditar dependencias cuando haya vulnerabilidades presentes:```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
Auditar dependencias incluyendo 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
Auditar dependencias incluyendo descripciones:```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.
Auditar dependencias en formato 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": [] } ]
Auditar e intentar actualizar automáticamente las dependencias vulnerables:```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)
¿Has resuelto un problema con pip-audit? ¡Ayúdanos contribuyendo a esta sección!
pip-audit muestra informes de vulnerabilidades irrelevantesEn un mundo perfecto, los feeds de vulnerabilidades tendrían una relación señal/ruido infinita: cada informe de vulnerabilidad sería (1) correcto y (2) aplicable a cada uso de cada dependencia.
Desafortunadamente, ninguna de estas garantías se cumple: los feeds de vulnerabilidades no son inmunes a informes extraños o de spam, y no todos los usos de una dependencia particular se corresponden con todas las clases potenciales de vulnerabilidades.
Si tus ejecuciones de pip-audit generan informes de vulnerabilidades que no son accionables para tu aplicación o caso de uso particular, puedes usar la opción --ignore-vuln ID para ignorar informes de vulnerabilidades específicos. --ignore-vuln soporta alias, por lo que puedes usar un ID GHSA-xxx o CVE-xxx en lugar de un ID PYSEC-xxx si el informe en cuestión no tiene un ID PYSEC.
Por ejemplo, así es como podrías ignorar GHSA-w596-4wvx-j9j6, que es una fuente común de informes de vulnerabilidades ruidosos y falsos positivos para los usuarios de pytest:```console
$ pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6
La opción `--ignore-vuln ID` funciona con todas las demás opciones de resolución de dependencias y auditoría, lo que significa que debería funcionar correctamente con entradas estilo requirements, fuentes de vulnerabilidades alternativas, etc.
También se puede pasar varias veces para ignorar múltiples informes:
``````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 toma más tiempo del que espero!Dependiendo de cómo lo estés usando, pip-audit puede tener que realizar su propia resolución de dependencias, que puede tomar aproximadamente el mismo tiempo que pip install para un proyecto. Consulta el modelo de seguridad para obtener una explicación.
Tienes dos opciones para evitar la resolución de dependencias: auditar un entorno preinstalado, o asegurarte de que tus dependencias ya estén completamente resueltas.
Si sabes que ya has configurado completamente un entorno equivalente al que pip-audit -r requirements.txt auditaría, simplemente puedes reutilizarlo:```console
$ pip-audit
$ pip-audit --local
Alternativamente, si su entrada está completamente fijada (y opcionalmente con hash), puede indicarle a `pip-audit` que omita la resolución de dependencias con `--no-deps` (fijado sin hashes) o `--require-hashes` (fijado incluyendo hashes).
Esta última opción es equivalente al [modo de verificación de hash](https://pip.pypa.io/en/stable/cli/pip_install/#hash-checking-mode) de `pip` y es preferida, ya que ofrece integridad adicional.```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 no puede autenticarse en mi índice de terceros!pip-audit admite --index-url y --extra-index-url para configurar índices de paquetes alternativos o suplementarios, al igual que pip.
Cuando no están autenticados, estos índices deberían funcionar como se espera. Sin embargo, cuando un índice de terceros requiere autenticación, pip-audit tiene algunas restricciones adicionales además de las de pip normal:
pip-audit no le solicitará un nombre de usuario/contraseña para el índice.keyring de pip está soportada, pero de forma limitada: pip-audit utiliza el proveedor de llavero subprocess, ya que las auditorías ocurren en entornos virtuales aislados. El proveedor subprocess a su vez está sujeto a restricciones adicionales (como un nombre de usuario obligatorio); la documentación de pip explica esto en profundidad.Además de lo anterior, algunos índices de terceros tienen nombres de usuario obligatorios y codificados. Por ejemplo, para Google Artifact Registry, el nombre de usuario codificado es oauth2accesstoken. Consulte #742 y pip#11971 para obtener más contexto.
pipenvpipenv utiliza tanto un archivo Pipfile como Pipfile.lock para rastrear y congelar dependencias en lugar de un archivo requirements.txt. pip-audit no puede procesar los archivos Pipfile[.lock] directamente, sin embargo, estos se pueden convertir a un archivo requirements.txt compatible contra el que pip-audit pueda ejecutarse. pipenv tiene un comando integrado para convertir dependencias a un archivo requirements.txt (a partir de v2022.4.8):```console
$ pipenv run pip-audit -r <(pipenv requirements)
### Suprimir códigos de salida de `pip-audit`
`pip-audit` no admite intencionadamente la supresión interna de sus propios códigos de salida.
Los usuarios que necesiten suprimir una invocación fallida de `pip-audit` pueden usar uno de los modismos estándar del shell para hacerlo:```bash
pip-audit || true
o, para salir completamente:```bash pip-audit || exit 0
El código de salida también puede ser capturado y manejado explícitamente:```bash
pip-audit
exitcode="${?}"
# do something with ${exitcode}
Consulte Códigos de salida para obtener una lista de posibles códigos que requieren manejo.
En los flujos de trabajo de desarrollo, es posible que desee ignorar las vulnerabilidades que aún no se han solucionado y solo investigarlas en su proceso de lanzamiento. pip-audit no admite ignorar vulnerabilidades no corregidas. Sin embargo, puede exportar su salida en formato JSON y procesarla externamente. Por ejemplo, si desea salir con un código distinto de cero solo cuando las vulnerabilidades detectadas tienen versiones de corrección conocidas, puede procesar la salida usando jq como:```shell
test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')"
Un ejemplo simple (e ineficiente) de usar este método sería:```shell
test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')" || pip-audit -r requirements.txt
que ejecuta pip-audit como de costumbre y sale con un código distinto de cero solo si hay versiones corregidas para las vulnerabilidades conocidas.
Esta sección existe para describir las suposiciones de seguridad que puedes y no debes hacer al usar pip-audit.
TL;DR: Si no lo instalarías con pip install, no deberías auditarlo con pip audit.
pip-audit es una herramienta para auditar entornos Python en busca de paquetes con vulnerabilidades conocidas. Una "vulnerabilidad conocida" es un fallo reportado públicamente en un paquete que, si no se corrige, podría permitir que un actor malicioso realice acciones no deseadas.
pip-audit puede protegerte contra vulnerabilidades conocidas informándote cuándo las tienes y cómo deberías actualizarlas. Por ejemplo, si tienes somepackage==1.2.3 en tu entorno, pip-audit puede decirte que necesita actualizarse a 1.2.4.
Puedes asumir que pip-audit hará el mejor esfuerzo para resolver completamente todas tus dependencias Python y ya sea auditar completamente cada una o indicar explícitamente cuáles ha omitido, así como por qué las ha omitido.
pip-audit no es un analizador de código estático. Analiza árboles de dependencias, no código, y no puede garantizar que resoluciones de dependencias arbitrarias ocurran estáticamente. Para entender por qué es así, consulta la excelente publicación de Dustin Ingram sobre la resolución de dependencias en Python.
Por lo tanto: no debes asumir que pip-audit te defenderá contra paquetes maliciosos. En particular, es incorrecto tratar pip-audit -r INPUT como una variante "más segura" de pip-audit. A todos los efectos, pip-audit -r INPUT es funcionalmente equivalente a pip install -r INPUT, con una pequeña cantidad de aislamiento no relacionado con la seguridad para evitar conflictos con cualquiera de tus entornos locales.
pip-audit es ante todo una herramienta de auditoría para paquetes Python. No debes asumir que pip-audit detectará o marcará vulnerabilidades "transitivas" que podrían exponerse a través de paquetes Python, pero que en realidad no son parte del paquete en sí. Por ejemplo, es poco probable que las fuentes de información de vulnerabilidades de pip-audit incluyan un aviso sobre una biblioteca compartida vulnerable que un paquete Python popular podría usar, ya que la versión del paquete Python no está fuertemente relacionada con la versión de la biblioteca compartida.
pip-audit está bajo la licencia Apache 2.0.
pip-audit reutiliza y modifica ejemplos de resolvelib, el cual está bajo la licencia ISC.
Consulta la documentación de contribución para más detalles.
Se espera que todos los que interactúen con este proyecto sigan el Código de Conducta de la PSF.
| Banderas | Equivalente de entorno | Ejemplo |
|---|
--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 |