feat: support for Metadata.tools format intrduced with CDX 1.5

[WIStudent]

v1.5 introduced a new format for the metadata.tools field: https://cyclonedx.org/docs/1.5/json/#metadata_tools

It seems that @cyclonedx/cyclonedx-library currently only supports the legacy format:

cyclonedx-javascript-library/src/models/metadata.ts

Line 31 in bdbe727

tools?: Metadata['tools']

cyclonedx-javascript-library/src/models/metadata.ts

Line 43 in bdbe727

tools: ToolRepository

cyclonedx-javascript-library/src/models/tool.ts

Lines 25 to 59 in bdbe727

	export interface OptionalToolProperties {
	vendor?: Tool['vendor']
	name?: Tool['name']
	version?: Tool['version']
	hashes?: Tool['hashes']
	externalReferences?: Tool['externalReferences']
	}
	export class Tool implements Comparable<Tool> {
	vendor?: string
	name?: string
	version?: string
	hashes: HashDictionary
	externalReferences: ExternalReferenceRepository
	constructor (op: OptionalToolProperties = {}) {
	this.vendor = op.vendor
	this.name = op.name
	this.version = op.version
	this.hashes = op.hashes ?? new HashDictionary()
	this.externalReferences = op.externalReferences ?? new ExternalReferenceRepository()
	}
	compare (other: Tool): number {
	// The purpose of this method is not to test for equality, but have deterministic comparability.
	/* eslint-disable @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
	return (this.vendor ?? '').localeCompare(other.vendor ?? '') ||
	(this.name ?? '').localeCompare(other.name ?? '') ||
	(this.version ?? '').localeCompare(other.version ?? '')
	/* eslint-enable @typescript-eslint/strict-boolean-expressions */
	}
	}
	export class ToolRepository extends SortableComparables<Tool> {
	}

This prevents other tools like @cyclonedx/cyclonedx-npm from creating v1.5 or v1.6 SBOMs with the new tools format.

[jkowalleck]

The expected result would be a data model ToolRepository, that has the following capabilities:

• hold multiple instances of Tool -- the model for Tool already exists
• hold multiple instances of Component -- the model for Component already exists
• hold multiple instances of Service -- the model for Service does not yet exist

This new ToolRepository would be serialized to JSON/XML like following:

• If at least one Tool is included,
  or the serialization targets a spec before CDX 1.5:
  • Is serialized as a list of Tools.
  • all Tools held are serialized as they are.
  • all Components and Services held are serialized as Tool, too.
• else:
  • Is serialized as a collection of Components and Services.
  • all Components and Services held are serialized as they are.
  • no Tool is serialized.

Architecture-wise, the following new static function would be created:

• Tool.fromCromponent(component: ReadOnly<Component>): Tool
• Tool.fromService(service: ReadOnly<Service>): Tool

Since the new data model - regardless if it reuses the existing name ToolRepository - would be the type of existing property Metadata.tools.
Therefore, this is considered a breaking change. (no show-stopper, just a remark).

Services are a feature of #1164

[jkowalleck]

Thank you for the feature request, @WIStudent .
Is this a thing you plan on contributing?

[WIStudent]

@jkowalleck I am currently not planing to implement this, I am still evaluating if CycloneDX is the right tool for my usecase. I ran into this problem when I was trying to merge two SBOMs that were created with @cyclonedx/node-npm and cyclonedx-maven-plugin using the cyclonedx-cli. When creating a v1.6 SBOM, cyclonedx-maven-plugin uses the new tools format while @cyclonedx/node-npm uses the legacy format. The cyclonedx-cli is not able to merge new and legacy format correctly. I was looking into @cyclonedx/node-npm to see if there is an option to force the usage of the new format, but realized that @cyclonedx/cyclonedx-library needs to support the new format first.

For now I am telling cyclonedx-maven-plugin to generate a v1.4 SBOM, that way all tools fields use the legacy format and can be merged with the cyclonedx-cli.

[jkowalleck]

regardles of this very feature request here:

The cyclonedx-cli is not able to merge new and legacy format correctly.

Could you report this use case and the expected outcome to cyclonedx-cli? The project team then might decide whether this is a feature request or a bug report, and how to proceed.

[WIStudent]

For completeness: Here is the issue I opened in cyclonedx-cli CycloneDX/cyclonedx-cli#408

[jkowalleck]

downstream usage as requested: CycloneDX/cyclonedx-node-npm#1233

[jkowalleck]

I will work on a solution. stay tuned 🚀

[jkowalleck]

feature preview available as of https://github.com/CycloneDX/cyclonedx-javascript-library/releases/tag/v7.0.0-beta.1