Generate and Manage Software Bill of Materials (SBOM)

A Software Bill of Materials (SBOM) is an exhaustive list of all components, libraries, and other dependencies utilized in a software application. The SBOM Orchestration step within Harness SSCA facilitates the generation of SBOMs for your software artifacts.

This document elaborates on utilizing the SBOM Orchestration step for SBOM generation. If you already possess an SBOM and wish to ingest it, please refer to the Ingest SBOM section.

Requirements

Prepare a pipeline

You can generate the SBOM in both the Build and Deploy stages of your Harness pipeline.

Example Pipeline for SBOM generation

These example demonstrate how you could set up Build and Deploy stages to generate SBOM.

Build stage

This example Build stage has three steps:

• Run step: Build and test an artifact (image).
• Build and Push an image to Docker Registry step: Build and push the image to a Docker registry.
• SBOM Orchestration step: Generate the SBOM.

Deploy stage

SBOM Orchestration in deploy stage can only be used in the Containerized Step Groups This example Deploy stage has two steps:

• SBOM Orchestration step: Generate the SBOM.
• Rolling deployment step: Deploy the image.

Generate the keys for SBOM Attestation - optional

For enhanced trust and verification of your SBOM's integrity, the SBOM Orchestration step offers optional signing and attestation generation. This functionality requires a private key, password, and corresponding public key. If you choose to skip signing, you can proceed without generating or storing these keys.

Here's how to set these keys if you choose to enable signing

• Generate the keys: Begin by generating the keys using Cosign
• Securely store the keys: Safeguard the generated private key, public key, and password by creating Harness file secrets for each.

Add the SBOM Orchestration step

Use the SBOM Orchestration step to generate an SBOM in either the Build or Deploy stage of a Harness pipeline.

• In a Build stage, add the SBOM Orchestration step after the artifact (image) has been pushed to an artifact repository.
• In a Deploy stage, add the SBOM Orchestration step before the deployment step.

info

SBOM Orchestration and Enforcement steps in deploy stage can only be used in the Containerized Step Groups

The SBOM Orchestration step includes various settings for generating the SBOM for both Containers and Repositories. We will delve into the different fields that need to be configured for each option to support the generation of the SBOM.

• Name: Enter a name for the step.

• Step Mode: Select Generation.

• SBOM Tool: Select Syft, which is the tool Harness uses to generate the SBOM. For other SBOM tools, go to Ingest SBOM.

• SBOM Format: Select SPDX or CycloneDX.

The Artifact Source allows you to specify the source of the artifact. Presently, the SBOM Orchestration step supports both containers and code repositories. Specifically for containers, it offers native support with DockerHub and ECR. Here's how you can configure them accordingly.

Deprecation Alert:

Please note that the previously available Container option, has now been deprecated. In its place, we now offer native support for DockerHub, ECR, GCR, and ACR. Additionally, the support for other registries is coming soon. We encourage users to connect to their registries using the dedicated options available within the list of artifact sources.

DockerHub

• Artifact Type: Select DockerHub.

• Container Registry: Select the Docker Registry connector that is configured for the DockerHub container registry where the artifact is stored.

• Image: Enter the name of your image with tag, such as my-docker-org/repo-name:tag.

• Private Key: The Harness file secret containing the private key to use to sign the attestation.

• Password: The Harness text secret containing the password for the private key.

• SBOM Drift: This feature allows you to track changes in SBOMs, it can detect the changes by comparing the generated SBOM against a specified one. For an in-depth understanding of this functionality, please refer to the SBOM Drift documentation. If you prefer not to detect any changes in SBOMs, leave this option unchecked.

ECR

• Artifact Type: Select ECR.

• Container Registry: Select the Docker Registry connector that is configured for the Elastic container registry where the artifact is stored.

• Image: Enter the name of your image with tag for the image for which you're generating an SBOM, such as my-docker-repo/my-artifact:latest.

• Region: The geographical location of your ECR repository.

• Account ID: The unique identifier associated with your AWS account.

• Private Key: The Harness file secret containing the private key to use to sign the attestation.

• Password: The Harness text secret containing the password for the private key.

