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:
- Build – Uses
docker/build-push-action@v6withprovenance: trueandsbom: trueto enable native BuildKit attestations. - 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
- Sign Artifacts – Invokes
cosign signon the image digest andcosign sign-blobon each SBOM file. Signatures (*.sig) are uploaded as artifacts. - Provenance Attestation – Calls
actions/attest-build-provenance@v1with the image digest to emit an in-toto statement. - Verification – Executes
cosign verifyagainst the freshly signed image to smoke-test the signature. - Distribution – Uploads SBOMs and signatures via
actions/upload-artifact, enabling downstream inspection and promotion gates. - Vulnerability Scan – The
security-scanjob 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:
# 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.tschecks 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.yamlscripts/generate-sbom.shtests/security.sbom-provenance.spec.ts- SLSA Build Provenance