Document vulnerability scanning of CycloneDX files
Problem to solve
As part of &9534 (closed), the documentation of Dependency Scanning should be updated to introduce the new method of scanning, and deprecate the old one.
Further details
In the old method of scanning, CI jobs detect dependencies, compare them to the GitLab Advisory Database (GLAD), and upload Dependency Scanning reports.
In the new method of scanning, CI jobs upload CycloneDX JSON SBOMs. The backend compares these SBOMs to the GLAD to detect vulnerabilties.
Both method of scanning use the Gemnasium analyzers to detect dependencies.
Gemmnasium analyzers already upload CycloneDX SBOMs, and these SBOMs are already ingested by the backend. However, prior to &9534 (closed) the SBOMs were not used to detect vulnerabilities.
This change is somewhat similar to how License Scanning has evolved.
- Doc issue: Document new License Scanning SBOM Scanner (#388439 - closed)
- Doc page with deprecation notice: https://docs.gitlab.com/ee/user/compliance/license_compliance/
- New doc page: https://docs.gitlab.com/ee/user/compliance/license_scanning_of_cyclonedx_files/index.html
The limitations need to be documented. See &8026
Proposal
-
Remove Retire.js and bundler-audit documentation -
Add a new Solutions for vulnerabilities (auto-remediation)
section with a deprecation message- There is no dedicated section for auto-remediation, so this will centralize the auto-remediation configuration and deprecation. Container Scanning uses a similar section
-
Add a new Vulnerability detection
section- WHAT: Reports known vulnerabilities that affect one or more of your dependencies
- WHY: Makes it possible to remediate vulnerabilities that originate from third party dependencies
- HOW: The dependencies of a project are analyzed to see if they match the language, name, and version of a package that's known to be affected by a vulnerability.
-
Deprecate previous method for dependency scanning that ingests dependencies and their vulnerabilities from the dependency scanning report. -
Document new method for dependency scanning where dependencies are ingested from CycloneDX JSON files, and subsequently are analyzed for vulnerabilities using the GitLab Advisory Database (GLAD). -
Remove or deprecate the Contribute your scanner
section. Instead, we should encourage the use of CycloneDX JSON SBOM generators.- CycloneDX JSON files will only be used for dependency ingestion. Vulnerabilities included in the file are not ingested.
-
Update Configuration
-
Update Overriding dependency scanning jobs
so that it no longer mentions remediation. List of CI/CD variables affected:DS_REMEDIATE_TIMEOUT
DS_REMEDIATE
-
Extract CI variables related to gemnasium-db/GLAD and remediation from Configuring specific analyzers used by dependency scanning
, and add a deprecation warning explaining that this is tied to the old method of scanning. List of CI/CD variables affected:GEMNASIUM_DB_LOCAL_PATH
GEMNASIUM_DB_REF_NAME
GEMNASIUM_DB_REMOTE_URL
GEMNASIUM_DB_UPDATE_DISABLED
GEMNASIUM_LIBRARY_SCAN_ENABLED
-
-
Update the Contributing to the vulnerability database
section -
Update Running dependency scanning in an offline environment
.- Add deprecation warning to
Requirements for offline dependency scanning
andSet dependency scanning CI/CD job variables to use local dependency scanning analyzers
.
- Add deprecation warning to
-
Add deprecation warning to Hosting a copy of the gemnasium_db advisory database
.