• SBOM Drift: This feature allows you to track changes in SBOMs, it can detect the changes by comparing the generated SBOM against a specified one. For an in-depth understanding of this functionality, please refer to the SBOM Drift documentation. If you prefer not to detect any changes in SBOMs, leave this option unchecked.

GCR

• Artifact Type: Select GCR.

• Container Registry: Select the Docker Registry connector that is configured for the Google container registry where the artifact is stored.

• Image: Enter the name of your image with tag for which you're generating the SBOM, example docker-image:tag.

• Host: Enter your GCR Host name. The Host name is regional-based. For instance, a common Host name is gcr.io, which serves as a multi-regional hostname for the United States.

• Project ID: Enter the unique identifier of your Google Cloud Project. The Project-ID is a distinctive string that identifies your project across Google Cloud services. example: my-gcp-project

• Private Key: The Harness file secret containing the private key to use to sign the attestation.

• Password: The Harness text secret containing the password for the private key.

• SBOM Drift: This feature allows you to track changes in SBOMs, it can detect the changes by comparing the generated SBOM against a specified one. For an in-depth understanding of this functionality, please refer to the SBOM Drift documentation. If you prefer not to detect any changes in SBOMs, leave this option unchecked.

ACR

• Artifact Type: Select ACR.

• Container Registry: Select the Docker Registry connector that is configured for the Azure container registry where the artifact is stored.

• Image: Enter your image details in the format <registry-login-server>/<repository>:<tag>. The <registry-login-server> is a fully qualified name of your Azure Container Registry. It typically follows the format <registry-name>.azurecr.io, where <registry-name> is the name you have given to your container registry instance in Azure. Example input: automate.azurecr.io/acr:test

• Subscription Id: Enter the unique identifier that is associated with your Azure subscription.

• Private Key: The Harness file secret containing the private key to use to sign the attestation.

• Password: The Harness text secret containing the password for the private key.

• SBOM Drift: This feature allows you to track changes in SBOMs, it can detect the changes by comparing the generated SBOM against a specified one. For an in-depth understanding of this functionality, please refer to the SBOM Drift documentation. If you prefer not to detect any changes in SBOMs, leave this option unchecked.

Repository

• Artifact Type: Select Repository.

  info

  The Repository option requires that your repository is cloned into the stage workspace before the SBOM Orchestration step runs. There are several ways you can do this:

  • Clone the codebase by default, such as a Build stage's default codebase.
  • Add a Git Clone step or Run step to the Deploy stage.
  • Add a Git Clone step or Run step to a Build stage.

• Repository URL: The Repository URL you've configured for cloning into the workspace.

• Source Path: Leave blank or enter a path (in the repository) for which you want to generate SBOM. Use this setting to generate SBOM for a specific section of your code repo, rather than your entire repo. The path must start with /. For example, if your repository URL is https://github.com/username/repo, and you want to generate SBOM for https://github.com/username/repo/service-core/source, then enter /service-core/source for Source Path. To generate an SBOM for the entire repository, leave this field empty.

• Git Branch: The branch of the repository for which you want to generate the SBOM.

• Workspace: If you cloned the codebase to a different directory than the root workspace directory (/harness), enter the path to the subdirectory using the format /harness/PATH/TO/SUBDIRECTORY. Leave this field empty if you cloned your codebase into the default directory (/harness). Usually, your codebase is only cloned into a non-default directory if you are cloning multiple codebases into a pipeline.

• SBOM Drift: Select this option if you want to track changes in SBOM. Harness SSCA can detect the changes by comparing the generated SBOM against a specified base/primary SBOM.

Run the pipeline

When the pipeline runs, the SBOM Orchestration step performs the following actions:

• Generates an SBOM in the chosen format for both Containers and Repositories.
• Specifically for Containers:
  • Generates and signs an attestation using the provided private key and password.
  • Stores the SBOM in Harness and uploads the .att file to your container registry.

SBOMs for both Containers and Code Repositories are accessible in the Artifacts view. Additionally, you can locate the SBOM for any artifact on the Supply Chain tab within the Execution Details page in Harness. For detailed insights, please refer to the view pipeline execution results documentation.

Next steps

After generating an SBOM, you can apply SBOM Policy Enforcement to achieve open source governance.