Vigiles Enterprise 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 an 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

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 the preferences page 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>. An 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://{your vigiles url}/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 “New 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 the Preferences page 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. An 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 “New 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 the Preferences page 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>-SBOM.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 the Preferences page 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.

 

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

To generate a vulnerability report, follow the steps below:

Step 1: Create an SBOM following the SPDX specification

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

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

 

CycloneDX Software BOM

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

To generate a vulnerability report, follow 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 "New SBOM"

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

 

Software BOM CSV

To generate a vulnerability report, follow the steps below:

Step 1: On the Vigiles Dashboard page click on “CSV”, under "New 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 group."

 

Search CVEs

The “Search CVEs” feature allows searching specific vulnerabilities based on CVE-ID or by package name (software or hardware component) without creating an 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 that 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 an 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 are 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 to suggest remediation.

Vigiles API

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/tree/enterprise
Vigiles CLI documentation: https://linuxlink.timesys.com/docs/vigiles-cli
 
API manual: https://linuxlink.timesys.com/docs/enterprise-vigiles-api-manual

Report interpretation

Once an 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
    • BOM CSV: If the CSV specifies CVE IDs that are fixed
  • High/Critical CVSS (Unfixed): Count of vulnerabilities with a 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.
  • Filtered CVEs: Count of CVEs that are filtered out based on applied filters

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 of 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 that 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.

Filtered CVEs

This section provides insight on CVEs that were filtered out after applying filters. "Reason for filtering" column shows filters that apply to the CVE.

Triaging vulnerabilities

Once the summary is reviewed, the next step is to prioritize and investigate vulnerabilities. Vigiles automatically filters vulnerabilities that do not apply to the product based on features or portions of code that 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 to see vulnerabilities for those packages only.
  • Status: Filter based on status. The typical use case is to filter by Unfixed vulnerabilities.
  • References: Filter based on References. Used to filter CVEs having patches, migrations, or exploits.
  • 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" to show only High and Critical vulnerabilities.
  • Minimum Custom Score: Filter based on a threshold for the user-entered scores/priority.
  • Affected Platforms: Filter based on the affected platform. Used to filter CVEs affecting a particular OS platform.
  • 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 an 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 group level (i.e. a note added for a CVE affecting a package/version shows up on all reports across all SBOMs under that group)
  • Notes do not get lost on rescan or with the upload of a new SBOM
  • Notes can be imported to other groups
  • 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 are 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 group level (i.e. a CVE whitelisted for a package/version shows up “Whitelisted” on all reports across all SBOMs under that group)
  • Whitelisted status does not get lost on rescan or with the upload of new SBOM
  • Whitelists can be imported to other groups
  • 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 group level (i.e. custom score added for a CVE affecting a package/version shows up on all reports across all SBOMs under that group)
  • Custom scores are not lost on rescan or with the upload of a new SBOM
  • Custom scores can be imported to other groups

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 triage, 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.

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":https://{your vigiles url}/cves/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.

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 Groups 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 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 SBOMs (SBOM)

This section provides recommendations on monitoring vulnerabilities in multiple groups, where each group 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

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 Format'

Upload SBOM to a Group

Web Upload

To upload a SBOM to a particular group/subgroup follow:
  1. Click on the group/subgroup
  2. Click "New SBOM" on left side navigation panel
  3. Select the type of SBOM to be uploaded
  4. Click on "Already have a SBOM? You can upload it directly here." to expand the panel
  5. Upload the SBOM

Using SBOM creator

To create an SBOM using SBOM Creator:
  1. Click on the group/subgroup
  2. Click "New SBOM" on left side navigation panel
  3. Click SBOM Creator
  4. Add package name and version and click on "Save" to create an SBOM

Alternatively, on the Vigiles Dashboard, when:

  • Uploading SBOM: Select the desired group from ‘Select group to upload SBOM to' dropdown. Default selection is private workspace.
  • Creating SBOM: Select ‘Other group' from the ‘Save' dropdown and then select the desired group from the ‘Select Group' 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 group, download the associated “Dashboard Config” of the corresponding Group. The Dashboard Config file is located under the “actions” column of the Vigiles Dashboard or under the Group Settings of a particular group 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 an SBOM has already been uploaded to "Private Workspace" or another group and needs to be moved to a different group, use the move or copy SBOM feature.

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

  • 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 groups or other folders.

