uv-supply-chain-hardening

uv Supply-Chain Hardening

This skill converts a Python project from a loose pip install -r requirements.txt build into a locked, hash-verified, release-age-gated build using uv. It is the response to the wave of supply-chain attacks targeting Python (and especially crypto) projects, where a maintainer account is compromised and a malicious version is published to PyPI.

The defense has three layers:

1. Pin every dependency to an exact version — no floating ranges, so a build can't silently pull a newer (compromised) release.
2. Verify hashes — every PyPI distribution is checked against a SHA256 in the lockfile, so a tampered-with artifact on the registry is rejected.
3. Release-age gate — refuse any distribution published in the last N days, so a freshly-uploaded malicious version isn't pulled in before the community has a chance to catch and yank it.

When to Use This Skill

• You have a Python project (with requirements.txt and/or pyproject.toml) whose Docker build runs pip install against unpinned or loosely-pinned dependencies.
• You want reproducible, tamper-evident builds.
• You're worried about a dependency (or one of its transitive deps) being hijacked.
• You have private Git dependencies and need them to coexist with hash-locking.

What This Skill Changes

1. requirements.in (NEW) — human-edited source-of-truth list of direct deps.
2. requirements.txt (REWRITTEN) — machine-generated, fully-pinned, hashed lock.
3. pyproject.toml — adds [tool.uv] exclude-newer and pins the build backend (or a root uv.toml if the repo has no pyproject.toml).
4. Dockerfile — installs via a digest-pinned uv instead of pip; private-dep token stays a build-time ARG/secret (never baked into the image).
5. requirements-private.txt (NEW, optional) — first-party libs installed at HEAD when the user wants their own libraries to always track latest (Step 5b).

Nothing about the application code changes — this is purely the dependency pipeline.

---

Step 0: Establish the Baseline

IMPORTANT — pin to what is installed, not to "latest". The whole point is reproducing the environment you've actually been running and testing against. If you just run uv pip compile with no constraints, it resolves to the newest versions allowed, which can jump you across several releases you never tested (and, worse, is exactly the surface a supply-chain attack rides in on).

First, confirm uv is available and capture the currently-installed versions:

# Inside the project's activated virtualenv
uv --version || pip install uv            # or: brew install uv / pipx install uv
pip freeze > /tmp/installed-constraints.txt

/tmp/installed-constraints.txt is the constraint set that anchors the compile to exactly what you have installed today.

Ask the user:

1. "How many days should the release-age gate be?"

   • Default: 7 days. Long enough that most malicious releases get caught and yanked; short enough you still get timely security patches.

2. "Do you have private Git dependencies?" (yes/no)

   • If yes, note the token env var name (commonly CR_PAT for a GitHub PAT).

3. "Before we freeze, are there any of your own libraries you want to update first?"

   • Pinning captures a moment in time. If the user maintains internal libs with pending fixes, pull those in and re-pip install before freezing, so the lock captures the intended versions.

4. "Should your own private libraries be pinned, or always track latest?"

   • A common, legitimate stance: pin the third-party attack surface, but let your first-party libs (the ones requiring a token) float to the latest commit on every build — you review your own code and want fixes without a manual SHA bump. If they choose this, those libs do not get pinned in the lock; they go in a separate requirements-private.txt installed at HEAD. See Step 5b — it changes Steps 1, 2, and 4.

5. "What Python version does the container run?"

   • You must compile the lock for the container's Python (--python-version), not your laptop's. A local 3.14 venv resolving for a 3.13 image picks different wheels/markers. Read it off the FROM python:X.Y line.

---

Step 1: Create requirements.in (source of truth)

requirements.in lists only your direct dependencies — the things you actually import — with no version pins (the lock supplies those). This is the file a human edits; requirements.txt is never hand-edited again.

# requirements.in — direct dependencies only. Edit this, then recompile
# requirements.txt with:
#   uv pip compile requirements.in --generate-hashes -o requirements.txt
#
# Pins and hashes for the full transitive tree live in requirements.txt.

example-http-client
example-db-driver
some-public-lib

# Private Git dependency — pinned to an immutable commit SHA, not a branch.
# The commit SHA is the integrity anchor (a branch can be force-pushed; a SHA
# can't). ${TOKEN_ENV} is expanded from the build environment at install time;
# never commit a literal token here.
internal-lib @ git+https://${CR_PAT}@github.com/your-org/internal-lib.git@<commit-sha>

CRITICAL replacements:

