Create vulnerability findings from an SBOM's own vulnerability data
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Why are we doing this work
GitLab creates one Dependency Scanning finding for each vulnerability that a third-party SBOM reports against one of its components.
Terms:
- A vulnerability entry is an item of the SBOM's
vulnerabilitiesarray - It resolves to a component when its
affectsreference names a component of the SBOM - A finding is an entry in the vulnerability report, and it is created at the manifest of the affected component
A third-party CycloneDX SBOM can carry its own vulnerabilities array. GitLab's advisory matching compares each component with GitLab's advisory database, and today that is the only source of findings for a third-party component. Nothing is created from the SBOM's own data.
Update ingestion to:
- Create one finding for each vulnerability entry that resolves to a component, with the identifier and severity of the entry
- Place each finding at the manifest of its component, because GitLab matches a finding to a Dependency List row on package name, version and path
- Place a finding for a component with no recorded path at the default location
3rd Party Input File Path Unknown - Link each finding to the row of its package
The findings take the same form as the findings of GitLab's own scan, so the pipeline security tab, the vulnerability report and the merge request security widget need no change.
This applies when a CI job uploads a CycloneDX JSON SBOM under artifacts:reports:cyclonedx, on a plan with the vulnerability report available.
It belongs to epic &14760.
- Covers requirement 8 in part: GitLab creates the findings that the pipeline security tab, the vulnerability report and the merge request security widget read, and the child issue "Verify supported ecosystems and generator formats, and record the results" checks that the three show them
- Needs first for MR 1: MR 2 of the child issue "Recognize where Trivy, Syft, Grype and cdxgen record each package's file", which gives a component with no file the default location
- Needs first for MR 3: MR 2 of the child issue "Show each package at the manifest that declares it"
- Needs first for MR 4: MR 3 of the child issue "Show each package at the manifest that declares it"
- Needs first for the expected Trivy results: MR 3 of the child issue "Recognize where Trivy, Syft, Grype and cdxgen record each package's file"
The diagram below shows the new path that this issue adds, from an SBOM's vulnerability entries to findings in the Vulnerability Report. Yellow marks the new steps. The decision "GitLab already has this finding?" belongs to Show one finding when GitLab and a third-party ... (#633170).
Relevant links
- Epic &14760
Non-functional requirements
- Documentation: documented by the child issue "Document the supported generators and the CycloneDX fields we read"
- Feature flag: to be decided
- Performance:
- Testing: specs per merge request, on SBOMs of a few components with two or three vulnerability entries
Implementation plan
The merge requests are done in the order listed, each based on the one it names.
- MR 1: Read vulnerability entries and create findings. An entry that resolves to no component is skipped. Based on MR 2 of the issue "Recognize where Trivy, Syft, Grype and cdxgen record each package's file".
- MR 2: Take the severity from the severity ratings of the entry. The first rating that carries one wins. Based on MR 1.
- MR 3: Carry vulnerability entries onto split reports. Each entry goes to the report of its component. Based on MR 2 and MR 2 of the issue "Show each package at the manifest that declares it".
- MR 4: Give findings a location. A finding is at its component's manifest and linked to its row. Based on MR 3 and MR 3 of the issue "Show each package at the manifest that declares it".
- MR 5: Resolve a reference with no version. It resolves when exactly one component has that package URL. Based on MR 4.
- MR 6: Log the vulnerability entries. One log line per SBOM counts entries seen, findings created and entries skipped. Based on MR 1.
Acceptance Criteria
- Each vulnerability entry that resolves to a component gives one finding with its identifier and severity
- The severity is the first rating that carries one, and unknown when no rating carries one
- Each finding is at the manifest of its component, including in an SBOM with several manifests
- A finding of a component with no recorded path is at the default location
- A vulnerability entry that resolves to no component is skipped and counted
- A finding is linked to the Dependency List row of its package
Out of Scope
- Matching a finding with a finding GitLab's own scan created
- Solution text in the finding display
- Links in the finding display
- CVSS vectors in the finding display
- Rendering the merge request security widget
- A preferred rating source for severity
Verification steps
- Check out the branch of the last merge request listed in the Implementation plan, on a GitLab Development Kit (GDK) instance with a plan that has dependency scanning, container scanning or license scanning (Ultimate).
- Upload each SBOM in a project and run the pipeline on the default branch.
- Open the vulnerability report and the pipeline security tab, count the findings per path, and compare them with the expected values attached to this issue.
