Send SBOMs to Dependency-Track

Dependency-Track is an intelligent Component Analysis platform that allows organizations to identify and reduce risk in the software supply chain. Dependency-Track takes a unique and highly beneficial approach by leveraging the capabilities of Software Bill of Materials (SBOM).

Chainloop can be configured to automatically send any CycloneDX Software Bill Of Materials that has been received as part of an attestation to a Dependency-Track instance.

Once configured, any SBOM_CYCLONEDX_JSON piece of evidence received during the attestation process will be sent to Dependency-Track.

See below an example of a contract that includes a SBOM_CYCLONEDX_JSON material.

schemaVersion: v1
materials:
  # SBOMs will be uploaded to the CAS Backend of your choice, such as an OCI registry and referenced in the attestation
  - type: SBOM_CYCLONEDX_JSON
    name: skynet-sbom

See the integration in action in the following video:

Configure Integration

There are two steps involved to enable this integration:

Setup a Dependency-Track integration provider in your Chainloop account
Attach this integration instance to your workflow

Prerequisites

Dependency-Track API Token

An API Token is required for the Chainloop instance to communicate securely with DependencyTrack. The required permissions are BOM_UPLOAD, VIEW_PORTFOLIO (to validate that the provided project ID exists) and optionally PROJECT_CREATION_UPLOAD if project-auto-creation is enabled, more on that later.

The API Key can be created by going to Settings -> Access Management -> Teams -> Select (or create) a Team -> Set permissions -> Copy API key

1 - Setup the integration in your Chainloop account

Let’s register an instance of Dependency-Track that later on can be attached to any of your workflows.

Navigate to the integrations section and click Add Registration.

We can see that there are two required inputs: apiKey and instanceURI, provide those values and click on the Register button.

Navigate to the integrations section and click Add Registration.

We can see that there are two required inputs: apiKey and instanceURI, provide those values and click on the Register button.

With the CLI, we’ll use the chainloop integration registered add command but first let’s find out what are the required inputs using the available describe command.

chainloop integration available describe --name dependency-track

┌──────────────────┬─────────┬──────────────────────┬────────────────────────────────────────────────────────┐
│ ID               │ VERSION │ MATERIAL REQUIREMENT │ DESCRIPTION                                            │
├──────────────────┼─────────┼──────────────────────┼────────────────────────────────────────────────────────┤
│ dependency-track │ 1.4     │ SBOM_CYCLONEDX_JSON  │ Send CycloneDX SBOMs to your Dependency-Track instance │
└──────────────────┴─────────┴──────────────────────┴────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────────────┐
│ Registration inputs                                                                  │
├─────────────────┬──────────────┬──────────┬──────────────────────────────────────────┤
│ FIELD           │ TYPE         │ REQUIRED │ DESCRIPTION                              │
├─────────────────┼──────────────┼──────────┼──────────────────────────────────────────┤
│ allowAutoCreate │ boolean      │ no       │ Support of creating projects on demand   │
│ apiKey          │ string       │ yes      │ The API key to use for authentication    │
│ instanceURI     │ string (uri) │ yes      │ The URL of the Dependency-Track instance │
└─────────────────┴──────────────┴──────────┴──────────────────────────────────────────┘
...

We can see that there are two required inputs: apiKey and instanceURI.

Let’s go ahead and add an integration for an instance hosted at https://dependency-track.chainloop.dev that allows the auto-creation of projects. You’ll get a prompt to introduce the API key

chainloop integration registered add dependency-track --name [my-registration] --opt instanceURI=https://dependency-track.chainloop.dev --opt apiKey=[REDACTED] --opt=allowAutoCreate=true

Command Output

┌──────────────────────────────────────┬──────────────────┬──────────────────────────────────────────────┬─────────────────────┐
│ ID                                   │ KIND             │ CONFIG                                       │ CREATED AT          │
├──────────────────────────────────────┼──────────────────┼──────────────────────────────────────────────┼─────────────────────┤
│ c48f3041-5745-4773-aed9-ccf2f288b2e4 │ Dependency-Track │ host: https://dependency-track.chainloop.dev │ 21 Dec 22 16:29 UTC │
│                                      │                  │ allowAutoCreate: true                        │                     │
└──────────────────────────────────────┴──────────────────┴──────────────────────────────────────────────┴─────────────────────┘

2 - Attach the Integration to a Workflow

