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