CVE Databases

Multiple sources of CVE information can be registered and used by sbom-cve-check tool. There are two kinds of databases:

  • The CVE database provides general information about CVEs. However, some of this information may be missing:

    • A CVE identifier.

    • A description.

    • Vulnerable versions, and not vulnerable versions. These version ranges are provided, among other things, via a CPE match block.

    • CPE provides vendor and product names, which allows to identify the component.

    • CVSS (Common Vulnerability Scoring System) information, including the score and the vector string.

  • The annotation database, which provides a VEX assessment for a specific CVE. This assessment is tied to one or more specific component versions: The analysis was realized for these versions. In addition to this assessment, the annotation entry can provide the same kind of information contained in a CVE database.

Common database options

All database options can be specified from the command line, using --add-db flag as described in the subsections below, or from one or more TOML configuration files.

Database type

The following CVE and annotation databases are supported:

Name

Short description

openvex-file

Path to one OpenVEX annotation file

openvex-dir

Directory containing OpenVEX annotation files

spdx3-file

Path to one SPDX v3.0 SBOM file

yocto-vex-manifest

Path to Yocto VEX manifest, generated by vex.bbclass

simple-annotations

Directory containing simple YAML annotation files

cve-db-nvd-fkie

Path to FKIE nvd-json-data-feeds git repository

cve-db-cvelist

Path to CVEProject cvelistV5 git repository

The database type can be specified:

  • From a configuration file using the type= option.

  • From the command line using the --add-db flag: The first value is the database type name.

Database priority

Each database has a priority, which is an integer: The higher the priority value, the higher the priority.

When checking for CVE, for a specific component identified, for example, by a CPE, the list of applicable CVE is obtained. Then, for each applicable CVE, each database is queried from the highest to the lowest priority, and an assessment is retrieved or computed. The highest valid assessment that was obtained is used in the export file.

An annotation database must have a unique priority: Another database cannot use the same priority. But a CVE database can have the same priority, which is the default for the NVD and the CVE List databases.

If the priority is not explicitly configured using the priority= option, a default is automatically assigned using the following strategy:

  • For CVE databases, the priority is set to 50.

  • For annotation databases:

    • If the information was specified from the command line, using the --add-db flag, the priority is set to 150 plus the order in which the database was declared.

    • If the information was specified from the command line, but using other flags, the priority is set to 100 plus the order in which the database was declared.

    • If the information was specified from a configuration file, the priority is set to 200 plus the order in which the database was declared.

In summary, the CVE databases should have the lowest priority, the databases added from the command line the middle priority, and the databases added from the configuration file the highest priority. And the databases declared at the beginning (of the configuration file, or of the command line) will have a lower priority than a database declared at the end.

Database path

Each database must have a path that can be specified:

  • From a configuration file using the path= option. If a relative path is used, this is a relative path from the directory containing this configuration file.

  • From the command line using the --add-db flag: The second value is the database path. If a relative path is used, this is a relative path to the current working directory.

This path can point to a file or a directory depending on the database type.

The path= option specified in a configuration file can contain environment variables: ${name} is replaced by the value of the environment variable “name”. Also, if the path starts with an initial component of ~, it will be replaced by that user’s home directory.

If the command line flag --databases-dir is used, it will set or override the SBOM_CVE_CHECK_DATABASES_DIR environment variable to the specified flag value.

If the environment variable SBOM_CVE_CHECK_DATABASES_DIR is not set, it will default to the following value: ~/.cache/sbom_cve_check/databases. This variable is used in the default configuration file: db_default.toml to specify the location of NVD and CVE List databases.

Database name

Each database has a name that describes it. The name may be used in various messages. The name is not required to be unique, but this is recommended. It can be specified:

  • From a configuration file using the name= option. If not present, it uses, instead, the configuration section name.

  • From the command line using the --add-db flag, by specifying the name= option. If not present, it uses the filename specified in the database path.

Obsolete assessment check

Annotation databases have an additional configuration option, named obsolete_assessment_check=. This option takes a boolean. If this option is enabled for a particular annotation database, then it checks if the assessments provided by this database are obsolete.

An assessment is considered obsolete if a CVE or annotation database with a lower priority provides the same kind of CVE assessment.

The list of obsolete assessments can be exported depending on the selected exporter.

By default, for all annotation databases, the search for obsolete assessments is disabled. It can be enabled or disabled for a specific database using the option previously mentioned. To change the default, and to be able to search for obsolete assessments on all annotation databases, the following flag needs to be set: --check-obsolete-assessment-by-default.

