git.stella-ops.org/docs/migration/cyclonedx-1-6-to-1-7.md

CycloneDX 1.6 to 1.7 migration

STATUS: MIGRATION COMPLETED CycloneDX 1.7 support completed in Sprint 3200 (November 2024). All scanner output now generates CycloneDX 1.7 by default. This document preserved for operators migrating from StellaOps versions <0.9.0.

Summary

• Default SBOM output is now CycloneDX 1.7 (JSON and Protobuf).
• CycloneDX 1.6 ingestion remains supported for backward compatibility.
• VEX exports include CycloneDX 1.7 fields for ratings, sources, and affected versions.

What changed

• specVersion is emitted as 1.7.
• Media types include explicit 1.7 versions:
  • application/vnd.cyclonedx+json; version=1.7
  • application/vnd.cyclonedx+protobuf; version=1.7
• VEX documents may now include:
  • vulnerability.ratings[] with CVSS v4/v3/v2 metadata
  • vulnerability.source with provider and PURL/URL reference
  • vulnerability.affects[].versions[] entries

Required updates for consumers

1. Update Accept and Content-Type headers to request or send CycloneDX 1.7.
2. If you validate against JSON schemas, switch to the CycloneDX 1.7 schema.
3. Ensure parsers ignore unknown fields for forward compatibility.
4. Update OCI referrer media types to the 1.7 values.

Compatibility notes

• CycloneDX 1.6 SBOMs are still accepted on ingest.
• CycloneDX 1.7 is the default output on Scanner and export surfaces.

References

• CycloneDX 1.7 specification: https://cyclonedx.org/docs/1.7/
• Scanner architecture: docs/modules/scanner/architecture.md
• SBOM service architecture: docs/modules/sbomservice/architecture.md