# ADR 0004 — SBOM and supply-chain provenance

- Status: Accepted
- Date: 2026-07-05

## Context

This package underpins security-scenario content across the ACES ecosystem.
Consumers (and their own downstream auditors) need to know exactly what a given
release contains and depends on. A Software Bill of Materials (SBOM) is the
standard, machine-readable way to provide that, and it is a prerequisite for
supply-chain review and vulnerability triage.

## Decision

- Every release produces a **CycloneDX** SBOM in JSON format, generated from the
  installed distribution and its resolved dependencies (`cyclonedx-py
  environment`). CycloneDX is chosen for broad tooling support in the security
  ecosystem.
- The SBOM is **attached to the GitHub Release** alongside the wheel and sdist
  (ADR 0003) and uploaded as a build artifact, so every published version has a
  downloadable component inventory. Embedding the SBOM inside the wheel is
  deferred; the Release attachment plus PyPI's OIDC provenance is the
  supply-chain record for now.
- The SBOM is generated in the release workflow, not committed to the source
  tree, so it always reflects the actual built artifact.
- Because publishing uses OIDC trusted publishing (ADR 0003), the release also
  carries PyPI's provenance/attestation; the SBOM complements that with the
  component inventory.

## Consequences

- Each published version has a verifiable component inventory a consumer can feed
  into supply-chain and vulnerability tooling.
- The release workflow gains an SBOM-generation step and a dependency on
  `cyclonedx-py` (build-time only, not a runtime dependency of the package).
- Keeping the dependency surface minimal (currently `PyYAML`) keeps the SBOM
  small and the attack surface low; adding a runtime dependency is a deliberate,
  reviewable change reflected in the next release's SBOM.