Auditing Python Dependencies

Overview

PyPI hosts north of 500,000 packages, with several thousand new releases every day. The package-install model is identical to npm in the relevant ways: a pip install resolves a transitive graph, runs each package's setup.py (which executes arbitrary Python at install time), and writes the result to your site-packages. The CVE attack surface is therefore the same shape: known vulnerabilities, maintainer-account takeovers, typosquats, and protestware.

The PyPA-blessed auditor is pip-audit. It queries the Open Source Vulnerabilities (OSV) database (which mirrors PyPA's advisory feed plus aggregated CVE / GHSA records) and reports per-package vulnerable versions. pip-audit integrates with requirements.txt, pyproject.toml, Pipfile.lock, and poetry.lock, so most Python project layouts are first-class.

This skill wraps pip-audit, normalizes its severity vocabulary to the shared Severity enum, and emits Findings in the canonical penetration-tester schema. If pip-audit isn't installed on the host, the skill falls back to pip list --outdated and emits INFO-level findings recommending the operator install pip-audit for accurate vulnerability detection.

When the skill produces findings

| Finding | Severity | Threshold | Affected control | |---|---|---|---| | Critical CVE in installed package | CRITICAL | OSV severity band corresponds to CVSS ≥ 9.0 | CWE-1104 | | High CVE in installed package | HIGH | OSV severity band corresponds to CVSS 7.0–8.9 | CWE-1104 | | Medium CVE in installed package | MEDIUM | OSV severity band corresponds to CVSS 4.0–6.9 | CWE-1104 | | Low CVE in installed package | LOW | OSV severity band corresponds to CVSS 0.1–3.9 | CWE-1104 | | Vulnerable package with no patch | HIGH | finding has no fix_versions and severity ≥ medium | CWE-1395 | | Outdated package (no CVE) | INFO | pip list --outdated reports a newer version | (operational) | | pip-audit not installed | INFO | binary not on PATH; scanner fell back to pip list | (operational) | | Audit DB unreachable | INFO | pip-audit network error reaching OSV | (operational) |

OSV is the upstream of record. pip-audit also consults the PyPA advisory database for Python-specific records that may not yet have a CVE assigned.

Prerequisites

• Python 3.9+
• pip-audit installed (pip install pip-audit); skill falls back

to pip list --outdated if absent

• Target project containing at minimum one of: requirements.txt,

pyproject.toml, Pipfile.lock, poetry.lock

• Network access to OSV (api.osv.dev) and PyPI (pypi.org)

Instructions

Step 1 — Identify the scan target

Locate the project directory. The scanner auto-detects requirement files in order of preference:

1. poetry.lock (most precise — exact resolved tree)
2. Pipfile.lock
3. requirements.txt (and requirements-*.txt siblings)
4. pyproject.toml (PEP 621 dependencies)
5. Installed environment via pip list (last resort)

Step 2 — Run the audit

bash
python3 ./scripts/audit_python.py /path/to/python-project

Options:

Usage: audit_python.py PATH [OPTIONS]

Options:
  --output FILE      Write findings to FILE (default: stdout)
  --format FMT       json | jsonl | markdown (default: markdown)
  --min-severity SEV (default: info)
  --requirement FILE Override auto-detection; specify a particular
                     requirements file (repeatable)
  --include-dev      Include development dependencies (default: prod
                     only when project layout allows the distinction)
  --strict           Treat pip-audit warnings as errors

Step 3 — Interpret findings

CRITICAL / HIGH = block release.

MEDIUM / LOW = track but don't block; many Python advisories report edge-case theoretical issues that don't apply to your usage.

INFO = log only; e.g. "outdated but no known CVE" is information for your release cadence, not a security action.

Step 4 — Remediation

For a vulnerable package with fix_versions:

1. Bump the version pin in your requirements file:

diff

• requests==2.20.0

+ requests==2.31.0

1. Run pip install -r requirements.txt --upgrade (or

poetry lock --no-update && poetry update <pkg>).

1. Run the test suite. CVE fixes occasionally include behavioral

changes you didn't expect.

1. Commit the lock file diff alongside the requirements bump.

For a vulnerable transitive dep (one you didn't declare directly):

1. Find the parent: pip show <vulnerable-package> lists the parents

in its "Required-by" line.

1. Check whether bumping the parent picks up the fix. pip index

versions <parent> lists available versions.

1. If parent doesn't have a newer release that floors the vulnerable

dep above the fix version, pin the transitive dep yourself in your requirements file. pip will use the more specific pin.

For a vulnerable package with NO fix available:

1. Subscribe to PyPA advisory notifications for that package.

1. If the vulnerability is exploitable in your usage, either

replace the package or vendor + patch locally.

1. Document the exception in your security register with a

re-evaluation date.

Examples

Example 1 — Pre-merge gate

bash
python3 ./scripts/audit_python.py . --min-severity high --format json --output audit.json
jq -e '. == []' audit.json || { echo "High/critical Python CVE — fix before merge"; exit 1; }

Example 2 — CI scan on every push

yaml
- name: pip-audit
  run: pip install pip-audit
- name: Run audit
  run: |
    python3 plugins/security/penetration-tester/skills/auditing-python-dependencies/scripts/audit_python.py \
        . --min-severity high --format markdown --output py-audit.md

Example 3 — SOC2 evidence collection

bash
mkdir -p evidence/CC7/
python3 ./scripts/audit_python.py . --include-dev --format json \
    --output evidence/CC7/py-audit-$(date +%Y%m%d).json

--include-dev for SOC2: include dev/test deps so auditors see the full surface, not just production.

Output

JSON / JSONL / Markdown per lib/report.py. Exit codes: 0 clean, 1 high/critical, 2 error.

Each Finding includes:

• id — synthesized as pypi-audit::<cve-id> (or pypi-audit::<ghsa> / pypi-audit::<pypa-id> when no CVE)
• severity — CRITICAL / HIGH / MEDIUM / LOW / INFO
• category — dependency-vulnerability
• summary — short CVE / GHSA title
• evidence — affected package, affected version, fix versions, advisory ID
• references — OSV URL, CVE URL, PyPA advisory URL

Error Handling

• pip-audit not installed → falls back to pip list --outdated,

emits an INFO Finding flagging the degraded scan, and proceeds.

• No requirement file found → emits an INFO Finding "no Python

project structure recognized" and exits 2.

• OSV API unreachable → emits an INFO Finding documenting the

outage and exits 0 (no actionable security finding).

• pip-audit returns malformed JSON → emits an INFO Finding with

the raw output truncated to 500 chars and exits 2.

Resources

• references/THEORY.md — PyPI supply-chain history, OSV vs NVD vs

PyPA advisory scopes, why ecosystem-specific severity matters, Python-specific install-time risks (setup.py execution, eager dependency resolution), pip-audit vs Safety vs Snyk trade-offs

• references/PLAYBOOK.md — Per-toolchain remediation patterns

(pip + requirements.txt, poetry, pipenv, uv, conda), monorepo / workspace scanning, override-equivalent patterns in Python ecosystem, GitHub Dependabot ecosystem mapping, SOC2 evidence retention