meta-vulnscout

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.

Getting Started

Requirements

docker command
python3-packaging package

Installation

Clone the repository next to where you store your other layers (like sources or layers 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"

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.

Using VulnScout Web Interface

Configure and Serve Web Interface

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 exec vulnscout /scan/src/entrypoint.sh --serve

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

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

Projects and Variants

meta-vulnscout organises data into projects and variants.
A project typically maps to a product, and variants represent different builds or architectures as the machine, the image or even the distro (e.g. x86_64, aarch64).

By default the project name is default and can be changed through the variable VULNSCOUT_PROJECT in the local.conf file.

And the variant is set as <distro>_<machine>_<image> of your build (e.g. poky_qemux86-64_ccore-image-minimal). It can be changed through the variable VULNSCOUT_VARIANT in the local.conf file.

Using VulnScout With a CI

Launch CI Mode

It is possible to launch VulnScout in a non-interactive mode, also known as CI mode. This mode will scan for vulnerabilities and automatically generate reports, without user interaction. To execute it, use the command:

bitbake core-image-minimal -c vulnscout_ci

All the files generated by vulnscout will be placed by default here: <project_root>/.vulnscout/

Options

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

First you need to export the environment variable BB_ENV_PASSTHROUGH_ADDITIONS+=" VULNSCOUT_MATCH_CONDITION"
For example, using the export command:

export BB_ENV_PASSTHROUGH_ADDITIONS+=" VULNSCOUT_MATCH_CONDITION"

Or every time you launch vulnscout in the CI mode:

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

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

VULNSCOUT_MATCH_CONDITION="cvss >= 9.0 and (pending == true or affected == true)" BB_ENV_PASSTHROUGH_ADDITIONS+=" VULNSCOUT_MATCH_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_MATCH_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 match condition this way will override the “VULNSCOUT_MATCH_CONDITION”

WARNING
If you set the “VULNSCOUT_MATCH_CONDITION” with the export command in your shell, it will always use it until you set it to null

Generating Reports

meta-vulnscout is capable of generating built-in reports and even custom ones. The built-in reports are the following:

all_assessments.adoc
match_condition.adoc
summary.adoc
time_estimate.csv
vulnerabilities.csv
vulnerability_summary.txt

All Custom reports must be placed in the following folder .vulnscout/custom_templates Custome report should follow the template format of VulnScout.

NOTE
The custom_templates could be changed through the “VULNSCOUT_CUSTOM_TEMPLATES_DIR” variable in the local.conf file.

There are two ways to generate reports with meta-vulnscout

Generating Reports Without a Scan

Multiple reports can be created within one command without a scan.

You must specify the reports you wish to generate to the variable “VULNSCOUT_REPORT” in the local.conf file. By default it will generate the summary.adoc

Example:

VULNSCOUT_REPORT = "summary.adoc time_estimate.csv"

Then reports can be created without scan using the command:

bitbake core-image-minimal -c vulnscout_report

The reports are generated by default in the folder .vulnscout/<image_basename-machine_suffix>/

Generating Reports During CI Scan

When launching a CI scan you can specify one or multiple reports to be generated at the same time in the variable VULNSCOUT_REPORT_CI.

For example, there is a match_condition.adoc template embedded in VulnScout which is relevant for CI pipelines, and it can be used with:

VULNSCOUT_REPORT_CI = "match_condition.adoc"

Now, when using the command -c vulnscout_ci the reports will be automatically generated.

Exporting SBOM Files

meta-vulnscout can export the enriched project data as standard SBOM formats. Exported files are written to the outputs directory (default: .vulnscout/<image_basename-machine_suffix>/).

To export the SBOM files, you have to specify the files in the variable “VULNSCOUT_EXPORT” in the local.conf.

For now you can export three types of SBOM:

cdx
spdx
openvex

Finally you just need to launch the command:

bitbake core-image-minimal -c vulnscout_export

Use Environment Variables in Templates

In VulnScout templates, you can use environment variables as stated in the documentation. These variables should be automatically detected if they are in a template in the custom_templates directory, and that the template is in use in VULNSCOUT_ENV_GENERATE_DOCUMENTS.

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

`kernel_generate_cve_exclusions.bbclass`

kernel_generate_cve_exclusions.bbclass makes use of the 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. This class is enabled when inheriting conf/distro/include/vulnscout-cve-check.inc, but it can be manually added with KERNEL_CLASSES += "kernel_generate_cve_exclusions"

`improve_kernel_cve_report.bbclass`

improve_kernel_cve_report.bbclass makes use of the script lib/vulnscout/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. This class is enabled when inheriting conf/distro/include/vulnscout-cve-check.inc, but it can be manually added with IMAGE_CLASSES += "improve_kernel_cve_report"

`kernel_filter_nonbuilt_cves.bbclass`

kernel_filter_nonbuilt_cves.bbclass updates 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%.

This class is enabled when inheriting conf/distro/include/vulnscout-cve-check.inc, but it can be manually added with KERNEL_CLASSES += "kernel_filter_nonbuilt_cves" or inherit kernel_filter_nonbuilt_cves in the kernel recipe.

After a kernel build, 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 and the final cve-check manifest will both 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.

Accelerate NVD Database Download

For faster NVD database downloads during VulnScout setup, you can set an 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 When Building in a Docker Container

The Yocto task vulnscout creates and starts a 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 Docker container used to build is not properly configured.

CQFD requires adding docker-cli to .cqfd/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

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.

Variables Glossary

meta-vulnscout can be configured through variables in the local.conf. Here is a recap of all the variable and their impact:

Variable	Purpose
`VULNSCOUT_ROOT_DIR`	Root directory of the ./vulnscout
`VULNSCOUT_BASE_DIR`	Base directory of the ./vulnscout configuration and output files
`VULNSCOUT_DEPLOY_DIR`	Directory of the ouput files (reports, exports, …)
`VULNSCOUT_CACHE_DIR`	Directory of the cache used by vulnscout (database, docker config file)
`VULNSCOUT_CUSTOM_TEMPLATES_DIR`	Directory used to implement custom template to vulnscout
`VULNSCOUT_CONFIG_FILE`	Docker config file
`VULNSCOUT_VARIANT`	Name of the variant used in vulnscout
`VULNSCOUT_PROJECT`	Name of the project used in vulnscout
`VULNSCOUT_EXPORT`	SBOM files to generate with the command `-c vulnscout_export` ( the value has to bee spdx, openvex or cdx)
`VULNSCOUT_REPORT`	Reports to generate with the command `-c vulnscout_report` using templates.
`VULNSCOUT_REPORT_CI`	Reports generated automatically when during `-c vulnscout_ci`
`VULNSCOUT_IMAGE_VERSION`	Version of the container image to use. If the version set in the variable is not the same as the container image used, recreate the vulnscout container.
`VULNSCOUT_IMAGE`	Name of the container image to use for vulnscout container.
`VULNSCOUT_ENV_VERBOSE_MODE`	Enable or disable the verbose mode (false by default)
`VULNSCOUT_ENV_FLASK_RUN_PORT`	Port vulnscout used for the Web Interface (7275 by default)
`VULNSCOUT_ENV_FLASK_RUN_HOST`	IP used on the host for the Web Interface (0.0.0.0 by default)
`VULNSCOUT_ENV_IGNORE_PARSING_ERRORS`	Enable or disable to ignore parsing error found in the entry SBOM files. (false by default)
`VULNSCOUT_MATCH_CONDITION`	Match-condition to set by default to avoid precise it everytime during the command `-c vulnscout_ci`

License

meta-vulnscout is released under the Apache License 2.0.

meta-vulnscout

Getting Started

Requirements

Installation

Configuration

Using VulnScout Web Interface

Configure and Serve Web Interface

Projects and Variants

Using VulnScout With a CI

Launch CI Mode

Options

Generating Reports

Generating Reports Without a Scan

Generating Reports During CI Scan

Exporting SBOM Files

Use Environment Variables in Templates

Extra VulnScout Configuration for cve-check Improvements

Configuration

kernel_generate_cve_exclusions.bbclass

improve_kernel_cve_report.bbclass

kernel_filter_nonbuilt_cves.bbclass

Accelerate NVD Database Download

Using the Web Interface When Building in a Docker Container

Using meta-sbom-cve-check

Variables Glossary

License

Extra VulnScout Configuration for `cve-check` Improvements

`kernel_generate_cve_exclusions.bbclass`

`improve_kernel_cve_report.bbclass`

`kernel_filter_nonbuilt_cves.bbclass`

Using meta-sbom-cve-check 