Support for CycloneDX schema version 1.4

cyclonedx/exception/model.py

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+"""
+Exceptions relating to specific conditions that occur when modelling CycloneDX BOM.
+"""
+
+from . import CycloneDxException
+
+
+class InvalidLocaleTypeException(CycloneDxException):
+    """
+    Raised when the supplied locale does not conform to ISD-639 specification.
+
+    Good examples:
+        - en
+        - en-US
+        - en-GB
+        - fr
+        - fr-CA
+
+    The language code MUST be lower case. If the country code is specified, the country code MUST be upper case.
+    The language code and country code MUST be separated by a minus sign.
+    """
+    pass
+
+
+class InvalidUriException(CycloneDxException):
+    """
+    Raised when a `str` is provided that needs to be a valid URI, but isn't.
+    """
+    pass

cyclonedx/exception/output.py

@@ -0,0 +1,30 @@
+# encoding: utf-8
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+"""
+Exceptions that are for specific error scenarios during the output of a Model to a SBOM.
+"""
+
+from . import CycloneDxException
+
+
+class ComponentVersionRequiredException(CycloneDxException):
+    """
+    Exception raised when attempting to output to an SBOM version that mandates a Component has a version,
+    but one is not available/present.
+    """
+    pass

cyclonedx/model/__init__.py

@@ -16,9 +16,11 @@
 #
 
 import hashlib
+import re
 from enum import Enum
-from typing import List, Union
+from typing import List, Optional, Union
 
+from ..exception.model import InvalidLocaleTypeException, InvalidUriException
 from ..exception.parser import UnknownHashTypeException
 
 """
@@ -28,6 +30,8 @@
 from a `cyclonedx.parser.BaseParser` implementation.
 """
 
+LOCALE_TYPE_REGEX = re.compile(r'^([a-z]{2})(-[A-Z]{2})?$')
+
 
 def sha1sum(filename: str) -> str:
     """
@@ -47,6 +51,16 @@ def sha1sum(filename: str) -> str:
     return h.hexdigest()
 
 
+class Encoding(Enum):
+    """
+    This is out internal representation of the encoding simple type within the CycloneDX standard.
+
+    .. note::
+        See the CycloneDX Schema: https://cyclonedx.org/docs/1.4/#type_encoding
+    """
+    BASE_64 = 'base64'
+
+
 class HashAlgorithm(Enum):
     """
     This is out internal representation of the hashAlg simple type within the CycloneDX standard.
@@ -154,6 +168,28 @@ class ExternalReferenceType(Enum):
     WEBSITE = 'website'
 
 
