adr for external references

docs/adrs/00003-external-references.md

@@ -0,0 +1,100 @@
+# 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 to extend the authority of an originating SBOM
+to use an additive approach reusing information from other SBOMs.
+
+### SPDX  
+For SPDX, external documents are listed in the externalDocumentRefs element.
+
+```json
+{
+  "SPDXVersion": "SPDX-2.3",
+  "dataLicense": "CC0-1.0",
+  "documentNamespace": "http://spdx.org/spdxdocs/example-sbom-1.0",
+  "documentName": "Example SBOM",
+  "Creator": [
+    "Tool: SPDX-Generator-1.0"
+  ],
+  "Created": "2023-10-01T12:00:00Z",
+  "packages": [
+    {
+      "PackageName": "PackageA",
+      "SPDXID": "SPDXRef-PackageA",
+      "PackageVersion": "1.0.0",
+      "PackageDownloadLocation": "https://example.com/packageA",
+      "PackageLicenseConcluded": "MIT",
+      "PackageLicenseInfoFromFiles": [
+        "MIT"
+      ]
+    }
+  ],
+  "externalDocumentRefs": [
+    {
+      "externalDocumentRef": "SPDXRef-OtherPackages",
+      "documentNamespace": "http://spdx.org/spdxdocs/another-sbom-1.0",
+      "documentName": "Another SBOM",
+      "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 - 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 the external SBOM:
+- externalDocumentRef
+- documentNamespace
+- The external document's Checksum/digest/hash
+
+We should be able to provide an unambiguous internal mapping from with which to relate between.
+
+
+### CycloneDX
+
+externalReference, bom-link
+
+## 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