How do I generate a CycloneDX SBOM Report?

  • 17 January 2023
  • 1 reply
  • 1011 views

 

What is SBOM?

A Software Bill of Materials (SBOM) is a record of the supply chain relationships between the components used when creating software. The record lists all components of a product, including all open source software, which can be helpful for both the developers and other stakeholders, such as Investors and legal teams. Visit our blog for more information.

 

What is CycloneDX?

CycloneDX, developed by the Open Web Application Security Project (OWASP), is an open common standard for communicating SBOM information, a data format.

 

What extra information is included in the SBOM Report?

There are a few data points included in the SBOM which are not included in the regular License Report:

  • Proof of license - a reference to the source from where we fetched the license information

  • License text - the actual text that the license consists of

  • Copyright statement - displays the person or organization who holds the copyright

  • Open Source Select link - a link to the dependency page in Open Source Select, where you can find additional information on the specific open source package 

  • Dependency relations - reference numbers (ref) for each component and an array of each direct dependency of that dependency (depends_on), see the section Dependency Relations below for more details

  • Root Fixes - can be found under Recommendation, consisting of information about the first version of the specific vulnerable dependency that is safe, as well as the first version of the root/direct dependency that doesn't contain a vulnerable version of the indirect dependency. See the section Root Fixes for more details

Keep in mind that license information may differ depending on the package and the specific version used.

 

Dependency Relations

In the dependencies array, you can find a reference number (ref) for each component and an array of each direct dependency of that dependency (depends_on). The roots of the relational trees will reference to the files in the project, together with the direct dependencies that it contains. By traversing the dependencies array, it is possible to build the entire dependency tree.

In example below, you can see the direct dependency `webpack:4.28.4` depending on `terser-webpack-plugin:1.2.1` which in turn depends on `terser:3.14.1`.


"dependencies": [
{
"ref": "e771afadf654cc12c324a0dd716518dd",
"depends_on": ["cpe:2.3::~:webpack:4.28.4:~:~:~:~:~:~:~"]
},
{
"ref": "cpe:2.3::~:webpack:4.28.4:~:~:~:~:~:~:~",
"depends_on": ["cpe:2.3::~:terser-webpack-plugin:1.2.1:~:~:~:~:~:~:~"]
},
{
"ref": "cpe:2.3::~:terser-webpack-plugin:1.2.1:~:~:~:~:~:~:~",
"depends_on": ["cpe:2.3::~:terser:3.14.1:~:~:~:~:~:~:~"]
},
{
"ref": "cpe:2.3::~:terser:3.14.1:~:~:~:~:~:~:~",
"depends_on": []
}
]

 

Here is how this would be visualised in our user interface:

 

 

Root Fixes

Under Recommendation you can find information about the first version of the specific vulnerable dependency that is safe, as well as the first version of the root/direct dependency that doesn't contain a vulnerable version of the indirect dependency. See example below:

"recommendation": "Multiple components are affected by this vulnerability.
Component: pkg:npm/async@3.2.0
Safe version: 3.2.2.
Root fixes: Update root dependency pkg:npm/htmlhint@0.14.2 to 0.16.2.
---------
Component: pkg:npm/async@2.6.0
Safe version: 2.6.4.
Root fixes: Update root dependency pkg:npm/gelf-pro@1.2.2 to 1.3.4.",
"created": "2022-04-06T17:15:00+00:00",
"published": "2022-04-06T17:15:00+00:00",
"updated": "2022-04-06T17:15:00+00:00",
"affects": [
{
"ref": "pkg:npm/async@3.2.0"
},
{
"ref": "pkg:npm/async@2.6.0"
}
],
"references": [
{
"id": "GHSA-fwr7-v2mv-hh25",
"source": {
"url": "https://github.com/advisories/GHSA-fwr7-v2mv-hh25",
"name": "GitHub"
}
}

 

Exporting a CycloneDX SBOM using our web tool

 

Keep in mind that this feature is only available for enterprise users.

 

In order to generate the CycloneDX SBOM report:

  1. Click on Generate Report in the top right corner of the page

  2. Under Scope select all repositories you wish to see the data for

  3. Select SBOM as the Report Type

  4. Click on Generate

  5. Check your email for the report, which will be sent to you in the .json format. If you can’t find the email in your inbox, make sure to check the SPAM folder.

 

Exporting a CycloneDX SBOM using our web tool - video guide

 

 

Exporting a CycloneDX SBOM to email using the API

If you have already integrated your repository with Debricked, you can generate a CycloneDX SBOM by fetching your data through the API. 

Keep in mind that to use our REST API you will need to authenticate first.

 

Endpoint: /api/{1.0}/open/sbom/generate-cyclonedx-sbom

Here’s an example of a request using curl:

curl -X 'POST' \

 'https://debricked.com/api/1.0/open/sbom/generate-cyclonedx-sbom' \

-H 'Authorization: Bearer <token>' \

-H 'Content-Type: application/json' \

-d '{

  "commitId": 1355119,

  "email": "user1@debricked.com",

  "locale": "en",

  "vulnerabilities": true,

  "licenses": true

}'

 

You can send the following parameters in the body of the request: commitId, email, repositoryIds, branch, locale. You can choose to add license and vulnerability data, using licenses: true/false and vulnerabilities: true/false.

If you provide a commitId, the branch and repositoryIds will be ignored. If you leave the branch field empty, the report is generated for our identified default branch (most likely 'main' or 'master', if applicable) of the selected repository. It is also possible to create an SBOM for all repositories by not specifying any repositoryIds

 

Once you send the request, you will receive your SBOM via email, which will be sent to you in the .json format. If you can’t find the email in your inbox, make sure to check the SPAM folder. If you don't provide an email address, the SBOM will be sent to the email of the user who created the request.

 

Exporting a CycloneDX SBOM to email using the API - video guide

 

Exporting CycloneDX SBOM directly from the API

If you have already integrated your repository with Debricked, you can generate a CycloneDX SBOM and download it directly through the API.

To export a CycloneDX SBOM use the endpoint: /api/1.0/open/sbom/generate-cyclonedx-sbom

You are able to specify whether or not to receive an email with the "sendEmail": true/false parameter. Set it to false if you don’t want to receive the email and true if you do. Regardless of what you put in that parameter, you can fetch the result of the generated SBOM using the reportUuid received from the first endpoint and entering that into the /api/1.0/open/sbom/download-generated-cyclonedx-sbom endpoint.

Once it’s ready, you will be able to download the SBOM directly from the response.

 

 

Check out an example of CycloneDX SBOM.

 


1 reply

Userlevel 4

If you want to deep dive into the topic, check out the video below where we go through an extensive explanation of a SBOM, its benefits and challenges as well as how to use Debricked to generate your SBOM.

 

Reply