Document continuous scans of SBOM components
Why are we doing this work
Users need to know what Continuous Vulnerability Scans (CVS) are, how they work, etc.
This complements Document vulnerability scanning of CycloneDX files (#416074 - closed), which documents how SBOM are scanned when uploaded by CI jobs.
Further details
Upon the ingestion of a new security advisory by GitLab, CVS scans all projects that have the affected component, and adds vulnerabilities to them. This new feature requires Ultimate, and it's limited to Dependency Scanning at the moment. Dependency Scanning CI jobs must be enabled, so that CycloneDX SBOMs are uploaded, and ingested by GitLab.
What is this new feature?
It detects new vulnerabilities in the components your project depends on, and add them to the vulnerability report.
The scan is triggered whenever a security advisory is added to the GitLab Advisory DB.
Why should I use it?
Projects using CVS get new vulnerabilities without running new scanning jobs. This removes the need for periodic scanning jobs; it saves resources and reduces operational costs.
How does it relate to other features?
CVS and Dependency Scanning jobs both use GitLab Advisory Database. Vulnerabilities reported by scanning jobs should be merged into the ones previously created by CVS.
How does it work?
When a CI job uploads a compatible CycloneDX SBOM, GitLab ingests that SBOM and keeps track of the component listed in that SBOM.
Later on, when it ingests a new advisory from the Package Metadata Database, GitLab looks for all the projects that depend on the newly affected component, and adds vulnerabilities to them.
Dependency Scanning CI jobs are responsible for uploading two types of reports.
- Dependency Scanning reports lists vulnerabilities.
- CycloneDX SBOM reports lists components.
These two types of reports complement one another.
- In a normal scan, GitLab ingests vulnerabilities listed in Dependency Scanning reports.
- CVS relies on components listed in CycloneDX SBOM.
What are requirements?
This feature requires an Ultimate license.
How do I set it up?
Include the Dependency Scanning CI template to the CI config of your project. Dependency Scanning jobs generate compatible CycloneDX SBOMs, and to track project components.
What are the current limitations?
CVS only supports Dependency Scanning vulnerabilities at the moment. Container Scanning vulnerabilities are not supported.
In some cases, the range of affected versions might not be interpreted correctly. This might result in false positives and false negatives: a fixed version might be marked as affected, and an affected version might be considered as fixed.
Go pseudo versions are not supported. A Go component that refers to a pseudo version is never considered as affected, and this might result in false negatives.
Vulnerabilities created by continuous scans don't show the direct dependency that introduced the vulnerable component, if the vulnerable component is transitive.
Results of continuous scans are not visible on the dependency list.
It might take a few hours between the moment when a security advisory is added to GitLab Advisory DB, and the moment when vulnerabilities are added to affected projects. This depends mainly on two things:
- the frequency at which the GitLab instance is synced with the Package Metadata DB
- the resources on the GitLab instance available to process new advisories, and create vulnerabilities
SBOM ingestion only supports CycloneDX 1.4 in JSON format. SBOMs must provide GitLab metadata.
At the moment users are not notified about vulnerabilities by CVS within GitLab. However, Slack users can be notified using the GitLab Slack integration. Also, you can periodically check the vulnerability findings API to identify new findings.
Implementation plan
-
Add new doc page for Continuous Vulnerability Scanning. !128482 (merged) -
Add to the navigation bar.