Auto-Annotations of SBOMs by Editing Tools

[riteshnoronha]

As SBOMs move through a pipeline, it would be highly beneficial to track how and what changes are made. Currently, I don’t believe any open-source tools automatically add annotations when they modify an SBOM, even though both major SBOM specifications (SPDX, CycloneDX) treat annotations as first-class objects, which can be used for exactly this purpose.

Minimum Annotation Guidelines:

Tool Identification: If a tool edits an SBOM, it should first add itself to the list of creators.

Detailed Change Tracking: Any changes to a component, dependency, or document should be annotated at the most granular level possible.

For example, if a supplier is added or removed for a component, the component itself should have an annotation noting this change.

Fallback to Document-Level Annotations: If specific details of a change cannot be captured at the component level, the annotation should be applied at the document level.

SBOMASM Approach:

In SBOMASM, we are implementing automatic annotations for every edit made. We are also introducing a new feature that allows for manual annotations, in case an editing tool does not natively support auto-annotations.

Example Annotation:
The following command in SBOMASM demonstrates how an edit would be tracked:

sbomasm edit --subject component-name-version --search "abc (v1.0.0)" --purl "pkg:deb/debian/[email protected]" in-sbom-3.json

This would produce an SBOM with the following annotation:

"annotations": [
    {
      "annotator": "Tool: sbomasm-v0.1.6",
      "annotationDate": "2024-10-14T14:00:00Z",
      "annotationType": "REVIEW",
      "comment": "Added purl",
      "SPDXID": "SPDXRef-Packages-abc-ABCDEFG"
    }
]

This ensures that every change is traceable, making the SBOM evolution transparent throughout the pipeline.

Would love your thoughts on this topic.

[vpetersson]

Generally speaking, I like this. Will raise it in today's call. My biggest concern would be lack support of this across tools.

[riteshnoronha]

Yes lack of support across tools is a problem for sure. For sbomasm i plan to add manual annotation command, so atleast in the reference implementation a makeshift solution can exist. If using the reference implementation an SBOM reaches the end-user and if the data turns out to be bad or misleading, they may end up thinking the generator is a fault, or maybe i am overthinking all of this :) lol