VulnScout

Table of Contents

• Introduction
• Usage
• Deployment
  • Recommended setup using vulnscout.sh wrapper
  • Alternative setup: Build and use a local image
  • Alternative setup: Use docker-compose instead of vulnscout.sh
• Specific configuration
  • Configuration for Yocto projects
  • Configuration tips for others projects

Introduction

Scanning project to export Software Bill of Materials (SBOM) and list of Vulnerabilities that affect them. Support for Cyclone DX, SPDX, Yocto JSON files and Open VEX.

This document use a lot of format names, accronyms and abbreviations which is evident for people working on them, but not for everyone. Here is a definition of the most used ones:

CVE

Common Vulnerabilities and Exposures. Most (but not all) vulnerabilities discovered by a security researcher are assigned a CVE number. This number is unique and is used to reference the vulnerability in various databases.

SBOM

Software Bill of Materials. A list of all the components used in a software project. This list can be used to track dependencies, licenses, and vulnerabilities.

SPDX

Software Package Data Exchange. A standard format for SBOMs developed by the Linux Foundation. Mostly found as JSON or XML files.

CDX

Cyclone DX. A standard format for SBOMs developed as an OWASP project. Mostly found as JSON or XML files.

Yocto

A build system for embedded Linux systems. It is used to build custom Linux distributions for embedded systems.

Usage

You can use VulnScout to scan your project, make report about your dependencies and vulnerabilities, and to manage them.

Support following inputs :

• SPDX 2.3 (Packages)

• Draft: 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)

Support following outputs :

• SPDX 2.3 (Packages)

• Draft: SPDX 3.0 (Packages + vulnerabilities)

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

• openVex (vulnerabilities + Assessments)

Grab data from following sources :

• NVD (National Vulnerability Database)

• All datasource supported by Grype

• EPSS (Exploit Prediction Scoring System)

• OSV (Open Source Vulnerabilities) Comming soon

• Information embedded in inputs files

Deployment

This project is made to run on local in a docker container.

Recommended setup using vulnscout.sh wrapper

1. Copy bin/vulnscout.sh at root of your project repository.

2. Create a .vulnscout folder at root of your project repository.
   Copy one of the example file in bin/.vulnscout-example folder into your .vulnscout folder.
   Adjust theses variables to your needs.

3. Run ./vulnscout.sh scan to start the scanner and open http://localhost:7275 to view the results.

4. If you get error when running container, try use docker login to authenticate to the registry.
   More information on [Authentification] section.

Alternative setup: Build and use a local image

1. Start by building the image at root of repository:
   BUILD_TAG="local-build" cqfd -b docker_build run

2. Then, copy bin/vulnscout.sh into root of your project repository. Create a .vulnscout folder also at root.
   Copy one of the .rc conf file from bin/.vulnscout-example into your .vulnscout folder.l`.

3. In your new copied file, customize variables to bind the correct paths.
   Replace the DOCKER_IMAGE value by your image name like vulnscout:local-build.

Now, after each build, you can run ./vulnscout.sh scan to run a new scan and open http://localhost:7275 to view the results.

Alternative setup: Use docker-compose instead of vulnscout.sh

1. Copy docker-compose.template.yml from this repository as docker-compose.yml at root of your project repository.

2. Edit this file to bind your volumes. Follow instructions in the file. Then adjust environment variables.

3. Run docker-compose up to start the scanner and open http://localhost:7275 to view the results.

Specific configuration

Configuration for Yocto projects

After having setup one of the Deployment tutorial, you have some steps needed make Yocto output necessary files.

Tip	CycloneDX is not mandatory to use VulnScout. If you want to use only SPDX and CVE-checker, skip step 1-3 and at step 4, ignore the line cyclonedx-export.

1. In the Yocto repository, if you use git submodules features, you can run:
   git submodule add https://github.com/savoirfairelinux/meta-cyclonedx.git sources/meta-cyclonedx
   (tips: if you have a .gitmodules, you should use this command).

2. If you don’t have a .gitmodules file and don’t want to use git submodules, you can add the source manually by going in sources folder and running the following command: git clone https://github.com/savoirfairelinux/meta-cyclonedx.git

3. After cloning meta-cyclonedx, you must enter inside (cd sources/meta-cyclonedx) and git checkout to a tag for your yocto version.

4. Add the following lines if their are not present in your layers.conf file:
   

INHERIT += "create-spdx" (1)
INHERIT += "cyclonedx-export" (2)
INHERIT += "cve-check" (3)
include conf/distro/include/cve-extra-exclusions.inc (4)

1. Native export to SPDX, handled by Yocto

2. Export to Cyclone DX format, made by the meta-cyclonedx layer

3. Check for CVE using Native Yocto tool

4. Exclude some old CVE that was corrected

Then you are almost ready. Make a new build of your Yocto project to generate SPDX, CDX and CVE files.
To allow vulnscout to find your SBOM files, ensure you have copied and configured .rc file in the .vulnscout folder.
If you haven’t already done it, check the examples in bin/.vulnscout-example/yocto.rc folder of this repository.

Configuration tips for others projects

If you are not using Yocto, you can still use the scanner. What you need is at least one SBOM in SPDX or CDX format. Grype and OSV scanner will then try to find all vulnerabilities matching packages in the SBOM. If your SBOM includes vulnerabilities, they will also be included in the final merge.

If you followed correctly the Deployment section, you should have a .vulnscout folder at the root of your project. You can edit this file in it and make the path bindings for SPDX / CDX variables:

Tip

You can delete the YOCTO_CVE variable if you don’t use Yocto CVE-check. You can refer as many files and folder as needed. They are Bash arrays. Scanner support reading in .tar, .tar.zst and .tar.gz archives. If your inputs may contains invalid files, you can set IGNORE_PARSING_ERRORS to true in your .rc file.

You can now run ./vulnscout.sh scan to start the scanner and open http://localhost:7275 to view the results.

README_DEV.adoc