Skip to main content

Using SBOM Manager

Learn how to use the feature to manage your Software Bill of Materials

Written by Micah Spieler
Updated over 12 months ago

Software Bills of Materials (SBOMs) are inventories that list all of the components in your applications, essential for uncovering vulnerabilities and meeting regulatory specific requirements. With SBOM Manager, you can keep tabs on your software and identify affected systems when new threats emerge, significantly reducing security risks.

Getting started

To start using SBOM Manager, click on the main menu item and then click on the 'New SBOM' Project button. You can create projects from files on your desktop, or use our GitLab or GitHub integrations to collect your SBOMs automatically from your pipelines.

Creating new projects

SBOM projects can be created for any project where software components play a vital role. Many organizations with different tech stacks may have multiple projects tracking multiple SBOMs.

For example, a company with a web app that utilizes multiple different micro-services may have an SBOM project for each microservice pipeline, as well as one (or two) for their main system environment.

Think of each project as a folder that holds a historic list of SBOMs collected from a single pipeline or software system.

Give your new project an identifiable name and description and then define how frequently a new SBOM is available for automated (or manual) collection.

Manual uploads

If you generate your SBOMs outside of a pipeline process or your SBOMs are accessible through the available integrations, you can manually upload an SBOM file from your desktop.

For automated vulnerability scans and proper display, ensure that your SBOM is a JSON structure in either CycloneDX or SPDX format.

Collecting from GitLab

You can automatically collect your current (and future) SBOMs from your GitLab repositories. To do so, you must set up a GitLab job to generate SBOMs during each merge to a particular branch, which can then be collected and scanned by SBOM Manager.

To collect from GitLab, you first need to have a Terraform for GitLab integration configured. Ensure that the project token used for the integration has read privileges to your pipeline jobs.

Setting up the Gitlab Job

The following instructions assumes that you are using YAML in your repo to provision your Gitlab Pipeline and Jobs.

Example for deployed software

This example configuration establishes a GitLab job called sbom_example inside the scan portion of a pipeline.

It leverages the open source syft SBOM scanner to pull in the specified image and then scans the current repo for packages, eventually generating a CycloneDX file.

sbom_example:
  stage: scan
  image: python:3.11.4-slim
  before_script:
    - apt-get update && apt-get install -y curl
    - curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
  script:
    - syft . -o cyclonedx-json > sbom-python.json
  artifacts:
    paths:
      - sbom-example.json
    expire_in: 3 weeks
  only:
    - release

This example assumes a 2 week release cadence so we set the artifact to “expire” in 3 weeks. It is also configured to only run on the release branch. We’ll collect this in our application setup below.

Example for Docker containers

This example shows how to set up GitLab’s scanning tool to scan a Docker image in a private AWS ECR repository.

This example YAML is based on information provided by GitLab in their documentation and source code. This assumes you have your AWS credentials available to the GitLab pipeline.

container_scanning:
  stage: scan
  image: registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning:7
  variables:
    CS_IMAGE: ${ECR_REPO}/environment_name:${CI_COMMIT_SHORT_SHA}
    CS_REGISTRY_USER: AWS
    CS_REGISTRY_PASSWORD: ${AWS_ECR_PASSWORD}
  before_script:
    - ruby -r open-uri -e "IO.copy_stream(URI.open('https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip'), 'awscliv2.zip')"
    - unzip awscliv2.zip
    - sudo ./aws/install
    - aws --version
    - export AWS_ECR_PASSWORD=$(aws ecr get-login-password)
  artifacts:
    reports:
      cyclonedx: "**/gl-sbom-*.cdx.json"
    paths:
      - "**/gl-sbom-*.cdx.json"
  script:
    - gtcs scan

Setting up collection

Once your repos are configured to generate SBOMs, you can then configure the project to automatically collect these files.

  • Project ID – this can be found on the main page of your GitLab project

  • Reference – this is branch name of the pipeline where SBOMs are generated

  • Job Name – this is the name of the specific job that generates the SBOMs

Collecting from GitHub

SBOM Manager can automatically collect your current (and future) SBOMs from dependency graph. This functionality is default and built directly into GitHub's standard offering.

To collect from GitHub, you first need to have a Terraform for GitHub integration configured. Ensure that the project token used for the integration has read privileges to your pipeline jobs. When setting up the GitHub access token, it's suggested that you use a “Fine Grained Token” and ensure at a minimum that it has “Read” access for “Contents” on all repositories you want to collect from.

Confirm dependency graph is enabled

Ensure that dependency graph is turned on for the GitHub repo that you plan to collect from. If dependency graph is enabled and you have dependencies, you’ll see them in the Insights section of your repository.

Setting up collection

Once you have confirmed that dependency graph is enabled, you can then configure the SBOM project to automatically collect your files.

  • Owner name – this is the name of the account in GitHub

  • Repository Name – this is the name of the repository where your SBOMs are being generated

Reviewing your SBOMs

Once your project is set up, SBOM Manager will analyze the provided file and then make the results available to view. Simply click on the file to open a model where you can view the software components and identified vulnerabilities.

Projects that are set to collect files from an integration will display a list of all the SBOMs collected, so you can review results from earlier builds of your software.

Vulnerabilities

SBOM Manager automatically scans each copy of the SBOM files and flags known vulnerabilities. This process looks across 10+ publicly maintained vulnerability databases and highlights any that may be associated to components listed in your bill of materials.

To view the vulnerabilities, click on the SBOM file to open the modal and switch to the Vulnerabilities tab.

If SBOM Manager finds any vulnerabilities that have a High or Critical severity rating, it will set the project to 'needs attention' status. This status can be resolved by fixing the vulnerabilities in your system and generating another SBOM to be collected.

Automated Collection

Projects that are configured to collect from an integration will also automatically collect new SBOM files based on the frequency schedule configured for the project. It's generally best practice to align the frequency schedule with your typical software release schedule — for example, if you release once a week, you can expect that each new release will generate a new SBOM and should be collected.

Did this answer your question?