Supply Chain Advisory

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

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

Incident Response

Triage Checklist

When a supply chain compromise is reported:

1. Scope Assessment (5 minutes)

• [ ] Identify affected package name and versions
• [ ] Search all lockfiles on machine: rg "package.*version" --glob "uv.lock" ~ (or grep -r --include="uv.lock")
• [ ] Check installed versions: find ~ -path "*/.venv/*/METADATA" -exec rg Version {} + (or grep)
• [ ] Search for malicious artifacts: find ~ -name "indicator_file" 2>/dev/null

2. Containment (if affected)

• [ ] Stop any running processes using the affected package
• [ ] Do NOT delete the virtualenv yet (preserve for forensics)
• [ ] Disconnect from sensitive services if credential theft suspected
• [ ] Capture current environment: env > /tmp/env_snapshot_$(date +%s).txt

3. Remediation

• [ ] Add version exclusions to pyproject.toml: !=affected.version
• [ ] Remove malicious artifacts from virtualenvs
• [ ] Regenerate lockfile: uv lock
• [ ] Reinstall: uv sync
• [ ] Rotate ALL credentials that were accessible to the process

4. Credential Rotation Priority

If a credential-stealing payload was present, rotate in this order:

1. Cloud provider keys (AWS, GCP, Azure): highest blast radius 2. Database passwords: data exfiltration risk 3. SSH keys: lateral movement risk 4. API tokens: service access 5. Kubernetes tokens: cluster compromise 6. Environment variables: may contain any of the above

5. Documentation

• [ ] Add incident to docs/dependency-audit.md
• [ ] Update known-bad-versions.json blocklist
• [ ] File GitHub issue linking to advisory
• [ ] Notify team members who may have affected environments

Post-Incident Review

After containment, evaluate:

1. Why did existing tooling not catch this? 2. What detection layer would have caught it earliest? 3. Should scanning frequency be increased? 4. Are there similar packages in our dependency tree at risk?

Scanning Patterns

Lockfile Audit

For each lockfile type, extract package names and versions, then compare against the known-bad-versions blocklist.

uv.lock

import re
from pathlib import Path

def parse_uv_lock(path: Path) -> dict[str, str]:
    """Extract package->version mapping from uv.lock."""
    packages = {}
    content = path.read_text()
    for match in re.finditer(
        r'^name\s*=\s*"([^"]+)".*?^version\s*=\s*"([^"]+)"',
        content,
        re.MULTILINE | re.DOTALL,
    ):
        packages[match.group(1)] = match.group(2)
    return packages

requirements.txt

def parse_requirements(path: Path) -> dict[str, str]:
    """Extract package->version from pinned requirements."""
    packages = {}
    for line in path.read_text().splitlines():
        line = line.strip()
        if "==" in line and not line.startswith("#"):
            name, version = line.split("==", 1)
            packages[name.strip()] = version.strip()
    return packages

Artifact Scanning

Search for known malicious file indicators across a directory tree:

from pathlib import Path

def scan_for_artifacts(root: Path, indicators: list[str]) -> list[Path]:
    """Find known malicious artifacts in a directory tree."""
    found = []
    for indicator in indicators:
        found.extend(root.rglob(indicator))
    return found

Version Matching

def is_compromised(
    package: str,
    version: str,
    blocklist: dict,
) -> dict | None:
    """Check if a package version is in the known-bad blocklist."""
    entries = blocklist.get(package, [])
    for entry in entries:
        if version in entry["versions"]:
            return entry
    return None