# SBOM, Signing, and Build Provenance Policy

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](https://github.com/anchore/syft)      | SPDX (`.spdx.json`) and CycloneDX (`.cyclonedx.json`) outputs |
| Vulnerability scanning | [Grype](https://github.com/anchore/grype)    | Operates against generated SBOMs                              |
| Signing & attestations | [Cosign](https://github.com/sigstore/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](https://slsa.dev/spec/v1.0/provenance)
