Unclear definition of serialNumber and version

[mmarseu]

I find the interaction between the serialNumber and version of a BOM very unclear.

The definition in CycloneDX 1.5 says (highlighting mine):

• serialNumber

  Every BOM generated SHOULD have a unique serial number, even if the contents of the BOM have not changed over time. If specified, the serial number MUST conform to RFC-4122. Use of serial numbers are RECOMMENDED.

• version

  Whenever an existing BOM is modified, either manually or through automated processes, the version of the BOM SHOULD be incremented by 1. When a system is presented with multiple BOMs with identical serial numbers, the system SHOULD use the most recent version of the BOM. The default version is '1'.

The first implies that any time a BOM is written (even if nothing has changed), it gets a new serial. The second implies that the same serial can exist in several versions.

Given the definition of serialNumber, in which scenario would I modify a BOM and keep the old serial while incrementing the version?

Some other resources discussing serialNumber are #11 and #97 but in neither do I find an answer.

[stevespringett]

Given the definition of serialNumber, in which scenario would I modify a BOM and keep the old serial while incrementing the version?

In the event a minor modification to an existing BOM needs to be made. This use case was documented in section 3.2 of the NTIA SBOM Framing Document, which calls for:

The SBOM should also change when new SBOM information becomes available even if the components themselves have not changed.

CycloneDX handles this through the version. Together, the serialNumber and version form the BOMs identity.

See also: https://cyclonedx.org/guides/sbom/object-model/#bom-identity

[mmarseu]

In the event a minor modification to an existing BOM needs to be made. This use case was documented in section 3.2 of the NTIA SBOM Framing Document, which calls for:

The SBOM should also change when new SBOM information becomes available even if the components themselves have not changed.

CycloneDX handles this through the version. Together, the serialNumber and version form the BOMs identity.

Thank you for clarifying!

See also: https://cyclonedx.org/guides/sbom/object-model/#bom-identity

I found this, too, when looking for answers but it just reiterates what's written in the spec.

Would you be open to modifying the definition of serialNumber in the spec? Particularly the passage highlighted above is very confusing, in the sense that: "if a new serial number must be created even if nothing changes, the same must surely be done if something changes".

Are there any guidelines as to what constitutes a minor change (i.e., version bump) vs a major change (i.e., new serial)?

I'm a practitioner of SBOMs, not a spec writer. So my field-of-view of the SBOM's use cases is very narrow and only encompasses what we're aiming to use them for at our company. That said, I'm trying to get a feeling for how to handle SBOM versioning, so here's me, thinking out loud, and I hope you can give me some feedback:

In practice, I'm going to be searching for BOMs in some sort of repository based on the metadata.component identity (name, group, version, etc.). When looking for a BOM of some product, I'd like the latest version of that BOM, because that is going to be the most correct one.
The version field establishes a clear and simple supersedes / superseded-by relationship between BOMs with the same serial, giving me what I want, but only as long as there aren't multiple BOMs with different serials for the same product in the repository. If there are, I have no way to know which is the correct one.
That implies a 1:1 mapping of serial to metadata.component identity. A new serial would only ever be generated for new versions of the product.

With that in mind, the following requirements would serve our use case:

1. Adding any new information which was simply missing before is a MINOR change, even if that means adding a new component which had been forgotten
2. Fixing any erroneous information is a MINOR change
3. Any changes to vulnerabilities are MINOR
4. Real-world changes in the make-up of the product (e.g., new component, different component version, new dependency relationship) are MAJOR. This requires a new serial but any such change should result in a new product version, anyway, with a new BOM.

As somebody which a much broader view of SBOM use cases, would you say we're "doing CycloneDX wrong" by going this way?

[jkowalleck]

related: #474

[jkowalleck]

related: #97