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 step 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 or cdxgen, which is the tool Harness uses to generate the SBOM. For other SBOM tools, go to Ingest SBOM.

• SBOM Format: Select SPDX or CycloneDX.

If you're using Syft to generate the SBOM and want to ensure it includes all component licenses with high accuracy, you'll need to set specific environment variables based on your project's programming language. Here are the relevant variables:

Programming Language	Name of Variable	Value
Go	SYFT_GOLANG_SEARCH_REMOTE_LICENSES	true
Java	SYFT_JAVA_USE_NETWORK	true
JavaScript	SYFT_JAVASCRIPT_SEARCH_REMOTE_LICENSES	true

To add a new environment variable, go to Overview section of your Build stage, and expand the Advanced section.

By setting these variables, Syft can more effectively fetch and populate the licensing data for the components in your SBOM. This not only enhances the quality of the SBOM but also improves its overall SBOM score. If your SBOM contains NOASSERTIONS, it indicates that Syft was unable to retrieve necessary data.

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.

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 repo-name:tag.

Generate key pairs using Cosign for SBOM Attestation

To perform the attestation process, you need to input the private key and password. You can use your preferred key generation services or use Cosign to generate them. Here's how you can generate keys using Cosign:

1. Install Cosign
2. Run the command cosign generate-key-pair to generate the key pairs.
3. Make sure to note the password used for generating the key pairs. This password is needed for attestation verification purpose.
4. This command will generate a private key as a .key file and a public key as a .pub file. To securely store these files, use Harness file secret.

• Private Key (optional): Input your Private key from the Harness file secret.

• Password (optional): Input your Password for the Private key from the Harness file secret.

• SBOM Drift (optional): 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.

Generate key pairs using Cosign for SBOM Attestation

To perform the attestation process, you need to input the private key and password. You can use your preferred key generation services or use Cosign to generate them. Here's how you can generate keys using Cosign:

1. Install Cosign
2. Run the command cosign generate-key-pair to generate the key pairs.
3. Make sure to note the password used for generating the key pairs. This password is needed for attestation verification purpose.
4. This command will generate a private key as a .key file and a public key as a .pub file. To securely store these files, use Harness file secret.

• Private Key: Input your Private key from the Harness file secret.

• Password: Input your Password for the Private key from the Harness file secret.

• 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

Generate key pairs using Cosign for SBOM Attestation

To perform the attestation process, you need to input the private key and password. You can use your preferred key generation services or use Cosign to generate them. Here's how you can generate keys using Cosign:

1. Install Cosign
2. Run the command cosign generate-key-pair to generate the key pairs.
3. Make sure to note the password used for generating the key pairs. This password is needed for attestation verification purpose.
4. This command will generate a private key as a .key file and a public key as a .pub file. To securely store these files, use Harness file secret.

• Private Key: Input your Private key from the Harness file secret.

• Password: Input your Password for the Private key from the Harness file secret.

• 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.

GAR

• Artifact Type: Select GAR.

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

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

• Host: Enter your GAR Host name. The Host name is regional-based. For example, us-east1-docker.pkg.dev.

• 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

Generate key pairs using Cosign for SBOM Attestation

To perform the attestation process, you need to input the private key and password. You can use your preferred key generation services or use Cosign to generate them. Here's how you can generate keys using Cosign:

1. Install Cosign
2. Run the command cosign generate-key-pair to generate the key pairs.
3. Make sure to note the password used for generating the key pairs. This password is needed for attestation verification purpose.
4. This command will generate a private key as a .key file and a public key as a .pub file. To securely store these files, use Harness file secret.

• Private Key: Input your Private key from the Harness file secret.

• Password: Input your Password for the Private key from the Harness file secret.

• 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.

Generate key pairs using Cosign for SBOM Attestation

To perform the attestation process, you need to input the private key and password. You can use your preferred key generation services or use Cosign to generate them. Here's how you can generate keys using Cosign:

1. Install Cosign
2. Run the command cosign generate-key-pair to generate the key pairs.
3. Make sure to note the password used for generating the key pairs. This password is needed for attestation verification purpose.
4. This command will generate a private key as a .key file and a public key as a .pub file. To securely store these files, use Harness file secret.

• Private Key: Input your Private key from the Harness file secret.

• Password: Input your Password for the Private key from the Harness file secret.

• 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.