Ingest components of third-party CycloneDX SBOMs
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Why are we doing this work
The goal is for GitLab to list each package of a third-party SBOM at the manifest or lockfile that declares it, and to show its package manager, as it does for packages from its own analyzer.
The CycloneDX specification does not say where a generator records the source file of a package, the manifest or lockfile that declares it.
GitLab currently reads the source file from one property that only the GitLab DS analyzer writes, gitlab:dependency_scanning:input_file:path. A package from any other generator therefore has no path.
This applies when a CI job uploads a CycloneDX JSON SBOM under artifacts:reports:cyclonedx.
The diagrams below show what a third-party SBOM gets today and with this issue. Yellow marks what this issue changes, amber marks a gap today, and a grey dashed box is a step that is skipped.
Hard requirement
GitLab SBOM ingestion shows no changes. This means component data derived from GitLab SBOMs continues to look the same after changes in this issue are applied.
Requirements covered
A valid CycloneDX SBOM of version 1.4 to 1.7 from a standard generator is ingested without the GitLab DS analyzer's properties
- An SBOM whose header,
metadata.properties, carries no GitLab property, meaning no property whose name starts withgitlab:, is handled as third-party when the feature flag is enabled- The tool entry,
metadata.tools, is not read to recognize an SBOM, so a third-party SBOM that names GitLab as its tool is handled as third-party, and a GitLab SBOM that carries another tool name is handled as GitLab's own - An SBOM whose header carries GitLab's properties, such as
gitlab:dependency_scanning:input_file:path, is GitLab's own and is ingested the original way
- The tool entry,
- Normalization is added to run during ingestion (after cyclonedx validation)
- It applies to known third-party formats in order to improve representation and categorization of components
- Reads the reported source file of each package from where its format records it (for example
syft:location:0:pathon Syft components and uses to populate the location of the component)
- A package with no usable or known source file gets a "default" location which is a fixed path
3rd Party Input File Path Unknown - With the feature flag enabled, an SBOM whose header carries no GitLab property will not generate an error message "Required GitLab CycloneDX properties are missing" in the alert "Error parsing SBOM reports", because such SBOMs are now expected
- An SBOM that declares some GitLab properties but misses a required one keeps the entry, as before
Components filtering
- Components that are not libraries or have a package URL type that is not one of the 17 that GitLab supports are skipped, as before
- Ingestion logs a line where it filters the component out
- Note: showing a message to the user for a skipped component is deferred to subsequent issue
- There is one exception with the
cdxgenformat- A
frameworkcomponent from cdxgen, recognized by its fieldevidence.identity, is read as a library, because cdxgen types ordinary libraries asframework - A
frameworkcomponent in an SBOM without the fieldevidence.identityis not read as a library however, because another generator may useframeworkfor a real framework, which GitLab does not list as a dependency
- A
Components appear in the Dependency List with a package manager
- Where the SBOM records no package manager, it is the default that maps the package URL type (the
typepart of apkg:identifier, such aspypiinpkg:pypi/requests) to a package manager - The package manager that the SBOM records is read first if the third-party format provides it
- For example trivy reports this in property
aquasecurity:trivy:PkgType - A third-party SBOM carries no GitLab property, so
gitlab:dependency_scanning:package_manager:namecannot be read for it
- For example trivy reports this in property
Continuous vulnerability scanning
According to requirement 7 of the epic, CVS should scan components of third-party SBOMs. This works as long as components are from a supported ecosystem (for example the package URL type gem).
Explicit third-party format handling
Each rule below applies only to an SBOM that has defined and known format on top of the CycloneDX spec. All other SBOMs are treated as generic CycloneDX.
Generic CycloneDX
- A
librarycomponent is converted to an sbom component - The specification does not say where the source file is recorded, so each package gets the default location
- A mapping of package manager to purl types maps known values
pypiis pip,npmis npm,mavenis maven,composeris composer,conanis conan,gemis bundler,golangis go,nugetis nuget,cargois cargo,pubis pub,condais conda andswiftis swift
Trivy
- Trivy adds a component for each manifest file, with no package URL and a type other than
library. To fit GitLab's current representation of components these are skipped. If the UX is updated to support non-library components, this could be changed
Syft/Grype
- A package can carry several
syft:location:N:pathproperties, one for each path - Ingestion reads these properties in any SBOM that carries them
Discussion
Format handling
For Dependency Scanning the GitLab UX deals with library components for representation of component lists and vulnerabilities. This is retained for simplicity with a special consideration for formats that represent library components as framework.
Handling for ecosystem to package manager mapping
Only the GitLab DS analyzer and Trivy record the package manager. Syft records an ecosystem name and cdxgen records nothing. For those two, the package manager is the default for the package URL type.
- GitLab DS analyzer
- Records it in
gitlab:dependency_scanning:package_manager:name, whose value is the package manager name itself, such aspoetry
- Records it in
- Trivy
- Records
aquasecurity:trivy:PkgTypeon each package, whose value is Trivy's own type name, such aspoetry,pomordebian
- Records
- Syft
- Records only an ecosystem in
syft:package:type, such aspython
- Records only an ecosystem in
- cdxgen
- Records nothing
A package URL type does not map one to one to a package manager. The Dependency List shows a package manager. The type pypi is pip, pipenv, poetry or uv, the type npm is npm, yarn or pnpm, and the type maven is Maven or Gradle.
At this time inference is not done when encountering "well known" file names (e.g. pom.xml) because certain package managers either can override default or because more than one package manager uses the same file name.
Relevant links
- Epic Extend SCA features coverage by supporting 3rd... (&14760)
- Remove the requirement for SBOM report to comply with the GitLab CycloneDX taxonomy: Remove the requirement for SBOM report to compl... (#474906)
- A guard against newer specification versions, which keeps the rejection of a version above 1.7: Prevent Trivy version bumps from outrunning mon... (#606541)
- Dependency List prerequisites: https://docs.gitlab.com/user/application_security/dependency_list/#prerequisites
Non-functional requirements
- Documentation: Document the supported generators and the Cyclo... (#633171) documents
- The supported formats
- The skipped component types
- The skipped package URL types
- The validation behavior
- Where each generator records the source file
- The default location
- The package manager table
- Feature flag: a new feature flag,
third_party_sbom_support, disabled by default and read for the project of the job that uploads the SBOM, gates every change of this issue and of the other child issues- With the flag disabled, ingestion runs the existing code
- Ingestion already handles the components and the dependency graph of a third-party SBOM, with no source and no path, and that keeps working unchanged with the flag disabled
- The flag has the type
wip, GitLab's type for a feature built over several merge requests and hidden until complete, and it has no rollout issue - A
wipflag lives at most 4 months after it merges into the default branch, and then its type changes tobetaorgitlab_com_derisk
- Performance: ingestion time of one large SBOM is recorded before and after
- Testing: specs for each merge request
- SBOMs that set
gitlab:dependency_scanning:input_file:path, which are the GitLab DS analyzer's own, keep every row they show before the change, with the feature flag enabled and disabled, and with the tool entry renamed - A spec per reading rule and per row of the package manager table, on small SBOMs trimmed by hand
- A spec on an SBOM that lacks what each rule reads, which gives the generic result
- SBOMs that set
Implementation plan
Feature flag and accepting SBOMs whose header carries no GitLab property
- Add the feature flag
third_party_sbom_support(disabled by default and read for the project of the job that uploads the SBOM, of typewip) - With the feature flag enabled, accept SBOMs without GitLab property
- These are treated as valid third-party SBOMs
- No "Required GitLab CycloneDX properties are missing" is shown in the "Error parsing SBOM reports" alert
Normalizing known formats
Normalize the SBOMs of known formats where possible. Ingestion reads their components and source files as it reads the GitLab DS analyzer's. Each rule applies only to SBOMs that contain the fields of that generator.
- cdxgen: component type
- from:
framework - to:
library - reason: cdxgen types ordinary libraries as
framework
- from:
- cdxgen: source file
- from: the property
internal:SrcFile(cdxgen 13) orSrcFile(cdxgen 12), which holds one value for each manifest or lockfile that declares the package - to: one source file path for each value
- reason: cdxgen does not set the GitLab DS analyzer's path property
- from: the property
- Trivy: source file when scanning a directory
- from: the manifest component that depends on the package, because Trivy sets no path on the package itself
- to: the name of that manifest component as the path, for example
foo/pom.xml - reason: Trivy records the file as a component that depends on the package and not as a property of the package
- Trivy: source file when scanning a container image
- from:
aquasecurity:trivy:FilePath - to: the value as the path
- reason: the GitLab DS analyzer's path property is not recorded
- from:
- Syft: source file
- from:
syft:location:N:path, for example/foo/pom.xml - to: the value without the leading slash as the path, for example
foo/pom.xml - reason: the GitLab DS analyzer's paths are relative
- from:
An operating system package, of package URL type apk, deb, rpm, cbl-mariner or wolfi, keeps no source and no path, as before, also where its format records a file.
A package that an SBOM records at several files is listed at every file the scanner recorded. No rule hides a manifest because a lockfile exists. A cdxgen SBOM of a NuGet project shows both, where internal:SrcFile lists a .csproj beside packages.lock.json.
Splitting an SBOM into one report per source file
GitLab ingests one source file for each report, because its own analyzer writes one SBOM for each manifest. A third-party SBOM may be a document for the whole project that lists packages at many files, instead. For these SBOMs ingestion splits the document into one report per file so that parsing and reporting continue to work with third-party SBOMs as it does with GitLab format.
Example, a Trivy SBOM of a Maven project with the modules core and foo, trimmed to three components:
commons-io2.4 is reached fromcore/pom.xmlcommons-text1.8 is reached fromcore/pom.xmljackson-databind2.9.10 is reached fromfoo/pom.xml
The SBOM becomes two reports:
- The report for
core/pom.xmlholdscommons-ioandcommons-text - The report for
foo/pom.xmlholdsjackson-databind
Default location
- Give a component with no source file the default location, so an SBOM with no location is read without a parse error
- An operating system package gets no default location and keeps no source and no path, as before
- Give a component whose SBOM records an install path instead of a manifest (such as
node_modules/lodashin cyclonedx-npm) the default location as well
Setting the package manager
- Set the package manager of each component from
- Value on an SBOM component record
- Mapped value for its package URL type
- The table below holds these rules, so that the Dependency List shows a package manager
The package manager comes from the first row that matches, read from the top. The first row applies only to SBOMs of the generator it names. Every other row applies to every SBOM. GitLab's own SBOMs are ingested as before, which reads gitlab:dependency_scanning:package_manager:name. A third-party SBOM carries no GitLab property, so the table has no row for that property.
| What is read | Value | GitLab package manager |
|---|---|---|
The property aquasecurity:trivy:PkgType in a Trivy SBOM |
a Trivy type name, such as pom |
the package manager that the existing map gives that type name, such as maven |
| The package URL type | pypi |
pip |
| The package URL type | npm |
npm |
| The package URL type | maven |
maven |
| The package URL type | composer |
composer |
| The package URL type | conan |
conan |
| The package URL type | gem |
bundler |
| The package URL type | golang |
go |
| The package URL type | nuget |
nuget |
| The package URL type | cargo |
cargo |
| The package URL type | pub |
pub |
| The package URL type | conda |
conda |
| The package URL type | swift |
swift |
Each row maps one input to one package manager. Where a package URL type could mean several tools, such as pypi, the row gives the most general one, pip.
Covered
- A package manager recorded in
aquasecurity:trivy:PkgType - The 12 package URL types in the table
Not covered
- The Dependency List shows only the package managers in its own fixed list, and this issue does not extend it
- A stored value outside that list shows as empty until the list is extended separately
- The values outside the list include
uv,swift,cocoapodsand the operating system managersapt,dnf,yum,zypperandtdnf - A recorded package manager that GitLab does not recognize, such as
foo, is stored as written and shows as empty - The container package URL types
apk,deb,rpm,cbl-marinerandwolfihave no default, so their package manager is empty unless the SBOM records it - A package URL type GitLab does not support is skipped and logged where it is filtered out, with no alert
- What is not covered is documented in Document the supported generators and the Cyclo... (#633171)
Limitations
- cdxgen lists a
.csprojbesidepackages.lock.jsonfor a NuGet package, and both are listed- No rule removes either
- The cdxgen rule reads the field
evidence.identityand not the tool- A
frameworkcomponent of any other generator that writesevidence.identityis therefore read as a library too
- A
- The default of a package URL type names one tool for a type that several tools share
- Where the SBOM records no package manager, a
pypipackage from a Poetry or uv project shows pip, annpmpackage from a yarn or pnpm project shows npm, and amavenpackage from a Gradle project shows maven
- Where the SBOM records no package manager, a
Acceptance criteria
General ingestion
- With the feature flag enabled, a valid CycloneDX SBOM of any version from 1.4 to 1.7 whose header carries no GitLab property is ingested without the alert "Error parsing SBOM reports" (example:
trivy-reactor.cdx.json, a Trivy SBOM of a Maven project) - Its
librarycomponents appear in the Dependency List with name, version, package URL type, source file path and package manager (example:syft.cdx.json, a Syft SBOM of a Maven project) - A whole-project SBOM is split into one report per file that its components carry, and a component with no file stays in one report (examples:
trivy-reactor.cdx.jsonatpom.xml,core/pom.xmlandfoo/pom.xml, andgeneric.cdx.jsonin one report) - A component with no recorded source file appears at the default location (example:
generic.cdx.json, an SBOM from a generator with no special handling) - A component that is not a
library, or whose package URL type is not supported, is not ingested, and a log line records where it was filtered out (example: theframeworkcomponentcommons-textingeneric.cdx.json) - A third-party row that has a source and a supported package URL type is scanned by continuous vulnerability scanning when the advisory database updates (example:
jackson-coreatfoo/pom.xmlintrivy-reactor.cdx.json, for GitLab's advisory for CVE-2025-49128)
Exceptional cases
- A
frameworkcomponent from cdxgen is ingested as a library (example:cdxgen.cdx.json) - The source file is read from where the format records it (example:
syft.cdx.jsonatcore/pom.xml) - A package that the SBOM records at several files is listed at every one of them (example: a NuGet SBOM from cdxgen 13.2 or later that lists a
.csprojbesidepackages.lock.json) - A package manager recorded by the SBOM is shown (example:
poetryfor the packages oftrivy-poetry-lock.cdx.json) - The name of the file does not set the package manager (example:
npm, notyarn, for the packages ofcdxgen-yarn-lockfile.cdx.json) - A package with no recorded package manager gets the default for its package URL type (example:
npmforlodashingeneric.cdx.json)
Validation
- An SBOM that is invalid against GitLab's CycloneDX schema is rejected as before, with the alert "Error parsing SBOM reports" (example:
cdxgen-dotnet-empty-version.cdx.json, which has an emptyversion)
FF behaviour
- With the feature flag disabled, a GitLab DS analyzer SBOM is ingested exactly as before the change, and with it enabled the SBOM keeps every row, path and package manager it shows before the change (example:
gl-sbom-maven-core.cdx.json, an SBOM written by the GitLab DS analyzer) - With the feature flag disabled, a third-party SBOM is interpreted without any special processing rules
A per-sample checklist is kept with the attached samples.
Out of scope
- Direct and transitive flags, covered by the dependency graph issue Ingest the dependency graph of third-party Cycl... (#633166)
- Removing the rows of a parent
pom.xmlthat only lists modules, and of a Maven module that is listed as a package of itself, covered by the dependency graph issue - Vulnerabilities in the SBOM, covered by Create vulnerability findings from an SBOM's ow... (#633169)
- A message shown to the user for skipped components and unsupported package URL types, which is deferred to a follow-up
- Reading a CPE, an identifier other than a package URL, to identify a component
Verification steps
These steps use the sample SBOMs attached to this issue, including one generic CycloneDX sample. The steps can be used to guide before/after comparisons as well as smoke tests.
SBOM list:
generic.cdx.json: plain CycloneDX 1.5 fromexample-sbom-generator, with no GitLab or tool propertiestrivy-reactor.cdx.json: a Trivy 0.74.0 filesystem SBOM of a Maven project with the modulescoreandfootrivy.cdx.json: a Trivy 0.74.0 SBOM with three packages and a manifest componenttrivy-poetry-lock.cdx.json: a Trivy SBOM of a Poetry project, with packages read frompoetry.locksyft.cdx.json: a Syft 1.52.0 SBOM of a Maven projectcdxgen.cdx.json: a cdxgen 13.0.1 SBOM of a Maven project, with libraries typedframeworkcdxgen-12-srcfile-maven.cdx.json: a cdxgen 12.7.0 SBOM of a Maven project that recordsinternal:SrcFilecdxgen-yarn-lockfile.cdx.json: a cdxgen 13.0.1 SBOM of a yarn workspace projectcdxgen-dotnet-empty-version.cdx.json: a cdxgen SBOM of a .NET project with an emptyversion, invalid against GitLab's schemacyclonedx-maven-plugin-no-location.cdx.json: a CycloneDX Maven plugin SBOM that records no file for a packagegl-sbom-maven-core.cdx.json: the SBOM of the GitLab DS analyzer for thecoremodulegl-container-scanning-debian.cdx.json: the SBOM of the GitLab container scanning analyzer for a Debian 10.3 image
Main branch
- Check out the branch of the last merge request of this issue, on a GitLab Development Kit (GDK) instance with a plan that has dependency scanning, container scanning or license scanning (Ultimate)
- Create a test project and enable the feature flag for it and for each other project that these steps use
- Add a sample SBOM to the project and a
.gitlab-ci.ymlwith a job that uploads it asartifacts:reports:cyclonedx - Commit both on the default branch and wait for the pipeline to finish
- Open the Dependency List and verify that the component list is correctly reported
- Open the alert "Error parsing SBOM reports" of the project and read it
- A criterion that says a sample gets ingested without the alert fails if the alert lists an error for that sample
- The alert shows the schema error of a sample that is invalid against GitLab's CycloneDX schema, such as
cdxgen-dotnet-empty-version.cdx.json, and that sample gives no row, as before
- Repeat for each sample
- Repeat once for a GitLab DS analyzer SBOM
- The rows, paths and package managers of that SBOM must equal those from before the change
- Rename the
toolsentry of that GitLab DS analyzer SBOM toacme-sbom-generatorand repeat- Any difference in name, version, package URL type, path or package manager from the readings before the rename is a failure
- Repeat once for a GitLab container scanning SBOM of an image without a tag
- Its rows and its entry "Required GitLab CycloneDX properties are missing" in the alert must equal those from before the change
- In another test project whose pipeline on the default branch uploaded only
trivy-reactor.cdx.json, trigger continuous vulnerability scanning for GitLab's advisory for CVE-2025-49128 by runningGitlab::VulnerabilityScanning::AdvisoryScanner.scan_projects_for(PackageMetadata::Advisory.find_by(advisory_xid: 'd71aed56-d672-40ed-af37-5306b9355549'))in a Rails console, and open the vulnerability report of that project- The call scans every project of the instance that has a
jackson-corerow - The report must list a finding for CVE-2025-49128 on
jackson-core2.9.10 atfoo/pom.xml - A missing finding is a failure
- The call scans every project of the instance that has a
- Disable the feature flag for the test project and repeat once for a third-party SBOM, such as
trivy-reactor.cdx.json, once for the GitLab DS analyzer SBOM and once for the GitLab container scanning SBOM- The rows, paths, package managers and alert entries of each SBOM must equal those from before the change

