up

docs/forensics/provenance-attestation.md

@@ -1,15 +1,20 @@
 # 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
+## 1. Attestation Workflow (online and offline)
 
-1. **Scanner** produces signed payload requests (SBOM, report metadata).
-2. **Signer** authenticates the caller, verifies release integrity, and issues DSSE bundles (keyless or KMS-backed).
-3. **Attestor** submits bundles to Rekor v2, caches inclusion proofs, and serves verification packages.
-4. **Consumers** (Export Center, Evidence Locker, CLI, Policy Engine) fetch bundles for verification.
+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
+## 2. DSSE Payload Types & Schemas
+
+Supported payload types (all versioned and protobuf/JSON dual-encoded):
 
 - `StellaOps.BuildProvenance@1`
 - `StellaOps.SBOMAttestation@1`
@@ -17,25 +22,55 @@ This guide explains how StellaOps generates, signs, verifies, and distributes DS
 - `StellaOps.PolicyEvaluation@1`
 - `StellaOps.VEXAttestation@1`
 - `StellaOps.RiskProfileEvidence@1`
+- `StellaOps.PromotionAttestation@1` (predicate `stella.ops/promotion@v1`, see `docs/release/promotion-attestations.md`)
 
-Schemas live under `src/Attestor/StellaOps.Attestor.Types` and are documented in module architecture guides.
+Schema sources: `src/Attestor/StellaOps.Attestor.Types` and module dossiers. All payloads include:
 
-## 3. Verification
+- `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`
 
-- CLI command `stella attest verify` requests proofs from Attestor.
-- Services embed Rekor UUID/index and DSSE digests in their APIs for downstream verification.
-- Verification pipeline checks signature trust roots, Rekor inclusion proofs, and transparency witness endorsements when enabled.
+## 3. Signing & storage controls
 
-## 4. Offline/air-gap considerations
+- **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.
 
-- Export Center bundles incorporate attestations and proofs for offline verification.
-- Evidence Locker stores immutable attestation bundles with retention policies.
+## 4. Verification workflow
 
-## 5. References
+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`