Vigiles User Guide

Table of Contents

Getting Started

What is Vigiles?

Vigiles is a Software Composition Analysis (SCA) tool that helps generate and analyze a Software Bill of Materials (SBOM) for publicly known cybersecurity vulnerabilities (particularly CVEs). In addition, Vigiles provides a complete vulnerability lifecycle management tool: discovery, prioritization, triaging, remediation, compliance and on-going monitoring/alerts. In short, it helps maintain the security of your product.

Vigiles is particularly optimized for embedded linux systems and readily integrates into build systems such as Yocto, Buildroot, OpenWrt, and Factory.

How does Vigiles work?

Vigiles reports vulnerabilities by analyzing the components in a SBOM (list of packages and associated versions i.e. Software Bill of Materials - SBOM for your product) against a Timesys curated vulnerability database. To generate the SBOM, there are three options:

  1. Automatic generation: Vigiles directly integrates with build systems (Yocto, Buildroot, OpenWrt, and Timesys Factory) to generate and upload the software SBOM to Vigiles.
  2. BOM CSV (manually or externally generated): Vigiles supports custom Software BOM in CSV format (example obtained from package managers, custom build systems, hand generated etc).
  3. Create SBOM wizard: Vigiles provides a UI where components can be selected to create a Software BOM.

Once the SBOM is uploaded/created, Vigiles scans the packages listed in the SBOM for vulnerabilities and redirects to the CVE Dashboard which provides tools/information to help remediate the vulnerabilities. For on-going monitoring of new vulnerabilities sign up for email alerts or run on-demand scans.

Quick Start

Demo SBOM

To try Vigiles without having to upload your product SBOM, a sample SBOM is pre-uploaded to your account. To get started, visit Vigiles Dashboard, and click on Private Workspace under Products. Vigiles should automatically trigger an initial scan (takes up to a minute) and redirect to the CVE dashboard where you can get familiar with the capabilities of Vigiles.

Note: On subsequent visits, click on “sample_config.csv” to view the CVE report.


 

Yocto

To generate a vulnerability report, follow the steps below:

Step 1: Clone meta-timesys into your Yocto source directory

git clone https://github.com/TimesysGit/meta-timesys.git -b master

 

Step 2: Include meta-timesys in bblayers.conf (modify path as needed)

BBLAYERS += "${TOPDIR}/../meta-timesys"

 

Step 3: Inherit Vigiles in local.conf by adding the line below:

INHERIT += "vigiles"

 

Step 4: Download an API key from here and store it in the path below:

/home/<user>/timesys/linuxlink_key

Note: If the key is stored elsewhere, then specify the full path in local.conf. e.g:

VIGILES_KEY_FILE = "/tools/timesys/linuxlink_key"

 

Step 5: Run bitbake <your-image-name>. A SBOM is automatically generated and uploaded to Vigiles, and a link to a vulnerability report is provided in the command line output.

$ bitbake core-image-minimal

Vigiles: Requesting image analysis from LinuxLink …

-- Vigiles CVE Report --

        View detailed online report at:
            https://linuxlink.timesys.com/cves/reports/ODUzOA.D9xLIQ.KKiK2E76n---q6_-KmJrsZ9ap9Y

        Unfixed: 62 (0 RFS, 60 Kernel, 2 Toolchain)
        Unfixed, Patch Available: 7 (2 RFS, 0 Kernel, 5 Toolchain)
        Fixed: 0 (0 RFS, 0 Kernel, 0 Toolchain)
        High CVSS: 30 (2 RFS, 24 Kernel, 4 Toolchain)

        Local summary written to:
            vigiles/core-image-minimal/core-image-minimal-2019-06-07_19.22.40-report.txt

By default, the SBOM is uploaded to the “Private Workspace” under your Vigiles account. To view other options and for more detailed information visit meta-timesys on GitHub.

Note: A SBOM file is generated at build/vigiles/<image-name>.json which may also be manually uploaded to Vigiles to generate a CVE report. To do so, click on Yocto under “Upload SBOM” on the Vigiles Dashboard page.


 

Buildroot

To generate a vulnerability report follow the steps below:

Step 1: Clone the vigiles-buildroot repository:

git clone https://github.com/TimesysGit/vigiles-buildroot

 

Step 2: Download an API key from here and store it in the path below:

/home/<user>/timesys/linuxlink_key

Note: If the key is stored elsewhere, then use the menuconfig option to specify the correct path.

 

Step 3: Export the path to vigiles-buildroot using the following command:

make BR2_EXTERNAL=/path/to/vigiles-buildroot menuconfig

Note: If you already have a custom external buildroot tree, then export both paths. e.g.:

make BR2_EXTERNAL=/path/to/vigiles-buildroot:/path/to/custom menuconfig

 

Step 4: Run the vigiles check command. A SBOM is automatically generated and uploaded to Vigiles, and a link to a vulnerability report is provided in the command line output:

make vigiles-check

 

By default, the SBOM is uploaded to the “Private Workspace” under your Vigiles account. To view other options and for more detailed information visit: vigiles-buildroot on GitHub.

Note: A SBOM file is generated at build/vigiles/<image-name>.json which may also be manually uploaded to Vigiles to generate a CVE report. To do so, click on Buildroot under “Upload SBOM” on the Vigiles Dashboard page.

 

OpenWrt

To generate a vulnerability report follow the steps below:

Step 1: Clone the vigiles-openwrt repository:

git clone https://github.com/TimesysGit/vigiles-openwrt.git

