meta-vulnscout is a Yocto meta-layer that uses VulnScout to scan a project, export its Software Bill of Materials (SBOM), and list the vulnerabilities affecting it.

Currently the supported formats are: CycloneDX, SPDX, Yocto JSON files, and OpenVEX.

Requirements

• docker-compose or docker compose command

• python3-packaging package. If you are running in CQFD, you should add it in .cqfd/docker/Dockerfile.

Installation

Clone the repository into the sources directory and add it to your build/conf/bblayers.conf file:

cd sources
git clone https://github.com/savoirfairelinux/meta-vulnscout.git

If you are using submodules to manage your sub-repos, you should include this meta-layer using the following commands:

$ cd sources
$ git submodule add https://github.com/savoirfairelinux/meta-vulnscout.git

And in your bblayers.conf file add the line:

BBLAYERS += "/path/to/meta-vulnscout"

Configuration

To enable and configure VulnScout, add the following lines to your local.conf or distro config:

# Required settings for VulnScout
require conf/distro/include/vulnscout-core.inc

This configuration enables VulnScout for all image recipes and should be sufficient for most users. If you want more fine-grained control on which images are enabling VulnScout, then you can add to your local.conf or distro config:

# Inherit create-spdx to generate SBOMs
# May be required if not using poky distro
INHERIT += "create-spdx"

HOSTTOOLS_NONFATAL += "docker-compose docker"

And then manually inherit vulnscout in specific image recipes to enable VulnScout.

The distro poky-vulnscout provided in this repo provides an example of a complete usage of meta-vulnscout features.

Extra VulnScout configuration for cve-check improvements

meta-vulnscout provides other classes for accurate cve-check file generation.

Configuration

Add this line to your distro config or local.conf to inherit the extra classes:

# Enable extra CVE analysis
require conf/distro/include/vulnscout-cve-check.inc

Description

• kernel_generate_cve_exclusions.bbclass can be used to integrate a library lib/vulnscout/generate_cve_exclusions_py derived from the script generate-cve-exclusions.py.
  It provides extra kernel CVE details and information through the variable CVE_STATUS.
  To integrate this script, a .bbappend on the kernel recipe can be used to add inherit kernel_generate_cve_exclusions as shown on the available example at meta-vulnscout/recipes-kernel/linux/linux-yocto_%.bbappend

• improve_kernel_cve_report.bbclass can be used to integrate the script improve_kernel_cve_report.py (reference : improve_kernel_cve_report).
  It reduces CVE false positives by 70%-80% and provides detailed responses for all kernel-related CVEs by analyzing the files used to build the kernel.
  To integrate this script, a .bbappend on the image recipe can be used to add inherit improve_kernel_cve_report as shown on the available example at meta-vulnscout/recipes-core/images/core-image-minimal.bbappend

• kernel_filter_nonbuilt_cves.bbclass can be used to update the cve-check file by removing CVEs based on elements that aren't present in the built kernel. A CVE linked with a driver that isn't compiled doesn't make your kernel vulnerable to it.
  It reduces the number of kernel CVEs to deal with by around 70%.
  To integrate this class, a simple inherit kernel_filter_nonbuilt_cves is required in the kernel recipe. After a kernel build tree, new files will be located in your deploy directory. A file with .kernel_remaining_cves.json extension will contain the remaining active CVEs, a second file with .kernel_removed_cves.json contains the details of CVEs that don't apply to your system. \ Also, the virtual kernel cve-check file will be affected and the final cve-check manifest will be affected by this class analysis setting all non-built CVEs to Ignored status with details set to cve-not-compiled-in-kernel and description to kernel_filter_nonbuilt_cves detected that this CVE is not affecting the current kernel build.

Using VulnScout Web Interface

After a normal build, you should see a new .vulnscout folder in ${TOPDIR}/.. (can be modified with variable VULNSCOUT_ROOT_DIR).

The scan and analysis of vulnerabilities can be started with:

bitbake core-image-minimal -c vulnscout

VulnScout Docker container can also be started without rescanning for new CVEs with the following command:

bitbake core-image-minimal -c do_vulnscout_no_scan

Or you can do it manually with the command:

docker compose -f "<project_root>/.vulnscout/core-image-minimal/docker-compose.yml" up

Without a custom configuration, a web interface will be started at the address http://localhost:7275.

Using VulnScout with a CI

It is possible to launch VulnScout in a CI mode, without the web interface using the command:

