Document the supported generators and the CycloneDX fields we read

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Why are we doing this work

The documentation says which generators were checked and what GitLab does with each CycloneDX field, so a user who brings a third-party SBOM knows what to expect.

It also says what an SBOM must provide and what happens when an SBOM records nothing for a field.

Add two documentation pages:

  • A field audit page classifies each relevant CycloneDX field as read and used, read and ignored, or not handled
  • A generators page lists the generators and says what each records for location, dependency edges and vulnerability data
    • It states the package manager defaults, which give a component a package manager from its package URL type, and the location default, the fixed path given to a component that records none, and what each means for rows and for findings
    • It marks each pair with its status, where a pair is one generator run on one sample project, a small project that the generator scans
    • It lists the limitations, which MR 5 and MR 6 below name

This applies when the user uploads the SBOM as a CycloneDX artifact. GitLab does not run the generator.

It belongs to epic &14760.

  • Covers requirement 10: the generators are documented, scoped to language-level components of type library
  • Covers requirement 11: a field-level audit is part of the general availability documentation
  • Needs first for MR 1: no other child issue
  • Needs first for MR 2 to MR 6, one line for each child issue
    • The child issue "Accept CycloneDX SBOMs from any generator"
    • The child issue "Show each package at the manifest that declares it"
    • The child issue "Recognize where Trivy, Syft, Grype and cdxgen record each package's file"
    • The child issue "Show the package manager of each package", for the mapping tables
    • The child issue "Create vulnerability findings from an SBOM's own vulnerability data"
  • Needs first for MR 8: the recorded results of the child issue "Verify supported ecosystems and generator formats, and record the results"

Non-functional requirements

  • Documentation: the two pages below
  • Feature flag:
  • Performance:
  • Testing: a documentation review, and each stated value checked against the other child issues and the results table

Implementation plan

The merge requests are done in the order listed, each based on the one it names.

  • MR 1: Field audit page. Each relevant CycloneDX field gets one classification. Based on master.
  • MR 2: Generator descriptions. The page says what each generator records and what an SBOM must provide. Based on MR 1.
  • MR 3: File names and package manager tables. The page lists the manifest and lockfile names and the two mapping tables. Based on MR 2.
  • MR 4: Package manager defaults and the location default. Each gets an example and its effect on rows and findings. Based on MR 2.
  • MR 5: Limitations on components. The pages state which components are skipped and what is not supported. Based on MR 3.
  • MR 6: Limitations on plans, pipelines and findings. The pages state the mixed-setup rule, to upload GitLab's report and the third-party SBOM in the same pipeline, the widget limit of 25 findings, and the severity rule, the first rating that carries one. Based on MR 2.
  • MR 7: Links. The Dependency List and SBOM documentation link to both pages. Based on MR 6 and MR 4.
  • MR 8: Statuses. Each pair on the generators page takes its status from the results table. Based on MR 2.

Acceptance Criteria

  1. Every relevant field has exactly one classification on the field audit page
  2. The generators page says where each generator records location, dependency edges and vulnerability data
  3. The pages list each package manager default and the location default with an example and its effect on rows and on findings
  4. The generators page marks each pair with the status from the results table
  5. The pages list the limitations
  6. The generators page says which pairs were compared as SBOMs and not ingested

Out of Scope

  • License formats and license scanning pages
  • Reading the CycloneDX scope field

Verification steps

  1. Build the documentation locally and open the field audit and generators pages.
  2. Check each classification against the parser code, and each generator statement against the results table and the expected values of the other child issues.
Edited by 🤖 GitLab Bot 🤖