Merge pull request #267 from CycloneDX/feat/bomlink-urn-helper-methods

feat: allow version of BOM to be defined

feat: allow serial_number of BOM to be prescribed

feat: add helper method to get URN for a BOM according to https://www.iana.org/assignments/urn-formal/cdx

Author: madpah

cyclonedx/model/bom.py

@@ -233,19 +233,21 @@ def from_parser(parser: BaseParser) -> 'Bom':
 
     def __init__(self, *, components: Optional[Iterable[Component]] = None,
                  services: Optional[Iterable[Service]] = None,
-                 external_references: Optional[Iterable[ExternalReference]] = None) -> None:
+                 external_references: Optional[Iterable[ExternalReference]] = None,
+                 serial_number: Optional[UUID] = None, version: int = 1) -> None:
         """
         Create a new Bom that you can manually/programmatically add data to later.
 
         Returns:
             New, empty `cyclonedx.model.bom.Bom` instance.
         """
-        self.uuid = uuid4()
+        self.uuid = serial_number or uuid4()
         self.metadata = BomMetaData()
         self.components = components or []  # type: ignore
         self.services = services or []  # type: ignore
         self.external_references = external_references or []  # type: ignore
         self.vulnerabilities = SortedSet()
+        self.version = version
 
     @property
     def uuid(self) -> UUID:
@@ -317,7 +319,7 @@ def get_urn_uuid(self) -> str:
         Returns:
             URN formatted UUID that uniquely identified this Bom instance.
         """
-        return 'urn:uuid:{}'.format(self.__uuid)
+        return self.__uuid.urn
 
     def has_component(self, component: Component) -> bool:
         """
@@ -401,6 +403,17 @@ def vulnerabilities(self) -> "SortedSet[Vulnerability]":
     def vulnerabilities(self, vulnerabilities: Iterable[Vulnerability]) -> None:
         self._vulnerabilities = SortedSet(vulnerabilities)
 
+    @property
+    def version(self) -> int:
+        return self._version
+
+    @version.setter
+    def version(self, version: int) -> None:
+        self._version = version
+
+    def urn(self) -> str:
+        return f'urn:cdx:{self.uuid}/{self.version}'
+
     def validate(self) -> bool:
         """
         Perform data-model level validations to make sure we have some known data integrity prior to attempting output

tests/test_model_bom.py

@@ -18,6 +18,7 @@
 # Copyright (c) OWASP Foundation. All Rights Reserved.
 
 from unittest import TestCase
+from uuid import uuid4
 
 from data import get_bom_with_component_setuptools_with_vulnerability
 
@@ -96,6 +97,7 @@ def test_bom_metadata_tool_multiple_tools(self) -> None:
         bom.metadata.tools.add(
             Tool(vendor='TestVendor', name='TestTool', version='0.0.0')
         )
+        self.assertEqual(bom.version, 1)
         self.assertEqual(len(bom.metadata.tools), 2)
 
     def test_metadata_component(self) -> None:
@@ -108,12 +110,29 @@ def test_metadata_component(self) -> None:
 
     def test_empty_bom(self) -> None:
         bom = Bom()
+        self.assertEqual(bom.version, 1)
         self.assertIsNotNone(bom.uuid)
         self.assertIsNotNone(bom.metadata)
         self.assertFalse(bom.components)
         self.assertFalse(bom.services)
         self.assertFalse(bom.external_references)
 
+    def test_empty_bom_defined_serial(self) -> None:
+        serial_number = uuid4()
+        bom = Bom(serial_number=serial_number)
+        self.assertEqual(bom.uuid, serial_number)
+        self.assertEqual(bom.get_urn_uuid(), serial_number.urn)
+        self.assertEqual(bom.version, 1)
+        self.assertEqual(bom.urn(), f'urn:cdx:{serial_number}/1')
+
+    def test_empty_bom_defined_serial_and_version(self) -> None:
+        serial_number = uuid4()
+        bom = Bom(serial_number=serial_number, version=2)
+        self.assertEqual(bom.uuid, serial_number)
+        self.assertEqual(bom.get_urn_uuid(), serial_number.urn)
+        self.assertEqual(bom.version, 2)
+        self.assertEqual(bom.urn(), f'urn:cdx:{serial_number}/2')
+
     def test_bom_with_vulnerabilities(self) -> None:
         bom = get_bom_with_component_setuptools_with_vulnerability()
         self.assertTrue(bom.has_vulnerabilities())