Skip to content

Commit

Permalink
Add an SBOM URI field to artifact events
Browse files Browse the repository at this point in the history
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: #132

Signed-off-by: Andrea Frittoli <[email protected]>
  • Loading branch information
afrittoli committed Nov 25, 2023
1 parent 6c4a279 commit 4cb1b1b
Show file tree
Hide file tree
Showing 6 changed files with 38 additions and 17 deletions.
10 changes: 8 additions & 2 deletions continuous-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-uri | `URI-Reference` | The URI of the Software Bill of Material (SBOM) associated with the artifact | `https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom` |

## Events

Expand Down Expand Up @@ -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)

Expand All @@ -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-uri | `URI-Reference` | The URI of the Software Bill of Material (SBOM) associated with the artifact | `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)

Expand All @@ -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-uri | `URI-Reference` | The URI of the Software Bill of Material (SBOM) associated with the artifact | `https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom` |

### [`artifact signed`](examples/artifact_signed.json)

Expand Down
5 changes: 3 additions & 2 deletions examples/artifact_packaged.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -14,7 +14,8 @@
"change": {
"id": "myChange123",
"source": "my-git.example/an-org/a-repo"
}
},
"sbom-uri": "https://sbom.repo/myorg/234fd47e07d1004f0aed9c.sbom"
}
}
}
6 changes: 4 additions & 2 deletions examples/artifact_published.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,15 @@
"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"
}
}
}
9 changes: 7 additions & 2 deletions schemas/artifactpackaged.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -77,6 +77,11 @@
"required": [
"id"
]
},
"sbom-uri": {
"type": "string",
"minLength": 1,
"format": "uri-reference"
}
},
"additionalProperties": false,
Expand Down
12 changes: 9 additions & 3 deletions schemas/artifactpublished.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -59,7 +59,13 @@
"default": "artifact"
},
"content": {
"properties": {},
"properties": {
"sbom-uri": {
"type": "string",
"minLength": 1,
"format": "uri-reference"
}
},
"additionalProperties": false,
"type": "object"
}
Expand Down
13 changes: 7 additions & 6 deletions tools/verify-examples.sh
Original file line number Diff line number Diff line change
Expand Up @@ -44,20 +44,21 @@ go install github.com/neilpa/[email protected]
# - 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

0 comments on commit 4cb1b1b

Please sign in to comment.