c2c6b58b41
- Introduced a new document for promotion-time attestations, detailing the purpose, predicate schema, producer workflow, verification flow, APIs, and security considerations. - Implemented the `stella.ops/promotion@v1` predicate schema to capture promotion evidence including image digest, SBOM/VEX artifacts, and Rekor proof. - Defined producer responsibilities and workflows for CLI orchestration, signer responsibilities, and Export Center integration. - Added verification steps for auditors to validate promotion attestations offline. feat: Create Symbol Manifest v1 Specification - Developed a specification for Symbol Manifest v1 to provide a deterministic format for publishing debug symbols and source maps. - Defined the manifest structure, including schema, entries, source maps, toolchain, and provenance. - Outlined upload and verification processes, resolve APIs, runtime proxy, caching, and offline bundle generation. - Included security considerations and related tasks for implementation. chore: Add Ruby Analyzer with Git Sources - Created a Gemfile and Gemfile.lock for Ruby analyzer with dependencies on git-gem, httparty, and path-gem. - Implemented main application logic to utilize the defined gems and output their versions. - Added expected JSON output for the Ruby analyzer to validate the integration of the new gems and their functionalities. - Developed internal observation classes for Ruby packages, runtime edges, and capabilities, including serialization logic for observations. test: Add tests for Ruby Analyzer - Created test fixtures for Ruby analyzer, including Gemfile, Gemfile.lock, main application, and expected JSON output. - Ensured that the tests validate the correct integration and functionality of the Ruby analyzer with the specified gems.
112 lines
5.1 KiB
Markdown
112 lines
5.1 KiB
Markdown
# Promotion-Time Attestations for Stella Ops
|
||
|
||
> **Status:** Draft – sprint 186/202/203 coordination
|
||
> **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"
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
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.
|
||
|
||
### 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` | TODO |
|
||
|
||
When all tasks are completed this document should be updated with status links and sample payloads.
|