CycloneDX#561: Add component and services for tools

CycloneDX spec 1.5 depcreated 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.

Signed-off-by: Joshua Kugler <[email protected]>

Author: jkugler

cyclonedx/model/bom.py

@@ -18,7 +18,7 @@
 
 from datetime import datetime
 from itertools import chain
-from typing import TYPE_CHECKING, Generator, Iterable, Optional, Union
+from typing import TYPE_CHECKING, Any, AnyStr, Dict, Generator, Iterable, Optional, Union
 from uuid import UUID, uuid4
 from warnings import warn
 
@@ -27,6 +27,7 @@
 
 from .._internal.time import get_now_utc as _get_now_utc
 from ..exception.model import LicenseExpressionAlongWithOthersException, UnknownComponentDependencyException
+from ..model.tool import Tool, ToolRepository, ToolRepositoryHelper
 from ..schema.schema import (
     SchemaVersion1Dot0,
     SchemaVersion1Dot1,
@@ -37,7 +38,7 @@
     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
@@ -59,7 +60,7 @@ class BomMetaData:
         See the CycloneDX Schema for Bom metadata: https://cyclonedx.org/docs/1.5/#type_metadata
     """
 
-    def __init__(self, *, tools: Optional[Iterable[Tool]] = None,
+    def __init__(self, *, tools: Optional[Union[Iterable[Tool], Dict[AnyStr, Any]]] = None,
                  authors: Optional[Iterable[OrganizationalContact]] = None, component: Optional[Component] = None,
                  supplier: Optional[OrganizationalEntity] = None,
                  licenses: Optional[Iterable[License]] = None,
@@ -115,22 +116,30 @@ def timestamp(self, timestamp: datetime) -> None:
     #    ... # TODO since CDX1.5
 
     @property
+    @serializable.type_mapping(ToolRepositoryHelper)
     @serializable.xml_array(serializable.XmlArraySerializationType.NESTED, 'tool')
     @serializable.xml_sequence(3)
-    def tools(self) -> 'SortedSet[Tool]':
+    def tools(self) -> ToolRepository:
         """
         Tools used to create this BOM.
 
         Returns:
             `Set` of `Tool` objects.
         """
-        # TODO since CDX1.5 also supports `Component` and `Services`, not only `Tool`
-        return self._tools
+        return self._tools  # type: ignore
 
     @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[ToolRepository, Iterable[Tool]]) -> None:
+        if isinstance(tools, ToolRepository):
+            self._tools = tools
+        else:
+            # This allows the old behavior of assigning the list of tools directly to bom.metadata.tools
+            warn(
+                '`bom.metadata.tools` as a list of Tool objects is deprecated from CycloneDX v1.5 '
+                'onwards. Please use lists of `Component` and `Service` objects as `tools.components` '
+                'and `tools.services`, respecitvely'
+            )
+            self._tools = ToolRepository(tools=tools)  # type:ignore
 
     @property
     @serializable.xml_array(serializable.XmlArraySerializationType.NESTED, 'author')

cyclonedx/model/tool.py

@@ -0,0 +1,232 @@
+from typing import Any, Dict, Iterable, List, Optional, Type, Union
+from xml.etree.ElementTree import Element  # nosec B405
+
+import serializable
+from serializable import ViewType
+from serializable.helpers import BaseHelper
+from sortedcontainers import SortedSet
+
+from .._internal.compare import ComparableTuple as _ComparableTuple
+from ..exception.serialization import CycloneDxDeserializationException, SerializationOfUnexpectedValueException
+from ..model import ExternalReference, HashType, _HashTypeRepositorySerializationHelper
+from ..model.component import Component
+from ..model.service import Service
+from ..schema.schema import SchemaVersion1Dot4, SchemaVersion1Dot5, SchemaVersion1Dot6
+
+
+@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)
+    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)
+    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)
+    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}>'
+
+
+class ToolRepository:
+    """
+    The repo of tool formats
+    """
+
+    def __init__(self, *, components: Optional[Iterable[Component]] = None,
+                 services: Optional[Iterable[Service]] = None,
+                 tools: Optional[Iterable[Tool]] = None) -> None:
+        self._components = components or SortedSet()
+        self._services = services or SortedSet()
+        # Must use components/services or tools. Cannot use both
+        self._tools = tools or SortedSet()
+
+    def __getattr__(self, name: str) -> Any:
+        if name == 'components':
+            return self._components
+        if name == 'services':
+            return self._services
+
+        return getattr(self._tools, name)
+
+    def __iter__(self) -> Tool:
+        for t in self._tools:
+            yield t
+
+
+class ToolRepositoryHelper(BaseHelper):
+    @classmethod
+    def json_normalize(cls, o: ToolRepository, *,
+                       view: Optional[Type[ViewType]],
+                       **__: Any) -> Any:
+        if not any([o._tools, o._components, o._services]):  # pylint: disable=protected-access
+            return None
+
+        if o._tools and any([o._components, o._services]):  # pylint: disable=protected-access
+            raise SerializationOfUnexpectedValueException(
+                'Cannot serialize both old (CycloneDX <= 1.4) and new '
+                '(CycloneDX >= 1.5) format for tools: {o!r}'
+            )
+
+        if o._tools:  # pylint: disable=protected-access
+            return [Tool.as_json(t) for t in o._tools]  # pylint: disable=protected-access
+
+        result = {}
+
+        if o._components:  # pylint: disable=protected-access
+            result['components'] = [Component.as_json(c) for c in o._components]  # pylint: disable=protected-access
+
+        if o._services:  # pylint: disable=protected-access
+            result['services'] = [Service.as_json(s) for s in o._services]  # pylint: disable=protected-access
+
+        return result
+
+    @classmethod
+    def json_denormalize(cls, o: Union[List[Dict[str, Any]], Dict[str, Any]],
+                         **__: Any) -> ToolRepository:
+
+        components = []
+        services = []
+        tools = []
+
+        if isinstance(o, Dict):
+            if 'components' in o:
+                for c in o['components']:
+                    components.append(Component.from_json(c))
+
+            if 'services' in o:
+                for s in o['services']:
+                    services.append(Service.from_json(s))
+
+        elif isinstance(o, Iterable):
+            for t in o:
+                tools.append(Tool.from_json(t))
+        else:
+            raise CycloneDxDeserializationException('unexpected: {o!r}')
+
+        return ToolRepository(components=components, services=services, tools=tools)
+
+    @classmethod
+    def xml_normalize(cls, o: ToolRepository, *,
+                      element_name: str,
+                      view: Optional[Type[ViewType]],
+                      xmlns: Optional[str],
+                      **__: Any) -> Optional[Element]:
+        pass
+
+    @classmethod
+    def xml_denormalize(cls, o: Element,
+                        default_ns: Optional[str],
+                        **__: Any) -> ToolRepository:
+        return ToolRepository()