/moai-ref-supply-chain

name: moai-ref-supply-chain
description: >
  Software supply-chain defensive security reference: SBOM generation and
  verification (SPDX / CycloneDX), dependency-confusion defense, malicious-package
  triage playbook, SLSA provenance levels, Sigstore / cosign signing and
  verification, package-registry hardening, typosquatting defense, and
  transitive-dependency auditing. Agent-extending skill that amplifies backend,
  security, and release-engineering work with production-grade defensive patterns
  for the software supply chain.
  NOT for: offensive techniques (dependency-confusion attack execution, malicious
  package authoring, registry exploitation), LLM/AI-specific security (see
  moai-ref-llm-security), web-app OWASP Top 10 (see moai-ref-owasp-checklist), or
  general API design (see moai-ref-api-patterns).

when_to_use: >
  Use when generating or verifying an SBOM, defending against dependency confusion
  or typosquatting, triaging a suspicious package before adoption, raising a build
  to a SLSA provenance level, signing or verifying artifacts with Sigstore, hardening
  a package registry, or auditing transitive dependencies for vulnerabilities and
  license risk. Loads as background knowledge for release-engineering, dependency-
  hygiene, and supply-chain-hardening tasks across any language ecosystem.

user-invocable: false
metadata:
  version: "1.0.0"
  category: "domain"
  status: "active"
  updated: "2026-06-24"
  tags: "supply-chain, sbom, slsa, sigstore, cosign, dependency-confusion, typosquatting, provenance, transitive-dependencies, reference"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 3000

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 | |---------|------