• Direct dependency names → the user's actual top-level imports (mine these from the existing pyproject.toml dependencies and/or the un-hashed requirements.txt).
• internal-lib @ git+...@<commit-sha> → each private dep, pinned by full commit SHA. If it's currently pinned to a branch or unpinned, resolve the current commit (git ls-remote https://github.com/your-org/internal-lib.git <branch>) and pin it.
• ${CR_PAT} → the user's token env var name.

Why a commit SHA for Git deps: Git distributions cannot carry a PyPI-style hash in the lock (see Step 5). The commit SHA is the hash — it's the only thing anchoring the integrity of a Git dependency, so it is non-negotiable for these.

⚠️ Token-baking via a library's OWN pyproject.toml (the subtle leak — check this every time). Distinct from the Dockerfile ENV leak in Step 4/6. If one of your private libraries declares its own dependencies as git+https://{env:CR_PAT}@github.com/... (the hatch {env:...} context form), hatchling expands the token at build time into the wheel's Requires-Dist metadata — so a live PAT gets frozen into every image built from that lib, even with a flawless Dockerfile. ${VAR} in a requirements file is fine (that file is never packaged); {env:VAR} inside a package's [project.dependencies] is not. Fix the library: declare its deps with token-free URLs (git+https://github.com/...) and let git insteadOf supply auth at install — this stays compatible with unpinned/always-latest deps. Then rotate the PAT, since older built images still carry it. Scan for it in Step 6.

---

Step 2: Compile the Locked, Hashed requirements.txt

Compile from requirements.in, constrained to the installed versions, with hashes:

# A raw `pip freeze` includes VCS/editable lines (`pkg @ git+...`, `-e ...`,
# `pkg @ file://...`) that uv rejects as constraints — keep only `name==version`:
grep -E '^[A-Za-z0-9._-]+==[0-9]' /tmp/installed-constraints.txt > /tmp/constraints.txt

uv pip compile requirements.in \
  --generate-hashes \
  --python-version 3.13 \
  -c /tmp/constraints.txt \
  -o requirements.txt

• --generate-hashes → writes a SHA256 (often several, one per wheel/sdist) for every PyPI distribution. This is what makes registry tampering detectable.
• --python-version <X.Y> → resolve for the Python the container runs, not your laptop's. Compiling under a different interpreter (local 3.14, image 3.13) can select different wheels/markers. Match the FROM python:X.Y in the Dockerfile.
• -c /tmp/constraints.txt → pins to the versions you already have installed rather than resolving to latest. This is the step people forget; without it the lock can leap forward across untested releases.
• The output is the full transitive tree, every package pinned to == with hashes.

Verify the pin matched the baseline. Diff the new pins against what you had:

# Sanity check: the compiled versions should match installed ones (modulo
# package-name normalization like Flask -> flask, PyYAML -> pyyaml).
diff <(grep -oE '^[a-zA-Z0-9_.-]+==[0-9][^ ]*' requirements.txt | sort) \
     <(sort /tmp/installed-constraints.txt)

Expected differences are only name-case/separator normalization. If a version actually moved, investigate before accepting it — that's the exact thing this process exists to make visible.

uv preserves existing pins on recompile. Once requirements.txt exists, a later uv pip compile keeps the current pins unless you pass --upgrade (or --upgrade-package NAME). So routine recompiles (e.g. after adding one new dep to requirements.in) won't silently bump everything else — only deliberate upgrades do. Document this in the file header so the next editor knows the lock is sticky.

---

Step 3: Add the Release-Age Gate + Pin the Build Backend (pyproject.toml)

Two additions to pyproject.toml.

(a) The release-age gate under [tool.uv]:

[tool.uv]
# Supply-chain defense: refuse any distribution published in the last 7 days when
# resolving/locking, so a freshly-uploaded (possibly compromised) version can't be
# pulled in before the community catches and yanks it. Applies to BOTH
# `uv pip compile` and `uv pip install`. This is a rolling window evaluated at
# run time — not a fixed date — so it keeps protecting future installs.
exclude-newer = "7 days"

• exclude-newer accepts a friendly duration ("7 days") or an ISO-8601 timestamp. Prefer the duration: it's a rolling gate that keeps working on every future build, whereas a fixed timestamp goes stale.
• Replace 7 days with the answer from Step 0.

No pyproject.toml? (a Flask/service repo, not a package.) Put the setting in a uv.toml at the repo root instead — uv reads it for both compile and install. In uv.toml the keys are top-level (no [tool.uv] table):

