CycloneDX 1.7 + CBOM Export Contract (SC2)

Scope: Defines the deterministic export profile for CycloneDX 1.7 BOMs enriched with Cloud BOM (CBOM) signals that Scanner emits and Replay consumes. Covers ordering, required fields, CBOM properties, hash/DSSE anchoring, and downgrade rules to 1.6.

Profile

• bomFormat: CycloneDX, specVersion: 1.7, version: 1, serialNumber: urn:uuid: (v4, lower-case, fixed length).
• Canonicalization: JSON with lexicographic object keys, stable array ordering, UTF-8, no insignificant whitespace when hashing. Use BLAKE3-256 primary hash and SHA-256 secondary.
• Timestamps: UTC ISO-8601 Z; strip milliseconds unless non-zero.
• Hash fields: metadata.component.hashes[*], component hashes; attach properties evidence:hash for CAS subject; include DSSE envelope digest in metadata.properties (provenance.dsse).

Required sections

• metadata.component: root application/service with type, name, version, purl, hashes, and evidence.properties (evidence:source, evidence:hash).
• metadata.properties (CBOM + provenance):
  • source.repo, source.ref, build.id, build.invocation.hash, provenance.dsse.
• metadata.tools: at least one entry with vendor, name, version; include properties for deterministic seeds if applicable.
• services[]: CBOM ingress/egress per service using properties namespaced cbom:* (e.g., cbom:ingress, cbom:egress, cbom:data.classification).
• components[]: libraries/artifacts with type, name, version, purl, hashes. Optional CBOM properties allowed (cbom:region, cbom:provider).
• vulnerabilities[]: must carry both CVSS v4 (method: CVSSv4) and v3.1 ratings when available; include properties evidence:source, evidence:proof-id, evidence:hash.

Ordering rules

1. Top-level keys: bomFormat, specVersion, serialNumber, version, metadata, services, components, vulnerabilities.
2. Arrays sorted by name then purl (components/services) and by id for vulnerabilities.
3. Hash lists sorted by alg; properties sorted by name.
4. Ratings sorted by method (CVSSv4 first, then CVSSv3.1, then others).

Deterministic hashing

• Compute bomHash = BLAKE3-256 over canonical JSON; record in DSSE subject.
• For downgrade tests, also compute SHA-256 and record in hashes.txt (see fixtures).

Downgrade to 1.6

• Remove CBOM namespaced properties; preserve non-CBOM properties.
• Drop CVSS v4 ratings; keep v3.1 and mark x-stellaops:cvss4-dropped: true in vulnerabilities[].properties for audit.
• Preserve component/service ordering; recompute hashes; record downgrade hash alongside 1.7 hash (hashes.txt).

Evidence linkage

• Every evidence:hash must reference a CAS object (BLAKE3 URI or sha256) present in replay bundle manifests.
• provenance.dsse must point to DSSE envelope hash for the build/provenance statement; verifier should fail closed when missing.

CI expectations

• Validate against CycloneDX 1.7 JSON schema.
• Determinism check: render BOM twice → identical hashes and ordering.
• Verify fixture hashes in docs/modules/scanner/fixtures/cdx17-cbom/hashes.txt.

Fixtures

• 1.7 reference: docs/modules/scanner/fixtures/cdx17-cbom/sample-cdx17-cbom.json.
• 1.6 downgrade: docs/modules/scanner/fixtures/cdx17-cbom/sample-cdx16.json.
• Hashes: docs/modules/scanner/fixtures/cdx17-cbom/hashes.txt (BLAKE3, SHA256 for both).