Skip to content
This repository was archived by the owner on Mar 13, 2024. It is now read-only.

Commit 7e57a6a

Browse files
migmartrimigmartri
authored
docs: update material types, sarif, openvex (#148)
 Signed-off-by: Miguel Martinez Trivino <migmartri@gmail.com>
1 parent b7e06d9 commit 7e57a6a

File tree

7 files changed

+50
-13
lines changed

7 files changed

+50
-13
lines changed

‎docs/reference/operator/contract.mdx‎

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -42,17 +42,31 @@ A full example of a Workflow Contract looks like
4242
| [`materials`](#material-schema) | no | List of [materials](#material-schema) to be added to the attestation |
4343
| `envAllowList` | no | List of environment variables that will be resolved and injected in the attestation |
4444
| [`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) |
45-
| `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.**|
45+
| `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.** |
4646

4747
## Material Schema
4848

49-
| Name | Required | Default | Description |
50-
| ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
51-
| `name` | yes | | unique identifier of the artifact |
52-
| `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> |
53-
| `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). |
54-
| `optional` | no | `false` | if set to `true`, providing this artifact during attestation will be optional. This is **useful for soft rollouts of new requirements** |
55-
| `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.**|
49+
Chainloop supports the collection of the following pieces of evidence types:
50+
51+
- [Container Image Reference](https://github.com/opencontainers/image-spec)
52+
- [CycloneDX SBOM](https://github.com/CycloneDX/specification)
53+
- [SPDX SBOM](https://spdx.dev/specifications/)
54+
- [CSAF VEX](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html)
55+
- [OpenVEX](https://github.com/openvex)
56+
- [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/)
57+
- [JUnit](https://www.ibm.com/docs/en/developer-for-zos/14.1?topic=formats-junit-xml-format)
58+
- Generic Artifact Types
59+
- Key-Value metadata pairs
60+
61+
To learn more on how to add them to your contract, refer to the `type` section below.
62+
63+
| Name | Required | Default | Description |
64+
| ------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
65+
| `name` | yes | | unique identifier of the artifact |
66+
| `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> |
67+
| `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). |
68+
| `optional` | no | `false` | if set to `true`, providing this artifact during attestation will be optional. This is **useful for soft rollouts of new requirements** |
69+
| `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.** |
5670

5771
## Runner Context
5872

@@ -131,7 +145,6 @@ The following environment variables will be automatically added to the attestati
131145

132146
A link to the Azure Pipeline build will be recorded in the control plane too during initialization.
133147

134-
135148
:::tip
136149
Remember, if all the **env variables** that you need are not defined in the context, you can extend such list via the `envAllowList` option.
137150
:::

‎examples/contracts/sarif/sarif.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
schemaVersion: v1
2+
materials:
3+
- type: SARIF
4+
name: static-output

‎examples/contracts/skynet/contract.cue‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ materials: [
3434
// SBOMs will be uploaded to the CAS and referenced in the attestation
3535
// Both SBOM_CYCLONEDX_JSON and SBOM_SPDX_JSON are supported
3636
{type: "SBOM_CYCLONEDX_JSON", name: "skynet-sbom"},
37+
// CSAF_VEX and OPENVEX are supported
38+
{type: "OPENVEX", name: "disclosure"},
39+
// And static analysis reports in SARIF format
40+
{type: "SARIF", name: "static-out"},
3741
]
3842

3943
// Env vars we want the system to resolve and inject during attestation initialization

‎examples/contracts/skynet/contract.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@
2424
{ "type": "ARTIFACT", "name": "rootfs" },
2525
{ "type": "ARTIFACT", "name": "dockerfile", "optional": true },
2626
{ "type": "STRING", "name": "build-ref" },
27-
{ "type": "SBOM_CYCLONEDX_JSON", "name": "skynet-sbom" }
27+
{ "type": "SBOM_CYCLONEDX_JSON", "name": "skynet-sbom" },
28+
{ "type": "OPENVEX", "name": "disclosure" },
29+
{ "type": "SARIF", "name": "static-output" }
2830
],
2931
"envAllowList": ["CUSTOM_VAR"],
3032
"runner": { "type": "GITHUB_ACTION" }

‎examples/contracts/skynet/contract.yaml‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,19 @@ materials:
2424
- type: ARTIFACT
2525
name: dockerfile
2626
optional: true
27-
# STRING kind materials will be injected as simple keypairs
28-
- type: STRING
29-
name: build-ref
3027
# SBOMs will be uploaded to the artifact registry and referenced in the attestation
3128
# Both SBOM_CYCLONEDX_JSON and SBOM_SPDX_JSON are supported
3229
- type: SBOM_CYCLONEDX_JSON
3330
name: skynet-sbom
31+
# CSAF_VEX and OPENVEX are supported
32+
- type: OPENVEX
33+
name: disclosure
34+
# And static analysis reports in SARIF format
35+
- type: SARIF
36+
name: static-out
37+
# STRING kind materials will be injected as simple keypairs
38+
- type: STRING
39+
name: build-ref
3440

3541
# Env vars we want the system to resolve and inject during attestation initialization
3642
# Additional ones can be inherited from the specified runner context below

‎examples/contracts/vex/csaf_vex.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
schemaVersion: v1
2+
materials:
3+
- type: CSAF_VEX
4+
name: disclosure

‎examples/contracts/vex/openvex.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
schemaVersion: v1
2+
materials:
3+
- type: OPENVEX
4+
name: disclosure

0 commit comments

Comments
 (0)