bitbake core-image-minimal -c vulnscout_ci

All the files generated by vulnscout will be placed by default here: <project_root>/.vulnscout/core-image-minimal/output

Options

vulnscout in CI mode can be launched with a specific fail condition using an environment variable.

First you need to export the environment variable BB_ENV_PASSTHROUGH_ADDITIONS+=" VULNSCOUT_FAIL_CONDITION"
Either way, by using the export command:

export BB_ENV_PASSTHROUGH_ADDITIONS+=" VULNSCOUT_FAIL_CONDITION"

Or every time you launch vulnscout in the CI mode:

BB_ENV_PASSTHROUGH_ADDITIONS+=" VULNSCOUT_FAIL_CONDITION" bitbake core-image-minimal -c vulnscout_ci

Now you can specify the fail condition with the VULNSCOUT_FAIL_CONDITION variable every time you use vulnscout in CI mode:

VULNSCOUT_FAIL_CONDITION="cvss >= 9.0" BB_ENV_PASSTHROUGH_ADDITIONS+=" VULNSCOUT_FAIL_CONDITION" bitbake core-image-minimal -c vulnscout_ci

With this command, vulnscout will list all the CVEs of the vulnerabilities with a CVSS score equal to or higher than 9.0.

It's possible to set more than one condition:

VULNSCOUT_FAIL_CONDITION="cvss >= 9.0 or (cvss >= 7.0 and epss >= 50%)" bitbake core-image-minimal -c vulnscout_ci

With this command, vulnscout will list all vulnerabilities critical (CVSS >= 9.0) or those with both a high CVSS and EPSS score.

Note

Setting up the fail condition this way will overload the "VULNSCOUT_ENV_FAIL_CONDITION" variable in the vulnscout.bbclass

Warning

If you set the "VULNSCOUT_FAIL_CONDITION" with the export command in your shell, it will always uses it until you set it to null

Add custom export templates

VulnScout supports additional custom templates for export files. These templates can be stored in the folder .vulnscout/custom_templates, and should follow the template format of VulnScout.

To use custom templates, specify their names in your local.conf using:

VULNSCOUT_ENV_GENERATE_DOCUMENTS = "template1.adoc,template2.csv"

Some default templates are already included in VulnScout:

• all_assessments.adoc
• summary.adoc
• time_estimates.csv
• vulnerabilities.csv
• vulnerability_summary.txt

They can be used in VULNSCOUT_ENV_GENERATE_DOCUMENTS.

Accelerate NVD database download

For a faster NVD database downloading during VulnScout setup, you can set a NVD key with the variable NVDCVE_API_KEY.

Yocto Documentation reference : https://docs.yoctoproject.org/ref-manual/variables.html#term-NVDCVE_API_KEY

You can generate a new NVD key at : https://nvd.nist.gov/developers/request-an-api-key

Using the web interface with a building Docker container

The Yocto task vulnscout creates and starts the Docker container with a Web interface available.

Using a Docker container to build the project requires additional configuration to access the web interface.

Indeed, the web interface won't be mapped to the host if the building Docker container is not properly configured.

CQFD requires adding docker-compose (for Ubuntu 22.04 and earlier) or docker-compose-v2 (for Ubuntu 24.04 and later) to your .cfqd/docker/Dockerfile and exporting the following variable:

export CQFD_EXTRA_RUN_ARGS="-v /run/docker.sock:/run/docker.sock"

For a permanent change, you can instead modify the .cqfdrc file with docker_run_args="-v /run/docker.sock:/run/docker.sock".

Now, you can build your image and use the vulnscout task with one of these commands:

If you use CQFD and KAS

cqfd kas shell -c "bitbake -c <your_Yocto_image> -c vulnscout"

If you use CQFD and the script build.sh made by Savoir-faire Linux

cqfd run ./build.sh -- bitbake <your_Yocto_image> -c vulnscout

If the container can't be configured (e.g., with kas-container). VulnScout web interface can still be run directly on the host with the docker-compose command.

Using meta-sbom-cve-check

The output of meta-sbom-cve-check is supported in VulnScout. However, this layer is incompatible with the cve-check improvements provided in meta-vulnscout. As a consequence, do not use conf/distro/include/vulnscout-cve-check.inc with meta-sbom-cve-check.

Result

License

Copyright (C) 2025-2026 Savoir-faire Linux, Inc.

meta-vulnscout is released under the Apache License 2.0.