Getting started

The intent of this guide is to guide you through the installation steps and first run of CVE Scan.

1. CVEScan Setup

From Sources

CVE Scan has been tested and is supported on Ubuntu, Debian, Kali and Arch Linux, but should work on any standard Linux distribution running on Intel x64.

The simplest way to install CVE Scan is to invoke the install.sh script located in the root directory, which will guide you through all installation steps.

You will have the choice of installing CVE Scan in a Python virtual environment (refer to the Python documentation for details about how to use a virtual environment). We recommend doing this, so that CVE Scan does not interfere with existing Python packages you may use on your system.

Once the virtual environment is installed (for instance in ~/cvescan/.venv) you can activate it to have access to all CVE Scan commands using the following bash command:

source ~/cvescan/.venv/bin/activate

Later on if you don't need access to CVE Scan and want to revert to your global Python environnment you just have to use the deactivate command.

The full installation instructions can be found here.

Setup from Docker Image

To build the image, run

docker build -t cvescan -f ./docker/Dockerfile .

Now with

docker run \
    -v "$CVESCAN_WORKDIR:/home/user/workdir" \
    -v "$CVESCAN_SOURCES:/home/user/.local/share/cvescan" \
    -v "$CVESCAN_CACHE:/home/user/.cache/cvescan" \
    -v ~/.ssh:/home/user/.ssh:ro \ # (1)!
    -e uid=$(id -u) \
    -e gid=$(id -g) \
    -p 8000:8000 \ # (2)!
    -it --rm cvescan

If you don't use the --git-dir option with the filter-report subcommand and are referencing a remote src_uri in your inventory, your ssh credentials can be required. Otherwise this volume is not needed.
This port mapping is needed if you intend to serve the UI locally with the serve-ui subcommand.

you have access to the CVEScan CLI.

Where $CVESCAN_WORKDIR is the directory that will contain your SBOMs and reports.

And $CVESCAN_SOURCES is the directory containing CVEScan required data-sources that we will fetch in step 2.

The CVEScan docker manual can be found here.

Warning

For compatibility with microprocessors not supporting Advanced Vector Extensions (AVX), use the install.sh --lts-cpu option or add the --build-arg LTS_CPU=1 to you docker build command.

2. Download the required data sources

CVEScan requires data sources (linux repository, NVD replication, Ubuntu CVE tracker) to be downloaded. The full process is described here.

Upon execution of the cvescan datasources-update subcommand, a ~/.local/share/cvescan directory will be created where cvescan will fetch the Linux kernel stable and Ubuntu CVE Tracker git repositories, respectively from git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git and git://git.launchpad.net/ubuntu-cve-tracker, as well as NVD vulnerabilities through the dedicated API.

Tip

You can initialize your nvd datasource state by restoring it from a snapshot in the Zstandard format. e.g.

cvescan datasources-update --restore-snapshot cvescan-datasources-snapshot-20250619104957.zst

cvescan datasources-update nvd will then only perform the delta update since snapshot creation.

3. Run your first scan

Now let's run a scan on the sample SBOM with the following command:

cvescan run --inventory demo.inventory.json --advanced-filter

Automatic assesments execution time

CVEScan's automatic filtering-out of detected vulnerabilities will take some time as it performs git introspection. On your first run of cvescan, a cache is built to track linux-kernel sources. This operation is long and can take more than an hour. After that you can expect ~20-30 minutes runtimes.

Analysis without access to product linux-kernel repository

The --use-upstream-linux-ref option e.g

cvescan run --inventory demo.inventory.json --advanced-filter --use-upstream-linux-ref v6.9

will let you set a linux-kernel reference tag to base our analysis on if you don't have access to your product's linux-kernel git repository.

A report.json has been created, listing all the vulnerabilities.

4. Check all detected vulnerabilities

It's time to check your product's vulnerabilities. To do this you can load CVE Scan in CVE Scan Web UI: first run the following command to launch the UI:

cvescan serve-ui

Then you can connect to the UI from your preferred browser and load the report you've just generated: follow the instructions from this page to browse your report.

5. Do your first manual assessment

Now you can work on your vulnerabilities.

Each line of the "Vulnerabilities" view in the WebIU presents a CVE that may impact your product. Clicking on a specific vulnerability opens a "Detailed" view that presents vairous informations:

an identifier (e.g. CVE-2018-16395) which will allow you to gain additional information online (e.g. on the NVD website, the Ubuntu CVE tracker, or other sources),
a description,
the dates of initial publication and last modification,
the affected software component (e.g. openssl),
the version of the software component used in the product (e.g. 1.1.1l),
the automatic assessment made by CVE Scan as to whether the product is vulnerable or not.

Let's take a brief pause here to understand how CVE Scan and the vulnerabilities database interact. The main source of information is the NVD, which maps CVEs to CPEs (see the concepts page for more details). Thus a CVE will appear in the report whenever it is mapped to a CPE that matched on of the software components from your inventory. This is done regardless of whether the version you use is concerned by the CVE. Then CVE Scan (during the scan-inventory phase) will try to determine if the version you use is vulnerable according to its data sources. This is this information you will find in the "Vulnerable" field. If on top of the scan-inventory you also ran the filter-report command then this status may change to "False" (i.e. the CVE is not applicable) for various additional reasons (for precisions refer to the filter-report command documentation), e.g.: - the CVE is whitelisted by Yocto, - the CVE is valid for some specific configuration of the kernel or UBoot, and this configuration is not active in your build, - the CVE has been patched in the precise version of the kernel you are using in your build, - the CVE has been marked as "Not vulnerable" in the annotations file.

CVE Scan will report all information regarding this automatic assesment in the "Automatic assessment" frame.

Now let's continue listing all fields reported for each CVE:

various information regarding the criticity of the vulnerability, including CVSSv2 and CVSSv3 (together with aditional information linked with these scores, such as access vectors, complexity, ...) which you can use to sort the CVEs and process the most critical first;
information regarding fixes to the CVE that have of have not been applied can be found in "Whitelist reason", "Applied patches", and "Available patches"
all information that comes from the manual assessment via the annotations file.

The annotations file is where you can track the progress of your analysis. It follows a syntax described here. The first thing you need to do is create an initial annotations file.

Although it is possible to manually create and edit the annotations file, we recommend using the web user interface for this task, following the instructions provided here. Don't forget to export your annotation file though, so that you can keep it for the subsequent scans.

Update the data sources

CVEs appear every day. On the other hand patched for them also appear on a regular basis. Thus it's important to get your data sources updated at all time, to avoid missing one of them.

We recommend to update all data sources before running CVE Scan (for instance on a daily basis), so let's do this now, assuming that you installed all sources in ~/.local/share/cvescan during installation:

cvescan datasources-update

To go further

Optimize your manual assessment by using scopes to share you annotations across several report;
Rationalize the CLI invocations using the configuration files;
Enrich the lkconfig file to refine the automatic assessment;
Use the Python API to automatize CVE Scan invocation.