Inventories formats

CVE Scan processes SBOM inventories in the following formats: - Inventories formats - CVE Scan JSON format - CycloneDX JSON format - SPDX JSON format

The desired input format is determined through the --inventory-format CLI option, which supports cvescan, cyclonedx-json and spdx-json as valid values.

CVE Scan JSON format

If your project is based on Yocto the meta-cvescan may be used to generate the inventory in the cvescan JSON format.

For non-Yocto projects, an inventory can still be written in the CVE scan JSON format manually or, more realistically, with a script.

A CVE Scan JSON format inventory will be passed to cvescan as follows --inventory "inventory.json" --inventory-format "cvescan".

The remainder of this section decribes the CVE Scan JSON syntax.

{
    "packages": {
        "pkg_id": pkg_data
        …
    }
}

pkg_id: Unique identifier for the package. As it serves to identify the package in the output report it should be descriptive (i.e. human-readable, not some number or hex string).

pkg_data:

{
    "cve_product": [vendor_product …],
    "cve_version": cpe_version,
    "runtime": [rt_pkg …],
    "bpn": bpn,
    "pv": pv,
    "cve_whitelist": [cve_id …],
    "patched_cves": [cve_id …],
    "src_uri": src_uri,
    "sources": sources,
}

vendor_product: either "product_name" or "vendor_name:product_name" (certain packages are known under multiple names in the NVD). If vendor_name is not specified any vendor will match.

cve_version: CPE version string. Its format should comply with the numbering scheme used in the NVD. For example do not pass 1.2.3+git5091fe2f when 1.2.3 is expected or version strings will not match when they should.

vendor_product and cve_version are combined into CPE Well-Formed Names (WFN), see the CPE Specification.

rt_pkg (optional): Yocto ‘runtime’ package information. A rt_pkg value should be a dictionary like:

{
    "name": name,
    "runtime_name": runtime_name,
    "arch": arch,
    "ver": ver
}

A Yocto recipe may yield multiple packages. In general name and runtime_name are equal but there are exceptions. The contents of rt_pkg are not used at the moment. An empty "runtime" list means that, while the recipe was somehow involved in the build, none of its code made it to the target filesystem image. This is the case for native tools like compilers and interpreters but also certain non-native dependencies. Currenly if "runtime" is missing or empty the package will not be scanned for vulnerabilities unless the --keep option is used.

bpn (required): Yocto Base Package Name (BPN), in general the name of the recipe.

pv (required): Yocto Package Version (PV). May differ from cve_version. Appears in the output report.

cve_whitelist (optional): The CVEs with the specified cve_ids will be marked as whitelisted. This allows one to whitelist CVEs at recipe level, via the CVE_CHECK_WHITELIST variable.

patched_cves (optional): The CVEs with the specified cve_ids will be marked as patched (cvescan-inventory.bbclass detects patches with a specific format during the build).

src_uri (optional): Information about source code location.

sources (optional): Subset of the package code that was enabled by build configuration and built. See the docstring of _unflatten_tree in meta-cvescan/lib/inventory/collection.py for details.

vendored (optional): a key value list, containing vendor copies that are used within the build of component. Each item is in the form of

{
    "product": <CVE_PRODUCT of the vendor copy>,
    "version": <CVE_VERSION of the vendor copy>
}

config (optional): Build configuration. Example:

{
    ".config": "<contents of .config>"
}

Note: Building U-Boot may involve more than one .config file.

src_uri, sources and config: At the moment cvescan-inventory collects this information for U-Boot, Linux, and Busybox; but it is used for the analysis of Linux CVEs only.

CycloneDX JSON format

CycloneDX is a standardized SBOM format used for application security and component analysis (for details about the cyclonedx-json format see cyclonedx inventory).

A CycloneDx JSON format inventory will be passed to cvescan as follows --inventory "inventory.json" --inventory-format "cyclonedx-json".

SPDX JSON format

SPDX serves as an SBOM format, enabling standardized exchange of software package data, including licensing, copyright, and security information. Find more details about SPDX here.

A SPDX JSON format inventory will be passed to cvescan as follows --inventory "inventory.spdx.json" --inventory-format "spdx-json".

cvescan allows for passing a whole directory as inventory so that a collection of single .spdx.json can be aggregated into a single SBOM.