git.stella-ops.org/docs/forensics/provenance-attestation.md

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):

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