The search for obsolete assessments is not enabled by default, since it can make the execution of the tool way slower in some cases.

Git database options

Some database types can be fetched from a git repository. These databases take the following configuration options:

  • git_url=: Allow to specify or to override the default fetch URL of the git repository. The repository will be cloned in the directory specified by the path= database option. This directory is going to be a git repository, the git is not cloned inside a subdirectory.

  • auto_update_max_age=: Allows to configure the duration since the last “update”, see max_age_since_last_commit=; if exceeded, an update of the git repository is automatically performed via “git pull”. If not specified, the default value is 20 hours. Otherwise, it takes either:

    • Some duration in seconds (or in other time units).

    • The special string off. If set to off, the git database will never be updated.

    • Value 0. In this case, a git pull will always be realized.

  • max_age_since_last_commit=: A boolean that allows to configure what is considered the last “update”:

    • If set to True, it indicates that this is the duration since the last commit. The committer date time of the HEAD commit is used.

    • If set to False, this is the duration since the last command that moves the HEAD in a drastic way. The modification date time of ORIG_HEAD is checked. This should reflect the last git fetch/pull.

    If not specified, default to True for a CVE database and to False for an annotation database.

  • cache_index_path=: Path to the cache file containing the database index. By default, the cache file is stored at the root of the git repository under the following file name: .sbom-cve-check-cache-index.json. The cache could be disabled by setting a null value or an empty string to this option.

  • git_branch=: Clone from a specific branch name. If not set, use the default remote branch.

  • git_ref=: Checkout a specific commit identifier or tag. If this configuration is not set, checkout the latest (HEAD) commit from remote.

    If the git branch is not specified, when cloning, consider that the git reference is a tag, and clone the tag directly. Combined with the git_fetch_depth= option, that allows cloning only the tag and not the complete git history.

    After an initial clone, if the git reference is changed in the configuration file, the git branch should be specified. The complete git history will be downloaded. If this is not wanted, the git repository could be removed. This way a new clone will be realized.

  • git_fetch_depth=: Configure git clone/fetch depth. By default, if this option is not set:

    • When cloning, if no git reference is specified, a shallow clone is realized with a depth of 1. Otherwise, a normal clone is realized.

    • When fetching to update the git repository, do not limit the number of commits to fetch.

Warning

Be aware that any commit not pushed to remote, or any local modifications will be discarded.

Before each CVE analysis, the git repository is reset. If you do not want this and prefer to manage the Git repository on your own, do not set git_url= or set it to an empty string. Otherwise, your local modifications will be overwritten/lost.

Database types

Each supported database type may have additional configuration options.

openvex-file

This annotation database provides a unique OpenVEX JSON file. The database path needs to point to the JSON file.

openvex-dir

This annotation database is a directory containing one or multiple OpenVEX json files. The database path needs to point to this directory.

This database type requires an additional configuration option: globs=. This is a list of glob patterns, which allows only matching files to be provided. If it is specified from the command line, the value passed to the globs= option needs to be a comma-separated list.

