d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
77 lines
3.9 KiB
Markdown
77 lines
3.9 KiB
Markdown
# 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`
|