Release a software package story

Problem:
Example of release process using an SBOM.

Solution:
Added sbom entry to EVENTS_CREATE when releasing a software
package using an SBOM.

Signed-off-by: Paul Hewlett <phewlett76@gmail.com>

Author: eccles

archivist/constants.py

@@ -52,6 +52,7 @@
 SBOMS_METADATA = "metadata"
 SBOMS_PUBLISH = "publish"
 SBOMS_WITHDRAW = "withdraw"
+SBOM_RELEASE = "SBOM_RELEASE"
 
 SUBJECTS_SUBPATH = "iam/v1"
 SUBJECTS_LABEL = "subjects"

archivist/events.py

@@ -22,9 +22,9 @@
 
 """
 
+from copy import deepcopy
 from logging import getLogger
 from typing import Dict, Optional
-from copy import deepcopy
 
 # pylint:disable=unused-import      # To prevent cyclical import errors forward referencing is used
 # pylint:disable=cyclic-import      # but pylint doesn't understand this feature
@@ -36,6 +36,7 @@
     ASSETS_WILDCARD,
     CONFIRMATION_STATUS,
     EVENTS_LABEL,
+    SBOM_RELEASE,
 )
 from . import confirmer
 from .dictmerge import _deepmerge
@@ -166,19 +167,38 @@ def create_from_data(self, asset_id: str, data: Dict, *, confirm=False) -> Event
         """
         data = deepcopy(data)
 
+        event_attributes = data["event_attributes"]
         # is location present?
         location = data.pop("location", None)
         if location is not None:
             loc, _ = self._archivist.locations.create_if_not_exists(
                 location,
             )
-            data["event_attributes"]["arc_location_identity"] = loc["identity"]
+            event_attributes["arc_location_identity"] = loc["identity"]
+
+        sbom = data.pop("sbom", None)
+        if sbom is not None:
+            sbom_result = self._archivist.sboms.create(sbom)
+            for k, v in sbom_result.items():
+                event_attributes[f"sbom_{k}"] = v
 
         attachments = data.pop("attachments", None)
         if attachments is not None:
-            data["event_attributes"]["arc_attachments"] = [
-                self._archivist.attachments.create(a) for a in attachments
-            ]
+            result = [self._archivist.attachments.create(a) for a in attachments]
+            for i, a in enumerate(attachments):
+                if a.get("type") == SBOM_RELEASE:
+                    sbom_result = self._archivist.sboms.parse(a)
+                    for k, v in sbom_result.items():
+                        event_attributes[f"sbom_{k}"] = v
+
+                    event_attributes["sbom_identity"] = result[i][
+                        "arc_attachment_identity"
+                    ]
+                    break
+
+            event_attributes["arc_attachments"] = result
+
+        data["event_attributes"] = event_attributes
 
         event = Event(
             **self._archivist.post(

archivist/sboms.py

@@ -26,9 +26,11 @@
 
 from typing import BinaryIO, Dict, Optional
 from copy import deepcopy
+from io import BytesIO
 from logging import getLogger
 
 from requests.models import Response
+from xmltodict import parse as xmltodict_parse
 
 # pylint:disable=unused-import      # To prevent cyclical import errors forward referencing is used
 # pylint:disable=cyclic-import      # but pylint doesn't understand this feature
@@ -45,6 +47,7 @@
 from . import publisher, uploader, withdrawer
 from .dictmerge import _deepmerge
 from .sbommetadata import SBOM
+from .utils import get_url
 
 LOGGER = getLogger(__name__)
 
@@ -66,12 +69,147 @@ def __init__(self, archivist: "type_helper.Archivist"):
     def __str__(self) -> str:
         return f"SBOMSClient({self._archivist.url})"
 
+    @staticmethod
+    def parse(data: Dict) -> Dict:  # pragma: no cover
+        """
+        parse the sbom and extract pertinent informtion
+
+        Args:
+            data (dict): dictionary
+
+        A YAML representation of the data argument would be:
+
+            .. code-block:: yaml
+
+                filename: functests/test_resources/sboms/gen1.xml
+
+            OR
+
+            .. code-block:: yaml
+
+                url: https://some.hostname/cdx.xml
+
+             Either 'filename' or 'url' is required.
+
+        Returns:
+
+            A dict suitable for adding to an asset or event creation
+
+        """
+        result = None
+        filename = data.get("filename")
+        if filename is not None:
+            with open(filename, "rb") as fd:
+                sbom = xmltodict_parse(fd, xml_attribs=True, disable_entities=False)
+
+        else:
+            url = data["url"]
+            fd = BytesIO()
+            get_url(url, fd)
+            sbom = xmltodict_parse(fd, xml_attribs=True, disable_entities=False)
+
+        b = sbom["bom"]
+        m = b["metadata"]
+        c = m["component"]
+        hash_value = c["hashes"]["hash"]["#text"]
+        result = {
+            "author": c["author"],
+            "component": c["name"],
+            "hash": hash_value,
+            "supplier": c["supplier"]["name"],
+            "uuid": b["@serialNumber"],
+            "version": c["version"],
+        }
+
+        return result
+
+    def create(self, data: Dict) -> Dict:  # pragma: no cover
+        """
+        Create an sbom and return struct suitable for use in an asset
+        or event creation.
+
+        Args:
+            data (dict): dictionary
+
+        A YAML representation of the data argument would be:
+
+            .. code-block:: yaml
+
+                filename: functests/test_resources/sboms/gen1.xml
+                content_type: text/xml
+                confirm: True
+                params:
+                  privacy: PRIVATE
+
+            OR
+
+            .. code-block:: yaml
+
+                url: https://some.hostname/cdx.xml
+                content_type: text/xml
+                confirm: True
+                params:
+                  privacy: PRIVATE
+
+             Either 'filename' or 'url' is required.
+             'content_type' is required.
+
+        Returns:
+
+            A dict suitable for adding to an asset or event creation
+
+        A YAML representation of the result would be:
+
+            .. code-block:: yaml
+
+                arc_display_name: Acme Generation1 SBOM
+                arc_attachment_identity: sboms/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+                .....
+
+        """
+        result = None
+        filename = data.get("filename")
+        if filename is not None:
+            with open(filename, "rb") as fd:
+                sbom = self.upload(
+                    fd,
+                    confirm=data.get("confirm", False),
+                    mtype=data.get("content_type"),
+                    params=data.get("params"),
+                )
+
+        else:
+            url = data["url"]
+            fd = BytesIO()
+            get_url(url, fd)
+            sbom = self.upload(
+                fd,
+                confirm=data.get("confirm", False),
+                mtype=data.get("content_type"),
+                params=data.get("params"),
+            )
+
+        # response to sbom upload contains all the info we need.
+        s = sbom.dict()
+        _, hash_value = s["hashes"][0].split(":")
+        result = {
+            "author": ",".join(s["authors"]),
+            "component": s["component"],
+            "identity": s["identity"],
+            "hash": hash_value,
+            "supplier": s["supplier"],
+            "uuid": s["unique_id"],
+            "version": s["version"],
+        }
+
+        return result
+
     def upload(
         self,
         fd: BinaryIO,
         *,
         confirm: bool = False,
-        mtype: str = "text/xml",
+        mtype: Optional[str] = None,
         params: Optional[Dict] = None,
     ) -> SBOM:
         """Create SBOM
@@ -89,6 +227,8 @@ def upload(
 
         """
 
+        mtype = mtype or "text/xml"
+
         LOGGER.debug("Upload SBOM %s", params)
 
         sbom = SBOM(

docs/runner/events_create.rst

@@ -12,6 +12,11 @@ added to the event before posting.
 The optional 'location' setting creates the location if it does not exist and adds it to
 the event.
 
+The optional 'sbom' setting uploads the sbom to archivist and the response added to the
+event before posting. (see second example below)
+
+An example when opening a door in Paris:
+
 .. code-block:: yaml
     
     ---
@@ -51,3 +56,54 @@ the event.
           - filename: functests/test_resources/doors/events/door_open.png
             content_type: image/png
         confirm: true
+
+
+An example when releasing a software package as an sbom:
+
+.. code-block:: yaml
+    
+    ---
+    steps:
+      - step:
+          action: EVENTS_CREATE
+          description: Release YYYYMMDD.1 of Test SBOM for YAML story
+          asset_name: ACME Corporation Detector SAAS
+          print_response: true
+        operation: Record
+        behaviour: RecordEvidence
+        confirm: true
+        event_attributes:
+          arc_description: ACME Corporation Detector SAAS Released YYYYMMDD.1
+          arc_display_type: sbom release
+        sbom:
+          filename: functests/test_resources/sbom/gen1.xml
+          content_type: text/xml
+          display_name: ACME Generation1 SBOM
+          confirm: True
+          params:
+            privacy: PRIVATE
+
+
+An example when releasing a software package as an sbom attachment:
+
+.. code-block:: yaml
+    
+    ---
+    steps:
+      - step:
+          action: EVENTS_CREATE
+          description: Release YYYYMMDD.1 of Test SBOM for YAML story
+          asset_name: ACME Corporation Detector SAAS
+          print_response: true
+        operation: Record
+        behaviour: RecordEvidence
+        confirm: true
+        event_attributes:
+          arc_description: ACME Corporation Detector SAAS Released YYYYMMDD.1
+          arc_display_type: sbom release
+        attachments:
+          - filename: functests/test_resources/sbom/gen1.xml
+            content_type: text/xml
+            display_name: ACME Generation1 SBOM
+            type: SBOM_RELEASE
+