Skip to main content

Software Bill of Materials (SBOM) Quick Start

Use this guide to get up to speed with Software Bill of Materials (SBOMs) and how you can use them in your build pipeline. Sonatype Lifecycle supports both the CycloneDX and SDPX formats.

Overview

If you are here, you probably heard the buzz around the executive order requiring vendors to provide SBOM security for the software supply chain. This is great news! Since our beginning, automating the identity and management of open-source risk has been our key focus. We were early adopters of the SBOM standard with a number of key features:

  • Sonatype actively participates in CycloneDX SBOM spec and development.

  • Sonatype Lifecycle supports scanning SBOMs using our CLI, APIs, and UI.

  • Sonatype Lifecycle can export any application scan report in either CycloneDX or SDPX formats.

CycloneDX

CycloneDX is a fantastic standard for reporting and tracking all of the open-source dependencies used in an application. It includes both the hash fingerprints of the components and also the packageUrl to determine where the component is coming from. Recently the standard began including basic vulnerability data along with the component details to understand the risk, which is both good and bad. This may present us with the known security risks at the time, however, this may give a false sense of security as new vulnerabilities are found after the SBOM is generated.

SPDX

The Software Package Data Exchange (SPDX) is another open standard for communicating software bill of material information, which excels in capturing license information and positions itself as an alternative to CycloneDX.

SBOM use cases

So the question is, what do we do with them?

Here are the three primary use cases Sonatype customers do with SBOMs:

  1. Consuming SBOMs

  2. Generating SBOMs

  3. Managing SBOMs

Consuming SBOMs

Sonatype Lifecycle can scan an SBOM as part of application analysis or run a scan on a stand-alone SBOM.

Analysis Phases

The Sonatype analysis is made of three phases:

  1. analyzing all the components going into the application during the build

  2. gathering identity and vulnerability data of those found components

  3. and comparing that data against your governance policies to generate a report

Including an SBOM with an analysis during the build

In some situations, doing an analysis with the SBOM may lead to better results than scanning build artifacts alone. This is because we can report not only everything found in an application but more definitely where those parts came from. SBOMs provide a pedigree of how the application was built which is not included in the final application. This is especially true for ecosystems where parts of the component are used instead of the entire component. Similarly, we can better determine the definitive source component used for common parts shared by many components. This is critical when metadata such as licenses are only associated with the component and not their parts.

Analyzing an SBOM before building the application

One challenge is you cannot always do the analysis during your build process. The way the application was built is not stored with the final artifacts. Trying to scan your applications before or after the build may end up with confusing or incomplete results. Sonatype has solved this issue by allowing you to use or include SBOMs in your analysis to include the pedigree of the components in the results of your scan. This allows you to do an analysis of the application at any time using the SBOM.

Here are some use cases worth considering:

  • Shift left by analyzing your source code manifests in active development to learn of risk before becoming too dependent on new open-source components.

  • When promoting an application to production, review if any new violations have been discovered or enforce a more stringent release policy.

  • Keep a point-in-time copy of the SBOMs either in the repository along with your binaries or in a secure central repository where you can quickly access them when needed.

SBOM best practices

  • When building your application, generate and store an SBOM along with your packaged binaries so that you always know exactly what went into the final application

  • Use your SBOMs to analyze your applications before deploying to keep critical vulnerabilities from going out into production

  • Share your SBOMs with key stakeholders but you may wish to avoid making them public

Note

Sonatype Lifecycle scanners and UI are expecting the SBOM to have a specific naming format for the scanner to identify the file as an SBOM. Use the following naming format when scanning SBOMs otherwise, the scan will ignore the file. The prefix and first dash are optional and you will need to use the correct file type accordingly. The prefix is used as the identity source for any unknown components.

[prefix]-bom.[xml|json]

Scanning an SBOM with the CLI

  • Review the CLI documentation on using the CLI to scan applications with the Command Line Scanner.

  • Target your SBOM directly as formatted to the above naming requirements or include the SBOM at the root of the scan context with the rest of your application during the build.

  • Review the CycloneDX Application Analysis and SPDX Application Analysis pages for additional details on scanning SBOMs.

Scanning an SBOM with the API

SBOMs can also be uploaded directly with the Third-Party REST API.

  1. Example for the REST call including your SBOM as the data target (-d) for the call.

    1. We are using 'cyclonedx' for the source parameter to identify where the sbom is being sourced ('spdx' could be used for the source parameter for SPDX content scanning).

    2. Alternatively, use 'application/json' in your headers to upload a JSON file.

      curl -u {user}:{password} -X POST -H "Content-Type: application/xml" -d '{bom_text}' 'http://localhost:8070/api/v2/scan/applications/{applicationid}/sources/cyclonedx'

  2. A statusUrl is returned to monitor the results.

    1. Repeat the call to the statusUrl until the results are ready.

    2. The analysis typically takes around 20 secs to return the report with large projects taking a few minutes.

      {"statusUrl": "api/v2/scan/applications/{applicationId}/status/{statusId}"}

  3. Details of the scan will be returned along with policy actions and the { reportHtmlUrl } where you can find the complete results.