On the group page in which the folder currently exits, under the "action" column, click on "Move Folder" 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 group. If a folder with the same name already exists in the target location, you will be asked to change 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 linked SBOMs (think of it as automatic SBOM revision control) which is enabled by default when a new Group is created. When a new version of an SBOM with a matching image name is uploaded to that group, 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 the upload date to Vigiles.

This behavior can be changed anytime by clicking on the group settings and then deselecting "Enable SBOM linking in this group"

Note: The link option is only available to groups 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 the 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 group can be imported into another group. On the Group page, click Import Triage Data and then choose the group to import from the dropdown. If a group 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 group 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 groups have differing notes for the same CVE for the same package/version), then the user is prompted to resolve it by either:

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

Edit SBOM

Packages in the SBOM can be added/removed/modified using 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 Report 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 group 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
    • Applied filters

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

  • Within a group: On the group 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 groups: On the Vigiles dashboard page, click on "Compare SBOMs," select the group, 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 the group and folder pages.
When saving alerts you can choose to apply the settings to just the base group or all subgroups and folders in the group.

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 an 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 groups that contain that package. Filters are available to limit your search:

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

Group Management

The Groups feature makes it easier for you to collaborate within teams (internal and external) while allowing you to restrict access on a need basis. The group structure is as follows:

Organization: the highest level of grouping; for example, the entire company (and/or external clients you work with).
Groups: the second highest level of grouping; for example, your division.
Sub-Group: the third level of grouping; for example, your project/product team.
Folders: Organize/manage SBOMs within folders; for example, a product release folder.

Members of the organization can be added to multiple groups or subgroups based on the desired level of access

Organization

An Organization is the topmost group. Once a new instance of the Enterprise edition is set up, the admin user can log in and create an organization from the top right-hand side of the navigation bar.
Once an Organization is created, an admin can add users to it.

Groups

Groups are next in the hierarchy. These can be created from the Vigiles Home page (endpoint: /groups), by clicking "Create Group" on the left side navigation bar.
A default group named "Private Workspace" is automatically created for each user which is only accessible to that user.

Subgroups

Subgroups can be created from the Groups page (endpoint: /groups/<group_token>), by clicking the "+" icon on the Subgroups panel next to the side navigation bar or by clicking "Create Group" on the side navigation bar.
A subgroup can be created within another subgroup by first selecting a location in the Subgroups panel on the left and then creating a new subgroup.

Folders

Folders can be created inside Groups, subgroups as well as other folders. These can be created from groups page (endpoint: /groups/<group_token>), by clicking "+" dropdown icon on SBOM sub-section and selecting "New Folder".

Member Management

Members and their roles can be edited from the Members page. To access this page, first, select the desired group/subgroup from the groups dashboard and then click the "Members" button on the side navigation bar.

Add/Remove members in an organization

Only admins can add/remove members from organizations.

To add a member to an organization:
  • Switch to the desired organization by selecting it from the dropdown in the top navigation bar
  • Click Organization members from sidenav on Vigiles home (endpoint: /groups)
  • Select the user from dropdown in Add members subsection (endpoint: /groups/<group_token>/members)
  • Select the role that the new user should have for this group and click "Add user"

Added members can be viewed in the "Current Members" sub-section.

To remove a member from an organization, click on the remove icon in the action column of the table in the "Current Members" sub-section

Add/Remove members in a group/subgroup

Users can add/remove the members in groups only if the user is given "Maintainer" privileges for the current group

To add a member to group:
  • Click "Members" in the sidenav on the groups home page(endpoint: /groups/<group_token>)
  • Select the user from dropdown in Add members subsection (endpoint: /groups/<group_token>/members)
  • Select the role user should have for this group and click "Add user"

Change member role

Members are assigned a role while adding users to the group, which can be changed later on the Members page.

To update member's role:
  • Go to the Members page for the group
  • Select the role for the member user in the role column of the "Current Members" sub-section.
  • Changes will be saved automatically

Add/Remove

Groups can be added/removed by a user with "admin" or "Maintainer" privileges

Add/remove an organization

Organization can be added/removed only by an admin user.

To add an organization:
  • Click on the organization name on the top right navigation bar as an admin user
  • Click "+ New.." to create a new organization
To remove organization:
  • From the top right navigation bar go to the Admin dashboard.
  • Click on the "X" icon to remove an organization

Add/remove group

Group can be added/removed by a user with "Maintainer" privileges for the group

To add a group:
  • On Vigiles home page click "Create Group" link on the left side navigation bar
To remove group:
  • On Vigiles home page click the "X" icon on the actions column in the Groups table.

Add/remove subgroup

