feat!: Add component and services for tools (#635)

CycloneDX spec 1.5 deprecated an array of tools in bom.metadata and
instead prefers object with an array of components and an array of
services.

This PR implements that.

This works de-serializing a Syft SBOM with a tool section like so:
```
  "metadata": {
    "timestamp": "2024-06-10T13:06:52-08:00",
    "tools": {
      "components": [
        {
          "type": "application",
          "author": "anchore",
          "name": "syft",
          "version": "1.4.1"
        }
      ]
    },
    "component": {
      "bom-ref": "08329a07b4eb8eac",
      "type": "file",
      "name": "./"
    }
  },
```
Next up: docs, XML (de)serialization code, and tests.

fixes #561

---------

Signed-off-by: Joshua Kugler <[email protected]>
Signed-off-by: Jan Kowalleck <[email protected]>
Co-authored-by: Jan Kowalleck <[email protected]>

Author: jkugler

cyclonedx/model/__init__.py

@@ -1127,139 +1127,6 @@ def __repr__(self) -> str:
         return f'<Note id={id(self)}, locale={self.locale}>'
 
 
-@serializable.serializable_class
-class Tool:
-    """
-    This is our internal representation of the `toolType` complex type within the CycloneDX standard.
-
-    Tool(s) are the things used in the creation of the CycloneDX document.
-
-    Tool might be deprecated since CycloneDX 1.5, but it is not deprecated in this library.
-    In fact, this library will try to provide a compatibility layer if needed.
-
-    .. note::
-        See the CycloneDX Schema for toolType: https://cyclonedx.org/docs/1.3/#type_toolType
-    """
-
-    def __init__(
-        self, *,
-        vendor: Optional[str] = None,
-        name: Optional[str] = None,
-        version: Optional[str] = None,
-        hashes: Optional[Iterable[HashType]] = None,
-        external_references: Optional[Iterable[ExternalReference]] = None,
-    ) -> None:
-        self.vendor = vendor
-        self.name = name
-        self.version = version
-        self.hashes = hashes or []  # type:ignore[assignment]
-        self.external_references = external_references or []  # type:ignore[assignment]
-
-    @property
-    @serializable.xml_sequence(1)
-    @serializable.xml_string(serializable.XmlStringSerializationType.NORMALIZED_STRING)
-    def vendor(self) -> Optional[str]:
-        """
-        The name of the vendor who created the tool.
-
-        Returns:
-            `str` if set else `None`
-        """
-        return self._vendor
-
-    @vendor.setter
-    def vendor(self, vendor: Optional[str]) -> None:
-        self._vendor = vendor
-
-    @property
-    @serializable.xml_sequence(2)
-    @serializable.xml_string(serializable.XmlStringSerializationType.NORMALIZED_STRING)
-    def name(self) -> Optional[str]:
-        """
-        The name of the tool.
-
-        Returns:
-             `str` if set else `None`
-        """
-        return self._name
-
-    @name.setter
-    def name(self, name: Optional[str]) -> None:
-        self._name = name
-
-    @property
-    @serializable.xml_sequence(3)
-    @serializable.xml_string(serializable.XmlStringSerializationType.NORMALIZED_STRING)
-    def version(self) -> Optional[str]:
-        """
-        The version of the tool.
-
-        Returns:
-             `str` if set else `None`
-        """
-        return self._version
-
-    @version.setter
-    def version(self, version: Optional[str]) -> None:
-        self._version = version
-
-    @property
-    @serializable.type_mapping(_HashTypeRepositorySerializationHelper)
-    @serializable.xml_sequence(4)
-    def hashes(self) -> 'SortedSet[HashType]':
-        """
-        The hashes of the tool (if applicable).
-
-        Returns:
-            Set of `HashType`
-        """
-        return self._hashes
-
-    @hashes.setter
-    def hashes(self, hashes: Iterable[HashType]) -> None:
-        self._hashes = SortedSet(hashes)
-
-    @property
-    @serializable.view(SchemaVersion1Dot4)
-    @serializable.view(SchemaVersion1Dot5)
-    @serializable.view(SchemaVersion1Dot6)
-    @serializable.xml_array(serializable.XmlArraySerializationType.NESTED, 'reference')
-    @serializable.xml_sequence(5)
-    def external_references(self) -> 'SortedSet[ExternalReference]':
-        """
-        External References provides a way to document systems, sites, and information that may be relevant but which
-        are not included with the BOM.
-
-        Returns:
-            Set of `ExternalReference`
-        """
-        return self._external_references
-
-    @external_references.setter
-    def external_references(self, external_references: Iterable[ExternalReference]) -> None:
-        self._external_references = SortedSet(external_references)
-
-    def __eq__(self, other: object) -> bool:
-        if isinstance(other, Tool):
-            return hash(other) == hash(self)
-        return False
-
-    def __lt__(self, other: Any) -> bool:
-        if isinstance(other, Tool):
-            return _ComparableTuple((
-                self.vendor, self.name, self.version
-            )) < _ComparableTuple((
-                other.vendor, other.name, other.version
-            ))
-        return NotImplemented
-
-    def __hash__(self) -> int:
-        return hash((self.vendor, self.name, self.version, tuple(self.hashes), tuple(self.external_references)))
-
-    def __repr__(self) -> str:
-        return f'<Tool name={self.name}, version={self.version}, vendor={self.vendor}>'
-
-
 @serializable.serializable_class
 class IdentifiableAction:
     """
@@ -1397,6 +1264,9 @@ def __repr__(self) -> str:
         return f'<Copyright text={self.text}>'
 
 
+# Importing here to avoid a circular import
+from .tool import Tool  # pylint: disable=wrong-import-position # noqa: E402
+
 ThisTool = Tool(
     vendor='CycloneDX',
     name='cyclonedx-python-lib',
@@ -1434,4 +1304,5 @@ def __repr__(self) -> str:
             type=ExternalReferenceType.WEBSITE,
             url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/#readme')
         )
-    ])
+    ]
+)

cyclonedx/model/bom.py

@@ -37,13 +37,14 @@
     SchemaVersion1Dot6,
 )
 from ..serialization import LicenseRepositoryHelper, UrnUuidHelper
-from . import ExternalReference, Property, ThisTool, Tool
+from . import ExternalReference, Property, ThisTool
 from .bom_ref import BomRef
 from .component import Component
 from .contact import OrganizationalContact, OrganizationalEntity
 from .dependency import Dependable, Dependency
 from .license import License, LicenseExpression, LicenseRepository
 from .service import Service
+from .tool import Tool, ToolsRepository, _ToolsRepositoryHelper
 from .vulnerability import Vulnerability
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -61,7 +62,7 @@ class BomMetaData:
 
     def __init__(
         self, *,
-        tools: Optional[Iterable[Tool]] = None,
+        tools: Optional[Union[Iterable[Tool], ToolsRepository]] = None,
         authors: Optional[Iterable[OrganizationalContact]] = None,
         component: Optional[Component] = None,
         supplier: Optional[OrganizationalEntity] = None,
@@ -89,7 +90,7 @@ def __init__(
                 DeprecationWarning)
 
         if not tools:
-            self.tools.add(ThisTool)
+            self.tools.tools.add(ThisTool)
 
     @property
     @serializable.type_mapping(serializable.helpers.XsdDateTime)
@@ -119,22 +120,22 @@ def timestamp(self, timestamp: datetime) -> None:
     #    ... # TODO since CDX1.5
 
     @property
-    @serializable.xml_array(serializable.XmlArraySerializationType.NESTED, 'tool')
+    @serializable.type_mapping(_ToolsRepositoryHelper)
     @serializable.xml_sequence(3)
-    def tools(self) -> 'SortedSet[Tool]':
+    def tools(self) -> ToolsRepository:
         """
         Tools used to create this BOM.
 
         Returns:
-            `Set` of `Tool` objects.
+            `ToolsRepository` objects.
         """
-        # TODO since CDX1.5 also supports `Component` and `Services`, not only `Tool`
         return self._tools
 
     @tools.setter
-    def tools(self, tools: Iterable[Tool]) -> None:
-        # TODO since CDX1.5 also supports `Component` and `Services`, not only `Tool`
-        self._tools = SortedSet(tools)
+    def tools(self, tools: Union[Iterable[Tool], ToolsRepository]) -> None:
+        self._tools = tools \
+            if isinstance(tools, ToolsRepository) \
+            else ToolsRepository(tools=tools)
 
     @property
     @serializable.xml_array(serializable.XmlArraySerializationType.NESTED, 'author')
@@ -292,7 +293,7 @@ def __eq__(self, other: object) -> bool:
     def __hash__(self) -> int:
         return hash((
             tuple(self.authors), self.component, tuple(self.licenses), self.manufacture, tuple(self.properties),
-            self.supplier, self.timestamp, tuple(self.tools), self.manufacturer,
+            self.supplier, self.timestamp, self.tools, self.manufacturer,
         ))
 
     def __repr__(self) -> str: