moai-ref-supply-chain

# Software Supply-Chain Defensive Security Reference

Defensive practitioner reference for hardening a software supply chain — the chain
from source, through build, to the artifact a consumer installs. Every section is
framed as defense, hardening, detection, or verification: it describes the weakness,
how to detect it, and how to prevent it, never how to exploit it. AI/LLM-specific
supply-chain concerns (model and training-data provenance) live in
`moai-ref-llm-security`; web-application vulnerabilities live in
`moai-ref-owasp-checklist`.

## Target Use

Apply when building, releasing, or consuming software components. The threat model
is an untrusted supply chain: any dependency you pull, any build step you run, and
any artifact you ship may have been substituted, tampered with, or impersonated.
The defenses below establish provenance (where did this come from?), integrity
(has it been altered?), and hygiene (is this the component I meant to use?).

## The Supply-Chain Trust Boundaries

The core defensive insight: each hand-off in the chain is a boundary where a
component can be substituted or tampered. Establish provenance and verify integrity
at every hand-off.

| Boundary | Substitution / tamper risk | Primary defense |
|----------|----------------------------|-----------------|
| Source resolution (name → package) | Dependency confusion, typosquatting | Namespace scoping, install-time verification, name allowlist |
| Dependency download | Compromised registry, MITM | Lockfile pinning by hash, signature verification |
| Transitive closure | Vulnerable or malicious deep dependency | Transitive audit, depth limits, SBOM diff |
| Build | Tampered build, injected step | SLSA provenance, isolated/ephemeral builders |
| Artifact publish | Substituted artifact | Sigstore signing, provenance attestation |
| Consumer install | Unverified artifact accepted | Signature + provenance verification at install/admission |

## SBOM — Generation and Verification

A Software Bill of Materials (SBOM) is the inventory of components in an artifact.
It is the foundation for every downstream defense: you cannot audit, scan, or verify
what you have not inventoried.

### Format selection

The two open SBOM formats are interoperable; pick by ecosystem fit and consumer needs.

| Format | Steward | Strength |
|--------|---------|----------|
| SPDX | Linux Foundation (ISO/IEC 5962 standard) | License-centric; broad regulatory and legal acceptance |
| CycloneDX | OWASP | Security-centric; native vulnerability and dependency-relationship modeling |

### Minimum-element baseline

A useful SBOM carries at least the NTIA minimum elements: the supplier, the
component name, the version, unique identifiers, the dependency relationships, the
author of the SBOM data, and a timestamp. An SBOM missing dependency relationships
is an inventory, not a graph — it cannot answer "what pulls in this vulnerable
component?".

### Generation and verification practice

The standard SBOM-generation tool (syft is the de-facto cross-ecosystem standard
that emits both SPDX and CycloneDX) inspects an artifact or source tree and produces
the component inventory. Generate the SBOM **as part of the build**, not after — an
SBOM generated later cannot see build-time-only dependencies. Verify an SBOM by
re-generating it from the artifact and diffing: a drift between the shipped SBOM and
the re-generated one signals tampering or an incomplete original.

- **Generate at build time** so the SBOM reflects the exact resolved closure.
- **Attach the SBOM as a signed attestation** (see Sigstore below) so a consumer can
  trust the inventory, not just read it.
- **Diff SBOMs across releases** to surface a newly-introduced or version-bumped
  dependency before it ships.

## Dependency-Confusion Defense

Dependency confusion (public disclosure, 2021) is when a resolver pulls a public
package that shadows an intended private/internal package of the same name, because
the resolver preferred the public registry. The defense is to make the resolver
prefer — or exclusively use — the trusted source for internal names. This section is
purely defensive: it describes how to prevent the substitution, not how to perform it.

| Control | Defensive rationale |
|---------|---------------------|
| Namespace / scope reservation | Reserve the organization's package namespace on the public registry so an internal name cannot be claimed externally |
| Source pinning per name | Configure the resolver to fetch internal names ONLY from the internal registry; never let an internal name fall through to a public registry |
| Install-time hash verification | Pin every dependency to a content hash in the lockfile so a same-name substitution with different content is rejected |
| Registry routing controls | Use a registry proxy that routes internal-namespace requests to the internal source and refuses public fallback for those names |

Lockfile hash-pinning is the cross-cutting control here: package managers across
ecosystems each record a content hash for every resolved dependency — `pip` writes
hashes in a requirements lockfile, `npm` records integrity hashes in its lockfile,
and `cargo` records checksums in its lockfile — and verify that hash on install, so
a same-name substitution with different bytes fails the check regardless of which
registry served it.

## Malicious-Package Triage Playbook

When a dependency is suspect — flagged by a feed, an advisory, or a reviewer — triage
it before it enters (or to decide whether to evict it). The playbook is detection and
response, never an analysis of how to author a malicious package.

### Triage signals (detection)

| Signal | What it indicates |
|--------|-------------------|
| Name near-match to a popular package | Possible typosquat (see Typosquatting Defense) |
| Recent maintainer change or new publisher | Possible account takeover or hand-off to a bad actor |
| Install/post-install script presence | Code runs at install time — a