1 - Update gemnasium to output CycloneDX SBOMs
Release notes
In order to align with a popular Software Bill of Materials (SBOM) industry format standard, Dependency Scanning's gemnasium analyzers will now output a CycloneDX Software Bill of Materials (SBOM) for each supported lock or build file detected. These CycloneDX SBOMs are named cyclonedx-<package-type>-<package-manager>.json
, and are saved in the same directory as the detected lock or build files. The CycloneDX SBOMs can be downloaded the same way as other job artifacts.
Proposal
This issue implements the MVC of the migration outlined in Create plan for ISBOM rollout.
The current process flow for Dependency Scanning jobs is to upload DS reports/artifacts that list vulnerabilities and dependencies, and these reports are consumed by the Rails backend to render both the Dependency List and the Vulnerability Report:
flowchart TB
subgraph "DS Analyzer 1"
1[Analyze project]-- generate -->2[/"Report \n(deps/vulns)"/]
end
subgraph "Rails app"
2 -- upload --> 3[Merge]
3[Merge] --> 4[/Reports/]
4 --> 5[Parse]
5 --> 6[/Vulnerabilities/]
5 --> 7[/Dependencies/]
6 --> 8[Display]
7 --> 9[Display]
end
subgraph "DS Analyzer 2"
10[Analyze project]-- generate -->11[/"Report \n(deps/vulns)"/]
end
11 -- upload --> 3[Merge]
The purpose of this issue is to update the Dependency Scanning jobs to generate extra CycloneDX artifacts. The artifacts aren't leveraged in GitLab, but the frontend will display links to allow users to download them.
After the completion of this issue, the process flow for Dependency Scanning jobs will be the following:
flowchart TB
subgraph "Dependency Scanning Analyzer 1"
1[Analyze project]-- generate -->2[/"CycloneDX Report"/]
1[Analyze project]-- generate -->3[/"Report \n(deps/vulns)"/]
end
subgraph "Rails app"
2 -- upload --> 14["Display download link"]
3 -- upload --> 4[Merge]
4 --> 5[/Reports/]
5 --> 6[Parse]
6 --> 7[/Vulnerabilities/]
6 --> 8[/Dependencies/]
7 --> 9[Display]
8 --> X[Display]
13[CycloneDX Report]
end
subgraph "Dependency Scanning Analyzer 2"
10[Analyze project]-- generate -->11[/"Report \n(deps/vulns)"/]
10[Analyze project]-- generate -->12[/"CycloneDX Report"/]
end
11 -- upload --> 4
12 -- upload --> 13["Display download link"]
Implementation Plan
-
Update gemnasium to output a CycloneDX document for each detected project. For example, if we have the following multi-project repository: . ├── ruby-project/ │ └── Gemfile.lock ├── ruby-project-2/ │ └── Gemfile.lock ├── php-project/ │ └── composer.lock └── go-project/ └── go.sum
Then a CycloneDX report should be generated for each of the above lockfiles, and stored in the same directory as the scanned lockfile:
. ├── ruby-project/ │ ├── Gemfile.lock │ └── cyclonedx-gem-bundler.json ├── ruby-project-2/ │ ├── Gemfile.lock │ └── cyclonedx-gem-bundler.json ├── php-project/ │ ├── composer.lock │ └── cyclonedx-packagist-composer.json └── go-project/ ├── go.sum └── cyclonedx-go-go.json
The CycloneDX report filename will be named as follows:
cyclonedx-<package type>-<package manager>.json
This naming convention will allow multiple CycloneDX reports to exist within a single directory, for example:
. ├── Gemfile.lock ├── cyclonedx-gem-bundler.json ├── composer.lock ├── cyclonedx-packagist-composer.json ├── go.sum └── cyclonedx-go-go.json
The fields in the CycloneDX report should match the current fields provided by Dependency Scanning. See the Security Report Schema for Dependency Scanning for details.
-
[-]
Add new fields to the CycloneDX report using global metadata properties to capture the following details:the dependency filethe optional lockfilethe build filethe dependency export file
Each of these fields will be distinct.Instead of providing the different file types displayed above, we've ended up listing only a single
gitlab:input_file
, which provides the path to the file used for generating the dependency list. The reason this was scaled back was because the current data structure lacks the information necessary for providing this level of detail, as described in this thread. This work has been moved to Update gemnasium scanner package to include additional information which needs to be completed before we can provide these details. -
Add image integration tests for the new behaviour implemented in step 1.
above. -
[-]
Add job integration tests to ensure that CylconeDX documents are uploaded as CI artifacts.To be completed in Add job integration test to ensure that CycloneDX documents are uploaded as CI artifacts.
-
Manually test the behaviour to make sure the CycloneDX reports can be downloaded -
Update the Dependency Scanning documentation to explain: - how CycloneDX reports are generated
- how to download them
- how to merge them together, providing an example
.gitlab-ci.yml
file showing how to add acyclonedx merge
job to your pipeline that uses the CycloneDX CLI to merge multiple CyloneDX reports into a single file. - that the CycloneDX reports are a beta feature. Please do not build an integration around the format of the CycloneDX report since it will likely change.