Step 2: Download an API key from here and store it in the path below:

/home/<user>/timesys/linuxlink_key

Step 3: Run Vigiles CVE Scanner (vigiles-openwrt.py) with paths of OpenWrt build directory and a Vigiles output directory path (where generated report and SBOM would be kept):

cd {vigiles-openwrt clone directory}
./vigiles-openwrt.py -b {path of openwrt directory} -o {path of Vigiles output directory}

By default, the SBOM is uploaded to the “Private Workspace” under your Vigiles account. To view other options and for more detailed information visit: vigiles-openwrt on GitHub.

Note: A SBOM file is generated at {Vigiles output directory}/vigiles/output/<board-name>-manifest.json which may also be manually uploaded to Vigiles to generate a CVE report. To do so, click on OpenWrt under “New SBOM” on the Vigiles Dashboard page.

 

Timesys Factory

Note: If you already have Desktop Factory installed, skip to step 3 below.

To generate a vulnerability report follow the steps below:

Step 1: Clone and setup Timesys Factory as documented here

Step 2: Download an API key from here and store it in the path below.

/home/<user>/timesys/linuxlink_key

Note: If the key is stored elsewhere, then export the variable below in the shell environment:

export KEY_FILE="/tools/timesys/linuxlink_key"

 

Step 3: Run the checkcves command. The Factory Workorder will automatically be uploaded to Vigiles and a link to a vulnerability report will be provided in the command line output:

make checkcves

By default, the SBOM is uploaded to the “Private Workspace” under your Vigiles account.

 

Note: The Factory Workorder (.config file) can be manually uploaded to Vigiles to generate a CVE report. To do so, click on Factory under “Upload SBOM” on the Vigiles Dashboard page.

 

How to generate a PTXdist CSV SBOM.

To generate a vulnerability report, follow the steps below:

Step 1. Generate a csv SBOM from ptxdist using the below commands:

ptxdist list-packages | xargs ptxdist package-info | grep -e package: -e version: | awk '{ print $2 }' | (echo "package,version"; sed '$!N;s/\n/,/') > ptxdist.csv

