Skip to main content

Formats

The CLI merges components with the same identity, meaning the same PURL and version, into one. A package listed in both package.json and package-lock.json, or one that is both detected and declared, appears once. Different versions of the same PURL stay separate.

Component order

Components are listed by the number of files they’re the primary match for, then by the number of files they match, then by url_hash. In a scan of your own project, that puts your project first, its vendored dependencies next, and forks and mirrors last. All three formats use this order.

Which component a file comes from

For each file, the scanner returns its candidate components origin first. The first candidate is the component the file comes from, such as the vendored dependency it belongs to. The others redistribute it: forks, mirrors, and packages that bundle it. raw output is grouped by component, so each matched file’s evidence carries match_index: where that component stood in the file’s candidate list, after the BOM rules have run.
  • match_index 0 is the file’s primary match. To rebuild a file’s candidate list, collect its evidence across components and sort by match_index.
  • match_index is absent on declared evidence, which has no candidate list, and in documents written by versions before v0.10.0.
  • When two catalog entries with the same PURL and version merge into one component and both matched a file, that file keeps one evidence entry: the better-placed of the two.
Only raw output has match_index. CycloneDX evidence.occurrences has no field for it, and SPDX has no per-file evidence.

Converting formats offline

The sbom command converts between formats without contacting the API. It detects the input format from the file’s content:
Conversion is best-effort. The CLI drops any data the target format can’t represent and prints a warning. For example, SPDX 2.3 has no vulnerability model, so converting to spdx leaves out the vulnerabilities. sbom takes -f, --format (cyclonedx or spdx) and -o, --output.