feat: add support for properties in external references (#907)

part of #903


---------

Signed-off-by: Johannes Feichtner <johannes@web-wack.at>

Author: Churro

cyclonedx/model/__init__.py

@@ -835,11 +835,13 @@ def __init__(
         url: XsUri,
         comment: Optional[str] = None,
         hashes: Optional[Iterable[HashType]] = None,
+        properties: Optional[Iterable['Property']] = None,
     ) -> None:
         self.url = url
         self.comment = comment
         self.type = type
         self.hashes = hashes or []
+        self.properties = properties or []
 
     @property
     @serializable.xml_sequence(1)
@@ -909,10 +911,27 @@ def hashes(self) -> 'SortedSet[HashType]':
     def hashes(self, hashes: Iterable[HashType]) -> None:
         self._hashes = SortedSet(hashes)
 
+    @property
+    @serializable.view(SchemaVersion1Dot7)
+    @serializable.xml_array(serializable.XmlArraySerializationType.NESTED, 'property')
+    def properties(self) -> 'SortedSet[Property]':
+        """
+        Provides the ability to document properties in a key/value store. This provides flexibility to include data not
+        officially supported in the standard without having to use additional namespaces or create extensions.
+
+        Return:
+            Set of `Property`
+        """
+        return self._properties
+
+    @properties.setter
+    def properties(self, properties: Iterable['Property']) -> None:
+        self._properties = SortedSet(properties)
+
     def __comparable_tuple(self) -> _ComparableTuple:
         return _ComparableTuple((
             self._type, self._url, self._comment,
-            _ComparableTuple(self._hashes)
+            _ComparableTuple(self._hashes), _ComparableTuple(self.properties),
         ))
 
     def __eq__(self, other: object) -> bool:

tests/_data/models.py

@@ -588,7 +588,7 @@ def get_bom_just_complete_metadata() -> Bom:
 
 def get_bom_with_external_references() -> Bom:
     bom = _make_bom(external_references=[
-        get_external_reference_1(), get_external_reference_2()
+        get_external_reference_1(), get_external_reference_2(), get_external_reference_with_properties()
     ])
     return bom
 
@@ -896,6 +896,17 @@ def get_external_reference_2() -> ExternalReference:
     )
 
 
+def get_external_reference_with_properties() -> ExternalReference:
+    return ExternalReference(
+        type=ExternalReferenceType.VCS,
+        url=XsUri('https://cyclonedx.org'),
+        properties=[
+            Property(name='property_1', value='value_1'),
+            Property(name='property_2', value='value_2')
+        ]
+    )
+
+
 def get_issue_1() -> IssueType:
     return IssueType(
         type=IssueClassification.SECURITY, id='CVE-2021-44228', name='Apache Log3Shell',

tests/_data/snapshots/get_bom_with_external_references-1.1.xml.bin

@@ -6,6 +6,9 @@
       <url>https://cyclonedx.org</url>
       <comment>No comment</comment>
     </reference>
+    <reference type="vcs">
+      <url>https://cyclonedx.org</url>
+    </reference>
     <reference type="website">
       <url>https://cyclonedx.org</url>
     </reference>

tests/_data/snapshots/get_bom_with_external_references-1.2.json.bin

@@ -5,6 +5,10 @@
       "type": "distribution",
       "url": "https://cyclonedx.org"
     },
+    {
+      "type": "vcs",
+      "url": "https://cyclonedx.org"
+    },
     {
       "type": "website",
       "url": "https://cyclonedx.org"

tests/_data/snapshots/get_bom_with_external_references-1.2.xml.bin

@@ -8,6 +8,9 @@
       <url>https://cyclonedx.org</url>
       <comment>No comment</comment>
     </reference>
+    <reference type="vcs">
+      <url>https://cyclonedx.org</url>
+    </reference>
     <reference type="website">
       <url>https://cyclonedx.org</url>
     </reference>

tests/_data/snapshots/get_bom_with_external_references-1.3.json.bin

@@ -11,6 +11,10 @@
       "type": "distribution",
       "url": "https://cyclonedx.org"
     },
+    {
+      "type": "vcs",
+      "url": "https://cyclonedx.org"
+    },
     {
       "type": "website",
       "url": "https://cyclonedx.org"

tests/_data/snapshots/get_bom_with_external_references-1.3.xml.bin

@@ -11,6 +11,9 @@
         <hash alg="SHA-256">806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b</hash>
       </hashes>
     </reference>
+    <reference type="vcs">
+      <url>https://cyclonedx.org</url>
+    </reference>
     <reference type="website">
       <url>https://cyclonedx.org</url>
     </reference>

tests/_data/snapshots/get_bom_with_external_references-1.4.json.bin

@@ -11,6 +11,10 @@
       "type": "distribution",
       "url": "https://cyclonedx.org"
     },
+    {
+      "type": "vcs",
+      "url": "https://cyclonedx.org"
+    },
     {
       "type": "website",
       "url": "https://cyclonedx.org"

tests/_data/snapshots/get_bom_with_external_references-1.4.xml.bin

@@ -11,6 +11,9 @@
         <hash alg="SHA-256">806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b</hash>
       </hashes>
     </reference>
+    <reference type="vcs">
+      <url>https://cyclonedx.org</url>
+    </reference>
     <reference type="website">
       <url>https://cyclonedx.org</url>
     </reference>

tests/_data/snapshots/get_bom_with_external_references-1.5.json.bin

@@ -11,6 +11,10 @@
       "type": "distribution",
       "url": "https://cyclonedx.org"
     },
+    {
+      "type": "vcs",
+      "url": "https://cyclonedx.org"
+    },
     {
       "type": "website",
       "url": "https://cyclonedx.org"