supply-chain-sbom-provenance

name	supply-chain-sbom-provenance
description	SBOM generation and provenance verification for research software releases. Use when reviewing or writing release workflows that publish to PyPI, npm, GHCR, or similar registries; when verifying a downstream artifact's signatures or attestations; or when evaluating SLSA level for a release pipeline. Covers CycloneDX/SPDX SBOM generation with syft, Sigstore keyless signing with cosign, npm provenance, and SLSA build levels.
metadata	{"references":["references/sigstore-cookbook.md","references/slsa-levels.md"],"assets":["assets/sbom-workflow.yml"]}

Supply Chain SBOM and Provenance

Threat Model

SBOM and provenance catch tag-hijack and maintainer account-takeover: the artifact digest stops matching the signed attestation even when CVE scanners report clean. CVE scanners cannot detect these attacks; only cryptographic attestations tied to the build pipeline can.

Decision Matrix

Registry	Mechanism	Key management	SLSA level	Complexity
PyPI	OIDC trusted publishing + Sigstore	Keyless via GitHub OIDC	L2-L3	Low
npm	npm provenance (--provenance)	Keyless via GitHub OIDC	L2	Low
GHCR	actions/attest-build-provenance	Keyless via GitHub OIDC	L2-L3	Low
Docker Hub	cosign keyless	Sigstore (Fulcio short-lived cert)	L2	Medium
Self-hosted (no OIDC)	cosign with hardware key	KMS or YubiKey	L3 if hermetic	High

Pick the lowest-complexity row for your registry. PyPI/npm/GHCR default to GitHub-OIDC keyless — no secrets to rotate.

Generation Workflow

Run these steps in order in the release job. Each is independently runnable for local debugging.

Step 1 — Build artifact and capture its digest

# Build whatever artifact the project ships (wheel, tarball, container)
python -m build                            # → dist/*.whl, dist/*.tar.gz
sha256sum dist/* > dist/SHA256SUMS         # record digests for the attestation

Step 2 — Generate CycloneDX SBOM with syft

# Scan the built directory (works for source trees, dirs, OCI images)
syft dir:. -o cyclonedx-json=sbom.cdx.json

# Or scan an already-built artifact
syft dist/myproject-1.0.0.tar.gz -o cyclonedx-json=dist/sbom.cdx.json

Step 3 — Sign artifact and SBOM with Sigstore keyless

In CI, prefer the GitHub-native attestation action (writes to the public attestation API):

permissions:
  id-token: write      # required for OIDC
  attestations: write  # required for attest-build-provenance
- uses: actions/attest-build-provenance@<sha>  # v3.0.0
  with:
    subject-path: 'dist/*'

Or sign each artifact directly with cosign keyless (works for any registry):

cosign sign-blob --yes --bundle artifact.sigstore artifact.tar.gz

See references/sigstore-cookbook.md for permissions: block and failure modes.

Step 4 — Attach SBOM and signatures to the release

gh release upload "${GITHUB_REF_NAME}" \
  dist/sbom.cdx.json \
  dist/*.sigstore \
  dist/SHA256SUMS

Drop-in workflow that wires all four steps together: assets/sbom-workflow.yml. For a one-shot SBOM-only scan from any source tree: syft dir:. -o cyclonedx-json=sbom.cdx.json.

Verification Checklist

Run each item below downstream or in the project's pre-release smoke test.

• Bundle present. Check: gh attestation list <artifact> or release page for *.sigstore.
• Signature verifies:

  cosign verify-blob \
    --bundle artifact.sigstore \
    --certificate-identity-regexp "https://github.com/<owner>/<repo>/.github/workflows/.+" \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    artifact.tar.gz
  

• SBOM digest matches. Check: sha256sum artifact.tar.gz appears in sbom.cdx.json (metadata.component.hashes) or SHA256SUMS.
• certificate-identity is the expected repo + workflow path (not a fork, not a different workflow).
• Rekor log timestamp falls in the expected release window. Check: cosign tree <artifact>.

If any item fails, treat as unverified — do not install.

Quick Recipes

Complementary recipes for scenarios beyond the standard release pipeline above.

npm publish with provenance (alternative to syft+cosign for npm packages):

npm publish --provenance --access public

Requires permissions: id-token: write in the publish job and an OIDC-enabled npm account.

Verify a GitHub attestation (consumer side, no Sigstore tooling needed):

gh attestation verify artifact.tar.gz --owner <owner>

Uses the gh CLI to verify build-provenance attestations published via actions/attest-build-provenance. Faster than cosign verify-blob when the artifact is from a GitHub-hosted repo.

Generate an SBOM from a built container image (instead of source tree):

syft <registry>/<image>:<tag> -o spdx-json=sbom.spdx.json

Use this when shipping container images to GHCR or Docker Hub. Format is SPDX (alternative to CycloneDX); both are accepted by GitHub's attestation infrastructure.

Output: Provenance Posture Report

When invoked for a release-pipeline review, produce a Markdown report with the structure below. Every PASS/WARN/FAIL must cite a file:line from the workflows or "absent" if the control is missing entirely.

## Provenance Posture: <project>

### Generation Posture
| Criterion | PASS/WARN/FAIL | Evidence |
|-----------|----------------|----------|
| SBOM generated for releases | ... | <workflow file:line or "absent"> |
| SBOM format (CycloneDX/SPDX) | ... | <format detected> |
| Sigstore signing in release workflow | ... | <workflow file:line> |
| npm provenance enabled (npm projects) | ... | <evidence or N/A> |
| SLSA level achieved | ... | <level + reasoning, see references/slsa-levels.md> |

### Verification Posture
| Criterion | PASS/WARN/FAIL | Evidence |
|-----------|----------------|----------|
| Downstream verification documented | ... | <README/docs reference> |
| Attestation references build pipeline | ... | <evidence> |

### Top 3 Priority Actions
1. <highest-impact upgrade> — apply `assets/sbom-workflow.yml` or follow `references/sigstore-cookbook.md`
2. <second priority>
3. <third >