Step 2. Upload it to Vigiles manually and/or using the API (https://linuxlink.timesys.com/docs/vigiles-api) along with any associated configs (kernel/u-boot)

Note: The only thing that will be missing from the above SBOM mechanism is information regarding any cves "fixed" via patches applied in the build system.

 

SPDX Software BOM

Vigiles supports uploading SPDX SBOMs (versions 2.2 - 2.3) in the following formats:
Tag/Value, JSON, XML, YAML, RDF/XML, RDF/TTL, XLSX Spreadsheet, XLS Spreadsheet

 

Vulnerability reports can be generated using the Vigiles CLI or by following the steps below:

Step 1: Create an SBOM following the SPDX specification

Step 2: On the Vigiles Dashboard page click on “SPDX”, under "Upload SBOM"

Step 3: Upload the SPDX file. Vigiles will automatically generate a report and redirect to the CVE dashboard.

 

Fields that are used by Vigiles
  • name - Used to link SBOMs together in order to provide a history of changes within an SBOM for a product
  • annotator - Used to further restrict which SBOMs will be linked
Packages

Vigiles tracks packages in SPDX SBOMs by consuming the following fields:

If both PackageLicenseConcluded and PackageLicenseDeclared are included in an SBOM, both will be displayed in a CVE report

When searching for CVEs for a given component, SBOMs may contain multiple package definitions. Vigiles scans the following:
  1. CPE
  2. Package name and version

 

CycloneDX Software BOM

Vigiles supports uploading CycloneDX SBOMs in either JSON or XML formats and CycloneDX versions 1.1 to 1.4

 

Vulnerability reports can be generated using the Vigiles CLI or by following the steps below:

Step 1: Create a CycloneDX SBOM following the JSON or XML specifications

Step 2: On the Vigiles Dashboard page click on “CycloneDX”, under "Upload SBOM"

Step 3: Upload the CycloneDX file. Vigiles will automatically generate a report and redirect to the CVE dashboard.

 

Fields that are used by Vigiles

name - Used to link SBOMs together in order to provide a history of changes within an SBOM for a product

Packages

Vigiles tracks packages in CycloneDX SBOMs by consuming the following component fields:

When searching for CVEs for a given component, SBOMs may contain multiple package definitions. Vigiles scans the following:
  1. purl
  2. CPE
  3. Component name and version
Licenses (optional):

Either a license or an expression can be used

If a license is used, Vigiles will use the following fields:

Either the license id or name will be displayed in a CVE report with id having priority. If a url is provided, a link be included in the CVE report.

Patches (optional):

Patches can be included in an SBOM to automatically mark CVEs as "Fixed" in Vigiles reports. These CVEs will be included in the "Fixed" summary counts and can be easily filtered out of the report.

Vigiles uses the following fields:

  • type - Patch type ("defect", "enhancement", or "security")
  • id - CVE ID

 

Software BOM CSV

To generate a vulnerability report, follow the steps below:

Step 1: On the Vigiles Dashboard page click on “BOM - CSV”, under "Upload SBOM"

Step 2: Create a BOM CSV file.

Start by clicking on the ‘CSV template' button to get a working CSV template with sample data and then modify it to add your components. A CSV SBOM consists of the following fields:

  • Product — the CPE Name (product field) that packages use when reporting CVEs1
  • Version — the version of the package used (leave blank to report all vulnerabilities)
  • (optional) Patched CVEs — a space-separated list of CVE IDs to be listed as "Fixed" in the report
  • (optional) Whitelisted CVEs — a space-separated list of CVE IDs to be ignored, listed as "Whitelisted" in the report

CSV Example (simple):

package,version
busybox,
linux_kernel,4.18.21

 

CSV Example (advanced):

package,version,patched,whitelist
busybox,1.29.2,,
glibc,2.28,,CVE-2016-10739 CVE-2019-7309
linux_kernel,4.18.21,CVE-2018-16880 CVE-2019-9003,CVE-2016-8660

 

Step 3: Upload the CSV file. Vigiles will automatically generate a report and redirect to the CVE dashboard.

 

Create SBOM Wizard

To generate a vulnerability report, follow the steps below:

Step 1: On the Vigiles Dashboard page click on “Create SBOM”

Step 2: Select components present in your product.

Start by clicking the "Package Name1" input, then type in your package name and click "Add Package2". The "Package Version" information is optional. Leave it blank to report all vulnerabilities for that package.

 

Step 3: When done adding packages, click "Save". Vigiles will automatically generate a report and redirect to the CVE dashboard.

 

By default, the SBOM gets saved to the “Private Workspace”. To save the SBOM elsewhere, click the dropdown next to "Save" and then select "Other product."

 

Search CVEs

The “Search CVEs” feature allows searching specific vulnerabilities based on CVE-ID or by package name (software or hardware component) without creating a SBOM. The vulnerability information reported is from the Timesys curated database. To begin:

Step 1: Click “Search CVEs” feature on the Vigiles Dashboard

Step 2: Select the search type and enter the Package Name (eg: busybox) or CVE-ID (eg: CVE-2019-19767) and then Search. The results from the search are displayed.

 

Why Vigiles?

Superior vulnerability data

  • Timesys curated data (up to 40% improvement over NVD, fewer false positives)
  • Multiple vulnerability feeds for better coverage
  • Expedited notification of new vulnerabilities (up to four weeks earlier than NVD)

Optimized for embedded systems

  • Linux kernel and u-boot configs filter results based on features used (4x CVE triage reduction!)
  • Reports only vulnerabilities for packages installed on the target
  • Automatically tracks CVEs which are already fixed in your build system
  • Includes support for reporting CPU/SoC vulnerabilities

One stop easy solution: Monitoring, triaging, remediation

  • Email alerts for new vulnerabilities based on your preferred frequency
  • Intuitive prioritization and filtering mechanisms
  • Complete vulnerability management workflow: History, reports, notes, whitelist
  • Links to applicable patches and recommends minimum version upgrades with relevant fixes

End-to-End workflow support

  • Team collaboration/sharing
  • Powerful and convenient "comparison" capability for a quick into what has changed between builds
  • Integration with other SDLC and CI/CD tools using APIs
  • Access to Timesys Security team for any questions about vulnerabilities

To learn more about accuracy and false positives read our Embedded Linux Conference presentation.

 

Vigiles technology overview

 

Vigiles works by comparing the packages/versions in a SBOM against a Timesys curated database to report vulnerabilities.

 

Vigiles pulls vulnerability data from multiple sources such as NVD and Security Bulletins (Ubuntu, Debian), which is run through Timesys-developed curation algorithms to reduce false positives (by cross-verifying available fixes against git commits to confirm affected version ranges, etc.), map vulnerabilities to package config options, and limit to affected platforms. This curation and feed update happens automatically on a nightly basis. In addition, the Timesys security research team manually monitors vulnerabilities in packages from build systems such as Yocto and Buildroot, SoC vendor advisories, and mailing lists such as oss-security, and adds/curates vulnerability information as needed. All of these steps lead to improved accuracy and coverage while reducing false positives.

Vigiles also tracks the latest versions of packages and checks if vulnerabilities are fixed in those in order to suggest a remediation.

Vigiles APIs

The Vigiles CLI contains a Python package and a command-line tool for interacting with APIs for Timesys services such as Vigiles.

Download Vigiles CLI: https://github.com/TimesysGit/vigiles-cli
Vigiles CLI documentation: https://linuxlink.timesys.com/docs/vigiles-cli/
 
API manual: https://linuxlink.timesys.com/docs/vigiles-api-manual

Report interpretation

Once a SBOM is uploaded, Vigiles automatically generates a CVE report and redirects to the CVE dashboard page containing the sections below.

Summary section

This section gives an overview of the vulnerabilities that Vigiles has identified affecting the packages in your SBOM, broken down into:

  • Unfixed: Count of vulnerabilities that need to be addressed
  • Fixed: Count of vulnerabilities that are applicable but already addressed
    • Yocto/Buildroot/OpenWrt/Factory: If a patch is being applied and CVE ID is present in the patch file name or header, Vigiles marks the vulnerability as fixed
      For example:
      In the yocto build system, CVE-2020-8169 is patched by a file with a CVE ID in patch file name (Patch file names are case insensitive) for v7.69.1 . Hence after the build when the CVE report is generated the CVE ID will appear as Fixed in the report as shown in the picture. The applied patch name will appear in the “Applied Fix” as shown below.
    • BOM CSV: If the CSV specifies CVE IDs that are fixed
      For example:
      A fixed CVE (or patched CVEs ) can be marked as Fixed by using the field “patched” in the csv file as in the CSV example (advanced).
  • High/Critical CVSS (Unfixed): Count of vulnerabilities with Common Vulnerability Scoring System (CVSS) score greater than 7. The CVSS score (0 to 10 range) is an industry standard that gives an insight into how easy it is to exploit and how damaging the vulnerability is. These are the vulnerabilities that typically should be addressed first.

Package section

This section gives a high-level summary of the vulnerabilities in each package broken down into Unfixed, Fixed, and Whitelisted (vulnerabilities marked to be ignored). Additionally, for Yocto, Buildroot, and OpenWrt users, license information is provided.

By default, only packages with unfixed vulnerabilities are displayed. They are sorted by the number of critical vulnerabilities, followed by high, medium, and low counts. To view all packages, uncheck the “Show Unfixed Only” box.

Clicking on any package jumps to the CVE section which provides details about the vulnerabilities for that package.

 

CVE section

This section provides details about vulnerabilities per package / version with the following info:

Fixed Version

The minimum version of the package which includes a fix for the vulnerability. If this is left blank then either a fix is not yet available, or Vigiles does not yet know about the fix or newer version.

 

CVE ID

Corresponds to the vulnerability ID. Clicking on it displays details about the vulnerability along with any Timesys curated information. A section of particular interest might be “Affected Configurations” which shows all the package and version combinations affected by this vulnerability.

 

Status

Specifies one of these states:

  • Fixed: Vulnerability is already addressed
  • Unfixed: Vulnerability needs to be addressed
    • Yocto: icon means a fix is available for BSP maintenance customers
    • Timesys Factory: "Unfixed, Update Factory" indicates upgrading the Factory and/or the Workorder will address this vulnerability
  • Whitelisted: Vulnerability is to be ignored

 

CVSSv3

As noted in the summary section, the CVSS score determines the severity of the vulnerability. By default, CVSSv3 scores are displayed but will fall back to CVSSv2 for older vulnerabilities without a CVSSv3 score. "None" is displayed when a CVSS score is not yet assigned (typically when NIST NVD has yet to analyze the CVE).

 

Attack Vector

This determines the context in which the vulnerability can be exploited:

  • Network: “Remotely exploitable” and can be thought of as an attack at the protocol level from one or more network hops away
  • Adjacent: Attacks must be launched from the same shared physical (e.g., Bluetooth) or logical (e.g., local IP subnet) network, or from within a secure or otherwise limited administrative domain (e.g., VPN)
  • Local: The vulnerable component is not bound to the network stack and the attacker's path is via read/write/execute capabilities. (e.g.: keyboard, console, valid ssh credentials, user interaction via social engineering techniques, etc.)
  • Physical: The attack requires the attacker to physically touch or manipulate the vulnerable component (e.g., via inserting a USB device).

 

References, patches, and config options

Clicking anywhere on the vulnerability row provides more information including links to patches or mitigation along with links to possible exploits. It would be prudent to prioritize fixing high-CVSS score vulnerabilities with public exploits first.

For packages like the Linux Kernel and U-Boot, Vigiles provides links to mainline commits that address the vulnerability along with information on which config options result in the vulnerability.

 

Custom Score/Notes/Whitelist

Refer to the "Triaging Vulnerabilities" section for details on these user-entered fields.

Triaging vulnerabilities

Once the summary is reviewed, the next step is to prioritize and investigate vulnerabilities. Vigiles automatically filters vulnerabilities that are not applicable to the product based on features or portions of code which are not being used (e.g.: linux kernel/u-boot config filtering), platform applicability (e.g.: windows only) which, in combination with Timesys curated vulnerability data, reduces the triage burden on the end user and keeps false positives to a minimum.

Filters

Use the various filter options to quickly drill down to vulnerabilities that matter.

  • Package: If only particular packages are of importance, use the dropdown to select them in order to see vulnerabilities for those packages only.
  • Status: Filter based on status. The typical use case is to filter by Unfixed vulnerabilities.
  • Attack Vector: Filter based on the context from which the vulnerability can be exploited. Typical use cases:
    • For remote exploits, select “Network”
    • For air-gapped devices with no user input, select “Physical”
  • Minimum CVSS: Filter based on severity threshold. The typical use case is to set it to "High" in order to show only High and Critical vulnerabilities.
  • Minimum Custom Score: Filter based on a threshold for the user-entered scores/priority.
  • Kernel/U-Boot configuration: This is an extremely handy feature if the Linux kernel and U-Boot packages are in your SBOM. Uploading the full configuration for these packages results in reporting vulnerabilities based on what is being used (i.e. don't show vulnerabilities for drivers/sub-systems not being compiled).

For Yocto, Buildroot, and OpenWrt users, the kernel/u-boot config is automatically uploaded by default along with the SBOM from the command line. All other users need to upload the kernel config manually using the web interface. Click on the Kernel/U-boot config filter and upload the full config file (not defconfig) from your computer3.

Note: The configs are stored at a SBOM level, so if a new SBOM is uploaded then the config will need to be re-uploaded for it.

Notes

The notes field is intended for saving user triage information. On the CVE row, click on the dropdown and then enter data and click "Save."

More details about how this feature behaves:

  • The note is unique per CVE per package/version (i.e. if a CVE affects multiple packages and/or versions, unique notes can be captured for each)
  • Notes are stored at a product level (i.e. a note added for a CVE affecting a package/version shows up on all reports across all SBOMs under that product)
  • Notes do not get lost on rescan or with the upload of a new SBOM
  • Notes can be imported to other products
  • The user info and timestamp are logged to allow an audit of the last modification

Whitelist

When investigating CVEs, it might turn out that the vulnerability is not applicable (false positive) or important. The whitelist feature allows one to mark such CVEs or all CVEs for a package to be ignored. Doing so changes the status to ‘Whitelisted', which allows the user to focus on ‘Unfixed' CVEs that need to be addressed.

In the CVE row, click on the dropdown and then click on "Move to Whitelist." The default behavior is to whitelist just that CVE. Select the "Package" option from the "Move to Whitelist" dropdown to whitelist all CVEs for that package/version instead.

More details about how this feature behaves is below:

  • The whitelist is unique per CVE per package/version (i.e. if a CVE affects multiple packages and/or versions, each CVE can be separately whitelisted)
  • Whitelists are stored at a product level (i.e. a CVE whitelisted for a package/version shows up “Whitelisted” on all reports across all SBOMs under that product)
  • Whitelisted status does not get lost on rescan or with the upload of new SBOM
  • Whitelists can be imported to other products
  • The user info and timestamp are logged to allow an audit of the last modification

Custom scores

Assign custom severity/priority to a CVE based on internal metrics. In the CVE row under the "Custom Score" column you may assign a value (0.0 to 10.0) and click the check-mark to save. Vigiles allows sorting and filtering based on the custom score, which allows you to easily prioritize CVEs based on custom metrics.

More details about how this feature behaves is below:

  • The custom score is unique per CVE per package/version (i.e. if a CVE affects multiple packages and/or versions, unique custom scores can be assigned)
  • Custom scores are stored at a product level (i.e. custom score added for a CVE affecting a package/version shows up on all reports across all SBOMs under that product)
  • Custom scores are not lost on rescan or with the upload of a new SBOM
  • Custom scores can be imported to other products

Feedback / Reporting errors

If there are vulnerabilities in the report that are not applicable (false positives) or are not being reported (missed by Vigiles), please click on the “Send Feedback” button on the CVE dashboard page and notify us. We typically get back within 72 hours with a response or a fix. It is recommended to read through the FAQ before reporting an error.

Remediating vulnerabilities

After triaging, the next step is to remediate or mitigate. The typical options are listed below.

Upgrade package

The ideal option is to upgrade to the latest version of the package because this typically resolves most of the vulnerabilities. Use the “Fixed Version” field to determine if upgrading the package might resolve the vulnerability. For Linux kernel vulnerabilities, Vigiles tracks if the fix has been backported to the LTS versions of the kernel, in order to avoid any major kernel update.

Note: Timesys Factory users should check the status "Unfixed, Upgrade Factory" in order to see if a fix is available in the latest version of Factory.

Backport patch

Sometimes upgrading a package might not be an option due to various reasons like API changes requiring custom application changes, package license change, potential regression issues, and/or needing to emergency patch severe vulnerabilities. In such cases, refer to the References and/or Patch links provided by Vigiles and try to apply or backport the patch.

Mitigate

In some cases disabling a config option for an unused feature might mitigate the vulnerability. Use the References and/or Config options provided by Vigiles to see if this is possible.

For example: Consider CVE-2018-12233. As per the ‘Config Options Affected' list in the ‘Curated Info' section, CONFIG_JFS_FS results in the vulnerability. So if journaled file system support is not required, then disabling this config option will result in mitigating the vulnerability.

Timesys BSP maintenance service

Timesys offers a service where we do the monitoring/triaging/remediation of vulnerabilities for your product and validate the updated software running on your hardware. This service includes Linux kernel upgrades and driver testing. Learn more here.

Ongoing monitoring (new vulnerability alerts)

After the initial SBOM upload and CVE report generation, there are two ways to get alerted of new vulnerabilities:

  1. On demand scans
  2. Email notifications via automatic scheduled scans

If a component is upgraded or patched, a new SBOM needs to be uploaded to inform Vigiles about the change. If not, it will continue to alert about vulnerabilities corresponding to the components in the old SBOM. There are 3 ways to inform Vigiles of changes to the SBOM:

  1. Running a Vigiles check from the command line automatically results in uploading the latest version of the SBOM and generating a new report. Older SBOMs are still available for viewing/generating reports online.
  2. Use the "Upload SBOM" feature on the web to upload the latest SBOM
  3. Use the "Edit SBOM" feature on the CVE Dashboard to specify the changes

On demand

  • Rescan from desktop: Running a Vigiles check from the command line for Yocto, Buildroot, OpenWrt, or Factory automatically generates the new report with a link that will show the latest report with changes highlighted.
  • Rescan from web: On the product page or CVE report page, clicking on "Rescan" will generate a new report which will highlight new CVEs and any other changes since the last scan.

Automated Notifications

Subscribing to notifications (daily/weekly/monthly) will result in Vigiles performing automatic scans based on your chosen cadence and will send an email with a summary of new vulnerabilities and links to detailed reports.

  • To Subscribe: On the Vigiles Product page under the “Notifications” column, select the desired frequency of notification.
  • To Unsubscribe: Change the notification setting to “None”.

Vigiles offers the ability to link SBOMs (think of it as automatic SBOM revision control) which is enabled by default when a new Product is created. If SBOM linking is enabled (this can be verified under individual product settings on the Product page), then the notification is for the product (i.e. when new SBOMs are uploaded to that product, notifications are sent based on the latest SBOM). If linking is disabled (e.g. in the "Private Workspace") then the notification is at SBOM level and needs to be subscribed on every new SBOM upload.

To unsubscribe from all security and update emails, visit the User Preferences page.

History and Report Comparison

Each time a scan is performed (either on-demand or automatic), a new report is generated and the old one is archived. Clicking on “View History” from the CVE Dashboard page, or clicking “All” from the Product page, takes you to the historical view detailing vulnerabilities over time. Reports can be compared using the compare option dropdown.

Managing products and SBOMs (SBOM)

This section provides recommendations on monitoring vulnerabilities in multiple products, where each product can have multiple software releases.

SPDX SBOM

Software Package Data Exchange(SPDX) is an open standard for communicating software bill of material (SBOM) information, including components, licenses, copyrights, and security references4.

Export SPDX SBOM

Vigiles can convert and export SBOMs of other types to SPDX 2.2

Step 1: Navigate to the CVE report for the SBOM that you would like to export
Step 2: Click 'Download SBOM'
Step 3: Select 'SPDX' or 'SPDX Lite' in the side menu
Step 4: Select an SPDX file format in the dropdown menu
Step 5: Click Download

CycloneDX SBOM

CycloneDX is a lightweight Software Bill of Materials (SBOM) standard designed for use in application security contexts and supply chain component analysis.

Export CycloneDX SBOM

Vigiles can convert and export SBOMs of other types to CycloneDX 1.4

Step 1: Navigate to the CVE report for the SBOM that you would like to export
Step 2: Click 'Download SBOM'
Step 3: Select 'CycloneDX' in the side menu
Step 4: Select between JSON, XML, or CSV file formats
Step 5: Click Download

Create Product

On the Vigiles Dashboard, click on “Create Product” and provide a name, then click "Save." This will create a product to which SBOMs can be uploaded to.

Create Folder

On the Product Dashboard, click on “Create Folder” and provide a name, then click "Save." This will create a folder where SBOMs can be uploaded to. This is a way to separate your SBOMs within the same product. Folders can be nested, and SBOM linking is available as a setting in each folder separately.

Upload SBOM to a product

Web Upload

To upload a SBOM to a particular product, click on the product, and then click on the SBOM type under “Upload SBOM”. Upon upload, the SBOM is saved to that product.

Alternatively, on the Vigiles Dashboard, when choosing:

  • Upload SBOM: Select the desired product from ‘Select product to upload SBOM to' dropdown.
  • Create SBOM: Select ‘Other product' from the ‘Save' dropdown and then select the desired product from the ‘Product' dropdown.

Dashboard config

By default, when using the Yocto or Buildroot command line, the SBOM is uploaded to the “Private workspace”. To upload the SBOM to a specific product, download the associated “Dashboard Config” of the corresponding Product. The Dashboard Config file is located under the “actions” column of the Vigiles Dashboard or under the Product Settings of a particular Product page. Once the file is downloaded, specify the path in your Yocto or Buildroot configuration. Refer to the README files of Yocto and Buildroot for more information.

Dynamic subfolder creation

If a Dashboard Config is used, a subfolder can also be specified. If a subfolder within the Dashboard Config location exists, the SBOM will be saved there. Otherwise, a new subfolder will be created with the specified name, and the SBOM will be saved there. Refer to the README files of Yocto and Buildroot for more information.

Move/Copy SBOM

If a SBOM has already been uploaded to "Private Workspace" or another product and needs to be moved to a different product, use the move or copy SBOM feature.

On the product page in which the SBOM currently exits, under the "action" column, click on "move" and then use the "Select product to move SBOM to" dropdown to select a different product.

  • Selecting “Copy” results in copying instead of moving.
  • Selecting “Include previous versions” results in copy/move of all versions of that SBOM if linking is enabled in the product (see next section)

Move/Copy folder

Folders can be moved and copied between products or other folders.

On the product page in which the folder currently exits, under the "action" column, click on "move" and then select the location to move the folder to. If no folder location is set, the selected folder will be moved to the base level of the selected product. If a folder with the same name already exists in the target location, you will be asked to changed the name of the folder that you are moving to avoid duplicate folder names.

  • Selecting “Copy” results in copying instead of moving.
  • "Copy SBOM linking settings" will copy the linking settings of the copied folder
  • "Copy alert settings" will copy the alert settings of the copied folder if any are set

Vigiles offers linking SBOMs (think of it as automatic SBOM revision control) which is enabled by default when a new Product is created. When a new version of a SBOM with a matching image name is uploaded to that product, it automatically hides/archives the older version and only shows the latest version with a version number. The older versions can still be viewed using the dropdown next to the SBOM. The versioning is based on upload date to Vigiles.

This behavior can be changed anytime by clicking on the product settings and then deselecting "Link all SBOMs in a product based on upload date."

Note: The link option is only available to products, and is not available for "Private Workspace."

SBOMs are linked based on attributes or combinations of attributes for different SBOM types. Linked SBOMs will be ordered by upload date.

Factory: Linked by image
Yocto: Linked by machine and image
Buildroot: Linked by machine and hostname
OpenWrt: Linked by machine and hostname
SPDX: Linked by name and annotator
CycloneDX: Linked by name
CSV: All CSV SBOMs are linked

Import notes/whitelist/custom scores

Notes/whitelist/custom scores entered on any product can be imported into another product. On the Product page, click Import Triage Data and then choose the product to import from the dropdown. If a product does not have anything to import from then it does not show up in the dropdown.

Imports can also be made through a CSV file upload by clicking on Import Triage Data, then choosing from File to import the CSV file containing the triage data.

Valid CSV files must include cve_id, package, and version in the header. The notes header is optional.

Below are both valid examples:

cve_id, package, version, notes
CVE-2018-1000517,busybox,1.19.3,fix this

cve_id, package, version
CVE-2020-8177,curl,7.67.0

If the existing product already has data (e.g., Notes for a CVE), the import feature tries to merge the new data from the import. If there is a conflict (e.g., Both products have differing notes for the same CVE for the same product/version), then the user is prompted to resolve it by either:

  • Cancel Import
  • Keep existing entries (only for the conflict entries, the rest of entries will still be imported)
  • Overwrite entries (only for the conflict entries, the rest of entries will still be imported)

Edit SBOM

Packages in the SBOM can be added/removed/modified using the this feature.

The typical use case is:

  1. A package was updated in the product build and needs to be tracked in the Vigiles SBOM (mostly for BOM CSV and Create SBOM users, since for supported build system users the updated SBOM can be automatically uploaded from the command line)
  2. Tracking packages built outside of your build system and/or hardware CVEs

To Edit a SBOM on the CVE Dashboard page, click on "Edit SBOM" and then click on the "Package Name" or "Package Version" inputs to edit, and then click "Save." Optionally add or delete packages and then click "Save", a summary of changes is shown and a new report is generated.

Note: A new SBOM is created with the same name but if “Link SBOM” is enabled for the product it will show up as the latest version.

Compare SBOMs

This feature is useful to review changes between two different SBOMs (i.e. what changed between builds or even products) in terms of packages/versions/patches and in terms of CVEs. The diff gives:

  • Package summary
    • Changed Packages (version upgrade/downgrade)
    • Added Packages
    • Removed Packages
    • Added Patches
    • Removed Patches
  • CVE summary
    • CVEs addressed from going from old SBOM to new
    • CVEs newly introduced in new SBOM

This is particularly useful when generating release notes for a product that might be required for compliance. Below are different ways to use SBOM comparison:

  • Within a product: On the product page, click on "Compare SBOMs," then select the newer and older versions to compare. By default, the last generated report for the SBOM is selected for CVE comparison.
  • Across products: On the Vigiles dashboard page, click on "Compare SBOMs," select the product, and then select the SBOM. By default, the last generated report for the SBOM is selected for CVE comparison.

CVE Report Alerts

Alerts can be configured by accessing the "Alert Settings" menu item on product and folder pages.
When saving alerts you can choose to apply the settings to just the base product or all folders in the product.

Changes to alerts will take effect during the next report generation.

When enabled, an Alerts section will be added to your CVE reports.
Additionally, you may choose to enable email notifications or the automatic creation of a Jira issue.

CVSS Alerts

On the alert settings page, you can set an alert for CVEs with a CVSS greater than or equal to a user-defined value.

License Alerts

Alerts can be set for whenever specified licenses are found for packages in a SBOM. These alerts can be set for two matching modes:

  • Contains: this will be triggered if any occurrence is found in the licenses for a package.
  • Exact: will only match license if the exact license name is found. This matching mode can be more precise.

For example, the licenses for a package are "BSD & GPLv2+ & LGPLv2+ & PD" and an alert for "GPL" is set.
If the alert is set for contains, the alert action will be triggered. If it is set to exact, it will not be triggered.
However, if an exact alert is set for "GPLv2+", the alert action will be triggered.

The SBOM search page can be accessed by clicking the "Search SBOMs" button in the side navigation.

On this page, you can search by package name and find SBOMs throughout all of your products that contain that package. Filters are available to limit your search:

  • "Only search my SBOMs" checkbox
    • This will filter out any SBOMs that have been shared with you.
  • "Search only the latest SBOM if linked" checkbox
    • This will filter out any SBOMs that are an older version of a SBOM in a product with linking enabled.
  • Package version (optional)
    • Only search for SBOMs which contain this package version.
  • Select product (optional)
    • Only search for SBOMs that are in this product.
  • Select folder (optional)
    • Only search for SBOMs that are in this folder. This requires selecting a product to filter by.

Sharing and team collaboration

Exporting reports

Vigiles supports exporting the CVE report in CSV, XLS and PDF (Summary and Full) formats. On the CVE dashboard page, select “Export Report” and the desired format. The exported report includes any custom notes and whitelists that were added. This can be shared with other non-Vigiles users within your organization.

Share Report

Use case: Share a view-only version of the latest CVE report with anyone who has a Vigiles account. This is particularly useful for sharing a report with others who are not on the same team. A view-only report does not allow the user to: rescan the SBOM, view the SBOM history, use the SBOM editor for this SBOM, or modify notes, whitelist, or any savable filters (e.g., kernel config or u-boot config).

On the CVE Dashboard, click on “Share Report” and then click “Sharing” to generate a “sharable link”. This link will always redirect to the latest version of CVE report for that SBOM. To disable sharing toggle the “sharing” button to "Off."

If a link was previously shared and access to it needs to be revoked, clicking on “Revoke Access” button will invalidate all old share links for that SBOM and generate a new share link.

Teams

Teams are initially provisioned by Timesys upon purchase of Vigiles subscription. Once a team is provisioned, users can manage the teams themselves by using the instructions provided here. Users need to be on the same team in order to collaborate. To check which Users are on the team, click on the corresponding “Account” name under your profile.

Shared products

Sharing a product allows team members to view that product and any SBOMs uploaded it. Team members can also contribute/collaborate by uploading SBOMs, entering notes, whitelisting CVEs, etc.

  • To Share: On the Vigiles Dashboard page under Actions column for a product, click on Share. Optionally users can select a team but this is not a common use case.
  • To Unshare: On the Vigiles Dashboard page under Actions column for a product, click on Unshare on a product you previously shared. If other users have uploaded SBOMs to that product then you are only allowed to Delete the product.
    Note: "Private Workspace" can not be shared with other users.

Integrations

Integrations allow users to communicate with other services beyond those provided by Vigiles. To view available integrations click the Integrations button in the side navigation on any Vigiles page.

Jira Integration

The Jira integration allows creation of an issue from a CVE report.
These issues are tied to the SBOM and will persist on other versions of the SBOM if it is linked.

To get started, enter the email you use for Jira, the domain where your Jira server is located, your Atlassian API token, and the project key where you would like your issues to be created.

For more information on how to generate the Atlassian API token, visit https://confluence.atlassian.com/cloud/api-tokens-938839638.html

Project Keys
Project keys have two scopes: product level and default.
The default project key is the one filled in on the integrations page. A product-level key can be defined within the product settings option in the side navigation of a product. This key will be applied to all SBOMs in the product, including those in folders. Anyone with access to the product can view this key, however, only those with the integration enabled can edit it.

Creating Issues
Once the integration is configured, you are ready to add issues on a CVE report.
Click the Create Issue button next to the notes section. This will create the issue in Jira and link it to this SBOM.

Viewing Issues
You can go directly to the issue using the new View Issue button that replaces the button used to create the issue. These linked issues will persist on rescan and they are visible to those who have the report shared with them. Users viewing a shared report are unable to add or delete issues to the report. When moving or copying a report to another product, issues will be retained.

Deleting Issues
Issues can be deleted using the dropdown on the View Issue button.

The typical workflow for an user after registering for a Vigiles account is as follows:

  1. View the CVE report for the sample SBOM to get familiar with Vigiles
  2. Create a product on the Vigiles Dashboard
    1. Share the product (if part of a team)
  3. Create a folder (and optionally subfolders) for each major release or branch within that product
    1. Example Product Release Structure
      Product: Foo
Folder: Release X.x
Folder: Release Y.y
Folder: Development (Or Master)
    2. This will allow you to maintain a unique SBOM history for each release of your product
    3. By default the SBOM within each folder gets revision controlled (linked) when there is a change in the packages (add/remove/version/patches). If the SBOM content does not change it will just generate a new report.
  4. Upload or create a SBOM in the product
    1. Yocto / Buildroot / OpenWrt/ Factory
      1. Clone the appropriate repository to generate a SBOM
      2. Download a LinuxLink API key
      3. Download a Dashboard config
        1. If you followed the release structure suggested above then download the folder config for your specific release and check it into the appropriate branch.
      4. Specify a subfolder name for dynamic subfolder creation
      5. Run the appropriate command to do a CVE check
    2. BOM - CSV
    3. Create SBOM Wizard
  5. Review the report
  6. Subscribe for notifications
  7. Prioritize vulnerabilities using filters and custom scores
  8. Triage vulnerabilities — add notes/whitelist
  9. Remediate vulnerabilities
    1. Update packages / Backport patches / Mitigate based on Vigiles information
  10. Re-generate the report with the new SBOM
    1. Supported build system users re-run the CVE check from the desktop for auto upload
    2. Others use "Edit SBOM" or "Upload SBOM" actions
  11. Download reports for compliance/release notes

Specify a CVE product

Having the correct CVE product is an important step to ensure you get the most accurate results when scanning a package.
Some package names may be different from the name used to file CVEs against2. If you find that one of your packages was not found in our database you can set the the cve product in your recipe to ensure it is.

Why is my package not being tracked?

Vigiles uses the NVD CPE dictionary for tracking CVEs against package names. If a * is indicated against a package, it means that package does not exist in the NVD CPE dictionary.

Here are some possible reasons why your package might not be tracked:
  1. The package name does not match the name specified in the NVD CPE dictionary in which case the user is supposed to review the packages with * and fix up using the CVE_PRODUCT variable to match it.
  2. The package has no CVEs ever reported and the maintainer of the package has not requested a CPE entry. In which case user can submit a CPE name request to NVD or hope that in the future when a CVE does show up for the package, the CPE name will match the package name in which case Vigiles will report the CVE correctly.
  3. The package is either a proprietary package or a build system artifact in which case it can be safely ignored.

To obtain the correct product name under which a CVE is reported against, use the NIST NVD CPE product dictionary which specifies the CPE1.

Yocto

Use of the variable "CVE_PRODUCT" to set the CVE product to something other that the recipe name.

To set the variable follow the format below:

CVE_PRODUCT = "<cve product name>"

excerpt from the wpa-supplicant recipe in poky to illustrate its use:

CVE_PRODUCT = "wpa_supplicant"

Buildroot

Currently buildroot has not added a standard variable to set cve product. There is an open issue for this and vigiles-buildroot will be updated upon the release of it.

vigiles-buildroot supports use of the variable _CVE_PRODUCT to set the CVE product.

To set the variable follow the format below:

< package name >_CVE_PRODUCT = "<cve product name>"

Footnotes

 

1 Common Platform Enumeration (CPE) is a standardized method of describing and identifying applications, operating systems, and hardware devices maintained by NIST. Package names correspond to the CPE Product field.

2 If a package name is not available, then it is either listed under a different product name or is missing because there are no known vulnerabilities. If it is not yet available, type the name as-is. Any spaces in this field will be converted into hyphens.

3 Here you can also click on "Disable" to disable the filter, or download the configuration the filter is using.

4 SPDX About https://spdx.dev/about/