Skip to content

Commit 4801f98

Browse files
javirlnjavirln
authored
feat(docs): Update documenttion for contract-less and auto-discovery (#1006)
Signed-off-by: Javier Rodriguez <[email protected]>
1 parent d533f3c commit 4801f98

File tree

3 files changed

+195
-0
lines changed

3 files changed

+195
-0
lines changed

‎docs/docs/getting-started/attestation-crafting.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,10 @@ $ chainloop attestation add --name build-ref --value 80e461e9b385c6986cdb8096c9d
140140
$ chainloop attestation add --name skynet-sbom --value sbom.cyclonedx.json
141141
```
142142

143+
:::tip
144+
There is also the option of leaving Chainloop CLI to figure out the material type when adding a piece of evidence in an attestation, learn more about auto-discover [here](../reference/attestations.md#auto-discovery-of-pieces-of-evidence).
145+
:::
146+
143147
### Inspecting the crafting status
144148

145149
If we check the status of the attestation we'll see that the three required materials have been added

‎docs/docs/quickstart.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,10 @@ This quickstart will guide you through the process of installing the Chainloop C
7070
chainloop att add --value my-sbom.json
7171
```
7272
73+
:::info
74+
The piece of evidence kind were automatically detected, learn more about auto-discover [here](reference/attestations.md).
75+
:::
76+
7377
And finally [we sign and push the attestation](/getting-started/attestation-crafting#encode-sign-and-push-attestation) to Chainloop for permanent preservation.
7478
7579
```bash

‎docs/docs/reference/attestations.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
sidebar_position: 1
3+
title: Contract-less and auto-discovery of pieces of evidence
4+
---
5+
A Workflow Contract specifies the necessary content that a workflow must include in its attestation. For instance, it might mandate the inclusion of the URI@digest of the generated container image, the container root filesystem used during the build, and the Software Bill of Materials for that container image. These pieces of evidence must be associated with a specific material type. Operators define what must be included in the [contracts](operator/contract.mdx), and developers need to understand and comply with these requirements.
6+
7+
This has been the case up until now, with the introduction of contract-less pieces of evidences and auto-discovery, we ease the job of operators and developers when working with attestations.
8+
9+
## Contract-less pieces of evidence
10+
Not all pieces of evidences need to to be registered as a material on the contract, you can add as many pieces of evidences as you like by adding
11+
its value and a new flag `--kind`, which determines that type of material you’re attesting, example:
12+
13+
```bash
14+
$ chainloop attestation init --name wf-test
15+
INF Attestation initialized! now you can check its status or add materials to it
16+
┌───────────────────┬──────────────────────────────────────┐
17+
│ Initialized At │ 21 May 24 07:23 UTC │
18+
├───────────────────┼──────────────────────────────────────┤
19+
│ Attestation ID │ 6e9d2e76-fdc0-4493-a344-4cf44a2b7bf2 │
20+
│ Name │ wf-test │
21+
│ Team │ founding │
22+
│ Project │ core │
23+
│ Contract Revision │ 3 │
24+
└───────────────────┴──────────────────────────────────────┘
25+
┌────────────────────────┐
26+
│ Materials │
27+
├───────────┬────────────┤
28+
│ Name │ one-file │
29+
│ Type │ ARTIFACT │
30+
│ Set │ No │
31+
│ Required │ Yes │
32+
│ Is output │ Yes │
33+
├───────────┼────────────┤
34+
│ Name │ other-file │
35+
│ Type │ EVIDENCE │
36+
│ Set │ No │
37+
│ Required │ Yes │
38+
│ Is output │ Yes │
39+
└───────────┴────────────┘
40+
```
41+
There are two expected materials of kind `ARTIFACT` and `EVIDENCE`. With the changes we can perform the following:
42+
43+
```bash
44+
$ chainloop attestation add --value controlplane.cyclonedx.json --kind SBOM_CYCLONEDX_JSON
45+
INF material added to attestation
46+
```
47+
We are explicitly saying which is the kind (`SBOM_CYCLONEDX_JSON`) we want to apply to material that is not found on the contract. After fulfilling the required materials,
48+
the ones stated on the contract, we can perform the attestation as usual:
49+
50+
```bash
51+
$ chainloop attestation push
52+
INF push completed
53+
┌───────────────────┬──────────────────────────────────────┐
54+
│ Initialized At │ 21 May 24 06:37 UTC │
55+
├───────────────────┼──────────────────────────────────────┤
56+
│ Attestation ID │ 57b8dc22-d84d-40c3-a04c-8948231b3134 │
57+
│ Name │ wf-test │
58+
│ Team │ founding │
59+
│ Project │ core │
60+
│ Contract Revision │ 3 │
61+
└───────────────────┴──────────────────────────────────────┘
62+
┌─────────────────────────────────────────────────────────────────────────────────────┐
63+
│ Materials │
64+
├───────────┬─────────────────────────────────────────────────────────────────────────┤
65+
│ Name │ one-file │
66+
│ Type │ ARTIFACT │
67+
│ Set │ Yes │
68+
│ Required │ Yes │
69+
│ Is output │ Yes │
70+
│ Value │ go.mod │
71+
│ Digest │ sha256:29773f085c46a33efcb6cdb185f6ec30ce1c4ca708b860708cd055b70488ef4d │
72+
├───────────┼─────────────────────────────────────────────────────────────────────────┤
73+
│ Name │ other-file │
74+
│ Type │ EVIDENCE │
75+
│ Set │ Yes │
76+
│ Required │ Yes │
77+
│ Is output │ Yes │
78+
│ Value │ LICENSE.md │
79+
│ Digest │ sha256:c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4 │
80+
├───────────┼─────────────────────────────────────────────────────────────────────────┤
81+
│ Name │ material-1716273574284654000 │
82+
│ Type │ SBOM_CYCLONEDX_JSON │
83+
│ Set │ Yes │
84+
│ Required │ No │
85+
│ Is output │ Yes │
86+
│ Value │ controlplane.cyclonedx.json │
87+
│ Digest │ sha256:a6bc29d7a2d8d9f6df12a86ee4c86c58189d77bb6ded9487330c39f46ee00d9a │
88+
└───────────┴─────────────────────────────────────────────────────────────────────────┘
89+
Attestation Digest: sha256:61832d846b870d01647a384c3df49e3c75fd87f45821c9295d97ab91d5bae198
90+
```
91+
92+
## Auto-discovery of pieces of evidence
93+
In top of contract-less pieces of evidences, we have introduced auto-discovery. Auto-discovery it’s a way of inspecting the incoming piece of evidence and try to match it with at least of of the available type of [materials](operator/contract.mdx#material-schema) of Chainloop. Please note this is a best effort and the prediction might fail and matching it with the wrong type of material, defaulting in `ARTIFACT`.
94+
95+
In order to let the auto-discovery work, don’t set `--name` nor `--kind`, let the CLI work it our for you.
96+
97+
Example of usage. Given the following contract:
98+
99+
```bash
100+
$ chainloop attestation init --name wf-test
101+
INF Attestation initialized! now you can check its status or add materials to it
102+
┌───────────────────┬──────────────────────────────────────┐
103+
│ Initialized At │ 22 May 24 13:38 UTC │
104+
├───────────────────┼──────────────────────────────────────┤
105+
│ Attestation ID │ 583553ef-d051-4c41-aec4-a4cdd725bf89 │
106+
│ Name │ wf-test │
107+
│ Team │ founding │
108+
│ Project │ core │
109+
│ Contract Revision │ 3 │
110+
└───────────────────┴──────────────────────────────────────┘
111+
┌────────────────────────┐
112+
│ Materials │
113+
├───────────┬────────────┤
114+
│ Name │ one-file │
115+
│ Type │ ARTIFACT │
116+
│ Set │ No │
117+
│ Required │ Yes │
118+
│ Is output │ Yes │
119+
├───────────┼────────────┤
120+
│ Name │ other-file │
121+
│ Type │ EVIDENCE │
122+
│ Set │ No │
123+
│ Required │ Yes │
124+
│ Is output │ Yes │
125+
└───────────┴────────────┘
126+
```
127+
Let's add the required materials:
128+
129+
```bash
130+
$ chainloop attestation add --value go.mod --name one-file
131+
INF material added to attestation
132+
133+
$ chainloop attestation add --value LICENSE.md --name other-file
134+
INF material added to attestation
135+
```
136+
And finally let's try to discover one material without specifying its type:
137+
138+
```bash
139+
$ chainloop attestation add --value controlplane.cyclonedx.json
140+
INF material kind detected kind=SBOM_CYCLONEDX_JSON
141+
INF material added to attestation
142+
```
143+
As a result we can see how it's added to the result:
144+
145+
```bash
146+
$ chainloop attestation push
147+
INF push completed
148+
┌───────────────────┬──────────────────────────────────────┐
149+
│ Initialized At │ 22 May 24 13:38 UTC │
150+
├───────────────────┼──────────────────────────────────────┤
151+
│ Attestation ID │ 583553ef-d051-4c41-aec4-a4cdd725bf89 │
152+
│ Name │ wf-test │
153+
│ Team │ founding │
154+
│ Project │ core │
155+
│ Contract Revision │ 3 │
156+
└───────────────────┴──────────────────────────────────────┘
157+
┌─────────────────────────────────────────────────────────────────────────────────────┐
158+
│ Materials │
159+
├───────────┬─────────────────────────────────────────────────────────────────────────┤
160+
│ Name │ one-file │
161+
│ Type │ ARTIFACT │
162+
│ Set │ Yes │
163+
│ Required │ Yes │
164+
│ Is output │ Yes │
165+
│ Value │ go.mod │
166+
│ Digest │ sha256:29773f085c46a33efcb6cdb185f6ec30ce1c4ca708b860708cd055b70488ef4d │
167+
├───────────┼─────────────────────────────────────────────────────────────────────────┤
168+
│ Name │ other-file │
169+
│ Type │ EVIDENCE │
170+
│ Set │ Yes │
171+
│ Required │ Yes │
172+
│ Is output │ Yes │
173+
│ Value │ LICENSE.md │
174+
│ Digest │ sha256:c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4 │
175+
├───────────┼─────────────────────────────────────────────────────────────────────────┤
176+
│ Name │ material-1716385111238449000 │
177+
│ Type │ SBOM_CYCLONEDX_JSON │
178+
│ Set │ Yes │
179+
│ Required │ No │
180+
│ Value │ controlplane.cyclonedx.json │
181+
│ Digest │ sha256:a6bc29d7a2d8d9f6df12a86ee4c86c58189d77bb6ded9487330c39f46ee00d9a │
182+
└───────────┴─────────────────────────────────────────────────────────────────────────┘
183+
Attestation Digest: sha256:8a0b3a9db0372fdf571dbe85c8a9b5202f473ca97e9dbcdf77c3f9b423ea3b9c
184+
```
185+
186+
## In a nutshell
187+
Contract-less and auto-discovery and two features that walk hand by hand. They compose a new way of adding pieces of evidences to an existing contract in a frictionless way. You can see it in action in our [quickstart](../quickstart.md) guide.

0 commit comments

Comments
 (0)