Python Supply Chain Security Cheat Sheet

Check Without Running Python

• Never run pip show, uv pip, uv sync, or uv run in a suspect environment. Any Python start can rerun the payload.
• No output doesn’t prove the machine was never infected.
• Compare Docker’s INDEX digests with the bad ones in the issue. Self-built images show <none>.
• A cook.pth hit is a lead, so compare its hash with the issue’s. docker export skips volumes.

$ sudo find / \( -name cook.pth \
    -o -name 'litellm-1.107.0.dist-info' \
    \) 2>/dev/null

$ cid=$(docker create <image> true)
$ docker export "$cid" | tar -t \
  | grep -E \
  '(^|/)(cook\.pth|cook\.py|sitecustomize\.py)$'
$ docker rm "$cid"

Not sure how a hook slipped in?

Quiz me on spotting infected environments

Scan Startup Hooks

• Python runs .pth lines that start with import during site initialization.
• -S skips the site module, and -I ignores PYTHON* variables.
• They don’t make a compromised Python safe. Scan a suspect folder with a TRUSTED Python from a clean machine.
• Use .venv/bin/python only for the fresh demo.

$ .venv/bin/python -I -S pthscan.py \
    .venv/lib/python3.14/site-packages

"""List startup hooks in a site-packages
folder without running them."""

import sys
from pathlib import Path

if len(sys.argv) != 2 or not Path(
    sys.argv[1]
).is_dir():
    sys.exit(
        "Usage: python -I -S pthscan.py "
        "<site-packages folder>"
    )

folder = Path(sys.argv[1])

for pth in sorted(folder.glob("*.pth")):
    text = pth.read_text(
        encoding="utf-8-sig",
        errors="replace",
    )
    for num, line in enumerate(
        text.splitlines(), start=1
    ):
        if line.startswith(
            ("import ", "import\t")
        ):
            print(
                f"{pth.name}:{num}: "
                f"{line[:60]}"
            )

for name in ("sitecustomize.py",
             "usercustomize.py"):
    if (folder / name).exists():
        print(f"{name}: present")

$ find / -type d \
    \( -name site-packages \
    -o -name dist-packages \) \
    2>/dev/null

$ grep -lF <name> <venv>/lib/python3*/\
site-packages/*.dist-info/RECORD

Curious what runs when Python starts?

Show me how .pth files run code

If You Find Something

• Isolate the system and preserve evidence.
• Rotate every credential it could reach from a clean machine, then check for misuse.
• Rebuild from known-good images. Deleting hooks doesn’t prove the host is clean.
• Set tokens to an explicit short expiration.

$ gh auth status

Not sure what to do after a hit?

Walk me through a response plan

Dependency Cooldowns

• A cooldown skips releases younger than N days.
• It stops malicious releases, but it also delays fixes.
• Rebuilding with litellm==1.106.2 needs exclude-newer-package = { litellm = false }.

[tool.uv]
exclude-newer = "3 days"

[tool.uv]
exclude-newer = "3 days"
exclude-newer-package = { certifi = "1 day" }

[global]
uploaded-prior-to = P3D

Wondering how long a cooldown should be?

Help me pick a cooldown length

Lock With Hashes

• uv sync --locked fails if the lock is stale.
• PEP 751 pylock.toml works across tools.

$ uv lock
$ uv sync --locked

$ uv export --quiet \
    --format pylock.toml \
    --no-emit-project -o pylock.toml

Lock files still fuzzy?

Explain lock files another way

Audit Dependencies

• pip-audit --locked reads pylock.toml, not uv.lock.
• Audits identify known vulnerable versions, but you apply the fix.
• A clean audit doesn’t prove there’s no malware.

$ uv tool install \
    --exclude-newer "3 days" \
    pip-audit==2.10.1
$ pip-audit --locked .

Ready to test what you know about audits?

Quiz me on auditing dependencies

Guard Your AI Agent

• * is a wildcard, so other install forms such as uv pip install can slip past.
• Hooks add policy checks, not isolation.
• A default sandbox can still read credential files. Use a dedicated container or VM, with no secrets in its environment.

{
  "permissions": {
    "ask": ["Bash(uv add *)"]
  }
}

Want a safer agent setup?

Help me set up guardrails for my agent

Trusted Publishing

• Trusted Publishing swaps API tokens for 15-minute tokens.
• Whoever controls the workflow controls publishing.
• Bind the environment in both the workflow and the PyPI publisher.
• Require an independent reviewer, with no self-review and no admin bypass.

publish:
  environment: pypi
  permissions:
    id-token: write

Does your release pipeline hold up?

Walk me through gating my publish job

Ready for the next step?

Build me a supply chain learning plan

You can download this information as a printable cheat sheet:

Free Bonus: Python Supply Chain Security Cheat Sheet

Get a Python Supply Chain Security Cheat Sheet (PDF) and keep incident checks, cooldowns, lock and audit commands, and key rotation steps at hand:

Send My Python Supply Chain Security Cheat Sheet »