A subgroup can be added/removed by a user with "Maintainer" privileges for the subgroup

To add a subgroup:
  • On the groups dashboard click the "+" icon on the subgroups subsection
To remove a subgroup:
  • On the groups page click "..." against the subgroup to be removed on the subgroups subsection
  • Select "Delete Subgroup" from the dropdown.

Add/remove a folder

To add a folder:
  • Select a subgroup if you would like to create a folder there
  • Click "+" dropdown icon on SBOM subsection
  • Select the New Folder option from the dropdown
To remove folder:
  • On Groups Dashboard click "..." against the folder to be removed.
  • Click "Delete Folder" from the dropdown.

Single Sign-on (SSO)

Companies that use identity management systems can leverage SSO, and have employees sign in to Vigiles using their corporate identity. This facilitates easy provisioning of Vigiles to users. Vigiles Enterprise currently supports Azure AD and Okta as Identity Providers (IdP) for SAML SSO.

To use this feature set flag "enabled" to True in [SSO] section of your Settings.ini file

Role-Based Access Control

Vigiles Enterprise provides four different types of members/users:
1. Admin
2. Maintainer
3. Developer
4. Guest

A user assigned the Guest role has the least permissions, and a user assigned the Admin role has the most.

The Guest, Developer, and Maintainer role are all assigned at the group level, while the Admin role is site-wide. Only users with the Admin role can manage the Vigiles instance, organizations, and users.

Permissions

The following table describes the permissions granted by each role.

Action Guest Developer Maintainer Admin
Organization Management ✓
Create Groups ✓ ✓
Move Groups ✓ ✓
Rename Groups ✓ ✓
Delete Groups ✓ ✓
Change Group Settings ✓ ✓
Product Management ✓ ✓ ✓
Upload SBOM ✓ ✓ ✓
Download SBOM ✓ ✓ ✓ ✓
Generate CVE Report ✓ ✓ ✓
Use Notes ✓ ✓ ✓
Use Filters ✓ ✓ ✓
View Vigiles Pages ✓ ✓ ✓ ✓
View Docs ✓ ✓ ✓ ✓
View Reports ✓ ✓ ✓ ✓
Export Reports ✓ ✓ ✓ ✓
Search CVES ✓ ✓ ✓ ✓
Compare Manifests ✓ ✓ ✓
Access Jira Integration ✓ ✓ ✓
Alert Settings ✓ ✓ ✓
Import Triage Data ✓ ✓ ✓
Search SBOMs ✓ ✓ ✓
View SBOM History ✓ ✓ ✓
Add/Remove Users to/from Groups ✓ ✓
See Users in Group ✓ ✓
Add/Remove Users from Vigiles ✓
Edit Vigiles Instance Settings ✓
Access Vigiles API ✓ ✓ ✓

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.

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 the 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: group level and default.

The default project key is the one filled in on the integrations page. A group-level key can be defined within the group settings option in the side navigation of a group. This key will be applied to all SBOMs in the group, including those in subgroups and folders. Anyone with access to the group 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 to 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 Admins, Maintainers, and Developers. When moving or copying a report to another group, issues will be retained.

Deleting Issues

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

The typical workflow for a user after the initial account setup by the admin is as follows:

  1. View the CVE report for the sample SBOM to get familiar with Vigiles
  2. Create a group or subgroups on the Vigiles Dashboard
    1. Adding members to group or subgroup to share content
  3. Create a folder (and optionally subfolders) for each major release or branch within that product
    1. Example Release Structure
      Group: 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 an SBOM in the group
    1. Yocto / Buildroot / OpenWrt/ Factory
      1. Clone the appropriate repository to generate an 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 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 the 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 cve-product name under which a CVE is reported against, use the NIST NVD CPE product dictionary which specifies the CPE1.

Yocto

Use the variable "CVE_PRODUCT" to set the CVE product to something other than 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 a CVE product. There is an open issue for this and vigiles-buildroot will be updated upon the release of it.

vigiles-buildroot supports the use of the variable "CVE_PRODUCT" to set the CVE product to something other than the recipe name.

To set the variable follow the format below:

CVE_PRODUCT = "<cve product name>"

Admin Dashboard

The Admin Dashboard is available only to Admins. This dashboard allows for both user and organization management.

Organizations

This page shows a list of all organizations. This page provides links to the organizations as well as the ability to rename and delete them.

Users

This page shows a list of all users and their status. Their status of Admin or Regular can be toggled here.

Register User

Admins can add new users from this page.

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/