# uv.toml
exclude-newer = "7 days"

And skip part (b) below — a repo that never builds a wheel has no build backend to pin.

(b) Pin the build backend under [build-system] — otherwise the backend itself (e.g. hatchling/setuptools) is an unpinned dependency resolved at wheel-build time, and is just as hijackable as any other:

[build-system]
# Pinned (not floating) so the build backend can't be swapped for a newer,
# potentially compromised release at build time. exclude-newer keeps it >=7 days
# old; bump deliberately when upgrading.
requires = ["hatchling==1.29.0"]
build-backend = "hatchling.build"

CRITICAL: use the backend the project already uses, pinned to its installed version (pip show hatchling / pip show setuptools). Don't switch backends.

---

Step 4: Convert the Dockerfile from pip to uv

Replace the pip install flow with a uv install. Three things matter here, each of which closes a real hole.

FROM python:3.13-alpine

# 1) Bring in the uv binary, PINNED BY IMMUTABLE DIGEST — not just the version tag.
# A version tag can be re-pushed to point at a different (malicious) binary; the
# @sha256 digest cannot. This binary installs everything else, so it must be the
# most trusted thing in the build. To upgrade uv, bump BOTH the tag and the digest.
COPY --from=ghcr.io/astral-sh/uv:0.9.28@sha256:<digest> /uv /uvx /bin/

# 2) Private-dep token as a BUILD ARG ONLY. It is available to the RUN steps below
# for cloning private Git deps, but is deliberately NOT promoted to ENV — promoting
# it bakes a live credential into the final image's environment (visible via
# `docker inspect`). ARG alone is enough for ${CR_PAT} expansion in RUN steps.
ARG CR_PAT

RUN apk add --no-cache git gcc musl-dev postgresql-dev   # build deps as needed

WORKDIR /app
COPY requirements.txt pyproject.toml README.md ./
COPY src/ ./src/                                          # your package sources

# 3) Install the locked, hash-verified dependencies. uv verifies every hash present
# in requirements.txt; ${CR_PAT} is expanded from the build ARG for private Git deps.
RUN uv pip install --system -r /app/requirements.txt

# Install the application package itself for its entry points. --no-deps because
# every dependency is already pinned and installed from the lock above.
RUN uv pip install --system --no-deps .

# ... non-root user, ENV, EXPOSE, ENTRYPOINT as before ...

CRITICAL points:

• --system installs into the image's Python (there's no venv inside the container), matching how pip install behaved before.
• Get the current uv digest so you can fill in <digest>:

  docker pull ghcr.io/astral-sh/uv:0.9.28
  docker inspect --format='{{index .RepoDigests 0}}' ghcr.io/astral-sh/uv:0.9.28
  

  Pin the version tag to whatever uv version you standardized on, then pin its digest.
• Remove any ENV CR_PAT=${CR_PAT} line if one existed. This is the single most important fix: the ENV form leaks the token into the published image. See the verification step below.
• If the project has no private deps, drop the ARG CR_PAT line and git from the apk install.
• Prefer a BuildKit secret over ARG when the build supports it. ARG CR_PAT passed via --build-arg is recorded in docker history and can surface in build logs; a secret mount never touches a layer at all:

  RUN --mount=type=secret,id=cr_pat \
      export CR_PAT=$(cat /run/secrets/cr_pat) \
      && git config --global url."https://${CR_PAT}@github.com/".insteadOf "https://github.com/" \
      && uv pip install --system -r requirements.txt \
      && git config --global --unset url."https://${CR_PAT}@github.com/".insteadOf
  

  Build with docker build --secret id=cr_pat,env=CR_PAT .... The insteadOf rewrite means your requirements/lock can use token-free https://github.com/ URLs — no credential in any committed file. If an existing build-publish.sh already passes --secret, keep that interface (don't regress it to ARG).

---

Step 5: The --require-hashes / Git-dependency Tradeoff

You may consider adding --require-hashes to the install for maximum strictness. Be aware of the catch and decide consciously:

• PyPI deps all carry hashes in the lock, so they're verified regardless.
• Git dependencies cannot be hashed — there's no immutable artifact hash for a git+https://... source, only the commit SHA (which you already pinned in Step 1).
• --require-hashes is all-or-nothing: it rejects the entire requirements file if any single line lacks a hash. So you can't use it unless you split the install into two steps — hashed PyPI deps in one file, unhashable Git deps in another.

