Auditando dependencias de Python con pip-audit

pip-audit: cómo escanear dependencias Python contra la base de datos pública de vulnerabilidades PyPA y cómo integrar el testeo en CI.

Una dependencia vulnerable no avisa. Se instala cuando ejecutas pip install, queda fijada en tu requirements.txt y se queda ahí mientras en la base de datos pública de avisos de seguridad se van acumulando CVEs que la afectan directamente. El problema no es que las vulnerabilidades aparezcan: es que nadie las busca hasta que ya es tarde.

pip-audit es la herramienta oficial del PyPA (Python Packaging Authority) para resolver este problema: toma cada paquete con su versión exacta, lo consulta contra la OSV (Open Source Vulnerabilities) y el PyPI Advisory Database, y te devuelve qué está comprometido y a qué versión tienes que actualizar.

El detalle que diferencia pip-audit de un script casero es el exit code: pip-audit devuelve un valor distinto de cero en cuanto encuentra una vulnerabilidad, lo que significa que cualquier sistema de CI - GitHub Actions, GitLab CI, Jenkins, etc. - lo interpreta como un fallo sin necesitar configuración adicional. El paso falla solo, el build se detiene y el problema queda visible antes de que llegue a producción.

Qué compara y contra qué

Antes de ejecutar nada vale la pena entender contra qué base de datos trabaja pip-audit. Por defecto consulta la OSV, el agregador de Google que unifica avisos de múltiples ecosistemas en un único punto de consulta. Como fuente secundaria usa el PyPA - PyPI Advisory Database, el repositorio oficial de avisos de seguridad para paquetes publicados en PyPI (el repositorio oficial de paquetes Python).

Por cada coincidencia devuelve el identificador del aviso en formato GHSA- o PYSEC-, las versiones afectadas y la versión en la que el problema queda corregido. Esa última columna, Fix Versions, es la que hace que la auditoría sirva para algo en lugar de quedarse en una lista de problemas sin salida.

Instalación

La herramienta debería instalarse en un entorno virtual aislado:

python3 -m venv .venv
source .venv/bin/activate

Con el entorno virtual activo, instalamos la herramienta:

pip install pip-audit

Auditar un requirements.txt

El caso de uso habitual es escanear un fichero de requisitos con el flag -r. pip-audit resuelve las dependencias declaradas, incluyendo las transitivas, consulta la base de datos de avisos y devuelve una tabla. Si todo está limpio:

pip-audit -r requirements.txt

No known vulnerabilities found

Si hay problemas, la salida identifica el paquete, la versión instalada, el identificador del aviso y la versión a la que hay que moverse:

Name      Version  ID                  Fix Versions
--------- -------- ------------------- ------------
requests  2.19.0   GHSA-x84v-xcm2-53pg 2.20.0
jinja2    2.10     PYSEC-2019-217      2.10.1

Si en lugar de un fichero quieres auditar lo que hay realmente instalado en el entorno activo —que no siempre coincide con lo que dice el requirements.txt— basta lanzarlo sin argumentos:

pip-audit

Salida en formato máquina

Para procesarlo en CI o guardarlo, pip-audit acepta varios formatos con el flag -f. El flag -o escribe el resultado a fichero en lugar de a la terminal:

pip-audit -r requirements.txt -f json -o auditoria.json

Los formatos disponibles son columns, json, cyclonedx-json y markdown. Este último viene bien si quieres pegar el informe en un comentario de una pull request sin tocar nada más.

Corrección automática

pip-audit puede aplicar directamente las actualizaciones que resuelven lo que ha encontrado. Con --fix actualiza cada paquete vulnerable a la primera versión segura disponible. Si antes quieres ver qué haría sin que toque nada, combínalo con --dry-run:

pip-audit -r requirements.txt --fix --dry-run

pip-audit -r requirements.txt --fix

La distinción entre "versión segura" y "versión compatible con tu código" no la resuelve pip-audit. Eso requiere pasar los tests después del cambio, siempre en una rama aparte.

Integración en CI

Lo más útil de pip-audit en un pipeline es que no necesita configuración extra para fallar cuando encuentra algo: devuelve un exit code distinto de cero y el paso se pone en rojo solo. En GitHub Actions:

- name: Auditar dependencias
  run: |
    pip install pip-audit
    pip-audit -r requirements.txt

Si hay un aviso que todavía no tiene parche y necesitas convivir con él temporalmente, puedes ignorarlo por identificador. Eso sí, un --ignore-vuln sin comentario en el repositorio explicando por qué está ahí es deuda de seguridad esperando a que alguien la olvide:

pip-audit -r requirements.txt --ignore-vuln GHSA-x84v-xcm2-53pg

Conclusión

El problema de las dependencias Python no es técnico, es de hábito: las versiones se fijan al instalar y nadie las vuelve a mirar hasta que algo falla. pip-audit convierte esa revisión en un paso automático del pipeline, contra bases de datos actualizadas, sin infraestructura adicional.

La parte difícil no es la herramienta. Es aceptar que un paquete que llevas seis meses usando sin problemas puede tener un CVE publicado desde hace cinco. Esa suposición —que lo que funciona está a salvo— es exactamente la que explotan los ataques de cadena de suministro.

Fuentes:

PyPA - Repositorio oficial de pip-audit
Google - OSV: Open Source Vulnerabilities
PyPA - PyPI Advisory Database