Scanning an SBOM within the UI

You can scan an application's SBOM using the UI.

  1. Navigate to the Orgs and Policies tab and locate the application to scan (you may need to add it if it is not there)

  2. Under Actions in the upper right, choose the 'Evaluate a File' option.

  3. From the choose file option, locate your SBOM meeting the above naming requirements, pick a stage, and select the Upload button.

  4. Select View Report.

137202570.png

Generating SBOMs

Whether you are working on compliance with executive orders or need a standard method to report dependency data, creating an SBOM with Sonatype tools is easy. SBOMs generated by Sonatype tools align with the required criteria reported by NIST.

NIST SBOM Criteria

Sonatype Lifecycle

SBOM Completeness

Direct/Transitive OSS Dependencies

SDLC Integration

Analysis using build, release, and deployment showing SBOM and software risk

SBOM Accuracy

Report accurate component data and match with binaries

Integrated Risk Analysis

Identify known vulnerabilities in n-level dependencies

Malicious Code Detection (Counterfeit components, hidden functionalities)

Integrated component risk scoring based analysis of components, to identify known vulnerabilities, machine learning algorithms to search for unknown vulnerabilities

Every Sonatype scan report can be exported as either a CycloneDX or SPDX SBOM in an XML file or in JSON file format. You can do this in the UI of the scan report or programmatically through the REST API.

Exporting an SBOM through the UI

Getting the SBOM through the UI.

  1. Navigate to the latest application scan report

  2. Choose from the Options menu:

    1. Export CycloneDx - the CycloneDx SBOM is downloaded as an XML file

    2. Export SPDX - the SPDX SBOM is downloaded as a JSON file

170099035.png

Exporting an SBOM through the REST API

Example of getting the CycloneDx SBOM. Review the documentation on CycloneDX REST API.

curl -u admin:admin123 -X GET -H 'Accept: application/xml' -o 'bom.xml' 'http://localhost:8070/api/v2/cycloneDx/1.4/{applicationInternalId}/stages/build'

Example of getting the SPDX SBOM. Review the documentation on SPDX REST API.

curl -u admin:admin123 -X GET -o 'spdx.xml' 'http://localhost:8070/api/v2/spdx/{applicationInternalId}/stages/build?format=xml'

Generating a CycloneDX SBOM before scanning

CycloneDX can be used to generate an SBOM from your source code. These use your application build context to get a list of the declared and transitive dependencies referenced in your code. You can use their tools as a part of your build process to include in your Sonatype evaluation. Our analyzers will combine these results with anything discovered in your code to get a complete bill of material for your application.

Key considerations with third-party SBOMs

  • Use the naming requirements detailed above to have SBOMs picked up by the Sonatype analyzers.

  • The results from third-party tools may differ from our in-built analyzers.

    • They may use different methods for determining what are and what are not components.

    • They may misreport or include incomplete pedigree data that is rejected from our analysis.

    • They may only include components reported in the manifest while missing renamed or embedded components in the source.

    • They may include/exclude components used in the development scope which are often not included in the final application.

As a best practice, you will want to compare the results from the different analyzers to determine which model best aligns with your requirements and expectations. Once satisfied with the results, we recommend you standardize that method across your organization to maintain consistency throughout your build lifecycle.

Managing SBOMs

You need to decide how you are going to manage and use the SBOMs you have generated from your portfolio. So far, the industry as a whole has not standardized the best way to do this. Here are a few suggestions we have seen success with our partners.

Storing your SBOMs

Organizations use binary repositories, such as Nexus Repository, to store and manage their built artifacts in privately hosted repositories.

  • You can store your SBOMs along with your Java applications in a Maven repository for quick reference.

  • For non-java applications, you may choose to upload SBOMs to a raw repository for easy access.

  • Plan ahead and use clear namespacing and release details for your SBOMs to make things more manageable.

  • The Tagging API can be used to associate your release metadata with the components in your repository.

OWASP CycloneDX has launched a BOM Exchange API in order to better manage SBOMs across organizations. Check out their BOM Repository Server for details.

Searching for Dependencies

When trying to find which application's specific dependencies are used, start with the IQ Server Advance Search to avoid having to export and open every application SBOM.

Learn more from our 0-Day Vulnerability Best Practices.

Analyzing your Organization's Dependencies

The IQ Data Insight - Stack Divergence tool is awesome for analyzing component treads across your organization.

Additional Resources

Since you seem to like reading, here are more resources to check out!