stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
108d1c64b323808d6085fca05818fc581c6b003a
git.stella-ops.org/docs/modules/export-center/determinism.md
StellaOps Bot 4dc7cf834a
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Console CI / console-ci (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
VEX Proof Bundles / verify-bundles (push) Has been cancelled
Details
Add sample proof bundle configurations and verification script 
- 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.
2025-12-04 08:54:32 +02:00

4.5 KiB
Raw Blame History

Export Center Determinism & Rerun Hash Guide

Advisory anchor: docs/product-advisories/archived/27-Nov-2025-superseded/28-Nov-2025 - Export Center and Reporting Strategy.md (EC1–EC10).

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.

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)

./docs/modules/export-center/operations/verify-export-kit.sh src/ExportCenter/__fixtures/export-kit