Recommendation: unless the user wants the split, omit --require-hashes. uv still verifies every hash that is present (all the PyPI deps), so registry tampering is already caught; --require-hashes would only additionally block a future unhashed line from sneaking in. Note this as an accepted tradeoff rather than silently skipping it.

If the user does want it, split:

RUN uv pip install --system --require-hashes -r /app/requirements-pypi.txt
RUN uv pip install --system -r /app/requirements-git.txt

---

Step 5b: First-Party Libraries That Should Track Latest (the --override split)

Use this only if the user chose "always track latest" for their own libs in Step 0. The default model pins everything; this variant pins the third-party attack surface but lets first-party libs float to the latest commit on every build.

Why a plain compile won't do it — two uv behaviors collide:

1. uv resolves the entire graph; pip deduped by name. pip tolerated your private libs declaring each other with {env:CR_PAT}/unpinned URLs because the top-level requirement already "satisfied" them. uv actually fetches each transitive git URL from a library's metadata — and if it uses {env:CR_PAT} (uv can't expand it) or floats to HEAD (conflicting with a top-level pin), the compile fails with an auth or URL-conflict error.
2. uv pins a git dep to its resolved HEAD commit in the output even when the input had no SHA — so a single lock would freeze your first-party libs to compile-time HEAD, defeating "always latest."

The split that solves both:

requirements-private.txt — first-party libs, token-free and unpinned. Used twice: as the --override for the compile and as the install list in Docker.

internal-core @ git+https://github.com/your-org/internal-core.git
internal-models @ git+https://github.com/your-org/internal-models.git

requirements.in — third-party direct deps plus the private libs (token-free), so the compile discovers and locks their third-party sub-tree. The private lines are stripped from the output afterward.

