Review referenced document structure

[goneall]

Referencing artifacts in external documents seems to be structurally incompatible with the approach taken in SPDX.

Propose we review the 2 approaches (SBOM and SPDX) with concrete examples and determine if there are structural incompatibilities. If incompatible, propose changes to SBOM, SPDX or both.

[goneall]

SPDX has an additional class of ExternalDocumentRef and properties to manage the relationship between documents in a secure manner. SBOM takes a different approach which is structurally incompatible with the SPDX approach where the referenced item contains the package reference information.

Propose adding ExternalDocumentRef class.

[CASTResearchLabs]

Following the call on January 13, 2020,

1. here is the rationale behind the proposed modeling with the "referenceDocument" association from "ReferencedArtifact" class: this was following a graph-aware approach were main elements are nodes from a graph and are linked together; with this in mind, there was no need of a specific "ExternalDocumentRef" class.
2. I see two ways to align with SPDX: first one is to create such "ExternalDocumentRef" class, and change the "referenceDocument" attribute defition to be of type "ExternalDocumentRef" instead of "Document"; second one is to have an "AbstractDocument" class with two specializations, the current "Document" class and a new "ExternalDocumentRef" class, and change the "referenceDocument" attribute defition to be of type "AbstractDocument" instead of "Document" so that it can be another document (from the graph) or simply a reference to a document.

[goneall]

second one is to have an "AbstractDocument" class with two specializations, the current "Document" class and a new "ExternalDocumentRef" class, and change the "referenceDocument" attribute defition to be of type "AbstractDocument" instead of "Document" so that it can be another document (from the graph) or simply a reference to a document.

This approach seems very logical. If the ExternalDocumentRef had the same required parameters as the current SPDX ExternalDocumentRef, I believe the concrete documents would be compatible.

[kaywilliams]

Philippe-Emmanuel to update model for review.

[CASTResearchLabs]

as an illustration of how to contribute to the model, to perform the requested change, here is what I did:

1. update classes.json model JSON file to add the AbstractDocument and ExternalDocumentRef classes, and to change the generalisation link of the Document class to AbstractDocument class from Element class
2. update classes.attributes.json model JSON file to declare the attributes of the ExternalDocumentRef (no attribute for AbstractDocument although it could be that we move the signature, identifier, and namespace attributes to AbstractDocument if they are indeed shared between the Document and ExternalDocumentRef classes), to add a referencedDocuments attribute to the Document class and to change the type of the referenceDocument attribute of the ReferencedArtifact class to AbstractDocument class from Document class
3. run buildModel.R

I'll create a pull request with those two files ASAP

[CASTResearchLabs]

https://github.com/cdfoundation/sig-security-sbom/pull/20 for the two model JSON files

[goneall]

Looks good structurally, left a couple detail comments in the PR that, if accepted, would help compatibility.

[stevespringett]

FYI, references to external documents is not supported at all in CycloneDX. External resources, yes, but the BOM format requires all components to be identified in a single document. This is actually quite simple with CycloneDX due to its hierarchical nature. A supplier can add their components to a BOM, sign only their portion and it can continue on down the chain, each supplier signing their own respective part of the BOM. If the final goods assembler then wants to sign the entire BOM, then that can be done as well. Each signature can be validated for each portion of the BOM that each supplier has contributed to.

But attempting to resolve external documents is a non-starter in medium to high assurance environments that rely on automation, where build and security infrastructure typically has limited access to the outside world.

[goneall]

@stevespringett Thanks for the high assurance environment perspective.

I think the two approaches are compatible since you can always create a new SBOM and bring in all the elements you require.

The use cases that drove SPDX to support external documents were typically audit related where someone upstream would create a BOM for a distribution or package and someone downstream would provide an update, correction or a larger distribution. It was important that we could refer to the original unaltered and verified as unaltered bOM's.