stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
e923880694b66a819714782b43fed2b0d577a95b
git.stella-ops.org/docs/modules/policy/contracts/spine-versioning-plan.md
StellaOps Bot e923880694
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
Docs CI / lint-and-preview (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Details
feat: Add DigestUpsertRequest and LockEntity models 
- Introduced DigestUpsertRequest for handling digest upsert requests with properties like ChannelId, Recipient, DigestKey, Events, and CollectUntil.
- Created LockEntity to represent a lightweight distributed lock entry with properties such as Id, TenantId, Resource, Owner, ExpiresAt, and CreatedAt.

feat: Implement ILockRepository interface and LockRepository class

- Defined ILockRepository interface with methods for acquiring and releasing locks.
- Implemented LockRepository class with methods to try acquiring a lock and releasing it, using SQL for upsert operations.

feat: Add SurfaceManifestPointer record for manifest pointers

- Introduced SurfaceManifestPointer to represent a minimal pointer to a Surface.FS manifest associated with an image digest.

feat: Create PolicySimulationInputLock and related validation logic

- Added PolicySimulationInputLock record to describe policy simulation inputs and expected digests.
- Implemented validation logic for policy simulation inputs, including checks for digest drift and shadow mode requirements.

test: Add unit tests for ReplayVerificationService and ReplayVerifier

- Created ReplayVerificationServiceTests to validate the behavior of the ReplayVerificationService under various scenarios.
- Developed ReplayVerifierTests to ensure the correctness of the ReplayVerifier logic.

test: Implement PolicySimulationInputLockValidatorTests

- Added tests for PolicySimulationInputLockValidator to verify the validation logic against expected inputs and conditions.

chore: Add cosign key example and signing scripts

- Included a placeholder cosign key example for development purposes.
- Added a script for signing Signals artifacts using cosign with support for both v2 and v3.

chore: Create script for uploading evidence to the evidence locker

- Developed a script to upload evidence to the evidence locker, ensuring required environment variables are set.
2025-12-03 07:51:50 +02:00

4.0 KiB
Raw Blame History

SBOM/VEX Spine Versioning Plan (SP1)

Purpose

Establish versioned spine API/DTO schemas with migration rules, determinism guarantees, and DSSE-backed manifests, covering SP1–SP10 gaps from the 31-Nov-2025 findings advisory.

Scope

  • Spine APIs and DTOs shared by Scanner, Policy, Authority, and Graph.
  • Manifest/signing layers for spine bundles (online + offline).
  • Pagination/performance envelopes and Unknowns workflow.

Deliverables (SP tasks)

  • SP1: Versioned schemas + header/version negotiation rules; deprecation timetable.
  • SP2: Evidence requirements per predicate/edge (reachability proof, package identity, build metadata) with MUST/SHOULD fields.
  • SP3: Unknowns registry contract (states, SLA, surfacing rules, expiry/decay).
  • SP4: DSSE-signed spine manifest listing hashes for all artifacts; Rekor/mirror policy hooks.
  • SP5: Deterministic diff rules + fixtures (ordered deltas, canonical sorting, hash expectations).
  • SP6: Feed snapshot freshness/staleness thresholds and validation steps.
  • SP7: Stage-by-stage DSSE requirements, Rekor/mirror policy matrices (online/offline).
  • SP8: Policy lattice version field and embedding rules in spine objects.
  • SP9: Pagination/ordering/perf budgets (stable sort keys, default page size limits, deterministic cursors).
  • SP10: Crosswalk mappings SBOM ↔ VEX ↔ graph ↔ policy (table + sample payloads).

Migration & Determinism

  • Version headers and DTO version fields must be required; rejects if missing or downgraded without declared adapter.
  • Canonical JSON ordering for manifests; hashes computed over canonical form (UTF-8, no BOM).
  • Pagination uses deterministic primary/secondary sort keys; cursors are opaque, HMAC-free, reproducible from sort key + last id.

Versioning mechanics (v0.1)

  • Header: X-Spine-Version: v1 (required). DTO field mirror: schemaVersion (string, semver).
  • Deprecation window: N-1 supported for 90 days; adapters required to downgrade v2→v1 (CSV in docs/modules/policy/fixtures/spine-adapters/).
  • Hashing: canonical JSON, sorted properties, UTF-8 no BOM, normalized decimals (4dp), timestamps UTC ISO-8601.

Evidence minima per edge (SP2, draft)

  • reachability: state, confidence, score, method, evidenceRef (hash or URI), runtimeEvidence flag (bool).
  • package_identity: purl, name, version, supplier, hashes[] (at least SHA256).
  • build_metadata: buildId, sourceRepo, sourceRef, buildInvokerHash, provenanceHash (DSSE).

Unknowns workflow (SP3, draft)

  • States: unknown, under_review, resolved, expired.
  • SLA: auto-review escalation after 7 days; decay to expired at 30 days unless refreshed.
  • Surfacing: APIs must include unknowns.count and list endpoint with deterministic pagination; optional policy lattice flag to penalize unknowns.

Signing (SP4/SP7)

  • Manifest structure: list of artifacts (type, id, hash, version, uri), signed using DSSE/ED25519 by default; Rekor optional online, mirrored checkpoints offline.
  • Stage policy: compile → ingest → materialize → export; each stage produces DSSE, carries prior stage hash for chain-of-custody.

Pagination/perf budgets (SP9)

  • Default page size 200; max 500; stable sort: tenant asc, subjectPurl asc, advisoryId asc, createdAt asc.
  • Cursors: base64-encoded tuple of sort keys; must round-trip deterministically.

Crosswalk (SP10)

  • Provide table mapping: SBOM component ↔ spine node ↔ graph node ↔ policy evaluation input; include sample payloads in docs/modules/policy/fixtures/spine-crosswalk/.

Signing & Offline

  • DSSE envelope mandatory for spine manifest; Rekor entry optional online, mirrored checkpoints for offline kits.
  • Mirror bundles carry: manifest hash list, time-anchor digest, toolkit hashes, version map for adapters.

Open Items

  • Finalize evidence minima per predicate with Signals/Reachability guild once runtime schema lands.
  • Confirm lattice versioning alignment with policy engine release cadence.

Links

  • Sprint: docs/implplan/SPRINT_0186_0001_0001_record_deterministic_execution.md (SP1–SP10)
  • Advisory: docs/product-advisories/31-Nov-2025 FINDINGS.md