# SBOM

sbom-cve-check tool takes as input a software bill of materials (SBOM). This
file provides the list of components (or packages) deployed to the target
device.

The {term}`SBOM` needs to provide the following component information:
 - The component version
 - A way to identify the component: For example, by using a {term}`CPE`, package
   name, ...

For each component listed in the SBOM, the tool searches for applicable CVEs,
which may or may not be vulnerable. Then the result of this search can be
[exported](export.md) with an associated VEX {term}`assessment` for each CVE.

To specify the path to the SBOM, the following mandatory flag needs to be used:
`--sbom-path`. Depending on the SBOM format, the path could point to a file,
an archive or a directory.

## Supported formats

The following SBOM input formats are supported:

| Name    | Short description           |
|---------|-----------------------------|
| `spdx2` | SPDX v2.2 Yocto SBOM file   |
| `spdx3` | SPDX v3.0 JSON-LD SBOM file |

The SBOM type can be specified by using the `--sbom-type` flag. If this option
flag is not specified, *sbom-cve-check* tries to automatically detect the SBOM
format based on the file "extension".

### SPDX v2.2

For a {term}`SPDX` v2.2 format, the tool expects to receive the path to either:
 - a directory containing multiple `.spdx.json` files.
 - a TAR archive, typically with the following extension: `.spdx.tar.zst`.

*sbom-cve-check* was only tested with SBOMs generated by Yocto. SPDX v2
generated by other tools is not currently supported, but contributions are
welcome.

### SPDX v3.0

For a {term}`SPDX` v3.0 format, the tool expects to receive the path to a
{term}`JSON-LD` file.

The SPDX v3.0.1 provides more information than just a component list. It
contains, for example:
 - {term}`CVE` information.
 - {term}`CVSS` information associated with a CVE.
 - {term}`VEX` {term}`assessment` between a package and a CVE.

This implies that a SPDX v3.0 can also be seen as an [annotations](#annotations)
database, with the following type `spdx3-file`.

## Annotations

For some SBOM formats, an SBOM file can also be seen as an
[annotations database](cve-database.md). In this case the associated annotation
database is automatically created with a default priority of `100`, which is the
lowest priority for an annotation database.

To configure a custom [priority](cve-database.md#database-priority), for this
annotation database, the `--sbom-annotation-priority` flag can be used.

The tool can also search for
[obsolete assessments](cve-database.md#obsolete-assessment-check) in the
annotations contained in the SBOM file. To change the default configuration,
the following flags can be used: `--sbom-obsolete-assessment-check`,
`--no-sbom-obsolete-assessment-check`.

To prevent the automatic creation of an annotation database from the SBOM file,
the `--ignore-sbom-annotations` flag needs to be set.

## Yocto SBOM

### Yocto release compatibility

| Codename   | Yocto Version | Support status                         |
|------------|---------------|----------------------------------------|
| Kirkstone  | 4.0           | Not supported, and not functional      |
| Scarthgap  | 5.0           | Partially functional. See below        |
| Styhead    | 5.1           | Not supported, and not tested          |
| Walnascar  | 5.2           | Fully supported                        |
| Whinlatter | 5.3           | Should be functional, not tested (yet) |

For Yocto Scarthgap, the sbom-cve-check is usable using the latest revision
from `scarthgap` branch. But various CVE annotations are not exported, and the
`vex.bbclass` is missing. Various patches currently in review provide all the
missing information needed by sbom-cve-check.

### SPDX v3.0

Yocto is able to generate an SPDX SBOM file in v3.0.1 format. By default, the
`create-spdx.bbclass` is inherited: See `meta/conf/distro/defaultsetup.conf`.
Since Yocto *Styhead* release (5.1), the `create-spdx.bbclass` generates an SPDX
v3.0. For older releases, the `create-spdx-3.0.bbclass` needs to be explicitly
used:
```
INHERIT:remove = "create-spdx"
INHERIT += "create-spdx-3.0"
```

Yocto, by default, generates the SBOM in the `deploy` directory with the
following name: `${IMAGE_BASENAME}-${MACHINE}.rootfs.spdx.json`.

### SPDX v2.2

Yocto is able to generate an SPDX SBOM file in v2.2 format. By default, the
`create-spdx.bbclass` is inherited: See `meta/conf/distro/defaultsetup.conf`.
In Yocto *Scarthgap* release (5.0), the `create-spdx.bbclass` generates an SPDX
v2.2. For newer releases, the `create-spdx-2.2.bbclass` needs to be explicitly
used:
```
INHERIT:remove = "create-spdx"
INHERIT += "create-spdx-2.2"
```

Yocto exports very little information about CVE status when using SPDX v2.2.
It is recommended to either use SPDX v3.0, or also use the information provided
by the manifest generated by `vex.bbclass`.

Yocto, by default, generates the SBOM in the `deploy` directory with the
following name: `${IMAGE_BASENAME}-${MACHINE}.rootfs.spdx.tar.zst`.

### Yocto configuration

To be able to extract all Yocto annotations specified in the recipes by the
`CVE_STATUS` variable, there are 2 options:
 - Configure `SPDX_INCLUDE_VEX` to `all`, but this is not recommended;
   otherwise, the SPDX generation can be very slow, and the resulting SPDX
   file can be more than 1GB. It is highly recommended to set `SPDX_INCLUDE_VEX`
   to `current` (the default value).
 - Extracts these annotations using the `vex.bbclass` as explained in more
   detail in the [yocto-vex-manifest](cve-database.md#yocto-vex-manifest)
   section. This is the recommended method. Note: it is incompatible with
   `cve-check.bbclass`; only one of these `bbclass` can be enabled at a time.
   In `local.conf`, the following line needs to be added:
   ```
   INHERIT += "vex"
   ```

To be able to exclude CVE if affected source files are not compiled, it is
necessary to set `SPDX_INCLUDE_COMPILED_SOURCES` to `1` for recipes that need
this extra processing. Typically for the Linux kernel, in `local.conf`, the
following line could be added:
```
SPDX_INCLUDE_COMPILED_SOURCES:pn-linux-yocto = "1"
```