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.

Components today

Components with this issue

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 with gitlab:, 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
  • 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:path on 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 cdxgen format
    • A framework component from cdxgen, recognized by its field evidence.identity, is read as a library, because cdxgen types ordinary libraries as framework
    • A framework component in an SBOM without the field evidence.identity is not read as a library however, because another generator may use framework for a real framework, which GitLab does not list as a dependency

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 type part of a pkg: identifier, such as pypi in pkg: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:name cannot be read for it

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 library component 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
    • pypi is pip, npm is npm, maven is maven, composer is composer, conan is conan, gem is bundler, golang is go, nuget is nuget, cargo is cargo, pub is pub, conda is conda and swift is 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:path properties, 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 as poetry
  • Trivy
    • Records aquasecurity:trivy:PkgType on each package, whose value is Trivy's own type name, such as poetry, pom or debian
  • Syft
    • Records only an ecosystem in syft:package:type, such as python
  • 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.

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 wip flag lives at most 4 months after it merges into the default branch, and then its type changes to beta or gitlab_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

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 type wip)
  • 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
  • cdxgen: source file
    • from: the property internal:SrcFile (cdxgen 13) or SrcFile (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
  • 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
  • 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

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-io 2.4 is reached from core/pom.xml
  • commons-text 1.8 is reached from core/pom.xml
  • jackson-databind 2.9.10 is reached from foo/pom.xml

The SBOM becomes two reports:

  • The report for core/pom.xml holds commons-io and commons-text
  • The report for foo/pom.xml holds jackson-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/lodash in 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, cocoapods and the operating system managers apt, dnf, yum, zypper and tdnf
  • 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-mariner and wolfi have 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 .csproj beside packages.lock.json for a NuGet package, and both are listed
    • No rule removes either
  • The cdxgen rule reads the field evidence.identity and not the tool
    • A framework component of any other generator that writes evidence.identity is therefore read as a library too
  • 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 pypi package from a Poetry or uv project shows pip, an npm package from a yarn or pnpm project shows npm, and a maven package from a Gradle project shows maven

Acceptance criteria

General ingestion

  1. 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)
  2. Its library components 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)
  3. 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.json at pom.xml, core/pom.xml and foo/pom.xml, and generic.cdx.json in one report)
  4. 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)
  5. 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: the framework component commons-text in generic.cdx.json)
  6. 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-core at foo/pom.xml in trivy-reactor.cdx.json, for GitLab's advisory for CVE-2025-49128)

Exceptional cases

  1. A framework component from cdxgen is ingested as a library (example: cdxgen.cdx.json)
  2. The source file is read from where the format records it (example: syft.cdx.json at core/pom.xml)
  3. 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 .csproj beside packages.lock.json)
  4. A package manager recorded by the SBOM is shown (example: poetry for the packages of trivy-poetry-lock.cdx.json)
  5. The name of the file does not set the package manager (example: npm, not yarn, for the packages of cdxgen-yarn-lockfile.cdx.json)
  6. A package with no recorded package manager gets the default for its package URL type (example: npm for lodash in generic.cdx.json)

Validation

  1. 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 empty version)

FF behaviour

  1. 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)
  2. 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

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 from example-sbom-generator, with no GitLab or tool properties
  • trivy-reactor.cdx.json: a Trivy 0.74.0 filesystem SBOM of a Maven project with the modules core and foo
  • trivy.cdx.json: a Trivy 0.74.0 SBOM with three packages and a manifest component
  • trivy-poetry-lock.cdx.json: a Trivy SBOM of a Poetry project, with packages read from poetry.lock
  • syft.cdx.json: a Syft 1.52.0 SBOM of a Maven project
  • cdxgen.cdx.json: a cdxgen 13.0.1 SBOM of a Maven project, with libraries typed framework
  • cdxgen-12-srcfile-maven.cdx.json: a cdxgen 12.7.0 SBOM of a Maven project that records internal:SrcFile
  • cdxgen-yarn-lockfile.cdx.json: a cdxgen 13.0.1 SBOM of a yarn workspace project
  • cdxgen-dotnet-empty-version.cdx.json: a cdxgen SBOM of a .NET project with an empty version, invalid against GitLab's schema
  • cyclonedx-maven-plugin-no-location.cdx.json: a CycloneDX Maven plugin SBOM that records no file for a package
  • gl-sbom-maven-core.cdx.json: the SBOM of the GitLab DS analyzer for the core module
  • gl-container-scanning-debian.cdx.json: the SBOM of the GitLab container scanning analyzer for a Debian 10.3 image

Main branch

  1. 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)
  2. Create a test project and enable the feature flag for it and for each other project that these steps use
  3. Add a sample SBOM to the project and a .gitlab-ci.yml with a job that uploads it as artifacts:reports:cyclonedx
  4. Commit both on the default branch and wait for the pipeline to finish
  5. Open the Dependency List and verify that the component list is correctly reported
  6. 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
  7. Repeat for each sample
  8. Repeat once for a GitLab DS analyzer SBOM
    • The rows, paths and package managers of that SBOM must equal those from before the change
  9. Rename the tools entry of that GitLab DS analyzer SBOM to acme-sbom-generator and repeat
    • Any difference in name, version, package URL type, path or package manager from the readings before the rename is a failure
  10. 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
  11. 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 running Gitlab::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-core row
    • The report must list a finding for CVE-2025-49128 on jackson-core 2.9.10 at foo/pom.xml
    • A missing finding is a failure
  12. 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
Edited by Igor Frenkel