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 (closed)

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 and Set dependency scanning CI/CD job variables to use local dependency scanning analyzers.
• Add deprecation warning to Hosting a copy of the gemnasium_db advisory database.

Who can address the issue

Other links/references