Add sample proof bundle configurations and verification script
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Console CI / console-ci (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
VEX Proof Bundles / verify-bundles (push) Has been cancelled

- Introduced sample proof bundle configuration files for testing, including `sample-proof-bundle-config.dsse.json`, `sample-proof-bundle.dsse.json`, and `sample-proof-bundle.json`.
- Implemented a verification script `test_verify_sample.sh` to validate proof bundles against specified schemas and catalogs.
- Updated existing proof bundle configurations with new metadata, including versioning, created timestamps, and justification details.
- Enhanced evidence entries with expiration dates and hashes for better integrity checks.
- Ensured all new configurations adhere to the defined schema for consistency and reliability in testing.
This commit is contained in:
StellaOps Bot
2025-12-04 08:54:32 +02:00
parent e1262eb916
commit 4dc7cf834a
76 changed files with 3051 additions and 355 deletions

View File

@@ -1,34 +1,58 @@
# Export Center Determinism & Rerun Hash Guide
Advisory: `docs/product-advisories/28-Nov-2025 - Export Center and Reporting Strategy.md` (EC1EC10).
Advisory anchor: `docs/product-advisories/archived/27-Nov-2025-superseded/28-Nov-2025 - Export Center and Reporting Strategy.md` (EC1EC10).
## Adapter settings (runnable example)
- JSON adapters: `--compression zstd --compression-level 19 --deterministic-order`
- Mirror adapter: sort descriptors by digest, emit annotations in lexicographic order, disable mtime in tar (`--mtime 0`).
- Delta adapter: include `baseManifestHash` and sorted `added`/`removed` lists; tombstones must be explicit.
## EC1 — Signed schemas
- Export profile schema: `docs/modules/export-center/schemas/export-profile.schema.json` (selectors, approvals, quotas).
- Export manifest schema: `docs/modules/export-center/schemas/export-manifest.schema.json` (rerunHash, integrity headers, attestations, quotas/backpressure).
- Both schemas must be signed (DSSE) alongside publication; DSSE envelopes live next to the schema files when generated in CI.
## Rerun-hash check
## EC2 — Per-adapter determinism and rerun hash
- JSON adapters: canonical JSONL, sorted keys, zstd level 19; filenames stable (`advisories-<shard>.jsonl.zst`); gzip forbidden.
- Trivy adapters: pin schema version (see `trivy-adapter.md`), normalize namespaces, ordered records by `(namespace, package, vulnerabilityId)`.
- Mirror full: tar with `--sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner`; manifest entries sorted by path; indexes stable.
- Mirror delta: include `baseManifestDigest`, sorted `added`/`removed`, explicit `tombstones`; reject deltas without tombstones for removed entries.
- Rerun hash algorithm: SHA-256 over newline-joined, sorted `contents[*].digest` values; stored in `manifest.rerunHash` and asserted in CI.
- CI harness: `docs/modules/export-center/operations/verify-export-kit.sh` recomputes rerun hash and schema-consistent integrity hints.
## EC3 — DSSE + SLSA attestation with log metadata
- All manifests and provenance files carry DSSE envelopes; provenance must include SLSA v1 builder metadata plus log proof (`kind`, `logId`, `logIndex`, `entryDigest`, `timestamp`).
- Provenance subjects list both `manifests/export.json` and bundle tar/OCI digest; log metadata is mandatory even when transparency uploads are deferred.
## EC4 — Cross-tenant approval flow
- `selectors.tenants` must contain the profile tenant; when selectors include additional tenants or wildcards, `approval.required=true` with `approvedBy` and `ticket` is mandatory (validated by the verify script).
## EC5 — Distribution integrity headers and OCI annotations
- HTTP: `Digest: sha-256=<base64>` derived from bundle digest; `X-Stella-Signature: dsse-b64:<envelope>`; `X-Stella-Immutability: true` for immutable responses.
- OCI: annotations must include `io.stellaops.export.profile`, `io.stellaops.export.run`, `io.stellaops.export.manifest-digest`, `io.stellaops.export.provenance-ref`, and `org.opencontainers.image.ref.name`.
## EC6 — Trivy schema pinning
- Schema compatibility is pinned in `trivy-adapter.md`; CI rejects versions above the pinned set and emits `ERR_EXPORT_UNSUPPORTED_SCHEMA`.
- Mirror/export manifests must record the targeted `schemaVersion` so rerun-hash and consumers can enforce deterministic decoding.
## EC7 — Mirror delta/tombstone rules
- Deltas MUST include tombstones for all removals and a `baseManifestDigest` that matches the referenced baseline; omitted tombstones fail verification.
- `delta.added/removed` are sorted, and `resetBaseline=false` unless explicitly set; consumers apply deltas in order and refuse out-of-order manifests.
## EC8 — Encryption/recipient policy
- Only `age` or `aes-gcm` envelopes; recipients enumerated with `fingerprint` and optional `wrappedKey` in manifest and provenance.
- `strict=true` encrypts everything except manifest/provenance; defaults to `false` to keep discovery metadata plaintext.
## EC9 — Quotas and backpressure
- Manifest `quotas` block captures `maxActiveRuns`, `maxQueuedRuns`, `backpressureMode` (`reject`|`defer`|`throttle`), and optional `cpuThrottlePercent`.
- CI verifies presence of quotas; operators surface `429` with `X-Stella-Quota-*` hints when limits engage.
## EC10 — Offline export kit + verify script
- Fixtures: `src/ExportCenter/__fixtures/export-kit/*` (manifest, manifest.sha256, manifest.dsse, provenance).
- Verifier: `docs/modules/export-center/operations/verify-export-kit.sh`
- Validates manifest hash against `manifest.sha256`.
- Recomputes rerun hash.
- Confirms integrity headers align with OCI annotations.
- Enforces approval + quota presence for cross-tenant selectors.
- Confirms provenance references manifest digest and carries log metadata.
- Tar flags for offline kit assembly: `tar --sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner`.
## Quick rerun-hash smoke (uses fixtures)
```bash
set -euo pipefail
run_id=$(uuidgen)
stella export run --profile demo --run-id "$run_id" --out /tmp/export1
sha256sum /tmp/export1/manifest.json > /tmp/export1/manifest.sha256
# second run
run_id2=$(uuidgen)
stella export run --profile demo --run-id "$run_id2" --out /tmp/export2
sha256sum /tmp/export2/manifest.json > /tmp/export2/manifest.sha256
diff -u /tmp/export1/manifest.sha256 /tmp/export2/manifest.sha256
./docs/modules/export-center/operations/verify-export-kit.sh src/ExportCenter/__fixtures/export-kit
```
## Integrity headers (HTTP example)
- `Digest: sha-256=<base64>`
- `X-Stella-Signature: dsse-b64=<payload>`
- `X-Stella-Immutability: true`
## Offline kit packaging
- Tar flags: `tar --sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner`
- Include `export-kit/manifest.json` + `manifest.dsse`; add `verify-export-kit.sh` to check hashes and signatures.
## Where to place fixtures
- `src/ExportCenter/__fixtures/` for deterministic manifests/outputs used by tests.
- Add rerun-hash CI to compare fixture hash against regenerated outputs.