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

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

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:

   - requests==2.20.0
   + requests==2.31.0

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

poetry lock --no-update && poetry update ).

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 lists the parents

in its "Required-by" line.

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

versions ` 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

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

- 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

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:: (or pypi-audit:: / pypi-audit:: 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