Skip to content

Commit 033193b

Browse files
migmartrimigmartri
authored
docs: document dagger module and runner (#607)
Signed-off-by: Miguel Martinez Trivino <[email protected]>
1 parent 01ad13a commit 033193b

File tree

7 files changed

+274
-34
lines changed

7 files changed

+274
-34
lines changed

‎docs/docs/guides/dagger/README.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
title: Use Dagger With Chainloop
3+
---
4+
5+
# Chainloop Module for Dagger
6+
7+
![dagger-tested-version](https://img.shields.io/badge/dagger%20version-v0.10.0-green)
8+
9+
Daggerized version of [Chainloop](https://docs.chainloop.dev) that can be used to attest and collect pieces of evidence from your [Dagger](https://dagger.io/) pipelines.
10+
11+
## Prerequisites
12+
13+
- This module requires existing familiarity with Chainloop and its attestation process. Please refer to [this guide](https://docs.chainloop.dev/getting-started/attestation-crafting) to learn more.
14+
- You need a `token` (aka workflow robot account) [previously generated](https://docs.chainloop.dev/getting-started/workflow-definition#robot-account-creation) by your Chainloop administrator.
15+
16+
## Attestation Crafting
17+
18+
The [attestation process](https://docs.chainloop.dev/getting-started/attestation-crafting) starts with its initialization (`init`) or `resume`, then adding as many materials/pieces of evidence as needed (`add-raw-evidence` or `add-file-evidence`), and finally, signing and pushing the attestation to the Chainloop control plane (`push`).
19+
20+
You can invoke this module in two ways: either from the Dagger CLI `dagger call ...` or from your own Dagger pipeline by importing this module as a dependency.
21+
22+
### Using the Chainloop module in your Dagger pipeline
23+
24+
To use Chainloop in your module, first, you need to add it as a dependency.
25+
26+
```sh
27+
dagger install github.com/chainloop-dev/chainloop
28+
```
29+
30+
Once done, you'll have access to the Chainloop client via `dag.Chainloop()` and start the attestation process with Init().
31+
32+
You can find a full example of how to integrate attestation crafting in your `Go` pipeline [here](https://github.com/chainloop-dev/integration-demo/blob/main/chainloop-demo/dagger/src/main.go)
33+
34+
### Using the Dagger CLI
35+
36+
The [attestation process](https://docs.chainloop.dev/getting-started/attestation-crafting) starts with its initialization (`init`) or `resume`, then adding as many materials/pieces of evidence as needed (`add-raw-evidence` or `add-file-evidence`), and finally, signing and pushing the attestation to the Chainloop control plane (`push`).
37+
38+
This module is designed to support function chaining, so after initializing the attestation, you can chain the subcommands to add pieces of evidence and push the attestation. For example
39+
40+
```sh
41+
dagger call -m github.com/chainloop-dev/chainloop \
42+
# Initialize the command
43+
init --token env:CHAINLOOP_TOKEN \
44+
# we chain subcommands after the initialization
45+
# add a raw evidence
46+
add-raw-evidence --name my-evidence --value "my-value" \
47+
# and push the result
48+
push --key file:/path/to/cosign.key --passphrase env:COSIGN_PASSPHRASE
49+
```
50+
51+
If the attestation process end-to-end is not completed in one go, you can store the attestation-id after init and resume the attestation process using the `resume` method at any time down the line.
52+
53+
```sh
54+
# Initialize but this time we store the attestation-id
55+
ATTESTATION_ID=$(dagger call -m github.com/chainloop-dev/chainloop init --token env:CHAINLOOP_TOKEN attestation-id)
56+
57+
58+
# and we use it to resume the attestation process
59+
dagger call -m github.com/chainloop-dev/chainloop \
60+
resume --token env:CHAINLOOP_TOKEN --attestation-id $ATTESTATION_ID \
61+
# we chain subcommands after the initialization
62+
....
63+
```
64+
65+
#### 1 - Init attestation ([docs](https://docs.chainloop.dev/getting-started/attestation-crafting#initialization))
66+
67+
Initialize an attestation using the Chainloop token stored in the `CHAINLOOP_TOKEN` environment variable.
68+
69+
> NOTE: `--token` can be provided only by referencing an environment variable (env:MY_VAR), not by value
70+
71+
```sh
72+
# Initialize the attestation and get its ID
73+
dagger call -m github.com/chainloop-dev/chainloop \
74+
init \
75+
--token env:CHAINLOOP_TOKEN \
76+
--repository /path/to/repo \ # optional flag to automatically attest a Git repository
77+
--contract-revision 1 # optional flag to specify the revision of the Workflow Contract (default `latest`)
78+
```
79+
80+
#### 2 - Get the status ([docs](https://docs.chainloop.dev/getting-started/attestation-crafting#inspecting-the-crafting-status))
81+
82+
Resuming a previous attestation
83+
84+
```sh
85+
dagger call -m github.com/chainloop-dev/chainloop \
86+
resume --token env:CHAINLOOP_TOKEN --attestation-id $ATTESTATION_ID \
87+
status
88+
```
89+
90+
or chaining the command right after initialization
91+
92+
```sh
93+
dagger call -m github.com/chainloop-dev/chainloop \
94+
init --token env:CHAINLOOP_TOKEN \
95+
status
96+
```
97+
98+
#### 3 - Add pieces of evidence ([docs](https://docs.chainloop.dev/getting-started/attestation-crafting#adding-materials))
99+
100+
You can attest pieces of evidence by providing its material name and its value, either in the form of a path to a file (`--path`) or a raw value (`--value`).
101+
102+
A path to a file is required for materials derived from artifacts, such as Software Bill Of materials, or any other file-based evidence.
103+
104+
```sh
105+
# Provide a material of kind artifact through its path
106+
# Remember, we first resume the attestation or chain the commands
107+
dagger call -m github.com/chainloop-dev/chainloop \
108+
resume --token env:CHAINLOOP_TOKEN --attestation-id $ATTESTATION_ID \
109+
add-file-evidence --name my-sbom --path ./path/to/sbom.json
110+
```
111+
112+
```sh
113+
# Or one with a raw value such as a container image reference
114+
dagger call -m github.com/chainloop-dev/chainloop \
115+
resume --token env:CHAINLOOP_TOKEN --attestation-id $ATTESTATION_ID \
116+
add-raw-evidence --name my-container-image --value ghcr.io/chainloop-dev/chainloop/control-plane
117+
```
118+
119+
In some cases, you might be providing a private container image as a piece of evidence. In this case, you'll also need to preload the container registry credentials.
120+
121+
```sh
122+
dagger call -m github.com/chainloop-dev/chainloop \
123+
resume --token env:CHAINLOOP_TOKEN --attestation-id $ATTESTATION_ID \
124+
# Now load the registry credentials
125+
with-registry --address ghcr.io --username my-username --password MY_PAT_TOKEN \
126+
# And perform the attestation of the private container image
127+
add-raw-evidence --name my-container-image --value ghcr.io/chainloop-dev/chainloop/control-plane
128+
```
129+
130+
#### 4 - Sign and push attestation ([docs](https://docs.chainloop.dev/getting-started/attestation-crafting#encode-sign-and-push-attestation))
131+
132+
Sign and push the attestation using a cosign **key stored in a file** and a passphrase stored in an environment variable.
133+
134+
> NOTE: neither --signing-key nor --passphrase can be provided by value. You need to provide them either as a file (file:/) or an environment variable (env:/).
135+
136+
```sh
137+
dagger call -m github.com/chainloop-dev/chainloop \
138+
resume --token env:CHAINLOOP_TOKEN --attestation-id $ATTESTATION_ID \
139+
push --key file:/path/to/cosign.key --passphrase env:COSIGN_PASSPHRASE
140+
```
141+
142+
Alternatively, you can also provide the signing key in an environment variable `--key env:MY_COSIGN_KEY`
143+
144+
#### 5 - Cancel/mark attestation as failed
145+
146+
```sh
147+
dagger call -m github.com/chainloop-dev/chainloop \
148+
resume --token env:CHAINLOOP_TOKEN --attestation-id $ATTESTATION_ID \
149+
mark-failed --reason "Something went wrong"
150+
```
151+
152+
or cancel the attestation process
153+
154+
```sh
155+
dagger call -m github.com/chainloop-dev/chainloop \
156+
resume --token env:CHAINLOOP_TOKEN --attestation-id $ATTESTATION_ID \
157+
mark-canceled --reason "nothing to see here"
158+
```
159+
160+
## Documentation
161+
162+
To learn more, please visit the Chainloop project's documentation website, https://docs.chainloop.dev where you will find a getting started guide, FAQ, examples, and more.
163+
164+
## Community / Discussion / Support
165+
166+
Chainloop is developed in the open and is constantly improved by our users, contributors and maintainers. Got a question, comment, or idea? Please don't hesitate to reach out via:
167+
168+
- GitHub [Issues](https://github.com/chainloop-dev/chainloop/issues)
169+
- Discord [Community Server](https://discord.gg/f7atkaZact)
170+
- Youtube [Channel](https://www.youtube.com/channel/UCISrWrPyR_AFjIQYmxAyKdg)
171+
172+

‎docs/docs/integrations/development/overview.md‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,23 @@ The loading stage is when the plugin gets enabled in the Chainloop Control Plane
2525
- What kind of input you want your plugin to receive, materials, attestations or both.
2626
- Available input properties for the registration and attachment phases. These schemas will be shown to the user and will be used to validate the input.
2727

28+
Example, excerpt from the [Dependency-Track plugin](https://github.com/chainloop-dev/chainloop/tree/main/app/controlplane/plugins/core/dependency-track/v1):
29+
30+
```go
31+
base, err := sdk.NewFanOut(
32+
&sdk.NewParams{
33+
ID: "dependency-track",
34+
Version: "1.2",
35+
Description: "Send CycloneDX SBOMs to your Dependency-Track instance",
36+
// The input schema for both registration and attachment phases
37+
InputSchema: &sdk.InputSchema{
38+
Registration: registrationRequest{},
39+
Attachment: attachmentRequest{},
40+
},
41+
// Subscribed to receive CycloneDX SBOMs in json format
42+
}, sdk.WithInputMaterial(schemaapi.CraftingSchema_Material_SBOM_CYCLONEDX_JSON))
43+
```
44+
2845
Once loaded, the plugin will be available to be registered on any organization and will be shown in the list of available plugins.
2946

3047
```console
@@ -100,9 +117,22 @@ Examples:
100117

101118
This is the actual execution of the plugin. This is where the plugin will do its work. i.e forward the attestation/material data to a third-party API, send a notification and so on.
102119

120+
When an attestation is received, the attestation and any materials that match the list of material types the plugin supports will be sent to the execute handler. For example, if your plugin does not specify any supported material types, it will receive only the attestation information.
121+
122+
![execution](/img/fanout-execute.png)
123+
124+
On another hand, if the plugin is subscribed to for example support SBOM_CYCLONEDX_JSON, and JUNIX_XML it will receive the attestation information and both materials **on a single execution**
125+
126+
![execution](/img/fanout-execute-materials.png)
127+
103128
In addition to the attestation and material data, this handler **will also have access to the outputs from the registration and attachment phases**.
104129

105-
Examples:
130+
Some important notes about the execution handler:
131+
132+
- If your plugin is subscribed to a specific material type, it will get executed on every attestation, even if such attestation does not contain any material of the supported type.
133+
- It's up to the plugin developer to make sure the desired material is present and handle the case when it's not.
134+
135+
Some example use-cases:
106136

107137
A Dependency-Track SBOM plugin will
108138

‎docs/docs/integrations/integrations.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@ Below you can find the list of currently available integrations. If you can't fi
1515

1616
| ID | Version | Description | Material Requirement |
1717
| --- | --- | --- | --- |
18-
| [dependency-track](https://github.com/chainloop-dev/chainloop/blob/main/app/controlplane/plugins/core/dependency-track/v1/README.md) | 1.2 | Send CycloneDX SBOMs to your Dependency-Track instance | SBOM_CYCLONEDX_JSON |
19-
| [smtp](https://github.com/chainloop-dev/chainloop/blob/main/app/controlplane/plugins/core/smtp/v1/README.md) | 1.0 | Send emails with information about a received attestation | |
20-
| [oci-registry](https://github.com/chainloop-dev/chainloop/blob/main/app/controlplane/plugins/core/oci-registry/v1/README.md) | 1.0 | Send attestations to a compatible OCI registry | |
18+
| [dependency-track](https://github.com/chainloop-dev/chainloop/blob/main/app/controlplane/plugins/core/dependency-track/v1/README.md) | 1.4 | Send CycloneDX SBOMs to your Dependency-Track instance | SBOM_CYCLONEDX_JSON |
2119
| [discord-webhook](https://github.com/chainloop-dev/chainloop/blob/main/app/controlplane/plugins/core/discord-webhook/v1/README.md) | 1.1 | Send attestations to Discord | |
2220
| [guac](https://github.com/chainloop-dev/chainloop/blob/main/app/controlplane/plugins/core/guac/v1/README.md) | 1.0 | Export Attestation and SBOMs metadata to a blob storage backend so guacsec/guac can consume it | SBOM_CYCLONEDX_JSON, SBOM_SPDX_JSON |
21+
| [slack-webhook](https://github.com/chainloop-dev/chainloop/blob/main/app/controlplane/plugins/core/slack-webhook/v1/README.md) | 1.0 | Send attestations to Slack | |
22+
| [smtp](https://github.com/chainloop-dev/chainloop/blob/main/app/controlplane/plugins/core/smtp/v1/README.md) | 1.0 | Send emails with information about a received attestation | |
2323

2424
## How to use integrations
2525

‎docs/docs/reference/operator/contract.mdx‎

Lines changed: 33 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,39 @@ It has the following effect on the attestation process.
9797

9898
Currently, we support the following runner types
9999

100+
### `AZURE_PIPELINE`
101+
102+
The following environment variables will be automatically added to the attestation. For more information on what they mean, refer to [this link](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml).
103+
104+
- `BUILD_REQUESTEDFOREMAIL`
105+
- `BUILD_REQUESTEDFOR`
106+
- `BUILD_REPOSITORY_URI`
107+
- `BUILD_REPOSITORY_NAME`
108+
- `BUILD_BUILDID`
109+
- `BUILD_BUILDNUMBER`
110+
- `BUILD_BUILDURI`
111+
- `BUILD_REASON`
112+
- `AGENT_VERSION`
113+
- `TF_BUILD`
114+
115+
A link to the Azure Pipeline build will be recorded in the control plane too during initialization.
116+
117+
### `CIRCLECI_BUILD`
118+
119+
The following environment variables will be automatically added to the attestation. For more information on their meaning, refer to [the official CircleCI documentation](https://circleci.com/docs/variables/).
120+
121+
- `CIRCLE_BUILD_URL`
122+
- `CIRCLE_JOB`
123+
- `CIRCLE_BRANCH` (optional)
124+
- `CIRCLE_NODE_TOTAL`
125+
- `CIRCLE_NODE_INDEX`
126+
127+
A link to the CircleCI build will be recorded in the control plane too, during initialization.
128+
129+
### `DAGGER_PIPELINE`
130+
131+
To use Chainloop With Dagger you can use [this Dagger module](https://github.com/chainloop-dev/chainloop/tree/main/extras/dagger)
132+
100133
### `GITHUB_ACTION`
101134

102135
The following environment variables will be automatically added to the attestation. For more information on what they do refer to [this link](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables).
@@ -128,22 +161,6 @@ The following environment variables will be automatically added to the attestati
128161

129162
A link to the Gitlab CI job will be recorded in the control plane too, during initialization.
130163

131-
### `AZURE_PIPELINE`
132-
133-
The following environment variables will be automatically added to the attestation. For more information on what they mean, refer to [this link](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml).
134-
135-
- `BUILD_REQUESTEDFOREMAIL`
136-
- `BUILD_REQUESTEDFOR`
137-
- `BUILD_REPOSITORY_URI`
138-
- `BUILD_REPOSITORY_NAME`
139-
- `BUILD_BUILDID`
140-
- `BUILD_BUILDNUMBER`
141-
- `BUILD_BUILDURI`
142-
- `BUILD_REASON`
143-
- `AGENT_VERSION`
144-
- `TF_BUILD`
145-
146-
A link to the Azure Pipeline build will be recorded in the control plane too during initialization.
147164

148165
### `JENKINS_JOB`
149166

@@ -158,18 +175,6 @@ The following environment variables will be automatically added to the attestati
158175

159176
A link to the build will be recorded in the control plane too, during initialization.
160177

161-
### `CIRCLECI_BUILD`
162-
163-
The following environment variables will be automatically added to the attestation. For more information on their meaning, refer to [the official CircleCI documentation](https://circleci.com/docs/variables/).
164-
165-
- `CIRCLE_BUILD_URL`
166-
- `CIRCLE_JOB`
167-
- `CIRCLE_BRANCH` (optional)
168-
- `CIRCLE_NODE_TOTAL`
169-
- `CIRCLE_NODE_INDEX`
170-
171-
A link to the CircleCI build will be recorded in the control plane too, during initialization.
172-
173178
:::tip
174179
Remember, if all the **env variables** that you need are not defined in the context, you can extend such list via the `envAllowList` option.
175180
:::

‎docs/docusaurus.config.js‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,12 @@ ${content.replaceAll("../../../docs/img/", "/img/")}`,
7272
sourceBaseUrl:
7373
"https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/img",
7474
outDir: "static/img",
75-
documents: ["fanout.png", "fanout-sdk.png"],
75+
documents: [
76+
"fanout.png",
77+
"fanout-sdk.png",
78+
"fanout-execute-materials.png",
79+
"fanout-execute.png",
80+
],
7681
requestConfig: { responseType: "arraybuffer" },
7782
},
7883
],
@@ -85,7 +90,7 @@ ${content.replaceAll("../../../docs/img/", "/img/")}`,
8590
noRuntimeDownloads: true,
8691
performCleanup: false,
8792
sourceBaseUrl:
88-
"https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs",
93+
"https://raw.githubusercontent.com/chainloop-dev/chainloop/main/devel",
8994
outDir: "docs/integrations",
9095
documents: ["integrations.md"],
9196
modifyContent: (filename, content) => {
@@ -104,6 +109,34 @@ ${content.replaceAll("./img/fanout.png", "/img/fanout.png")}`,
104109
},
105110
},
106111
],
112+
// Dagger module guide
113+
// yarn run docusaurus download-remote-dagger-module
114+
[
115+
"docusaurus-plugin-remote-content",
116+
{
117+
name: "dagger-module",
118+
noRuntimeDownloads: true,
119+
performCleanup: false,
120+
sourceBaseUrl:
121+
"https://raw.githubusercontent.com/chainloop-dev/chainloop/main/extras/dagger",
122+
outDir: "docs/guides/dagger", // the base directory to output to.
123+
documents: ["README.md"], // the file names to download
124+
modifyContent: (filename, content) => {
125+
if (filename.includes("README")) {
126+
return {
127+
content: `---
128+
title: Use Dagger With Chainloop
129+
---
130+
131+
${content}
132+
`,
133+
};
134+
}
135+
136+
return undefined;
137+
},
138+
},
139+
],
107140
// Helm Chart readme
108141
// yarn run docusaurus download-remote-deployment-readme
109142
[

‎docs/static/img/fanout-execute-materials.png‎

448 KB
Loading

‎docs/static/img/fanout-execute.png‎

310 KB
Loading

0 commit comments

Comments
 (0)