Compile (token injected only into git's process config, never a committed file):

export GIT_CONFIG_COUNT=1 \
  GIT_CONFIG_KEY_0="url.https://${CR_PAT}@github.com/.insteadOf" \
  GIT_CONFIG_VALUE_0="https://github.com/"
uv pip compile requirements.in \
  --override requirements-private.txt \
  --generate-hashes --python-version 3.13 \
  -c /tmp/constraints.txt \
  -o requirements.full.txt
# Strip the first-party git lines → requirements.txt holds only the locked, hashed
# third-party tree (their PyPI sub-deps stay; the private libs themselves do not).
grep -vE '^(internal-core|internal-models) @ git\+' requirements.full.txt > requirements.txt
rm requirements.full.txt

• --override requirements-private.txt forces uv to resolve those packages from your token-free URLs instead of the {env:CR_PAT}@HEAD ones in their metadata.
• Note any transitive public git deps that remain in the lock (e.g. a logging lib pulled from GitHub) — they're unhashable, which is why --require-hashes needs the Step 5 split. Leave them in requirements.txt so the --no-deps install below can satisfy them.

Dockerfile — two installs:

RUN uv pip install --system -r requirements.txt                                # pinned + hashed third-party
RUN uv pip install --system --no-config --no-deps -r requirements-private.txt  # first-party at HEAD

• --no-deps because every sub-dep is already installed + locked by step 1.
• --no-config so exclude-newer (uv.toml) can't reject a first-party commit pushed within the gate window — you want the newest first-party commit. Without it, a lib commit younger than the gate fails the build.

⚠️ The cache trap (bites every rebuild). A RUN uv pip install ... requirements-private.txt layer is cached on the command string + the file's contents — neither changes when the upstream branch moves, so Docker silently reuses the old commit and "always latest" quietly becomes "whatever was latest the first time." To actually pull the newest first-party code you must docker build --no-cache (or bust the cache above that layer, e.g. an ARG GIT_REV passed each build). This is also why, right after merging a fix to a first-party lib, the next publish must be --no-cache.

---

Step 6: Verify the Build — and That the Token Did Not Leak

Do a clean, no-cache build to prove the locked install works end to end:

# Load the token into the build environment (private deps only)
export CR_PAT=...        # or: set -a; source .env; set +a

./build-publish.sh --no-cache      # or: docker build --no-cache --build-arg CR_PAT=$CR_PAT -t app:test .

Then prove the token is not baked into the image — this is the regression that the ARG-not-ENV change prevents, and it's worth confirming every time:

# Should print NOTHING. If it prints CR_PAT=..., the token leaked into the image.
docker inspect app:test --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -i CR_PAT

# Belt-and-suspenders: scan the whole image filesystem history for the token value.
docker history --no-trunc app:test | grep -i cr_pat || echo "clean"

# CRITICAL: scan installed package METADATA for a baked token. This catches the
# {env:CR_PAT} library-metadata leak (Step 1 callout) that the ENV and history
# checks above completely miss — the token lives in a .dist-info/METADATA file,
# not the image config. Should print nothing.
docker run --rm --entrypoint sh app:test -c \
  'grep -rl "ghp_\|github_pat_" /usr/local/lib/python*/site-packages/*.dist-info/METADATA 2>/dev/null' \
  || echo "no token in metadata"

Verify the published image, not just the local build. After build-publish.sh pushes, docker rmi the tag, docker pull it fresh, and re-run the scans above against the pulled image. A warm build/layer cache can mask a stale or token-bearing layer that only the registry copy reveals.

If a token was ever exposed (printed to a terminal, or baked into a previously published image via the old ENV line), fixing the Dockerfile only stops future images from carrying it. Images already pushed still contain it, and a leaked token stays valid until rotated. Flag this to the user and recommend rotating the token; let them decide.

---

Gotchas Worth Remembering

These are the non-obvious things that cost time the first time through:

1. Compile without constraints jumps to latest. Always pass -c <pip-freeze-output> on the first compile, or you'll lock to versions you never tested. (Step 2.)
2. uv keeps existing pins on recompile. Adding one dep to requirements.in and recompiling won't bump the rest — only --upgrade does. This is a feature; rely on it. (Step 2.)
3. exclude-newer is rolling and applies to install too, not just compile. A uv pip install inside Docker is also gated, so a base-image rebuild won't pull a day-old package either. (Step 3.)
4. The build backend is a dependency too. Pinning app deps but leaving requires = ["hatchling"] floating leaves a hole at wheel-build time. (Step 3.)
5. ARG is enough; ENV leaks. ${CR_PAT} expands in RUN from an ARG alone. The ENV form additionally persists the value into the image. (Step 4/6.)
6. Git deps are unhashable — the commit SHA is their integrity anchor, which is why Step 1 insists on pinning them by SHA, and why --require-hashes needs a split. (Step 1/5.)
7. Pin the uv binary by digest, not just tag — it's the root of trust for the whole install. (Step 4.)
8. {env:CR_PAT} in a library's own pyproject bakes the PAT into its wheel metadata. hatchling expands it at build time into Requires-Dist, so the token ships in every image — invisible to env/history checks. Scan *.dist-info/METADATA, fix the lib to token-free URLs, rotate the PAT. (Step 1/6.)
9. uv resolves the whole graph; pip dedups by name. A private lib that declares its own {env:CR_PAT}/unpinned deps will fail or conflict the compile. Use --override to force those packages to your chosen source. (Step 5b.)
10. uv pins git deps to a resolved commit even from a no-SHA input. A single lock therefore freezes first-party libs to compile-time HEAD — split them out and install --no-deps at HEAD if you want always-latest. (Step 5b.)
11. Docker caches HEAD git installs. The requirements-private.txt install layer reuses the old commit until you --no-cache (or cache-bust). "Always latest" silently rots otherwise — and a just-merged lib fix won't ship without it. (Step 5b.)
12. Compile for the container's Python, not your laptop's. --python-version X.Y matching FROM python:X.Y, or you lock the wrong wheels/markers. (Step 0/2.)
13. A raw pip freeze breaks -c. Strip VCS/editable/file:// lines (keep only name==version) before using it as a constraints file. (Step 2.)
14. exclude-newer gates installs too — including first-party HEAD. A first-party commit younger than the gate fails the build; run that install with --no-config. (Step 5b.)

---

Design Principles

1. Reproduce what you tested — pin to installed versions, not to latest.
2. Make tampering detectable — hashes on every PyPI artifact.
3. Buy time against fresh malware — a rolling release-age gate.
4. Pin the whole chain — app deps, the build backend, the uv binary, and (via commit SHA) Git deps. A single floating link defeats the rest.
5. Keep credentials out of artifacts — build-time ARG, never image ENV; verify with docker inspect.
6. Decide tradeoffs out loud — e.g. skipping --require-hashes is fine, but say so and say why, rather than leaving it silently unaddressed.

Composes With

• flask-docker-deployment / mcp-docker-deployment — run this after the Docker build exists to harden its dependency install (replaces the pip flow).
• python-lib-setup — when your internal libraries are the Git deps being pinned by commit SHA here.