ha:deps-audit
Audit PyPI deps for supply-chain security risk — bidi chars, install-time/build-backend exec, maintainer changes, typosquats, CVEs. Use after a dependency bump, when checking if a package upgrade is s
SKILL.mdskills/deps-audit/SKILL.md
GitHubPyPI Dependency Audit
Non-mutating supply-chain audit for PyPI packages. Runs an 8-rule MVP catalogue
against changed packages, enriches with PyPI JSON API metadata, wraps existing tools
(pip-audit, osv-scanner), and emits a triage table.
When to Use
- After a dependency bump brought in new versions (
pip install -r,uv pip install) - On PRs that touch
requirements*.txt/custom_components/*/manifest.json/pyproject.toml(pre-merge gate) - Before manually updating a single package (
--preview <pkg>) - When investigating a dependency you don't recognize
Iron Laws
- NEVER claim a diff is clean without inspecting it. Run all 8 rules
on the unpacked NEW sdist/wheel. "Looks fine" without a tool run is a false
pass. Always write
.claude/deps-audit/last-run.json— its absence is evidence the audit didn't actually run. - NEVER install
osv-scanner/pip-audit-adjacent tools — even if asked. Detect, warn with install instructions, skip cleanly if missing. If the user says "install it," respond with the install command (e.g.,uv tool install pip-auditor the platform binary release) and do not execute it. The audit skill is non-mutating;requirements*.txt/manifest.json/pyproject.tomlare off-limits regardless of consent. - NEVER promote a finding to BLOCK without rule citation. Every finding
shows
rule_id,severity,file:line,snippet,message. No handwaving. - NEVER fetch from PyPI without rate-limiting. Cap at 5 req/sec. Cache metadata 7 days, top-PyPI-packages list 1 day.
- NEVER run the audit on already-committed requirement changes silently —
tell the user which mode (A/B/C) is active and which
(old, new)pairs resolved. - LLM triage only above threshold. Native rules + Semgrep + YARA
are deterministic. The
pypi-deps-triageragent runs only when score10 (1 BLOCK or 3+ WARNs), and its verdicts are advisory — never auto-suppress a finding without human review.
Operating Modes
| Mode | Trigger | Old source | New source |
|---|---|---|---|
| B (default) | /ha:deps-audit |
git show HEAD:requirements.txt |
working requirement sources |
| C (PR) | /ha:deps-audit --base dev |
git show <ref>:requirements.txt |
working requirement sources |
| A (preview) | /ha:deps-audit --preview aiohttp |
pinned version | PyPI latest release |
See ${CLAUDE_SKILL_DIR}/references/operating-modes.md for full resolver logic.
Execution Flow
Default = full 8-rule scan with streaming progress. --quick opts out
to CVE + retirement only. See ${CLAUDE_SKILL_DIR}/references/execution-flow.md.
Step 1: Resolve the diff
Parse the requirement sources (requirements*.txt, custom_components/*/manifest.json
requirements, and pyproject.toml dependencies) for both old and new sources. Emit a
list of {pkg, old_version, new_version} tuples. Surface
new-only and removed-only packages separately (a removed package is not
audited; a brand-new package gets old_version = nil and skips diff-only
rules).
See ${CLAUDE_SKILL_DIR}/references/diff-resolver.md for shell + python3 -c snippets per mode and the JSON output contract.
Step 2: Fetch sdist + wheel (per-run tmpdir)
For each (pkg, old, new):
curl -s https://pypi.org/pypi/<pkg>/<old>/json | jq -r '.urls[] | select(.packagetype=="sdist") | .url' | xargs curl -sL | tar -xz -C ${AUDIT_TMPDIR}/dists/<pkg>/<old>/
curl -s https://pypi.org/pypi/<pkg>/<new>/json | jq -r '.urls[] | select(.packagetype=="sdist") | .url' | xargs curl -sL | tar -xz -C ${AUDIT_TMPDIR}/dists/<pkg>/<new>/
All ephemeral artifacts live under ${AUDIT_TMPDIR} (driver-owned, removed
on exit). See ${CLAUDE_SKILL_DIR}/references/audit-tmpdir.md and
${CLAUDE_SKILL_DIR}/references/tarball-fetcher.md.
Step 3: Run the 8 MVP rules on each NEW sdist/wheel
| # | Rule | Sev | Method |
|---|---|---|---|
| 1 | Bidi Unicode control chars in .py / .pyi |
BLOCK | grep |
| 2 | exec / eval / compile(...) with non-literal source at module scope |
BLOCK | AST (ast module) |
| 3 | subprocess/os.system/network calls in setup.py or build-backend hooks (install-time execution) |
BLOCK | AST + build config |
| 4 | Obfuscated/base64-decoded exec/eval payload without safe guard |
BLOCK | AST |
| 5 | New git/URL/pre-release requirement (vs old) in manifest/requirements | BLOCK | manifest diff |
| 6 | Maintainer change between versions | BLOCK | PyPI JSON API |
| 7 | Base64 blobs >256 chars outside tests/, fixtures/, data/ |
WARN | regex |
| 8 | Levenshtein ≤2 from top-PyPI-packages list + download delta >1000× | BLOCK | PyPI JSON API + fuzzy |
Full catalogue (35 rules, MVP marked) in ${CLAUDE_SKILL_DIR}/references/heuristics.md.
Bash + python3 -c implementations for all 8 MVP rules in
${CLAUDE_SKILL_DIR}/references/rules-impl.md (single-pass NEW + diff rules +
PyPI registry rules, with run_all_rules master loop).
Step 4: External tool wrappers (parallel)
pip-audit --format json— CVE + retirement check via the PyPI advisory DB / OSV, always attemptedosv-scanner— CVE check via OSV.dev ("ecosystem": "PyPI"), if installed (else warn + skip; do NOT install)
See ${CLAUDE_SKILL_DIR}/references/external-tools.md for detection, output parsing, and severity mapping per tool.
Step 5: PyPI registry enrichment (per package)
GET https://pypi.org/pypi/<name>/json— maintainers, releases,info, upload timesGET https://pypi.org/pypi/<name>/<version>/json— per-release files,upload_time, yanked status- Compute:
days_since_publish,maintainer_age_days,download_velocity(viahttps://pypistats.org/api/packages/<name>/recent)
Cap at 5 req/sec. Per-run cache under ${AUDIT_TMPDIR}/pypi-api/.
See ${CLAUDE_SKILL_DIR}/references/pypi-api.md for endpoint contracts,
caching strategy, Rule 6/8 detection, and Levenshtein implementation.
Step 5.5: Apply pypi-vet.json ledger (if present)
If pypi-vet.json exists at project root, vetted-version findings are
downgraded to INFO. Unvetted versions retain their severity.
Manifest-vs-ledger disagreement: manifest wins. See the deps-vet skill's
pypi-vet schema doc for the "Manifest-vs-ledger disagreement" section.
Use /ha:deps-vet <pkg> <version> (separate skill) to add entries.
Step 5.7: Differential subtract
When run with DIFFERENTIAL=1 (default), findings that existed in the
OLD sdist/wheel are downgraded to INFO. Net-new signals reach the renderer
at full severity. See ${CLAUDE_SKILL_DIR}/references/differential.md.
Step 5.8: LLM triage (when score > threshold)
For packages where the aggregate score exceeds 10, the
pypi-deps-triager sonnet agent reads finding + diff windows and
produces structured verdicts (confidence, verdict, rationale,
fp_reasons[]). A context-supervisor (haiku) consolidates verdicts
across packages into triage/consolidated.md. Main skill reads only
the consolidated file.
See ${CLAUDE_SKILL_DIR}/references/llm-triage.md.
Step 6: Score & render
Per-package weighted sum: BLOCK = 10, WARN = 3, INFO = 1. Risk band: 0 clean · 1–5 low · 6–15 medium · 16+ high.
Output:
- Stdout: markdown table —
pkg | old → new | risk | findings | pypi.org/project/<pkg>/<version> | maintainer-changeplus a per-package detail section for any non-clean row. - Sidecar (MANDATORY): Write
.claude/deps-audit/last-run.json. The Phase 3 gate reads this; an audit that doesn't write it is a no-op for the gate. Always emit, even on clean runs.
--json flag emits JSON to stdout instead of markdown. See
${CLAUDE_SKILL_DIR}/references/output-renderer.md for table format,
sidecar schema, exit-code rubric, and --quiet mode.
Out of scope / Phase 3 surface
- NEVER modify
requirements*.txt,manifest.json,pyproject.toml, or any project file (non-mutating) - NEVER auto-install missing tools (warn + skip)
- Integration deps come ONLY from manifest
requirements— dependency bumps are ALWAYS a separate PR (Iron Law P11 + PR1). - Gate
pip install/uv pip install/uv addviadeps-audit-gate.sh. See${CLAUDE_SKILL_DIR}/references/hook.md. - Prompt for
/ha:compoundafter BLOCK findings — corpus self-feeds. - Emit SARIF 2.1.0 via
--sarif <path>and gate CI via--ci.
References
${CLAUDE_SKILL_DIR}/references/heuristics.md— full 35-rule catalogue${CLAUDE_SKILL_DIR}/references/rules-impl.md— bash +python3 -cfor the 8 MVP rules${CLAUDE_SKILL_DIR}/references/operating-modes.md— Mode A/B/C resolver${CLAUDE_SKILL_DIR}/references/diff-resolver.md— shell snippets, requirement parser${CLAUDE_SKILL_DIR}/references/tarball-fetcher.md— fetch wrapper, parallel cap, cache prune${CLAUDE_SKILL_DIR}/references/external-tools.md—pip-audit,osv-scannerwrappers${CLAUDE_SKILL_DIR}/references/pypi-api.md— endpoint contracts, rate limit, Rule 6/8${CLAUDE_SKILL_DIR}/references/output-renderer.md— markdown, JSON v1, exit codes, SARIF${CLAUDE_SKILL_DIR}/references/testing.md— smoke runner, fixture matrix${CLAUDE_SKILL_DIR}/references/differential.md/llm-triage.md— Phase 2 NDJSON subtract + triager${CLAUDE_SKILL_DIR}/references/semgrep.md/yara.md— Phase 2 precision layers (soft deps)${CLAUDE_SKILL_DIR}/references/cassettes.md/sarif.md/hook.md/ci-integration.md— Phase 3 surface${CLAUDE_SKILL_DIR}/references/trusted-publishers.md/skill-checklist.md— upstream + eval${CLAUDE_SKILL_DIR}/references/audit-tmpdir.md— Phase 5 per-run ephemeral storage contract${CLAUDE_SKILL_DIR}/references/execution-flow.md/differential-cve.md— Phase 5 default scan + CVE diff