For example the following patterns could be used:

  • */CVE-*.json: it matches any directory (only one level), then any file starting with CVE- and ending with .json.

  • **/*.json: it matches any number of directory segments, then it matches any files ending with .json.

For more information about glob pattern language, see the pathlib documentation.

This database can optionally be fetched from a git repository. To enable that, the git_url option must be specified. Additional associated options can be configured as described in the git database section.

spdx3-file

This annotation database provides a single SPDX v3.0 JSON file. While it is possible to manually add an SPDX v3.0 database, it is expected, and much more common, for this database to be added automatically via the input SBOM file.

yocto-vex-manifest

This annotation database provides a single Yocto VEX manifest file generated from the Yocto vex.bbclass.

This file contains the following information for each Yocto recipe (non-exclusive list):

  • package version

  • list of CPE

  • list of associated Yocto annotations specified by CVE_STATUS

By default, in Yocto, the file is provided in the deploy directory with the following name: ${IMAGE_BASENAME}-${MACHINE}.rootfs.json

For convenience, this database file can also be directly added with the --yocto-vex-manifest flag followed by the path to the Yocto VEX manifest file. But in that case, no additional options can be specified: default options will be used.

simple-annotations

This annotation database is a directory containing one or multiple YAML files. The database path needs to point to this directory.

This database type requires an additional configuration option: globs=. This is a list of glob patterns. Each pattern could be:

  • A path to a directory. In this case, search in this directory for files named with the following format: CVE-2025-1234.yaml.

  • A pattern matching a CVE YAML file.

If it is specified from the command line, the value passed to the globs= option needs to be a comma-separated list.

The YAML file name must be the CVE identifier. Any extensions could be used, but it is recommended to use either .yaml or .yml.

The example below is one annotation entry for the CVE id CVE-2025-1234, which must be named CVE-2025-1234.yaml:

vulnerable: 'no'
last-review: '2025-01-01'
cve-product: curl:libcurl
versions: [7.12.3]
comment: 'Not applicable because ...'

The YAML file must contain the following keys, but additional keys can be specified:

  • vulnerable: Can be either a boolean or a string. In case of a string, if the value is equal to no then the CVE is considered not vulnerable, otherwise any other value is considered vulnerable.

  • last-review: A date time encoded in ISO format

  • cve-product: Either the vendor and the product name are separated by a colon, or just the product name.

  • versions: The list of versions that indicates which package version this annotation applies to. If in the SBOM the package version does not strictly match, this annotation is ignored.

  • comment: The annotation statement

Below is an example of a TOML configuration file for this simple annotation database.

[databases.my-annotations]
type = "simple-annotations"
git_url = "git@example.com:my-project/my-annotations.git"
path = "${SBOM_CVE_CHECK_DATABASES_DIR}/my-annotations"
auto_update_max_age = "10min"
max_age_since_last_commit = true
globs = ["common/yocto", "boards/my-board/yocto"]

This database can optionally be fetched from a git repository. To enable that the git_url option must be specified. Additional associated options can be configured as described in the git database section.

cve-db-nvd-fkie

This is a CVE database. This is the community reconstruction of the JSON NVD Data Feeds, managed by FKIE, stored in a git repository.

The database path points to the git directory. The path will be created if it does not exist.

This database also takes the optional configuration options described in the git database section.

cve-db-cvelist

This is a CVE database. This CVE List database contains the catalog of all CVE Records identified by, or reported to, the CVE Program.

The database path points to the git directory. The path will be created if it does not exist.

This database also takes the optional configuration options described in the git database section.

Database configuration

Typically, databases can be added from the command line by using the --add-db flag as many times as needed, or by loading configuration files, specified by the --config flag. Multiple configuration files can be loaded by using the --config flag as many times as needed.

The configuration file uses the TOML format. Each table, stored inside the databases table, represents a database to add. An example can be seen in the subsection below.

To add a database from the command line, see the subsection below for an example.

The list of supported database types that can be added is listed in the Database type subsection, and for detailed documentation of each database type, see the associated subsection in the Database types section.

Duration units

The duration of a configuration value can have a suffix to indicate the time unit. The following suffixes are supported:

Supported suffixes

Unit

msec, ms

milliseconds (0.001 seconds)

seconds, second, sec, s

seconds (1 second)

minutes, minute, min, m

minutes (60 seconds)

hours, hour, hr, h

hours (3600 seconds)

days, day, d

days (86400 seconds)

weeks, week, w

weeks (604800 seconds)

months, month, M

months (2629800 seconds)

The duration can be a decimal value followed by the unit, with an optional space between the value and the unit.

The duration can be specified in the TOML file as an integer or a decimal value. In this case, the default unit is the seconds.

Boolean value

For an option expecting a boolean value, the following case-insensitive value can be specified:

Possible boolean values

Result

1, yes, true, on

True

0, no, false, off

False

In the TOML file, it is recommended to specify the value as a normal boolean.

Default configuration file

The tool loads, by default, the db_default.conf configuration file, which contains the configuration for the NVD and the CVE List databases. To prevent loading this default configuration file, the following flag can be specified: --ignore-default-config.

Example of configuration file

Below is an example of a TOML configuration file that adds a directory containing multiple JSON OpenVEX files:

[databases.Annotations]
name = "My custom annotations"
type = "openvex-dir"
path = "../databases/annotations"
globs = ["abc/*/*.json", "recursive/**/*.json"]
obsolete_assessment_check = true

Example of command-line

To add the same database as described in the subsection above, but this time from the command line, the following arguments need to be specified:

--add-db openvex-dir ../databases/annotations \
  "name=My custom annotations"  \
  "globs=abc/*/*.json, recursive/**/*.json" \
  "obsolete_assessment_check=True"