docs: update material types, sarif, openvex (#148)

Signed-off-by: Miguel Martinez Trivino <migmartri@gmail.com>
chainloop-dev · Sep 27, 2023 · 7e57a6a · 7e57a6a
1 parent b7e06d9
commit 7e57a6a
Show file tree

Hide file tree

Showing 7 changed files with 50 additions and 13 deletions.
diff --git a/docs/reference/operator/contract.mdx b/docs/reference/operator/contract.mdx
@@ -42,17 +42,31 @@ A full example of a Workflow Contract looks like
 | [`materials`](#material-schema) | no       | List of [materials](#material-schema) to be added to the attestation                                                                                                         |
 | `envAllowList`                  | no       | List of environment variables that will be resolved and injected in the attestation                                                                                          |
 | [`runner`](#runner-context)     | no       | Specific runner type associated with this contract. If not set, this contract will be valid to be run `anywhere` but you'll miss out some of [its benefits](#runner-context) |
-| `annotations` | no       | Name/Value pairs of arbitrary annotations that will be added to the attestation. **If the value is not provided, it will be required during the attestation process.**|
+| `annotations`                   | no       | Name/Value pairs of arbitrary annotations that will be added to the attestation. **If the value is not provided, it will be required during the attestation process.**       |
 
 ## Material Schema
 
-| Name       | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`     | yes      |         | unique identifier of the artifact                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `type`     | yes      |         | <ul><li>`STRING` values will be injected in the attestation verbatim</li><li>`ARTIFACT` kinds will get uploaded to your OCI registry via the the built-in Content Addressable Storage proxy (CAS) and then referenced by their **content digest**</li><li>`CONTAINER_IMAGE` kinds will get resolved and referenced by **repository digest**</li><li>`SBOM_CYCLONEDX_JSON` or `SBOM_SPDX_JSON` will store and attach the Software Bill Of Materials (SBOM) to the attestation.</li><li>`JUNIT_XML` will validate, store and attach the JUnit XML file to the attestation.</li></ul> |
-| `output`   | no       | `false` | If set to `true` the artifact will get injected in the `subject` section of the [in-toto statement](https://github.com/slsa-framework/slsa/blob/main/docs/attestation-model.md#overview).                                                                                                                                                                                                                                                                                               |
-| `optional` | no       | `false` | if set to `true`, providing this artifact during attestation will be optional. This is **useful for soft rollouts of new requirements**                                                                                                                                                                                                                                                                                                                                                 |
-| `annotations` | no       | | Name/Value pairs of arbitrary annotations that will be added to the attestation. **If the value is not provided, it will be required during the attestation process.**|
+Chainloop supports the collection of the following pieces of evidence types:
+
+- [Container Image Reference](https://github.com/opencontainers/image-spec)
+- [CycloneDX SBOM](https://github.com/CycloneDX/specification)
+- [SPDX SBOM](https://spdx.dev/specifications/)
+- [CSAF VEX](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html)
+- [OpenVEX](https://github.com/openvex)
+- [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/)
+- [JUnit](https://www.ibm.com/docs/en/developer-for-zos/14.1?topic=formats-junit-xml-format)
+- Generic Artifact Types
+- Key-Value metadata pairs
+
+To learn more on how to add them to your contract, refer to the `type` section below.
+
+| Name          | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | yes      |         | unique identifier of the artifact                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `type`        | yes      |         | <ul><li>`STRING` values will be injected in the attestation verbatim</li><li>`ARTIFACT` kinds will get uploaded to your OCI registry via the the built-in Content Addressable Storage proxy (CAS) and then referenced by their **content digest**</li><li>`CONTAINER_IMAGE` kinds will get resolved and referenced by **repository digest**</li><li>`SBOM_CYCLONEDX_JSON` or `SBOM_SPDX_JSON` will store and attach the Software Bill Of Materials (SBOM) to the attestation.</li><li>`JUNIT_XML` will validate, store and attach the JUnit XML file to the attestation.</li><li>`OPENVEX` or `CSAF_VEX` for vulnerability disclosures</li><li>`SARIF` for static analysis</li></ul> |
+| `output`      | no       | `false` | If set to `true` the artifact will get injected in the `subject` section of the [in-toto statement](https://github.com/slsa-framework/slsa/blob/main/docs/attestation-model.md#overview).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `optional`    | no       | `false` | if set to `true`, providing this artifact during attestation will be optional. This is **useful for soft rollouts of new requirements**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `annotations` | no       |         | Name/Value pairs of arbitrary annotations that will be added to the attestation. **If the value is not provided, it will be required during the attestation process.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ## Runner Context
 
@@ -131,7 +145,6 @@ The following environment variables will be automatically added to the attestati
 
 A link to the Azure Pipeline build will be recorded in the control plane too during initialization.
 
-
 :::tip
 Remember, if all the **env variables** that you need are not defined in the context, you can extend such list via the `envAllowList` option.
 :::
diff --git a/examples/contracts/sarif/sarif.yaml b/examples/contracts/sarif/sarif.yaml
@@ -0,0 +1,4 @@
+schemaVersion: v1
+materials:
+  - type: SARIF
+    name: static-output
diff --git a/examples/contracts/skynet/contract.cue b/examples/contracts/skynet/contract.cue
@@ -34,6 +34,10 @@ materials: [
 	// SBOMs will be uploaded to the CAS and referenced in the attestation
 	// Both SBOM_CYCLONEDX_JSON and SBOM_SPDX_JSON are supported
 	{type: "SBOM_CYCLONEDX_JSON", name: "skynet-sbom"},
+  	// CSAF_VEX and OPENVEX are supported
+	{type: "OPENVEX", name: "disclosure"},
+	// And static analysis reports in SARIF format
+	{type: "SARIF", name: "static-out"},
 ]
 
 // Env vars we want the system to resolve and inject during attestation initialization

diff --git a/examples/contracts/skynet/contract.json b/examples/contracts/skynet/contract.json
@@ -24,7 +24,9 @@
     { "type": "ARTIFACT", "name": "rootfs" },
     { "type": "ARTIFACT", "name": "dockerfile", "optional": true },
     { "type": "STRING", "name": "build-ref" },
-    { "type": "SBOM_CYCLONEDX_JSON", "name": "skynet-sbom" }
+    { "type": "SBOM_CYCLONEDX_JSON", "name": "skynet-sbom" },
+    { "type": "OPENVEX", "name": "disclosure" },
+    { "type": "SARIF", "name": "static-output" }
   ],
   "envAllowList": ["CUSTOM_VAR"],
   "runner": { "type": "GITHUB_ACTION" }

diff --git a/examples/contracts/skynet/contract.yaml b/examples/contracts/skynet/contract.yaml
@@ -24,13 +24,19 @@ materials:
   - type: ARTIFACT
     name: dockerfile
     optional: true
-  # STRING kind materials will be injected as simple keypairs
-  - type: STRING
-    name: build-ref
   # SBOMs will be uploaded to the artifact registry and referenced in the attestation
   # Both SBOM_CYCLONEDX_JSON and SBOM_SPDX_JSON are supported
   - type: SBOM_CYCLONEDX_JSON
     name: skynet-sbom
+  # CSAF_VEX and OPENVEX are supported
+  - type: OPENVEX
+    name: disclosure
+  # And static analysis reports in SARIF format
+  - type: SARIF
+    name: static-out
+  # STRING kind materials will be injected as simple keypairs
+  - type: STRING
+    name: build-ref
 
 # Env vars we want the system to resolve and inject during attestation initialization
 # Additional ones can be inherited from the specified runner context below

diff --git a/examples/contracts/vex/csaf_vex.yaml b/examples/contracts/vex/csaf_vex.yaml
@@ -0,0 +1,4 @@
+schemaVersion: v1
+materials:
+  - type: CSAF_VEX
+    name: disclosure
diff --git a/examples/contracts/vex/openvex.yaml b/examples/contracts/vex/openvex.yaml
@@ -0,0 +1,4 @@
+schemaVersion: v1
+materials:
+  - type: OPENVEX
+    name: disclosure