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.
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
This project is made to run on local in a docker container.
-
Copy
bin/vulnscout.sh
at root of your project repository. -
Create a
.vulnscout
folder at root of your project repository.
Copy one of the example file inbin/.vulnscout-example
folder into your.vulnscout
folder.
Adjust theses variables to your needs. -
Run
./vulnscout.sh scan
to start the scanner and open http://localhost:7275 to view the results. -
If you get error when running container, try use
docker login
to authenticate to the registry.
More information on [Authentification] section.
-
Start by building the image at root of repository:
BUILD_TAG="local-build" cqfd -b docker_build run
-
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 frombin/.vulnscout-example
into your.vulnscout
folder.l`. -
In your new copied file, customize variables to bind the correct paths.
Replace theDOCKER_IMAGE
value by your image name likevulnscout: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.
-
Copy
docker-compose.template.yml
from this repository asdocker-compose.yml
at root of your project repository. -
Edit this file to bind your volumes. Follow instructions in the file. Then adjust environment variables.
-
Run
docker-compose up
to start the scanner and open http://localhost:7275 to view the results.
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 .
|
-
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). -
If you don’t have a
.gitmodules
file and don’t want to use git submodules, you can add the source manually by going insources
folder and running the following command:git clone https://github.com/savoirfairelinux/meta-cyclonedx.git
-
After cloning meta-cyclonedx, you must enter inside (
cd sources/meta-cyclonedx
) andgit checkout
to a tag for your yocto version. -
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)
-
Native export to SPDX, handled by Yocto
-
Export to Cyclone DX format, made by the meta-cyclonedx layer
-
Check for CVE using Native Yocto tool
-
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.
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 now run ./vulnscout.sh scan
to start the scanner and open http://localhost:7275 to view the results.