# Provenance & Attestation Reference

> **Imposed rule:** All exported evidence must ship with DSSE + transparency proof bundles; unsigned or proof-less artifacts are rejected at ingress and may not be stored in the Evidence Locker.

This guide explains how StellaOps generates, signs, verifies, and distributes DSSE attestations for SBOMs, policy evaluations, and runtime evidence.

## 1. Attestation Workflow (online and offline)

1. **Producer** (Scanner, Policy Engine, runtime probes) emits a payload and a request to sign.
2. **Signer** authenticates the caller, validates supply-chain policy (release integrity, image pinning), then signs using keyless or tenant KMS keys.
3. **Attestor** wraps the payload in DSSE, records it in Rekor v2 (when online), persists the bundle plus inclusion proof, and exposes a verification package API.
4. **Export Center** and **Evidence Locker** embed the bundle and proof into export artifacts for offline replay; CLI retrieves the same package via `stella attest fetch`.
5. **Verifiers** (CLI, Policy Engine, auditors) validate signature roots, Rekor proof, and optional transparency witness endorsements.

## 2. DSSE Payload Types & Schemas

Supported payload types (all versioned and protobuf/JSON dual-encoded):

- `StellaOps.BuildProvenance@1`
- `StellaOps.SBOMAttestation@1`
- `StellaOps.ScanResults@1`
- `StellaOps.PolicyEvaluation@1`
- `StellaOps.VEXAttestation@1`
- `StellaOps.RiskProfileEvidence@1`
- `StellaOps.PromotionAttestation@1` (predicate `stella.ops/promotion@v1`, see `docs/release/promotion-attestations.md`)

Schema sources: `src/Attestor/StellaOps.Attestor.Types` and module dossiers. All payloads include:

- `subject` (digest + PURL/NEVRA coordinates)
- `timestamp` (UTC, ISO-8601)
- `producer` (service + version)
- `critical` block (policy version, scanner defs, reachability context)
- `materials` (SBOM/VEX references) and optional `auxiliary_proofs`

## 3. Signing & storage controls

- **Key policy:** Short-lived OIDC keyless by default; tenant KMS allowed; Ed25519 and ECDSA P-256 supported.
- **Inclusion:** Rekor v2 UUID + log index cached; when offline, the Attestor stamps a `transparency_pending` marker to be replayed later.
- **WORM:** Evidence Locker keeps immutable copies; retention and legal hold are enforced per tenant and surfaced in `docs/forensics/evidence-locker.md`.
- **Redaction:** Sensitive fields (secrets, PII) must be excluded at payload creation; the signer refuses payloads marked `pii=true` without a redaction ticket.

## 4. Verification workflow

Command-line (online or offline bundle):

```sh
stella attest verify \
  --bundle path/to/bundle.dsse.json \
  --rekor-root pubkeys/rekor.pub \
  --fulcio-root pubkeys/fulcio.pub \
  --certificate-chain pubkeys/issuer-chain.pem
```

Verification steps performed by services and CLI:

- Validate DSSE signature against Fulcio/tenant roots and certificate policies.
- Confirm subject digest matches expected container/image/SBOM digest.
- Check Rekor inclusion proof and (if present) transparency witness signatures.
- Enforce freshness: reject bundles older than `attestation.max_age_days` (tenant policy).
- Record verification result into Timeline events for auditability.

## 5. Offline / air-gap posture

- Export Center emits self-contained bundles (`*.dsse.json`, `rekor-proof.json`, `cert-chain.pem`) plus a verification manifest for deterministic replay.
- CLI `stella attest verify --bundle bundle.dsse.json --offline` skips Rekor lookups and relies on embedded proofs.
- When connectivity returns, the Attestor replays pending `transparency_pending` entries and updates Evidence Locker indexes; Timeline events capture the replay.

## 6. References

- `docs/modules/signer/architecture.md`
- `docs/modules/attestor/architecture.md`
- `docs/modules/export-center/architecture.md`
- `docs/modules/policy/architecture.md`
- `docs/modules/telemetry/architecture.md`
- `docs/forensics/evidence-locker.md`
- `src/Provenance/StellaOps.Provenance.Attestation`