VulnScout

---

🔹 Introduction

VulnScout is designed to analyse and identify vulnerabilities in their software components and dependencies using an SBOM (Software Bill Of Materials).

It pulls known vulnerabilities from public sources like the NVD, EPSS, and Grype to figure out which parts of a codebase might be affected by security issues (CVE).

VulnScout also provides a web interface for visualisation and a command line to generate enriched output files.

VulnScout Features

• Analyse SBOMs

• Detect vulnerabilities

• Enrich SBOM files

• Generate detailed reports

• Help track fixes with the dashboard

🔧 Setting up VulnScout

Requirements & Installation

VulnScout is designed to run locally in a Docker container. It will require having docker-compose or docker compose available on your host.

If you need to install docker compose, look at: docker-compose

To install VulnScout, you only need to clone the repository:

git clone https://github.com/savoirfairelinux/vulnscout.git
cd vulnscout

🐧 Using VulnScout

Run VulnScout in interactive mode

This project contains default examples of VulnScout.

To run VulnScout demo in interactive mode, you can simply run the command:

./vulnscout.sh --name demo --spdx $(pwd)/.vulnscout/example/spdx3/core-image-minimal-qemux86-64.rootfs.spdx.json \
--cve-check $(pwd)/.vulnscout/example/spdx3/core-image-minimal-qemux86-64.rootfs.json

Or, if you prefer to run another example based on SPDX2, you can use the following command:

./vulnscout.sh --name example --spdx .vulnscout/example/spdx2/example.rootfs.spdx.tar.zst \
--cve-check .vulnscout/example/spdx2/example.rootfs.json \
--cdx .vulnscout/example/spdx2/cyclonedx-export

Then open your browser to view the results:

http://localhost:7275

These commands will dynamically generate and use docker-compose configuration files.

If you don’t need additional settings after the first configuration, VulnScout can be rerun directly without any additional arguments:

./vulnscout.sh --name example

Run VulnScout with Yocto

We have a dedicated layer for VulnScout integration in Yocto.

You can find the layer here: https://github.com/savoirfairelinux/meta-vulnscout

To be short, a simple inherit vulnscout in your image recipe will be enough to configure vulnscout for your project.

The vulnscout web interface can be started with a bitbake <image-recipe> -c vulnscout command.

Run VulnScout in non-interactive mode

If you want to use the non-interactive mode, without the web interface, you can the command with the --fail_condition argument:

./vulnscout.sh --name demo --spdx $(pwd)/.vulnscout/example/spdx3/core-image-minimal-qemux86-64.rootfs.spdx.json \
--cve-check $(pwd)/.vulnscout/example/spdx3/core-image-minimal-qemux86-64.rootfs.json \
--fail_condition "cvss >= 9.0 or (cvss >= 7.0 and epss >= 50%)"

You can obtain the report of vulnerabilities matching the condition by including the proper report remplate:

./vulnscout.sh --name demo --spdx $(pwd)/.vulnscout/example/spdx3/core-image-minimal-qemux86-64.rootfs.spdx.json \
--cve-check $(pwd)/.vulnscout/example/spdx3/core-image-minimal-qemux86-64.rootfs.json \
--fail_condition "cvss >= 9.0 or (cvss >= 7.0 and epss >= 50%)" \
--report-template match_condition.adoc

Configuration tips for other projects

To use VulnScout, you only need a Software Bill of Materials (SBOM) file in SPDX or CycloneDX format.
The Grype scanner will analyse the SBOM for vulnerabilities; if it already includes some, those will be merged into the final results.
To do so, create a new sub-folder in .vulnscout and place a modified yaml using your configuration.
To configure your yaml file, you can look at the example provided here .vulnscout/example/docker-example.yml

Tips for Editing your yaml file

Tip	.tar, .tar.gz, .tar.zst, and archives are supported as SPDX 2 input. .spdx files (tag-value format) are supported as SPDX 2 input. .spdx.json is supported as SPDX 3 input. To ignore parsing errors for malformed SBOMs, set: IGNORE_PARSING_ERRORS=true

List of environment variables and their purpose:

• USER_UID: This variable sets the UID of the user in the container, allowing Vulnscout to create output files with correct permissions

• USER_GID: This variable sets the GID of the user in the container, allowing Vulnscout to create output files with correct permissions

HTTP Proxy Configuration

If you want to run VulnScout with an HTTP proxy, simply add the standard http_proxy environment variables to the docker-compose file. These variables are respected by all traffic in the container:

environment:
  - HTTP_PROXY=http://proxy.example.com:8080
  - HTTPS_PROXY=http://proxy.example.com:8080
  - NO_PROXY=localhost,127.0.0.1

🔎 Architecture

📥 Supported input files

• SPDX 2.3 (Packages) - JSON and tag-value formats

• SPDX 3.0 (Packages + vulnerabilities)

• Cyclone DX 1.4, 1.5, 1.6 (Packages + vulnerabilities)

• Grype native JSON format (Packages + vulnerabilities)

• Yocto JSON output of cve-check module (Packages + vulnerabilities)

📤 Supported output files

• SPDX 2.3 (Packages)

• SPDX 3.0 (Packages + vulnerabilities)

• Cyclone DX 1.4, 1.5, 1.6 (Packages + vulnerabilities)

• openVex (vulnerabilities + assessments)

• All reports: Asciidoc, HTML, PDF

• Summary: Asciidoc, HTML, PDF

• Time estimates: csv

• Vulnerabilities: csv, txt

📊 Vulnerability Data Sources

The tool pulls vulnerability and risk data from multiple trusted sources:

• NVD (National Vulnerability Database)

• All data sources supported by Grype

• EPSS (Exploit Prediction Scoring System)

• OSV (Open Source Vulnerabilities) Coming soon

• Information embedded in input files

📝 Custom CVSS Scoring

VulnScout allows you to add a custom CVSS vector string to a vulnerability, enabling organisation-specific vulnerability scoring.

📋 Licence

Copyright © 2017-2025 Savoir-faire Linux, Inc.
VulnScout is released under the GPL-3.0 license.