Skip to content

Dependency list exports in CycloneDX SBoM format

Release notes

Since the US Federal Government issued the software bill of materials (SBOM) requirement, companies have been required to produce their SBOM to help further increase the security of the software supply chain. The CyloneDX format has become the adopted SBOM standard. In this release, you will be able to export an SBOM directly from the Dependency List.

Problem to solve

When a user clicks the Export button on the Dependency List, they download a JSON file in GitLab's custom format. Ideally users would be downloading an industry standard like CycloneDX.

Note: We will need to add a dropdown that let's users choose either the old custom GitLab format or the CycloneDX format. The old custom GitLab format can be deprecated and removed in a major milestone.

Intended users

Proposal

At the project level, a user can export their Dependency List and download their dependency list in CycloneDX.json format.

  • API access to download the file.
  • A user will have two options when they click on the Export button: 1. JSON, 2. CycloneDX.

image

At the group level, a user can export and download their Dependency List in a zip archive. The zip will contain one CycloneDX file per project.

Further details

Why CycloneDX?

There are two industry standard formats for dependency reporting; CycloneDX and SPDX. We are choosing to start with CycloneDX because it is a superset of data that is in SPDX. Users can convert the CycloneDX format to the SPDX format. However, if a user converts from SPDX to CycloneDX there might be missing information.

Why does the group Dependency List export a zipped file instead of just one, CycloneDX file?

The group-level dependency export file format must be streamable to be able to handle the large amount of data that may be present in a group. Additionally, a bill of materials represents components from a single project or software component.

Unfortunately, CycloneDX is not streamable either so it won't work for the group-level export. We can file an issue with the CycloneDX project to see if they'd be interested in offering a streamable format like this, but we would need them to implement it to do such a thing. In order to read or write JSON documents, you have to hold the entire document in memory. If a group produces an export that is 32 gigabytes in size, then that means that the machine running GitLab needs to have 32 gigabytes of memory free in order to create the export. This is too much. With CSV and JSONL formats, we only need to hold one line in memory at a time, which means that each export being created needs < 1 megabyte of memory no matter how big the export is. This is mandatory to be able to operate at GitLab.com scale at the group-level. Further, an SBOM contains the inventory for a single piece of software (project). Multiple projects need multiple SBOMs.

Why not write the CycloneDX format but use JSONL instead of JSON to meet the requirements to GitLab.com for the group level?

JSONL and JSON aren't interchangeable. The CycloneDX JSON document looks like this:

{
  "version": "1.5",
  "components": [
    { "type": "library", "name": "activesupport", "version": "7.0.1" },
    { "type": "library", "name": "activerecord", "version": "7.0.1" }
  ]
}

In JSONL, each line is a separate JSON document. You read the line, parse it, do whatever you want with the data, then repeat the process on the next line. The challenge here is how would CycloneDX distinguish between all the different properties when using this format? It might be doable by specifying the property in the JSON document. A JSONL version of CycloneDX might look something like this:

{ "property": "component", "type": "library", "name": "activesupport", "version": "7.0.1" }
{ "property": "component", "type": "library", "name": "activerecord", "version": "7.0.1" }

Permissions and Security

Documentation

https://docs.gitlab.com/ee/user/application_security/dependency_list/#downloading-the-dependency-list

Availability & Testing

Available Tier

GitLab Ultimate

Feature Usage Metrics

What does success look like, and how can we measure that?

What is the type of buyer?

Is this a cross-stage feature?

No

What is the competitive advantage or differentiation for this feature?

This allows customers to leverage the output of our dependency list in a format that is widely accepted by the industry.

Links / references

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

Edited by Brian Williams