+class XsUri:
+    """
+    Helper class that allows us to perform validation on data strings that are defined as xs:anyURI
+    in CycloneDX schema.
+
+    .. note::
+        See XSD definition for xsd:anyURI: http://www.datypic.com/sc/xsd/t-xsd_anyURI.html
+    """
+
+    invalid_uri_regex = re.compile("(%(?![0-9A-F]{2})|#.*#)", re.IGNORECASE + re.MULTILINE)
+
+    def __init__(self, uri: str) -> None:
+        if re.search(XsUri.invalid_uri_regex, uri):
+            raise InvalidUriException(
+                f"Supplied value '{uri}' does not appear to be a valid URI."
+            )
+        self._uri = uri
+
+    def __repr__(self) -> str:
+        return self._uri
+
+
 class ExternalReference:
     """
     This is out internal representation of an ExternalReference complex type that can be used in multiple places within
@@ -218,3 +254,136 @@ def get_url(self) -> str:
 
     def __repr__(self) -> str:
         return f'<ExternalReference {self._reference_type.name}, {self._url}> {self._hashes}'
+
+
+class IssueClassification(Enum):
+    """
+    This is out internal representation of the enum `issueClassification`.
+
+    .. note::
+        See the CycloneDX Schema definition: hhttps://cyclonedx.org/docs/1.4/xml/#type_issueClassification
+    """
+    DEFECT = 'defect'
+    ENHANCEMENT = 'enhancement'
+    SECURITY = 'security'
+
+
+class IssueType:
+    """
+    This is out internal representation of an IssueType complex type that can be used in multiple places within
+    a CycloneDX BOM document.
+
+    .. note::
+        See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.4/xml/#type_issueType
+    """
+
+    def __init__(self, classification: IssueClassification, id: Optional[str] = None, name: Optional[str] = None,
+                 description: Optional[str] = None, source_name: Optional[str] = None,
+                 source_url: Optional[XsUri] = None, references: Optional[List[XsUri]] = None) -> None:
+        self._classification: IssueClassification = classification
+        self._id: Optional[str] = id
+        self._name: Optional[str] = name
+        self._description: Optional[str] = description
+        self._source_name: Optional[str] = source_name
+        self._source_url: Optional[XsUri] = source_url
+        self._references: Optional[List[XsUri]] = references
+
+
+class Property:
+    """
+    This is out internal representation of `propertyType` complex type that can be used in multiple places within
+    a CycloneDX BOM document.
+
+    .. note::
+        See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.4/xml/#type_propertyType
+
+    Specifies an individual property with a name and value.
+    """
+
+    def __init__(self, name: str, value: str) -> None:
+        self._name = name
+        self._value = value
+
+    def get_name(self) -> str:
+        """
+        Get the name of this Property.
+
+        Returns:
+            Name of this Property as `str`.
+        """
+        return self._name
+
+    def get_value(self) -> str:
+        """
+        Get the value of this Property.
+
+        Returns:
+            Value of this Property as `str`.
+        """
+        return self._value
+
+
+class Properties:
+    """
+    This is out internal representation of `propertiesType` complex type that can be used in multiple places within
+    a CycloneDX BOM document.
+
+    .. note::
+        See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.4/xml/#type_propertiesType
+
+    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.
+    """
+
+    def __init__(self, properties: Optional[List[Property]] = None) -> None:
+        if properties:
+            self._properties = properties
+        else:
+            self._properties = []
+
+    def add_property(self, prop: Property) -> None:
+        """
+        Add a Property to this list of Properties.
+
+        Args:
+            prop:
+                `Property` to add
+
+        Returns:
+            None
+        """
+        self._properties.append(prop)
+
+    def get_properties(self) -> List[Property]:
+        """
+        Get all Property instances in this List.
+
+        Returns:
+             List of `Property` objects, or an empty List.
+        """
+        return self._properties
+
+
+class Note:
+    """
+    This is out internal representation of the Note complex type that can be used in multiple places within
+    a CycloneDX BOM document.
+
+    .. note::
+        See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.4/xml/#type_releaseNotesType
+    """
+
+    def __init__(self, text: str, locale: Optional[str] = None, content_type: Optional[str] = None,
+                 content_encoding: Optional[Encoding] = None) -> None:
+        self._text: str = text
+        self._locale: Optional[str] = None
+        self._content_type: Optional[str] = content_type
+        self._content_encoding: Optional[Encoding] = content_encoding
+        if locale:
+            if re.search(LOCALE_TYPE_REGEX, locale):
+                # Valid locale
+                self._locale = locale
+            else:
+                raise InvalidLocaleTypeException(
+                    f"Supplied locale '{locale}' is not a valid locale according to ISO-639 format."
+                )

cyclonedx/model/component.py

@@ -81,14 +81,15 @@ def for_file(absolute_file_path: str, path_for_bom: Optional[str]) -> 'Component
             package_url_type='generic'
         )
 
-    def __init__(self, name: str, version: str, namespace: Optional[str] = None, qualifiers: Optional[str] = None,
-                 subpath: Optional[str] = None, hashes: Optional[List[HashType]] = None, author: Optional[str] = None,
+    def __init__(self, name: str, version: Optional[str] = None, namespace: Optional[str] = None,
+                 qualifiers: Optional[str] = None, subpath: Optional[str] = None,
+                 hashes: Optional[List[HashType]] = None, author: Optional[str] = None,
                  description: Optional[str] = None, license_str: Optional[str] = None,
                  component_type: ComponentType = ComponentType.LIBRARY, package_url_type: str = 'pypi') -> None:
         self._package_url_type: str = package_url_type
         self._namespace: Optional[str] = namespace
         self._name: str = name
-        self._version: str = version
+        self._version: Optional[str] = version
         self._type: ComponentType = component_type
         self._qualifiers: Optional[str] = qualifiers
         self._subpath: Optional[str] = subpath
@@ -227,10 +228,12 @@ def get_type(self) -> ComponentType:
         """
         return self._type
 
-    def get_version(self) -> str:
+    def get_version(self) -> Optional[str]:
         """
         Get the version of this Component.
 
+        This is NOT optional for CycloneDX Schema Version <= 1.3.
+
         Returns:
             Declared version of this Component as `str`.
         """

cyclonedx/model/release_notes.py

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+# This file is part of CycloneDX Python Lib
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+import datetime
+from typing import List, Optional
+
+from ..model import IssueType, Note, Properties, XsUri
+
+
+class ReleaseNotes:
+    """
+    This is our internal representation of a `releaseNotesType` for a Component in a BOM.
+
+    .. note::
+        See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.4/#type_releaseNotesType
+    """
+
+    def __init__(self, type: str, title: Optional[str] = None, featured_image: Optional[XsUri] = None,
+                 social_image: Optional[XsUri] = None, description: Optional[str] = None,
+                 timestamp: Optional[datetime.datetime] = None, aliases: Optional[List[str]] = None,
+                 tags: Optional[List[str]] = None, resolves: Optional[List[IssueType]] = None,
+                 notes: Optional[List[Note]] = None, properties: Optional[Properties] = None) -> None:
+        self._type: str = type
+        self._title: Optional[str] = title
+        self._featured_image: Optional[XsUri] = featured_image
+        self._social_image: Optional[XsUri] = social_image
+        self._description: Optional[str] = description
+        self._timestamp: Optional[datetime.datetime] = timestamp
+        self._aliases: Optional[List[str]] = aliases
+        self._tags: Optional[List[str]] = tags
+        self._resolves: Optional[List[IssueType]] = resolves
+        self._notes: Optional[List[Note]] = notes
+        self._properties: Optional[Properties] = properties

cyclonedx/output/__init__.py

@@ -38,6 +38,7 @@ class SchemaVersion(Enum):
     V1_1: str = 'V1Dot1'
     V1_2: str = 'V1Dot2'
     V1_3: str = 'V1Dot3'
+    V1_4: str = 'V1Dot4'
 
 
 DEFAULT_SCHEMA_VERSION = SchemaVersion.V1_3