adr for external references

docs/adrs/00003-external-references.md

@@ -0,0 +1,115 @@
+# 00003. References to external SBOMs
+
+Date: 2025-01-24
+
+## Status
+DRAFT
+
+## Context
+
+Having the ability of an SBOM to cross reference to other SBOM 
+
+![Multiple sboms](product-component-sbom.png)
+
+Is not just a feature for managing complex distributions of SBOMs but also allows the extension of authority of an originating SBOM
+to apply additive approach reusing information from other SBOMs.
+
+### SPDX  
+For SPDX, external documents are listed in the externalDocumentRefs element.
+
+```json
+{
+  "SPDXID": "SPDXRef-DOCUMENT",
+  "SPDXVersion": "SPDX-2.3",
+  "dataLicense": "CC0-1.0",
+  "documentNamespace": "http://spdx.org/spdxdocs/example-sbom-1.0",
+  "documentName": "Example SBOM",
+  "packages": [
+    {
+      "name": "PackageA",
+      "SPDXID": "SPDXRef-PackageA",
+      "versionInfo": "3.8.1",
+      "originator": "Organization: JUnit",
+      "downloadLocation": "NOASSERTION",
+      "filesAnalyzed": false,
+      "homepage": "http://example.org",
+      "licenseConcluded": "NOASSERTION",
+      "licenseDeclared": "CPL-1.0",
+      "copyrightText": "UNSPECIFIED",
+      "summary": "",
+      "description": ""
+    }
+  ],
+  "externalDocumentRefs": [
+    {
+      "externalDocumentRef": "SPDXRef-OtherPackages",
+      "spdxDocument" : "http://spdx.org/spdxdocs/another-sbom-1.0",
+      "documentName": "Another SBOM",
+      "checksum" : {
+        "algorithm" : "SHA1",
+        "checksumValue" : "f2d13e3f9deeef2e3aefdc216f5c4ebb0eb4b152"
+      },
+      "documentVersion": "1.0",
+      "comment": "PackageB is defined in this external SBOM."
+    }
+  ],
+  "relationships": [
+    {
+      "RelationshipType": "DEPENDS_ON",
+      "RelatedSpdxElement": "SPDXRef-OtherPackages:SPDXRef-PackageB",
+      "SpdxElement": "SPDXRef-PackageA"
+    }
+  ]
+}
+```
+This SBOM asserts a relationship to a package in another SBOM ( _SPDXRef-PackageA_ **DEPENDS_ON** _SPDXRef-OtherPackages:SPDXRef-PackageB_) - which should not be considered bi-directional eg the 'authority' of 
+this SBOM is germane to the original SBOM.
+
+A few other spdx `externalDocumentRefs` examples:
+* https://github.com/spdx/spdx-examples/blob/7173f3148dc8a0fdf9397e676611b1e3cd116c66/software/example14/spdx2.3/examplemaven-0.0.1-enriched.spdx.json#L17
+* https://github.com/spdx/spdx-examples/blob/master/software/example7/spdx2.2/example7-bin.spdx.json
+
+Using the following properties of spdx SBOM:
+- **externalDocumentRef**: brings in components from external namespace
+- **spdxDocument**: concat with SPDXID is addressing mechanism 
+- **checksum**: external document's Checksum/digest/hash ensuring unique match
+
+We should be able to provide an unambiguous internal mapping from with which to locate and relate a package in an external SBOM.
+
+When a checksum is not directly embedded in the `externalDocumentRef` we can assist the heuristic by using an externally generated checksum.
+
+### CycloneDX
+
+externalReference, bom-link
+
+
+
+
+### Red Hat specific
+
+There are some Red Hat specific scenarios, using cyclonedx, where we would like to establish a multi sbom relationship based on denotion of 
+**evidence.identity**.
+
+
+## Decision
+
+
+sbom_external_node table
+- Checksum/digest/hash
+
+
+sbom_node where node_id is a symbolic link (document namespace + uuid)
+
+## Alternative approaches
+
+* drop FK
+* amend current table
+
+## Consequences
+
+* Having a general locator on any package/component in an SBOM useful for engineers wanting to know 'where' a package is
+* chain of product-x.y.z->component-1.2.3->component-blue-5.6.7->VULNERABLE(component-red.987)
+* do changes to the document must result in a new namespace in known sbom producer systems ?
+* package_relates_to_package should have been named node_relates_to_node ;)
+* reverse relationships are out of scope
+* The UX should over time start using the api/v2/analysis endpoints