Once the integration is live, it can be attached to any workflow. In practice, that means that every workflow attestation that is received that contains a SBOM_CYCLONEDX_JSON material will be forwarded.

The same integration can be attached to multiple workflows

Navigate to the workflow section and click on the Attach button.

During the attachment process, you can decide whether to send the SBOMs to a specific project projectID or create a new one defined by the provided projectName. For the latter to work, you need to make sure that the integration was setup with --allow-project-auto-create option. Furthermore, you can request the new project is created as a child of an existing one parentID, to enable you to group projects in Dependency Track.

Navigate to the workflow section and click on the Attach button.

The attachment is done via chainloop integration attached add command. But as we did before, let’s first find out what are the required inputs using the available describe command.

chainloop integration available describe --name dependency-track

┌──────────────────┬─────────┬──────────────────────┬────────────────────────────────────────────────────────┐
│ ID               │ VERSION │ MATERIAL REQUIREMENT │ DESCRIPTION                                            │
├──────────────────┼─────────┼──────────────────────┼────────────────────────────────────────────────────────┤
│ dependency-track │ 1.4     │ SBOM_CYCLONEDX_JSON  │ Send CycloneDX SBOMs to your Dependency-Track instance │
└──────────────────┴─────────┴──────────────────────┴────────────────────────────────────────────────────────┘
...
┌───────────────────────────────────────────────────────────────────────────────────────────┐
│ Attachment inputs                                                                         │
├─────────────┬────────┬──────────┬─────────────────────────────────────────────────────────┤
│ FIELD       │ TYPE   │ REQUIRED │ DESCRIPTION                                             │
├─────────────┼────────┼──────────┼─────────────────────────────────────────────────────────┤
│ parentID    │ string │ no       │ ID of parent project to create a new project under      │
│ projectID   │ string │ no       │ The ID of the existing project to send the SBOMs to     │
│ projectName │ string │ no       │ The name of the project to create and send the SBOMs to │
└─────────────┴────────┴──────────┴─────────────────────────────────────────────────────────┘

The workflowID can be found by running chainloop workflow list

# Attach integration to a specific workflow
$ chainloop integration attached add \
    --integration my-registered-integration \
    --workflow my-workflow --project my-workflow-project \
    --opt projectName=example-project

That’s all!

Next time Chainloop receives an attestation, its contained SBOMs will be uploaded to https://dependency-track.chainloop.dev to a project called example-project.

Advanced Options

Filter SBOMs dispatch

You can filter the SBOMs that are sent to Dependency-Track based on the attestation or material annotations by providing an optional filter option.

If multiple filters are provided, they will be applied in an AND operation.
If the same annotation is provided in both the attestation and the material, the value in the material will take precedence.

$ chainloop integration attached add \
    ...
    --opt filter="environment=prod,team=security"

Dynamically set the project name

You can also use interpolation to calculate the Depdendency-Track project name dynamically based on the annotations set in either the attestation and the materials.

For example, let’s say that you have the following contract

chainloop-contract.yaml

schemaVersion: v1

annotations:
  - name: version
    value: oss
materials:
  - type: SBOM_CYCLONEDX_JSON
    name: controlplane-sbom
    annotations:
      - name: component
        value: controlplane

You can then use the {{ .Material.Annotations.Component }} or {{ .Attestation.Annotations.Asset }} templates during attachment, for example

$ chainloop integration attached add \
    ...
    --opt projectName="project-{{ .Material.Annotations.component }}"
    # or both combined
    --opt projectName="project-{{ .Material.Annotations.component }}-{{ .Attestation.Annotations.version }}"

this will send the SBOM to a project called project-controlplane or project-controlplane-oss respectively.

Getting Started

Concepts

Guides

References

Misc

Configure Integration

Prerequisites

1 - Setup the integration in your Chainloop account

2 - Attach the Integration to a Workflow

Advanced Options

Filter SBOMs dispatch

Dynamically set the project name

Getting Started

Concepts

Guides

References

Misc

​Configure Integration

​Prerequisites

​1 - Setup the integration in your Chainloop account

​2 - Attach the Integration to a Workflow

​Advanced Options

​Filter SBOMs dispatch

​Dynamically set the project name

Configure Integration

Prerequisites

1 - Setup the integration in your Chainloop account

2 - Attach the Integration to a Workflow

Advanced Options

Filter SBOMs dispatch

Dynamically set the project name