Skip to main content

Chainloop Integrations

Operators can extend Chainloop functionality by setting up third-party integrations that operate on your attestation metadata. Integrations can range from sending a Slack message, uploading the attestation to a storage backend or sending a Software Bill Of Materials (SBOMs) to a third-party service for analysis, for example.

FanOut Plugin

Below you can find the list of currently available integrations. If you can't find the integration you are looking for, feel free to reach out or contribute your own!

Available Integrations​

IDVersionDescriptionMaterial Requirement
dependency-track1.4Send CycloneDX SBOMs to your Dependency-Track instanceSBOM_CYCLONEDX_JSON
discord-webhook1.1Send attestations to Discord
guac1.0Export Attestation and SBOMs metadata to a blob storage backend so guacsec/guac can consume itSBOM_CYCLONEDX_JSON, SBOM_SPDX_JSON
slack-webhook1.0Send attestations to Slack
smtp1.0Send emails with information about a received attestation

How to use integrations​

First, you need to make sure that the integration that you are looking for is available in your Chainloop instance, to do so you will:

$ chainloop integration available list
┌──────────────────┬─────────┬──────────────────────┬───────────────────────────────────────────────────────────┐
│ ID               │ VERSION │ MATERIAL REQUIREMENT │ DESCRIPTION                                               │
├──────────────────┼─────────┼──────────────────────┼───────────────────────────────────────────────────────────┤
│ dependency-track │ 1.2     │ SBOM_CYCLONEDX_JSON  │ Send CycloneDX SBOMs to your Dependency-Track instance    │
├──────────────────┼─────────┼──────────────────────┼───────────────────────────────────────────────────────────┤
│ smtp             │ 1.0     │                      │ Send emails with information about a received attestation │
├──────────────────┼─────────┼──────────────────────┼───────────────────────────────────────────────────────────┤
│ oci-registry     │ 1.0     │                      │ Send attestations to a compatible OCI registry            │
├──────────────────┼─────────┼──────────────────────┼───────────────────────────────────────────────────────────┤
│ discord-webhook  │ 1.1     │                      │ Send attestations to Discord                              │
└──────────────────┴─────────┴──────────────────────┴───────────────────────────────────────────────────────────┘

Once you find your integration, i.e oci-registry, it's time to configure it.

Configuring an integration has two steps: 1) register it in your organization and 2) attach the registered integration to your workflows.

Registering an integration​

Registration is when a specific instance of the integration is configured on a Chainloop organization. A registered instance is then available to be attached to any workflow.

In our case, we want to register an instance of the oci-registry integration. To do so, we need to first figure out what configuration parameters are required by the integration. We can do so by running:

$ chainloop integration available describe --name oci-registry
┌──────────────┬─────────┬──────────────────────┬────────────────────────────────────────────────┐
│ ID           │ VERSION │ MATERIAL REQUIREMENT │ DESCRIPTION                                    │
├──────────────┼─────────┼──────────────────────┼────────────────────────────────────────────────┤
│ oci-registry │ 1.1     │                      │ Send attestations to a compatible OCI registry │
└──────────────┴─────────┴──────────────────────┴────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ Registration inputs                                          │
├────────────┬────────┬──────────┬─────────────────────────────┤
│ FIELD      │ TYPE   │ REQUIRED │ DESCRIPTION                 │
├────────────┼────────┼──────────┼─────────────────────────────┤
│ password   │ string │ yes      │ OCI repository password     │
│ repository │ string │ yes      │ OCI repository uri and path │
│ username   │ string │ yes      │ OCI repository username     │
└────────────┴────────┴──────────┴─────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ Attachment inputs                                                       │
├────────┬────────┬──────────┬────────────────────────────────────────────┤
│ FIELD  │ TYPE   │ REQUIRED │ DESCRIPTION                                │
├────────┼────────┼──────────┼────────────────────────────────────────────┤
│ prefix │ string │ no       │ OCI images name prefix (default chainloop) │
└────────┴────────┴──────────┴────────────────────────────────────────────┘

In the console output we can see a registration section that indicates that 3 parameters are required, let's go ahead and register it using our Google Artifact Registry Credentials by running:

$ chainloop integration registered add oci-registry \
    --name [unique-registration-name] \
    # i.e us-east1-docker.pkg.dev/my-project/chainloop-cas-devel
    --opt repository=[region]-docker.pkg.dev/[my-project]/[my-repository] \
    --opt username=_json_key \
    --opt "password=$(cat service-account.json)"

Note: You can find more examples on how to configure this specific integration here

Attaching an integration​

Once the integration is registered, we can attach it to any workflow. In practice this means that attestations and material information generated in this workflow will be sent to the registered integration.

The attachment process has at least two required parameters, the workflowID and the registered integrationID. Additionally each integration might have additional to customize its behavior per-workflow. In our case, on the table above, we can see that the oci-registry integration has an optional parameter called prefix that allows you to customize the name of the image that will be pushed to the registry.

$ chainloop integration attached add --workflow $WID --integration $IID --opt prefix=custom-prefix

Congratulations, you are done now! Every new attestation from this workflow will be uploaded to your OCI registry!

FAQ​

How do I know if an integration is available?​

You can use the chainloop integration available list command to list all the available integrations.

How do I know what configuration parameters are required by an integration?​

You can use the chainloop integration available describe command to list all the required configuration parameters.

How do I know what registered integrations I have in my organization?​

You can use the chainloop integration registered list command to list all the registered integrations.

You can also delete a registered integration by using the chainloop integration registered delete command.

How do I know what attachments I have in my organization?​

You can use the chainloop integration attached list command to list all the attachments, and detach them by using the chainloop integration attached delete command.

What If I can't find the integration I am looking for?​

If you can't find the integration you are looking for, feel free to report it or contribute your own!

I am stuck, what do I do?​

If you have any questions or run into any issues, don't hesitate to reach out in Slack or open an Issue. We'll be happy to help.