e1262eb916
- 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.
48 lines
3.4 KiB
Markdown
48 lines
3.4 KiB
Markdown
# 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).
|