supply-chain-trust

What this skill does

# supply-chain-trust

Decision aid for verifying that the code you ship is the code you think you're shipping. Use when designing or reviewing systems whose threat model includes supply-chain compromise (build host, dependency mirror, package registry, firmware) — which is most production systems in 2026.

The skill is distinct from `sdlc-complete`'s SBOM and CVE-scanning capabilities. SBOM tells you **what is there**. CVE scanning tells you **what is known-broken**. This skill answers **"can I prove that what I shipped is what I expected, end-to-end"** — which neither of the others does.

## Triggers

- "reproducible build"
- "snapshot pinning" / "snapshot.debian.org"
- "vendor wheels" / "hash-locked deps"
- "firmware version" / "firmware pinning"
- "in-toto" / "SLSA"
- "transparency log" / "Sigstore"
- "build host compromise"
- "supply chain attack"

## When NOT to use this skill

- Pure CVE scanning of declared dependencies (use `sdlc-complete/skills/security-audit`)
- SBOM generation (use existing SBOM tooling — CycloneDX, SPDX)
- License compliance (out of scope; use a license scanner)

---

## Section 1: The four layers of supply-chain trust

```
Layer 4: Hardware / firmware
            ↑ (does the chip do what it says?)
Layer 3: Build environment
            ↑ (was the binary produced from the source we think?)
Layer 2: Source dependencies
            ↑ (did we get the source we expected?)
Layer 1: Source we wrote
            ↑ (we can audit this)
```

Each layer has its own attack surface and its own mitigations:

| Layer | Attack | Mitigation |
|---|---|---|
| 1 (own source) | malicious commit by insider | code review, signed commits, branch protection |
| 2 (deps) | typosquat, compromised maintainer, malicious update | pinning + hash-lock + vendoring; transparency logs |
| 3 (build) | compromised CI, build host malware | reproducible builds, signed-and-attested artifacts (in-toto, SLSA) |
| 4 (hardware) | malicious firmware, supply-chain implant | measured boot, vendor diversity, audit |

A system is only as trustworthy as the weakest layer in the chain it actually depends on.

---

## Section 2: Dependency pinning — beyond `requirements.txt`

### Suggested default: full hash-locked dependency manifests

For each language ecosystem:

| Ecosystem | Default tool | What it produces |
|---|---|---|
| Python | `pip-tools` (`pip-compile --generate-hashes`) → `requirements.txt` with hashes | `package==1.2.3 --hash=sha256:abc...` per dep, including transitive |
| Node | `npm ci` against `package-lock.json` (with `integrity` field), or `pnpm` | per-package SHA-512 integrity |
| Rust | `cargo` lock file (`Cargo.lock`) — versions only; for hashes use `cargo vet` |
| Go | `go.mod` + `go.sum` (per-module SHA-256) |
| Ruby | `Bundler` lockfile + `bundle config set --local frozen true` |
| Maven/Gradle | `dependency:resolve-plugin` with checksum verification |

**Required**: every dependency, including transitive, must have a hash in your lockfile. If a tool can't produce hashed locks, vendor the dep.

### Vendoring critical-path deps

For dependencies in security-sensitive paths (auth, crypto, key handling), go further than hash-locking — **vendor** them:

```
your-repo/
  vendor/
    python-fido2-1.1.3/        # checked-in source of the dep
    cryptography-41.0.7/        # ditto
    ...
  Cargo.toml or pyproject.toml  # references vendor/ paths, not registry
```

Why vendoring on top of hash-locking:

- Hash-locking verifies you got the bytes you expected; vendoring lets you AUDIT those bytes
- A compromised registry could publish a new "version" with a malicious patch; you control what's in `vendor/`
- Reduces transitive surface — you can prune deps that you don't actually use

Cost: you own update cadence. Acceptable for security-critical paths; impractical for everything.

### Anti-pattern: SHA-verified `.deb` whose SHA came from poisoned `apt` repo (review M10)

Original: bootstrap verifies SHA-256 of each downloaded `.deb`, but the SHA-256 manifest itself comes from `apt-cache` against the build-time `apt` repo.

What this skill flags: the verification is **circular within the same trust domain**. If `apt` is compromised, the manifest is compromised, the SHAs are compromised, all three layers verify a poisoned package.

Remediation:

- **Pin to `snapshot.debian.org`** URLs with a specific timestamp (`http://snapshot.debian.org/archive/debian/20260301T000000Z/`) — content-addressed, immutable
- **Verify signed Debian `Release` file** with explicit Debian archive signing keys, ground-truth at the timestamp
- **Pin transitive `.deb` URLs** discovered at that timestamp; commit the resulting SHA manifest to your **signed** git repo

The hash of the package must come from a **separately-trusted channel** than the package itself.

---

## Section 3: Reproducible builds

### What it gives you

A reproducible build means: given the same source, the same build environment, and the same build inputs, **any builder produces a byte-for-byte identical output**. This lets you:

- Verify a third-party-built binary against your own rebuild
- Detect compromised CI by comparing CI output to your local rebuild
- Allow others to verify your published artifacts by rebuilding from source

### Suggested defaults

| Use case | Approach |
|---|---|
| Bootstrap installers | NixOS — reproducible by construction; the entire system specification is hash-tracked |
| Container images | Bazel + `rules_oci` OR Nix-built OCI images; pinned base layer with verified digest |
| Linux distro packaging | Reproducible Builds project tooling (`reproducible-builds.org`); `dpkg --reproducible` flag in Debian |
| Cross-platform binaries | Static linking, hermetic build env (Bazel), check `diffoscope` between rebuilds |

### Verification step

```bash
# Local rebuild
bazel build //my:artifact
sha256sum bazel-bin/my/artifact

# Compare to CI-published
sha256sum downloaded/artifact.tar.gz

# If they differ, run diffoscope to see what diverges
diffoscope bazel-bin/my/artifact downloaded/artifact.tar.gz
```

Common reproducibility breakers: timestamps in archives, build-time UUIDs, parallel-build nondeterminism, locale-dependent string sorting. The `reproducible-builds.org` site catalogs known issues per ecosystem.

### When reproducibility isn't worth it

For internal tools with a single source-of-truth build host and signed output, the value is marginal. Reproducibility shines when:

- You publish artifacts users will run (binaries, container images)
- Your CI runs untrusted code (third-party PRs, etc.)
- Your build host might be compromised and you want a way to detect it

---

## Section 4: Build attestation (in-toto, SLSA)

### Suggested default: SLSA Level 3+ attestation for production releases

SLSA (Supply-chain Levels for Software Artifacts) defines compliance levels:

| Level | What it requires | What it tells consumers |
|---|---|---|
| 0 | nothing | "this came from somewhere" |
| 1 | build process documented | "the build is repeatable in principle" |
| 2 | build runs on hosted CI; provenance generated | "we know which CI built it" |
| 3 | build is hermetic, isolated; provenance is signed and tamper-evident | "we can prove the build chain end-to-end" |
| 4 | additional constraints — two-person review, hermetic builds | "highest assurance" |

**Tooling:**

- `cosign` (Sigstore) — signs container images and arbitrary blobs; integrates with Rekor transparency log
- `slsa-github-generator` — produces SLSA L3 provenance from GitHub Actions
- `in-toto` (CMU) — generic supply-chain attestation framework
- `Tekton Chains` — Kubernetes-native build attestation

### Verification on consumer side

```bash
cosign verify --certificate-identity-regexp=...@my-org \
    --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
    ghcr.io/my-org/my-image:1.2.3
```

Pin **specific certificate identities and OIDC issuers**. A bare `cosign verify` can be satisfied by any signature.

---