stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
bc0762e97d251723854b9c4e482b218c8efb1e04
git.stella-ops.org/docs/modules/scanner/design/cdx17-cbom-contract.md
StellaOps Bot e1262eb916 Add receipt input JSON and SHA256 hash for CVSS policy scoring tests 
- Introduced a new JSON fixture `receipt-input.json` containing base, environmental, and threat metrics for CVSS scoring.
- Added corresponding SHA256 hash file `receipt-input.sha256` to ensure integrity of the JSON fixture.
2025-12-04 07:30:42 +02:00

3.4 KiB
Raw Blame History

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).