supply-chain-advisory

---

name: supply-chain-advisory description: Audits dependency supply chains for bad versions, lockfile drift, and artifact integrity. Use when adding deps, handling incidents, or releasing a plugin. alwaysApply: false category: infrastructure tags:

• security
• supply-chain
• dependencies
• vulnerability
• pypi dependencies:
• error-patterns provides: infrastructure:
  • supply-chain-scanning
  • dependency-auditing
  • incident-response patterns:
  • known-bad-detection
  • lockfile-audit
  • artifact-scanning usage_patterns:
• dependency-security-check
• incident-response
• supply-chain-audit complexity: intermediate model_hint: standard estimated_tokens: 500 progressive_loading: true modules:
• modules/scanning-patterns.md
• modules/incident-response.md role: hook-target

---

Overview

Supply chain attacks bypass traditional code review by compromising upstream dependencies. This skill provides patterns for detecting, preventing, and responding to compromised packages in Python ecosystems.

When To Use

• After a supply chain advisory is published
• When auditing dependencies for a new or existing project
• During incident response for a suspected compromise
• When adding the SessionStart hook to a project

When NOT To Use

• General CVE triage unrelated to dependency supply chain
• Application-level vulnerability scanning (use a SAST tool)
• License compliance audits (different concern)

Known-Bad Versions Blocklist

The blocklist is at ${CLAUDE_SKILL_DIR}/known-bad-versions.json. It is consumed by:

1. SessionStart hook: warns per-session when compromised versions detected
2. make supply-chain-scan: CI/local scanning target
3. This skill: manual audit guidance

Blocklist Format

{
  "package_name": [{
    "versions": ["x.y.z"],
    "date": "YYYY-MM-DD",
    "description": "What the attack did",
    "indicators": ["files or patterns to search for"],
    "source": "advisory URL",
    "severity": "critical|high|medium"
  }]
}

Adding a New Entry

1. Add the entry to ${CLAUDE_SKILL_DIR}/known-bad-versions.json
2. Add version exclusions (!=x.y.z) to affected pyproject.toml files
3. Document in docs/dependency-audit.md under Supply Chain Incidents
4. Run make supply-chain-scan to verify detection works

Quick Scan Commands

Check all lockfiles on machine for known-bad versions

# Scan uv.lock files for a specific compromised version
grep -r "package_name.*version" --include="uv.lock" /path/to/projects

# Search for malicious artifacts
find /path/to/projects -name "suspicious_file.pth" 2>/dev/null

# Check installed versions in virtualenvs
find /path/to/projects -path "*/.venv/lib/*/PACKAGE*/METADATA" \
  -exec grep "^Version:" {} +

Verify lockfile hash integrity

uv.lock includes SHA256 hashes for every package. If a package is re-published with different content under the same version, uv sync will fail with a hash mismatch. This is your strongest automatic defense.

Defense Layers

Layer	Tool	Catches
Lockfile hashes	uv.lock SHA256	Tampered re-published versions
Version exclusions	pyproject.toml !=	Known-bad versions on fresh resolve
SessionStart hook	sanctum hook	Per-session warning for compromised deps
CI scanning	OSV, Safety	CVE database, and advisory matching
Artifact scanning	make supply-chain-scan	Malicious files (.pth, scripts)

Limitations

• Zero-day supply chain attacks have no prior advisory: lockfile hashes are the only automatic defense during the attack window
• Safety/CVE databases lag behind real-world compromises
• OSV provides broader coverage but is still reactive

Exit Criteria

• ${CLAUDE_SKILL_DIR}/known-bad-versions.json checked against all lockfiles in scope; any match reported with package name, bad version, severity, and advisory URL
• When a new known-bad entry is added: version exclusion (!=x.y.z) added to the affected pyproject.toml, entry documented in docs/dependency-audit.md, and make supply-chain-scan run to confirm detection works
• uv.lock SHA256 hash integrity verified; uv sync failure on hash mismatch surfaces as an explicit supply-chain warning rather than a generic install error
• Artifact scan checks for malicious file patterns (.pth files, unexpected scripts) in virtualenv paths before the session proceeds