Skip to content

Supply-chain evidence

dpone supply-chain attest creates release evidence for OSS and internal CI:

  • SPDX-like SBOM JSON;
  • CycloneDX-like SBOM JSON;
  • SLSA/in-toto-inspired provenance JSON;
  • optional local HMAC signature envelope;
  • one attestation bundle with checksums.

This command is dependency-light and works without external signing services. For public releases, pair it with GitHub artifact attestations or Sigstore/cosign in CI.

Contents

Quickstart

uv build

uv run dpone supply-chain attest \
  --project-root . \
  --output-dir test_artifacts/supply-chain/current \
  --release v0.7.1 \
  --subject dist/dpone-0.7.1-py3-none-any.whl \
  --subject dist/dpone-0.7.1.tar.gz \
  --repository https://github.com/PaulKov/dpone \
  --commit-sha "$GITHUB_SHA" \
  --builder-id "github-actions:$GITHUB_RUN_ID" \
  --signing-key "$DPONE_LOCAL_ATTESTATION_KEY" \
  --signing-key-id github-actions \
  --format json

Artifacts

File Purpose
sbom.spdx.json SPDX-like dependency inventory generated from pyproject.toml.
sbom.cyclonedx.json CycloneDX-like component inventory generated from pyproject.toml.
provenance.intoto.json Release subjects, SHA-256 digests, repo, commit, builder, and release metadata.
signature.hmac-sha256.json Local HMAC signature envelope for deterministic CI evidence.
supply_chain_attestation.json Bundle index with artifact paths and checksums.
supply_chain_attestation.md Human-readable release evidence summary.

Signing model

The built-in signature is a local HMAC-SHA256 envelope. It proves that the same CI environment with access to the same secret signed a specific provenance digest. It is useful for internal evidence chains and deterministic testing.

It is not a public identity replacement for:

  • GitHub artifact attestations;
  • Sigstore/cosign;
  • hardware-backed code signing;
  • cloud KMS signing.

Use external identity-backed signing for public release trust, and attach the dpone bundle as additional evidence.

CI pattern

Recommended release job order:

uv sync --all-extras
uv run pytest -m "not integration_live"
uv build
uv tool run twine check dist/*

uv run dpone supply-chain attest \
  --release "$GITHUB_REF_NAME" \
  --subject dist/dpone-*.whl \
  --subject dist/dpone-*.tar.gz \
  --repository "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" \
  --commit-sha "$GITHUB_SHA" \
  --builder-id "github-actions:$GITHUB_RUN_ID" \
  --signing-key "$DPONE_LOCAL_ATTESTATION_KEY" \
  --signing-key-id github-actions \
  --output-dir test_artifacts/supply-chain/current \
  --format json

Upload test_artifacts/supply-chain/current/ as a release artifact.

Runbook

Symptom Likely cause Action
subjects.empty No --subject files were provided. Run uv build first and pass wheel/sdist paths.
subject.missing.<path> A subject path does not exist. Check glob expansion and working directory in CI.
signature.missing_key No local signing key was provided. Set DPONE_LOCAL_ATTESTATION_KEY or run external Sigstore/GitHub attestation separately.
SBOM misses a dependency Dependency is not declared in pyproject.toml. Add dependency metadata or extend the SBOM reader for lockfile evidence.
Public users cannot verify trust HMAC is local-only evidence. Add GitHub artifact attestation or Sigstore/cosign in the release workflow.