docs consolidation and others
This commit is contained in:
master
118
docs/releases/promotion-attestations.md
Normal file
118
docs/releases/promotion-attestations.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# Promotion-Time Attestations for Stella Ops
|
||||
|
||||
> **Status:** Stable (2025-11)
|
||||
> **Owners:** Signing Guild · Provenance Guild · DevEx/CLI Guild · Export Center Guild
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Capture the full promotion-time evidence – image digest, SBOM/VEX artifacts, Rekor proof – in a single DSSE-wrapped statement so that air-gapped auditors can verify releases without talking to external services. This document explains the data shape, producer responsibilities, and downstream consumers that rely on the promotion attestation.
|
||||
|
||||
## 2. Predicate schema – `stella.ops/promotion@v1`
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"_type": "stella.ops/promotion@v1",
|
||||
"subject": [
|
||||
{ "name": "registry.example.com/acme/api", "digest": { "sha256": "…" } }
|
||||
],
|
||||
"materials": [
|
||||
{ "role": "sbom", "algo": "sha256", "digest": "…", "format": "CycloneDX-1.6", "uri": "oci://…/sbom@sha256:…" },
|
||||
{ "role": "vex", "algo": "sha256", "digest": "…", "format": "OpenVEX-1.0", "uri": "oci://…/vex@sha256:…" }
|
||||
],
|
||||
"promotion": {
|
||||
"from": "staging",
|
||||
"to": "prod",
|
||||
"actor": "ci/gitlab-runner",
|
||||
"timestamp": "2025-11-10T12:34:56Z",
|
||||
"pipeline": "https://git.example.com/acme/api/-/pipelines/12345",
|
||||
"ticket": "JIRA-1234",
|
||||
"notes": "risk accepted by ops"
|
||||
},
|
||||
"rekor": {
|
||||
"uuid": "REKOR_ENTRY_UUID",
|
||||
"logIndex": 1234567,
|
||||
"inclusionProof": {
|
||||
"rootHash": "MERKLE_ROOT",
|
||||
"hashes": ["…path…"],
|
||||
"treeSize": 9876543,
|
||||
"checkpoint": {
|
||||
"origin": "rekor.sigstore.dev - transparency log",
|
||||
"size": 9876543,
|
||||
"hash": "CHECKPOINT_HASH",
|
||||
"signedNote": "BASE64_NOTE"
|
||||
}
|
||||
}
|
||||
},
|
||||
"attestation": {
|
||||
"bundle_sha256": "sha256:…",
|
||||
"witness": "optional-transparency-witness-signature"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The Provenance Guild implements the predicate builder (task `PROV-OBS-53-003`). The signer pipeline accepts the predicate as a raw JSON payload and wraps it inside a DSSE envelope (`SIGN-CORE-186-005`). Rekor metadata is pulled from Attestor after DSSE submission.
|
||||
|
||||
## 3. Producer workflow
|
||||
|
||||
### 3.1 CLI orchestration (`CLI-PROMO-70-001/002`)
|
||||
|
||||
1. Resolve and freeze the image digest (`cosign triangulate`/`crane digest`).
|
||||
2. Hash SBOM and VEX artifacts, optionally publish them to an OCI registry.
|
||||
3. Upload the SBOM (or dummy artifact) to Rekor to obtain `{uuid, logIndex}`.
|
||||
4. Retrieve inclusion proof + checkpoint (`rekor-cli get`, `rekor-cli loginfo`).
|
||||
5. Build `attestation.json` using the template above and current promotion metadata.
|
||||
6. Call Signer to produce a DSSE bundle (`cosign attest` or `stella promotion attest`).
|
||||
7. Store the bundle alongside `attestation.json` and add both to Offline/Replay kits.
|
||||
8. Emit Timeline + Evidence Locker entries with bundle digest.
|
||||
|
||||
### 3.2 Signer responsibilities (`SIGN-CORE-186-004/005/006`)
|
||||
|
||||
* Accept the promotion predicate, verify Proof-of-Entitlement + release integrity.
|
||||
* Sign via StellaOps.Cryptography providers (keyless or KMS) and return DSSE+cert bundle.
|
||||
* Emit audit entries referencing the promotion metadata and Rekor proof.
|
||||
|
||||
### 3.3 Export Center integration (`EXPORT-OBS-54-002`)
|
||||
|
||||
* Bundle `attestation.json`, DSSE envelope, and Rekor checkpoint inside Offline kits.
|
||||
* Surface promotion evidence via API/CLI for air-gapped consumers.
|
||||
|
||||
## 4. Verification flow
|
||||
|
||||
Auditors can validate the promotion attestation offline:
|
||||
|
||||
1. Verify the DSSE signature using the provided bundle and trusted key/cert chain.
|
||||
2. Recompute Merkle inclusion using the embedded proof + checkpoint. The checkpoint’s signed note ties the inclusion to a known Rekor tree size.
|
||||
3. Hash SBOM/VEX artifacts and compare to the `materials` digests.
|
||||
4. Confirm the promotion metadata in release notes/CI evidence.
|
||||
|
||||
Authority exposes helper APIs (`AUTH-VERIFY-186-007`) to replay both DSSE and Merkle validations.
|
||||
|
||||
## 5. APIs & storage
|
||||
|
||||
| Component | Endpoint / Artifact | Notes |
|
||||
|------------------|--------------------------------------------------|-------|
|
||||
| Signer | `POST /api/v1/signer/sign/dsse` | Accepts promotion predicate, returns DSSE bundle + auditId. |
|
||||
| Attestor | `POST /api/v1/rekor/entries` | Persists DSSE, returns `{uuid, index, proof}`. |
|
||||
| Export Center | `GET /api/v1/exports/{id}/promotion` (planned) | Serve promotion attestation + bundle. |
|
||||
| Evidence Locker | Store DSSE + Rekor proof for long-term retention. |
|
||||
|
||||
Artifacts are content-addressed via CAS and mirrored into Offline kits (`docs/replay/DETERMINISTIC_REPLAY.md`).
|
||||
|
||||
## 6. Security considerations
|
||||
|
||||
* Promotion metadata is tenant-scoped; aim to avoid leaking pipeline URLs across tenants.
|
||||
* Rekor inclusion proofs must be fetched at promotion time and embedded; do **not** rely on on-demand Rekor access in air-gapped installs.
|
||||
* Rotate signing keys via Authority/KMS; promotion attestation inherits Signer’s DSSE trust model.
|
||||
|
||||
## 7. Implementation checklist
|
||||
|
||||
| Area | Sprint task | Status |
|
||||
|------|-------------|--------|
|
||||
| Predicate builder | `PROV-OBS-53-003` | TODO |
|
||||
| Signer support | `SIGN-CORE-186-004/005/006` | TODO |
|
||||
| CLI commands | `CLI-PROMO-70-001/002` | TODO |
|
||||
| Authority verifier | `AUTH-VERIFY-186-007` | TODO |
|
||||
| Export packaging | `EXPORT-OBS-54-002` | TODO |
|
||||
| Documentation | `DOCS-PROMO-70-001` | DONE (2025-11-26) |
|
||||
|
||||
When all tasks are completed this document should be updated with status links and sample payloads.
|
||||
@@ -307,7 +307,7 @@ This release has no breaking changes. All existing APIs, configurations, and wor
|
||||
|
||||
### Fresh Installation
|
||||
|
||||
Follow the [Installation Guide](../21_INSTALL_GUIDE.md).
|
||||
Follow the [Installation Guide](../INSTALL_GUIDE.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -363,7 +363,7 @@ Follow the [Installation Guide](../21_INSTALL_GUIDE.md).
|
||||
|
||||
### Updated Documentation
|
||||
|
||||
- [High-Level Architecture](../07_HIGH_LEVEL_ARCHITECTURE.md) - Added sections 4A, 4B, 4C
|
||||
- [High-Level Architecture](../ARCHITECTURE_OVERVIEW.md) - Added sections 4A, 4B, 4C
|
||||
|
||||
---
|
||||
|
||||
|
||||
8
docs/releases/templates/determinism-score.md
Normal file
8
docs/releases/templates/determinism-score.md
Normal file
@@ -0,0 +1,8 @@
|
||||
# Release Notes snippet — Scanner Determinism
|
||||
|
||||
- **Determinism score:** {{overall_score}} (threshold {{overall_min}}); per-image summary:
|
||||
- {{image_digest}} → score {{score}} ({{identical}}/{{runs}} identical)
|
||||
- {{next_image_digest}} → score {{score}} ({{identical}}/{{runs}} identical)
|
||||
- **Inputs:** policy {{policy_sha}}, feeds {{feeds_sha}}, scanner {{scanner_sha}}, platform {{platform}}.
|
||||
- **Evidence:** attached `determinism.json` + artefact hashes (DSSE-signed, offline-ready).
|
||||
- **Actions:** rerun harness with `stella detscore run --bundle determinism.json` if score < threshold; block promotion until pass.
|
||||
@@ -267,11 +267,11 @@ Memory overhead:
|
||||
New and updated documentation:
|
||||
|
||||
**Training Materials:**
|
||||
- [Score Proofs Concept Guide](docs/training/score-proofs-concept-guide.md)
|
||||
- [Reachability Analysis Guide](docs/training/reachability-concept-guide.md)
|
||||
- [Unknowns Management Guide](docs/training/unknowns-management-guide.md)
|
||||
- [FAQ](docs/training/faq.md)
|
||||
- [Troubleshooting Guide](docs/training/troubleshooting-guide.md)
|
||||
- [Score Proofs Concept Guide](docs/onboarding/concepts/score-proofs-concept-guide.md)
|
||||
- [Reachability Analysis Guide](docs/onboarding/concepts/reachability-concept-guide.md)
|
||||
- [Unknowns Management Guide](docs/onboarding/concepts/unknowns-management-guide.md)
|
||||
- [FAQ](docs/onboarding/faq/faq.md)
|
||||
- [Troubleshooting Guide](docs/onboarding/concepts/troubleshooting-guide.md)
|
||||
|
||||
**Operations Runbooks:**
|
||||
- [Score Replay Runbook](docs/operations/score-replay-runbook.md)
|
||||
@@ -281,9 +281,9 @@ New and updated documentation:
|
||||
- [Air-Gap Operations Runbook](docs/operations/airgap-operations-runbook.md)
|
||||
|
||||
**CLI Reference:**
|
||||
- [Score Proofs CLI](docs/cli/score-proofs-cli-reference.md)
|
||||
- [Reachability CLI](docs/cli/reachability-cli-reference.md)
|
||||
- [Unknowns CLI](docs/cli/unknowns-cli-reference.md)
|
||||
- [Score Proofs CLI](docs/modules/cli/guides/commands/score-proofs-cli-reference.md)
|
||||
- [Reachability CLI](docs/modules/cli/guides/commands/reachability-cli-reference.md)
|
||||
- [Unknowns CLI](docs/modules/cli/guides/commands/unknowns-cli-reference.md)
|
||||
|
||||
**API Reference:**
|
||||
- [Score Proofs API](docs/api/score-proofs-reachability-api-reference.md)
|
||||
|
||||
Reference in New Issue
Block a user