Skip to main content

SBOM Management

The Software Bill Of Materials (SBOM) is a powerful tool that can significantly enhance the transparency and security of your software supply chain. SBOMs are great for security, vulnerability monitoring, and Open Source License and Regulatory Compliance. Providing a comprehensive list of all software components, including their names, versions, dependencies, license information, unique ids, and more, helps you quickly find and update all affected libraries once a severe following security bug similar to HeartBleed or Log4Shell gets discovered.

If you're looking for a way to manage your SBOMs and other Software Supply Chain metadata, Chainloop is the perfect solution. It allows you to store SBOMs in the central location alongside signed in-toto attestations and, as it sits in the middle, enables you to connect SBOM producers with consumers seamlessly. It improves communication between Developers and Security teams and allows them to propagate compliance and security requirements across the organization.

Goals​

This guide demonstrates how to seamlessly integrate with Chainloop for SBOM secure storage and future consumption and analysis.

In the first part, we explain how to:

Assumptions and prerequisites​

This guide makes the following assumptions:

  • You have Chainloop CLI already installed, and you have already authenticated to the Chainloop control plane. Please check this CLI installation guide if you don't.
  • You have already added your OCI registry, where all artifacts, metadata, and attestations will be stored. Please learn more about how to do it in the Account Setup section.
  • You have a Chainloop Workflow, and an API Token created as explained in this document.
  • You have a Github Action created for your project in your GitHub repository, which is connected to your Chainloop workflow. The Chainloop Integration Demo Action is a good example. You can check it out here.
  • Your Chainloop API Token is set locally and in your GitHub project as the CHAINLOOP_TOKEN environment variable. The Chainloop CLI uses this token to authenticate with our Control Plane.
  • Your Private Key and Private Key Password are exposed locally and in your Github project as the following environment variables. We use this key to sign in-toto attestations for your artifacts, such as SBOMs.
    • CHAINLOOP_SIGNING_KEY
    • CHAINLOOP_SIGNING_PASSWORD

Define contract and requirements​

We define our requirements in the contract that developers must follow when adding new SBOMs.

chainloop workflow list --full

The last column shows your contract id for your workflow. Set the CONTRACT_ID environment variable with your contract id, and we will use it later in the following commands:

export CONTRACT_ID=<your_contract_id>
# export CONTRACT_ID=02eccacf-ad1d-4c31-844c-e515484293f7

Please check your contract to confirm that it is currently empty.

chainloop wf contract describe --name $CONTRACT_ID
[...]
{
  "schemaVersion": "v1"
}

In Chainloop, contracts play an essential role in separating teams and helping SecOps teams communicate their requirements to developers. This eliminates the need for extra meetings or calls, and tracking the status and spread of these requirements throughout the organization is easy. SecOps get a system that facilitates the ongoing adaptation of their security and compliance requirements, while developers are able to easily integrate their build and release pipelines once. With a one-time implementation on the left, it becomes a plug-and-play solution on the right. We will add one requirement to our contract to ensure Developers provide a CycloneDX SBOM during each workflow run.

contract.yaml
schemaVersion: v1
materials:
  # SBOMs will be uploaded to the CAS Backend of your choice, such as an OCI registry and referenced in the attestation
  # Additionally they can be sent to any downstream integration for analysis
  # i.e https://docs.chainloop.dev/guides/dependency-track/
  - type: SBOM_CYCLONEDX_JSON
    name: skynet-sbom
chainloop workflow contract update \
 --name my-contract \
 -f https://github.com/chainloop-dev/chainloop/blob/main/docs/examples/contracts/sbom/cyclonedx.yaml

In the future, the Security team may update this contract with new requirements. Those changes will be automatically propagated across the organization to developers. More on Workflows and Contracts in this document.

Storing and attesting SBOMs​

Once our contract is in place, we must add an SBOM and send it to Chainloop every time our workflow is run. Although the workflow run process can be complex, we will highlight the three most critical steps here. All necessary commands are detailed in the example GitHub github.yml.

Initializing an attestation​

Before adding and sending SBOMs to Chainloop, initiating the attestation process is necessary.

# --name sbom-cdx is an example of the name of the workflow registered in Chainloop's control plane
chainloop attestation init --workflow sbom-cdx --project my-project

Generating SBOMs​

Generate SBOM with Syft. Running this command locally will probably generate an empty SBOM, but it should be good enough in our example.

syft packages . -o cyclonedx-json --file sbom.cyclonedx.json

And shortly after, add it to the previously initialized attestation process.

chainloop att add --name sbom-cdx --value sbom.cyclonedx.json

When you execute this command, it will perform two actions. Firstly, it will upload the SBOMS to a Content Addressable Storage backend that you added during the account setup. Secondly, it will verify that the content is indeed a CycloneDX.

Attest and send the SBOM to Chainloop​

We send SBOMs to Chainloop for storage and additional analysis whenever we release a new version of our docs.

chainloop attestation push --key /tmp/cosign.key

We have implemented best practices by validating and storing SBOM files, CI runner ENV variables, other requirements, and signed in-toto attestations in the central OCI registry using CAS digest. Signed in-toto attestations give us authenticated, tamper-resistant data that meets SLSA 3 Provenance compliance. Please learn more about the attestation process in the Attestation crafting documentation. It's important to note that you can easily download all SBOMs from CAS and specify the sha256 of the CycloneDX file.

chainloop artifact download -d sha256:<cyclonedx_sbom_sha256>

SBOM analysis with Dependency track​

For compliance and auditing purposes, it’s helpful to have your SBOMS stored in a central location, but what if we want to perform some automatic and continuous analysis of it? The good news is that we have a detailed guide on this topic explaining how to configure Chainloop to automatically send all CycloneDX SBOMs to Dependency-Track.

Summary​

This guide shows how to use Chainloop to achieve the following:

  • Store SBOMs in a central location
  • Implement best practices by validating and storing SBOM files, CI runner ENV variables, other requirements, and signed in-toto attestations in the central OCI registry using CAS digest.
  • Automatically generated signed in-toto attestations give us authenticated, tamper-resistant data that meets SLSA 3 Provenance compliance.
  • Provide Developers with a single integration point, regardless of their CI/CD provider.
  • Enable Security Teams and Operators to enforce compliance requirements across the organization. In our example, developers must provide an SBOM file in the CycloneDX format for every workflow run.
  • Add integrations like Dependency Track in Chainloop to automatically send your SBOMs for further processing and analysis. You can add or change existing integrations, which makes Chainloop a future-proof solution.