git.stella-ops.org/docs/modules/scanner/design/standards-convergence-roadmap.md

Scanner Standards Convergence Roadmap (SC1)

Purpose

Define the concrete steps for adopting CVSS v4.0, CycloneDX 1.7 (incl. CBOM), and SLSA 1.2 across Scanner surfaces while keeping outputs deterministic and downgrade-friendly.

Scope

• Scanner WebService + Worker + Replay bundles.
• Surface contracts, CLI outputs, and CAS artifacts.
• Downgrade adapters to CVSS v3.1, CDX 1.6, SLSA 1.0 (see SC4).

Deliverables (tie to SC tasks)

• SC1: Roadmap with milestones, owners, and schema bump governance.
• SC2: Deterministic CDX 1.7 + CBOM contract (fields, ordering, evidence citations).
• SC3: SLSA Source Track capture fields for replay bundles (build-id, repo refs, provenance hooks).
• SC4: Mapping tables for downgrade adapters; deterministic mapping rules and hashes.
• SC5/SC8: Fixture set + determinism CI (stable ordering, seeded RNG, golden hashes).
• SC6: Binary ↔ source evidence alignment requirements (build-id, symbols, patch oracle) feeding policy/VEX.
• SC7: API/UI surfacing contract (filters, columns, pagination defaults) with deterministic ordering.
• SC9: Governance/RACI for schema bumps and adapter tables.
• SC10: Offline-kit parity: DSSE-signed schemas/mappings/fixtures, frozen bundle.

Contracts & owners (v0.1)

• Schema leads: Scanner Guild (CDX 1.7/CBOM), Sbomer Guild (mapping), Policy Guild (severity/vectors), Ops Guild (offline kit).
• Canonical CDX 1.7/CBOM fields (min set):
  • metadata/component (purl, hashes, evidence refs),
  • services with CBOM channels (ingress/egress),
  • vulnerabilities[*].ratings[] must carry CVSS v4 and v3.1 side-by-side; deterministic order: v4 first, then v3.1.
  • Evidence citations: properties["evidence:source"], properties["evidence:proof-id"], properties["evidence:hash"].
• SLSA Source Track (SC3):
  • replay bundle fields: source.repo, source.ref, build.id, build.invocation.hash, provenance.dsse (hash), all required.
• Deterministic ordering rules (apply across SC2/SC5/SC8):
  • sort components by purl, ties by name, then version (ordinal, case-insensitive);
  • vulnerabilities sorted by id, then source, then severity score desc;
  • timestamps UTC ISO-8601 without sub-ms; decimal rounding 4dp for ratios, 2dp for scores.
• Adapter tables (SC4): mapping CSVs checked in under docs/modules/scanner/fixtures/adapters/ with BLAKE3 + SHA256 hashes; adapters are pure, no net.

Fixtures (SC2/SC5/SC8)

• Golden payloads live in docs/modules/scanner/fixtures/cdx17-cbom/.
  • sample-cdx17-cbom.json (CDX 1.7 + CBOM + CVSS v4/v3.1 + SLSA Source Track + evidence).
  • sample-cdx16.json (downgraded CDX 1.6; CVSS v3.1 only; no CBOM channel properties).
  • hashes.txt records deterministic digests:
    • sample-cdx17-cbom.json BLAKE3=27c6de0ccd6adb8149c5521477fba8292aa119fb9e42b521cba6356b2308e761 SHA256=22d8f6f80f02be13f840b74b24b2eea769f108a225152695e1bf8d8a0577e6f6
    • sample-cdx16.json BLAKE3=da5b631a8cca865f929f8fd5d3b35adc512de1754fe2278cb8b415b01c81b3d3 SHA256=3cf6cb04aec97ec05fad0658f54b4ec099644176806f098897a9ba0bf1135cb0
• CI step: dotnet test hook runs deterministic serializer + hash assertion; env DOTNET_DISABLE_BUILTIN_GRAPH=1, fixed TZ=UTC, LC_ALL=C.
• Downgrade adapters (SC4) consume the CDX 1.7 fixture and emit the 1.6 fixture; verify hashes match the values above.

Governance (SC1/SC9)

• RACI: Product (A), Scanner TL (R), Sbomer TL (C), Policy TL (C), Ops (I).
• Schema bump flow: draft → review → freeze → DSSE-sign schemas + fixtures → publish hash list → lock downgrade adapters.
• Downgrade adapters cannot ship without approved mapping CSV + updated hashes; adapter CSVs live under docs/modules/scanner/fixtures/adapters/ (hash list alongside CSVs).

Offline (SC10)

• Offline kit must include: schemas, adapter CSVs, fixtures, hash list, DSSE envelope, tool versions (Syft/Trivy pinned) and their hashes.
• Bundle path: out/offline/scanner-standards-kit-v1/. DSSE envelope references manifest with all hashes; include CBOM sample, downgrade sample, adapter CSVs, and their BLAKE3/SHA256 values.

Milestones (locked for SC1 delivery)

1. Schema draft freeze (CDX 1.7/CBOM + CVSS v4 fields) — owners: Scanner Guild, due 2025-12-08.
2. Replay bundle field list for Source Track — owners: Scanner + Sbomer, due 2025-12-10.
3. Determinism harness upgrade (CI + fixtures) — owners: QA + Scanner, due 2025-12-13.
4. Downgrade adapter tables + hash tests — owners: Scanner, due 2025-12-15.
5. Offline-kit bundle update & DSSE signing — owners: Ops, due 2025-12-17.

Determinism & Offline requirements

• Stable field ordering, culture-invariant formatting, UTC ISO-8601 timestamps.
• No network calls during conversion/adapters; fixed seeds for any RNG.
• All schemas/adapters/fixtures shipped in offline kit with DSSE envelope and recorded hashes.

Decisions (2025-12-03)

• CBOM subset: include ingress + egress channel properties only; deeper data-flow capture deferred to policy/graph once schema stabilises.
• CVSS v4 rounding: keep vendor vector precision; round scores to 2dp using MidpointRounding.ToZero for deterministic alignment with CVSS v3.1 sidecar values.
• Evidence properties are mandatory for replay bundles and serialized CycloneDX 1.7 outputs; adapter must preserve them when downgrading.

Links

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