Add an SBOM URI field to artifact events (cdevents#171)

* Add an SBOM URI field to artifact events Artifact packaged and/or published events may include a link to a published SBOM. Since there is no default storage location for such SBOM documents, CDEvents may help linking the artifact with its SBOM by including a link to the SBOM in the artifact events. Partially-addresses: cdevents#132 Signed-off-by: Andrea Frittoli <andrea.frittoli@gmail.com>
afrittoli · Jan 15, 2024 · dac26c8 · dac26c8
1 parent e66556b
commit dac26c8
Show file tree

Hide file tree

Showing 6 changed files with 69 additions and 16 deletions.
diff --git a/continuous-integration.md b/continuous-integration.md
@@ -47,6 +47,7 @@ An `artifact` is usually produced as output of a build process. Events need to b
 | type | `String` | See [type](spec.md#type-subject) | `artifact` |
 | change | `object`        | The change (tag, commit, revision) of the repository which was used to build the artifact" | `{"id": "527d4a1aca5e8d0df24813df5ad65d049fc8d312", "source": "my-git.example/an-org/a-repo"}`, `{"id": "feature1234", "source": "my-git.example/an-org/a-repo"}` |
 | signature | `string`     | The signature of the artifact | `MEYCIQCBT8U5ypDXWCjlNKfzTV4KH516/SK13NZSh8znnSMNkQIhAJ3XiQlc9PM1KyjITcZXHotdMB+J3NGua5T/yshmiPmp` |
+| sbom | [`sbom`](#sbom) | The Software Bill of Material (SBOM) associated with the artifact | `{"uri": "https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom"}` |
 
 ## Events
 
@@ -96,8 +97,9 @@ This event represents a Build task that has finished. This event will eventually
 ### [`artifact packaged`](examples/artifact_packaged.json)
 
 The event represents an artifact that has been packaged for distribution; this artifact is now versioned with a fixed version.
+This event is usually produced by the build system. If an SBOM URI is available at this stage, it should be included.
 
-- Event Type: __`dev.cdevents.artifact.packaged.0.1.1`__
+- Event Type: __`dev.cdevents.artifact.packaged.0.2.0-draft`__
 - Predicate: packaged
 - Subject: [`artifact`](#artifact)
 
@@ -107,12 +109,15 @@ The event represents an artifact that has been packaged for distribution; this a
 | source | `URI-Reference` | See [source](spec.md#source-subject) | | |
 | type | `String` | See [type](spec.md#type-subject) | `artifact` | |
 | change | `object`        | The change (tag, commit, revision) of the repository which was used to build the artifact" | `{"id": "527d4a1aca5e8d0df24813df5ad65d049fc8d312", "source": "my-git.example/an-org/a-repo"}`, `{"id": "feature1234", "source": "my-git.example/an-org/a-repo"}` | ✅ |
+| sbom | [`sbom`](#sbom) | The Software Bill of Material (SBOM) associated with the artifact | `{"uri": "https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom"}` | |
 
 ### [`artifact published`](examples/artifact_published.json)
 
 The event represents an artifact that has been published and it can be advertised for others to use.
+This event may be produced both by the build system and by the artifact registry that received the artifact.
+If an SBOM was published and the SBOM URI is available at this stage, it should be included.
 
-- Event Type: __`dev.cdevents.artifact.published.0.1.1`__
+- Event Type: __`dev.cdevents.artifact.published.0.2.0-draft`__
 - Predicate: published
 - Subject: [`artifact`](#artifact)
 
@@ -121,6 +126,7 @@ The event represents an artifact that has been published and it can be advertise
 | id    | `Purl` | See [id](spec.md#id-subject) | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427?repository_url=mycr.io/myapp`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | ✅ |
 | source | `URI-Reference` | See [source](spec.md#source-subject) | | |
 | type | `String` | See [type](spec.md#type-subject) | `artifact` | |
+| sbom | [`sbom`](#sbom) | The Software Bill of Material (SBOM) associated with the artifact | `{"uri": "https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom"}` | |
 
 ### [`artifact signed`](examples/artifact_signed.json)
 
@@ -137,3 +143,13 @@ An artifact may be signed after it has been packaged or sometimes after it has p
 | source | `URI-Reference` | See [source](spec.md#source-subject) | | |
 | type | `String` | See [type](spec.md#type-subject) | `artifact` | |
 | signature | `string`     | The signature of the artifact | `MEYCIQCBT8U5ypDXWCjlNKfzTV4KH516/SK13NZSh8znnSMNkQIhAJ3XiQlc9PM1KyjITcZXHotdMB+J3NGua5T/yshmiPmp` | ✅ |
+
+## Objects
+
+### `sbom`
+
+Several events reference a Software Bill of Materials (SBOM). In CDEvents SBOMs are represented via the `sbom` object, which is a reference to an externally hosted SBOM. The `sbom` object includes a single `uri` field, and is defined as an object to allow for more fields to be added in a backwards compatible manner in future.
+
+| Field | Type | Description | Examples |
+|-------|------|-------------|----------|
+| `uri` | `URI-Reference` | Link to an externally hosted SBOM. | `https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom` |
diff --git a/examples/artifact_packaged.json b/examples/artifact_packaged.json
@@ -3,7 +3,7 @@
     "version": "0.4.0-draft",
     "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
     "source": "/event/source/123",
-    "type": "dev.cdevents.artifact.packaged.0.1.1",
+    "type": "dev.cdevents.artifact.packaged.0.2.0-draft",
     "timestamp": "2023-03-20T14:27:05.315384Z"
   },
   "subject": {
@@ -14,6 +14,9 @@
       "change": {
         "id": "myChange123",
         "source": "my-git.example/an-org/a-repo"
+      },
+      "sbom": {
+        "uri": "https://sbom.repo/myorg/234fd47e07d1004f0aed9c.sbom"
       }
     }
   }

diff --git a/examples/artifact_published.json b/examples/artifact_published.json
@@ -3,13 +3,17 @@
     "version": "0.4.0-draft",
     "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
     "source": "/event/source/123",
-    "type": "dev.cdevents.artifact.published.0.1.1",
+    "type": "dev.cdevents.artifact.published.0.2.0-draft",
     "timestamp": "2023-03-20T14:27:05.315384Z"
   },
   "subject": {
     "id": "pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c",
     "source": "/event/source/123",
     "type": "artifact",
-    "content": {}
+    "content": {
+      "sbom": {
+        "uri": "https://sbom.repo/myorg/234fd47e07d1004f0aed9c.sbom"
+      }
+    }
   }
 }
diff --git a/schemas/artifactpackaged.json b/schemas/artifactpackaged.json
@@ -20,9 +20,9 @@
         "type": {
           "type": "string",
           "enum": [
-            "dev.cdevents.artifact.packaged.0.1.1"
+            "dev.cdevents.artifact.packaged.0.2.0-draft"
           ],
-          "default": "dev.cdevents.artifact.packaged.0.1.1"
+          "default": "dev.cdevents.artifact.packaged.0.2.0-draft"
         },
         "timestamp": {
           "type": "string",
@@ -77,6 +77,20 @@
               "required": [
                 "id"
               ]
+            },
+            "sbom": {
+              "properties": {
+                "uri": {
+                  "type": "string",
+                  "minLength": 1,
+                  "format": "uri-reference"
+                }
+              },
+              "additionalProperties": false,
+              "type": "object",
+              "required": [
+                "uri"
+              ]
             }
           },
           "additionalProperties": false,

diff --git a/schemas/artifactpublished.json b/schemas/artifactpublished.json
@@ -20,9 +20,9 @@
         "type": {
           "type": "string",
           "enum": [
-            "dev.cdevents.artifact.published.0.1.1"
+            "dev.cdevents.artifact.published.0.2.0-draft"
           ],
-          "default": "dev.cdevents.artifact.published.0.1.1"
+          "default": "dev.cdevents.artifact.published.0.2.0-draft"
         },
         "timestamp": {
           "type": "string",
@@ -59,7 +59,22 @@
           "default": "artifact"
         },
         "content": {
-          "properties": {},
+          "properties": {
+            "sbom": {
+              "properties": {
+                "uri": {
+                  "type": "string",
+                  "minLength": 1,
+                  "format": "uri-reference"
+                }
+              },
+              "additionalProperties": false,
+              "type": "object",
+              "required": [
+                "uri"
+              ]
+            }
+          },
           "additionalProperties": false,
           "type": "object"
         }

diff --git a/tools/verify-examples.sh b/tools/verify-examples.sh
@@ -44,20 +44,21 @@ go install github.com/neilpa/yajsv@v1.4.1
 # - examples are subject_predicate.json
 # - schemas are subjectpredicate.json
 num_failed=0
-num_examples=$(ls "$EXAMPLES_FOLDER" | wc -l | awk '{ print $1 }')
-for example in $(ls "$EXAMPLES_FOLDER"); do
-    SUBJECT_PREDICATE=$(basename $example .json)
+num_examples=$(find "${EXAMPLES_FOLDER}" -type f -name '*json' | wc -l | awk '{ print $1 }')
+for example in $(find "${EXAMPLES_FOLDER}" -type f -name '*json'); do
+    EXAMPLE_FILE=$(basename ${example})
+    SUBJECT_PREDICATE=$(basename $EXAMPLE_FILE .json)
     splitArray=(${SUBJECT_PREDICATE//_/ })
     SUBJECT=${splitArray[0]}
     PREDICATE=${splitArray[1]}
-    EXAMPLE_FILE=${EXAMPLES_FOLDER}/${example}
     SCHEMA_FILE=${SCHEMAS_FOLDER}/${SUBJECT}${PREDICATE}.json
     echo "==> $SUBJECT $PREDICATE"
-    yajsv -s "$SCHEMA_FILE" "$EXAMPLE_FILE" || num_failed=$(( num_failed + 1 ))
+    echo yajsv -s "$SCHEMA_FILE" "$example"
+    yajsv -s "$SCHEMA_FILE" "$example" || num_failed=$(( num_failed + 1 ))
     echo
 done
 
 if [ $num_failed -gt 0 ]; then
     echo "${num_failed} out of ${num_examples} examples failed validation"
 fi
-exit $num_failed
+exit $num_failed