Eve library

SBOM, Signing, and Build Provenance Policy

Guide

Revision 1

On this page

This guide explains how the Lilith platform generates Software Bills of Materials (SBOMs), signs build artifacts, and publishes build-provenance attestations to satisfy supply-chain integrity requirements.

Objectives#

  • Produce SPDX and CycloneDX SBOMs for every service and container image.
  • Sign container images and SBOM payloads using keyless Sigstore (cosign).
  • Emit SLSA-compatible build provenance attestations for promotion through dev → staging → prod.
  • Provide deterministic, reproducible steps developers can run locally.
  • Continuously validate the workflow via GitHub Actions and Playwright audit checks.

Tooling Stack#

Capability Tool Notes
SBOM generation Syft SPDX (.spdx.json) and CycloneDX (.cyclonedx.json) outputs
Vulnerability scanning Grype Operates against generated SBOMs
Signing & attestations Cosign Keyless OIDC signing via GitHub Actions
Provenance actions/attest-build-provenance Emits SLSA provenance referencing the image digest

All tools are vendored in CI (.github/workflows/ci.yaml) and can be installed locally via scripts/generate-sbom.sh (see below).

CI Workflow Summary#

The docker-build job in .github/workflows/ci.yaml performs the following for each service image:

  1. Build – Uses docker/build-push-action@v6 with provenance: true and sbom: true to enable native BuildKit attestations.
  2. Generate SBOMs – Runs Syft against the service workspace and the pushed container image, producing:
    • ${service}-sbom.spdx.json
    • ${service}-sbom.cyclonedx.json
    • ${service}-container-sbom.spdx.json
  3. Sign Artifacts – Invokes cosign sign on the image digest and cosign sign-blob on each SBOM file. Signatures (*.sig) are uploaded as artifacts.
  4. Provenance Attestation – Calls actions/attest-build-provenance@v1 with the image digest to emit an in-toto statement.
  5. Verification – Executes cosign verify against the freshly signed image to smoke-test the signature.
  6. Distribution – Uploads SBOMs and signatures via actions/upload-artifact, enabling downstream inspection and promotion gates.
  7. Vulnerability Scan – The security-scan job downloads the SBOMs and runs Grype, failing on critical CVEs.

Artifacts live in the GitHub Actions artifacts store for 90 days and are mirrored into the release pipeline during promotion.

Local Workflow#

Developers can reproduce SBOMs and signatures locally for ad-hoc validation:

bash
# Ensure Syft, Grype, and Cosign are installed (see script below)
./scripts/generate-sbom.sh services/auth

# Output files (relative to repo root):
# auth-sbom.spdx.json
# auth-sbom.cyclonedx.json
# auth-sbom.spdx.json.sig
# auth-container-sbom.spdx.json
# auth-container-sbom.spdx.json.sig

# Optional: scan using grype
GRYPE_DB_CACHE_DIR=.grype-db grype sbom:auth-container-sbom.spdx.json

Tip: Run the script after building the local image (e.g., docker build services/auth -t lilith/auth:dev) so the container SBOM reflects your changes.

Promotion & Verification#

  • Deployment controllers (Argo CD) must verify container signatures using Cosign policy before admitting images to staging/production.
  • Promotion pipelines download the SBOM artifacts and provenance statements to attach them to release tickets.
  • Security reviews consume Grype JSON reports to track CVE remediation.

Monitoring & Compliance#

  • Playwright spec tests/security.coding-standards.spec.ts checks documentation/CI invariants.
  • Upcoming Playwright spec tests/security.sbom-provenance.spec.ts (see repository) ensures the workflow steps remain present in CI with the correct flags.
  • Any change to tool versions or signing policy requires an update to this document and the automated tests.

References#

  • .github/workflows/ci.yaml
  • scripts/generate-sbom.sh
  • tests/security.sbom-provenance.spec.ts
  • SLSA Build Provenance