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.

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.

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.

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)

Response procedure

1. Quarantine: pin the last-known-good version and block the suspect version in the resolver / proxy so no build pulls it.
2. Verify provenance: check whether the artifact has a signature and provenance attestation (Sigstore / SLSA below); an unverifiable artifact stays quarantined.
3. Inventory exposure: use the SBOM to find every build that already pulled the suspect version (this is what the SBOM dependency graph is for).
4. Report upstream: notify the package registry's security/advisory channel and, if internal, the internal security owner. Most registries provide a malware/abuse reporting channel.
5. Record: capture the triage verdict and the evidence so a future occurrence is faster to adjudicate.

SLSA Provenance Levels

SLSA (Supply-chain Levels for Software Artifacts) defines build-integrity levels. Provenance is signed metadata describing how an artifact was built; the level states how trustworthy that provenance is. The current Build track defines four levels (L0–L3); the level rises as the build becomes harder to tamper with. (Earlier SLSA versions numbered the levels L1–L4 — same idea, four graduated levels.)

Defensive practice: require a minimum level for what you consume. A release pipeline should refuse to deploy an artifact whose provenance is below the level the environment demands — production typically requires signed provenance (L2+) at minimum, and high-assurance environments require a hardened builder (L3).

Sigstore / cosign Signing and Verification

Sigstore is the de-facto cross-ecosystem standard for signing and verifying software artifacts. The standard Sigstore signing tool, cosign, signs artifacts and verifies signatures; it pairs with a certificate authority that issues short-lived identity-bound certificates and a transparency log that records every signature. This section frames Sigstore as the verification mechanism a consumer applies, never as a way to forge a signature.

Keyless signing model

Keyless signing removes the long-lived private key — the most-stolen secret in a signing pipeline. Instead:

1. The signer authenticates with an identity provider (OIDC).
2. The CA issues a short-lived certificate bound to that identity.
3. The artifact is signed with the ephemeral key.
4. The signature and certificate are recorded in a public transparency log.

The result: a verifier can confirm which identity signed this artifact without any party holding a long-lived key that could be stolen.

Verification at the consumer boundary

The defensive value is on the verify side. A consumer (or an admission gate) verifies an artifact's signature and checks the signer identity against an expected identity policy before accepting the artifact. The standard verification invocation shape is cosign verify --certificate-identity <expected> --certificate-oidc-issuer <expected> <artifact-ref>. Verification fails closed: an unsigned or wrong-identity artifact is rejected.

• Verify at install / admission time, not only at publish time — the boundary that matters is where the artifact is accepted.
• Pin the expected signer identity so a validly-signed-but-wrong-identity artifact is rejected.
• Verify the SBOM and provenance attestations the same way — they are signed artifacts too.

Package-Registry Hardening

The registry is a high-value target: compromising it lets an attacker substitute artifacts at the source. Harden both the registry you publish to and any internal mirror you operate.