# Configuration

You can pass one or more TOML configuration files to the `sbom-cve-check` tool
using the `--config` flag.

If multiple configuration files are provided, they are merged. For example, if
two configuration files are specified, the second file can add new options,
replace, or extend options declared in the first file. Note that it is not
possible to remove or unset a previously declared option.

The configuration file allows you to configure various elements, as detailed in
the following subsections.

For paths specified in a TOML configuration file (as documented in their
respective sections), relative paths are interpreted by default as relative to
the directory containing the configuration file.
To override this behavior and use the current working directory as the base for
relative paths, add the following setting to the TOML configuration file:

```toml
path_relative_to_cwd = true
```

This setting can be configured independently for each TOML file.

## Configurable elements

### Databases

You can add multiple {term}`CVE databases<CVE database>` and
{term}`annotation databases<annotation database>`, as described in the
[database configuration](database.md#database-configuration) section.

Databases are specified within the `[databases]` table.

### Plugins

You can configure search paths for loading plugins using the `plugins=` option.
This option expects an array of paths, as described in more detail in the
[plugins](plugins.md#search-locations) section.

If multiple configuration files include the `plugins=` option, the plugin
search paths are extended to include all specified paths.

### CNA

The tool includes an internal database of all known {term}`CNA` and organization
members. This database is provided in the following TOML file:
[`src/sbom_cve_check/vuln/cna.toml`](
https://github.com/bootlin/sbom-cve-check/blob/main/src/sbom_cve_check/vuln/cna.toml).

A typical entry looks like this:

```toml
[[cna]]
org_name = "kernel.org"
short_name = "Linux"
email = "cve@kernel.org"
org_id = "416baaa9-dc9f-4396-8d5f-8c081fb06d67"
```

If an organization member has special roles, they can be specified using the
`roles=` key. The value is an array that can include the following roles:
- `TL_ROOT`: Top-Level Root, the highest-level Root responsible for the
  governance and administration of a specified hierarchy, including Roots and
  CNAs within that hierarchy.
- `ROOT`: An organization authorized within the CVE Program that is responsible,
  within a specific scope, for the recruitment, training, and governance of one
  or more entities that are a CNA, CNA-LR, or another Root.
- `CNA_LR`: CVE Numbering Authority of Last Resort, a CNA authorized by a Root
  to assign CVE IDs and publish corresponding CVE Records within that Root's
  scope for vulnerabilities not covered by the scope of another CNA.
- `CNA`: CVE Numbering Authority, an authorized entity with a specific scope
  and responsibility to regularly assign CVE IDs and publish corresponding CVE
  Records.
- `ADP`: Authorized Data Publisher, an authorized entity with a specific scope
  and responsibility to enrich the content of CVE Records published by CNAs with
  additional information (e.g., risk scores, references, vulnerability
  characteristics, translations).
- `SECRETARIAT`: An organization authorized by the CVE Program to develop, host,
  and maintain the Program's infrastructure and to provide administrative and
  logistical support for the CVE Board, CVE Working Groups, and other parts of
  the Program.

For example:

```toml
[[cna]]
org_name = "CERT@VDE"
short_name = "CERTVDE"
email = "info@cert.vde.com"
org_id = "270ccfa6-a436-4e77-922e-914ec3a9685c"
roles = ["ROOT", "CNA"]
```

If the `roles=` key is not specified, the entry defaults to the `CNA` role.

You can add additional entries to any TOML configuration file using the same
format described above. If an organization identifier is unknown, a new entry is
automatically created with the default `CNA` role.

The CNA database is primarily used to determine whether a CVEList container
entry is provided by an ADP or a CNA.

### Products

The tool includes an internal database of product identifiers. This database
maps vendor and product names to a {term}`Component identifier`.

The {term}`CVE List` database contains many entries without a {term}`CPE`.
However, each "affected" node, providing version ranges, may include the
following fields:
 - `vendor`
 - `product`
 - `packageName`

**sbom-cve-check** attempts to derive {term}`component identifiers<Component identifier>`
from these fields using the following logic:
 - Fields are converted to lowercase.
 - If the `vendor` is "unknown" (or similar values), it is treated as
   unspecified.
 - A first component identifier is created from the `vendor` and `product`
   fields, if both are valid.
 - A second component identifier is created from the `vendor` and `packageName`
   fields, if the package name is valid. The `vendor` may remain unspecified in
   this case.

However, this algorithm is not always sufficient to create a valid
{term}`Component identifier` that matches a known {term}`CPE`.

To address this, sbom-cve-check includes a product database with entries
structured as follows:

```toml
[[products]]
ids = ["gnu:grub2"]
names = [
    { vendor="The Grub2 Project", product="grub2" },
    { vendor="GNU Project", product="GNU GRUB", package="grub2" },
]
```

Each product entry contains the following keys:
- `ids`: A list of {term}`component identifiers<Component identifier>`.
- `names`: A list of vendor, product, or package names associated with the
  component identifiers referenced by the `ids` key.

In the example above, the component identifier `gnu:grub2` is matched to a
CVE entry's "affected" node (which contains version ranges) if the node includes
**any** of the following:
 - `vendor = "The Grub2 Project"` and `product = "grub2"`,
 - `vendor = "GNU Project"` and `product = "GNU GRUB"`,
 - `vendor = "GNU Project"` and `packageName = "grub2"`.

By default, the built-in product database is loaded. You can disable this
using the `--no-builtin-products-db` flag.

To extend the database, you can add custom entries to any TOML configuration
file using the same format described above.

### Arguments

You can specify `sbom-cve-check` arguments directly in the configuration file.
These arguments are combined with those passed from the command line.

To add arguments in the configuration file, include them in the `args=` option
within the `[sbom-cve-check]` table. The value of `args=` must be an array of
strings.

For example, to enable verbose output, you can add the following to a TOML
file:

```toml
[sbom-cve-check]
args = ["-vv"]
```

You can also specify all arguments in the configuration file if needed. For
example, with a configuration file named `my-check.toml`:

```toml
[sbom-cve-check]
args = [
    "--sbom-path",
    "my-image.rootfs.spdx.json",
    "--export-type",
    "yocto-cve-check-manifest",
    "--export-path",
    "out.json"
]
```

In this case, you only need to run `sbom-cve-check` with the `--config`
argument:

```sh
sbom-cve-check --config my-check.toml
```

**Note:** If relative paths are used in the `args=` array, they are resolved
relative to the current working directory, not relative to the configuration
file. Keep this limitation in mind.

## Configuration generation

You can generate a configuration file that captures all the settings used
during the current execution of the tool. This file includes references to
databases, their versions, and the configuration applied, ensuring
reproducibility and traceability.

To generate this file, use the `--gen-repro-config` flag and specify the output
file path for the generated TOML file.

For example, the generated configuration file will look like this:

```toml
plugins = []

[sbom-cve-check]
version = "1.1.0"
args = [
    "--ignore-default-config",
    "--sbom-type",
    "spdx3",
    "--sbom-path",
    "/home/user/core-image-minimal-qemuarm.rootfs-20251009150829.spdx.json",
    "--sbom-annotation-priority",
    "100",
    "--no-sbom-obsolete-assessment-check",
    "--export-filter-vex-status",
    "under_investigation",
    "affected",
    "--export-process-native",
    "target",
    "--export-type",
    "yocto-cve-check-manifest",
    "--export-path",
    "/home/user/out.json",
]

[databases.db-df75fa3da5f9aa1d9ed834d109641c47]
type = "yocto-vex-manifest"
name = "core-image-minimal-qemuarm.rootfs-20251009150829.json"
priority = 101
obsolete_assessment_check = false
path = "/home/user/core-image-minimal-qemuarm.rootfs-20251009150829.json"

[databases.db-6061bd924825afe789df126a89638e7d]
type = "cve-db-nvd-fkie"
name = "nvd-fkie"
priority = 50
path = "/home/user/.cache/sbom_cve_check/databases/nvd-fkie"
cache_index_path = "/home/user/.cache/sbom_cve_check/databases/nvd-fkie/.sbom-cve-check-cache-index.json"
git_url = "https://github.com/fkie-cad/nvd-json-data-feeds.git"
auto_update_max_age = "20h"
max_age_since_last_commit = true
git_ref = "85d3d6c26f07c422388022a474f73fb41bfd4831"
git_branch = "main"

[databases.db-88fa58ee2922dd1af5aff646df045c9f]
type = "cve-db-cvelist"
name = "cvelist"
priority = 50
path = "/home/user/.cache/sbom_cve_check/databases/cvelist"
cache_index_path = "/home/user/.cache/sbom_cve_check/databases/cvelist/.sbom-cve-check-cache-index.json"
git_url = "https://github.com/CVEProject/cvelistV5.git"
auto_update_max_age = "20h"
max_age_since_last_commit = true
git_ref = "41ac2ebbc96d246e94a9fc76a6463988b013dd0b"
git_branch = "main"
```