Skip to content

Vigiles User Guide

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. It also offers a comprehensive vulnerability lifecycle management solution, covering Discovery, Prioritization, Triaging, Remediation, Compliance, and ongoing Monitoring and Alerts.

Vigiles is optimized for embedded Linux systems and readily integrates into build systems such as Yocto, Buildroot, OpenWrt, and Factory. Already have an SBOM? Vigiles also accepts SPDX and CycloneDX SBOM files.

Why Vigiles?

Superior vulnerability data

  • Timesys curated data (up to 40% improvement over NVD, fewer false positives)
  • Multiple vulnerability feeds for better coverage

Optimized for embedded systems

  • Linux kernel and u-boot configurations 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 and 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, status
  • Links to applicable patches and recommends minimum version upgrades with relevant fixes

End-to-End workflow support

  • Team collaboration and sharing
  • Powerful and convenient comparison capability for info 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.

How Does Vigiles Work?

Vigiles works by following a workflow of Discovery, Triaging, Remediation and Monitoring allowing you to secure your SBOM now and in the future.

Discovery

Discovering what vulnerabilities are contained within your SBOM is the first feature of Vigiles. This is done by uploading your SBOM either with a file upload or using one of our plugins to integrate with a build system and running a vulnerability scan. During the scan, Vigiles checks for vulnerabilities associated with each component in your SBOM, matching them by package name and version.

Triaging

Figuring out what vulnerabilities should be addressed first is the next step in Vigiles. This is partially done automatically, by obtaining the CVSS3 for a vulnerability that you can use to quickly rank the severity of said vulnerability. Vigiles allows you to take it a step further by providing you the ability to set custom scores, create Jira issues for the vulnerability, and filter out vulnerabilities based on several characteristics. Furthermore, you have the ability to set the status of packages and vulnerabilities based on their relevancy in your SBOM.

Remediation

Timesys offers a service that will maintain and remediate vulnerabilities in your build system for you called BSP Maintenance, but Vigiles will provide you with various suggestions on how to remediate these vulnerabilities on your end. After remediation has taken place and you have uploaded a new version of your SBOM, Vigiles will display the differences in SBOM comparisons

Monitoring

To keep your SBOM secure and compliant in the future, Vigiles offers features to schedule automatic vulnerability scans and the ability create compliance polices based on license name and CVSS3 score. Timesys also offers the Vigiles CLI that you can use to better integrate Vigiles into your technological ecosystem.

Brief Overview of Vigiles Features

Build System Integration

Vigiles offers direct integration with build systems such as Yocto, Buildroot, OpenWrt, and Timesys Factory, to generate and upload the SBOM to Vigiles. This is accomplished by cloning the repo corresponding to your build system, acquiring a Vigiles API key from your Vigiles profile page, under the API key header, and following the documentation provided for Timesys Factory, Vigiles OpenWrt, Meta Timesys (Yocto builds), and Buildroot

SBOM Management

  • SBOM Dashboard: A dedicated page to show details and characteristics of your SBOM
  • Editing: The ability to add, remove, or modify existing packages found within your SBOM
  • Conversion: Change the format of one SBOM to another (i.e. CycloneDX to SPDX)
  • Comparison: Compare any two SBOMs to one another, seeing differences in packages and vulnerabilities.
  • Linking: Link a group of SBOMs together based on image, machine, or hostname.

Vulnerability Reports

  • Vulnerability Report Generation:
    • 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, for hosted instances of Vigiles. The curation and feed updates must be performed manually for on premises solutions. 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 or curates vulnerability information as needed.
  • Report Exporting: Vigiles can export reports in multiple formats, including PDF, XLSX, and CSV, for compliance and monitoring purposes.
  • Report Comparison and Metrics: Compare any two reports and see the changes in the vulnerabilities across time in the SBOM history page
  • Scheduled Scans: Choose between Monthly, Weekly or Daily automatic scans for any new changes in the Vulnerability Status of your SBOM
  • Compliance Settings: Vigiles will display alerts if your SBOM contains vulnerabilities with a CVSS score or greater of your choosing. Other compliance settings such as license policy alerts and new package alerts are handled in the SBOM Dashboard

Group and User Management

  • Group structures Create structures using organizations, groups, subgroups and folders, to better organize products and releases
  • Role-Based Permissions Assign members of groups to specific roles that fill various niches, according to their permissions.
  • Single Sign-on SSO integration with Okta

Below is the recommended workflow for a new Vigiles user.

  1. Create a new group (and optionally subgroups, folders, or 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 (SBOM Linking) when there is a change. This change could be: adding or removing patches, modifying versions, or adding or removing packages. Even if the SBOM content does not change it will still generate a new report.
  2. Upload or create an SBOM in a previously created group
    1. Yocto / Buildroot / OpenWrt/ Factory
    2. SBOM File Upload
    3. SBOM Creator
  3. Review the report
  4. Subscribe your SBOM to Automatic Scans
  5. Set a Compliance policy for SBOMs found within your group
  6. Prioritize vulnerabilities using filters and custom scores
  7. Triage vulnerabilities — add notes/update status
  8. Remediate vulnerabilities
    1. Update packages / Back port patches / Mitigate based on Vigiles information
  9. 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
  10. Download reports for compliance and release notes

Getting Started with Vigiles

Vigiles reports vulnerabilities by analyzing the SBOM's components against a Timesys curated vulnerability database. To generate the SBOM, there are three options:

  1. Automatic Generation with Provided Plugins: Directly integrate with build systems such as Yocto, Buildroot, OpenWrt, and Timesys Factory, to generate and upload the SBOM to Vigiles. Vigiles provides in-depth guides to all of our plugins on their respective GitHub Pages, with locally hosted versions in the links below
  2. SBOM File Upload (manually or externally generated)
    • Supported SPDX SBOM file types: Tag/Value, JSON, XLSX, XLS, RDF/XML, YAML, XML
    • Support CycloneDX SBOM file types: JSON, XML
  3. SBOM Creator: A Vigiles UI where components can be selected to form an SBOM.

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

Timesys Factory

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

Step 1: Clone and setup Timesys Factory as documented here

Step 2: Download an API key from your Vigiles Profile page, under the API Key header, by clicking on the three dots in the 'Actions' column in the relevant organization's row. And store it at this location on your machine

/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 Vulnerability report. To do so, click on Factory under “Upload SBOM” on the Vigiles Dashboard page.

SBOM File Upload

Build Systems

Any SBOM that can be uploaded using build system tools can also be uploaded manually if you have the corresponding SBOM file. Vigiles supports all SBOM file formats generated by any of the listed build systems.

Step 1: Get your SBOM file from one of the previous build systems

Step 2: On the Vigiles Dashboard page click on "Upload", under "New SBOM"

Step 3: Upload the file.

SPDX SBOM

SPDX Versions and file types Supported
Version 2.2 2.3
File Types Supported SPDX, JSON, XLSX, XLS, RDF/XML, YAML, XML SPDX, JSON, XLSX, XLS, RDF/XML, YAML, XML
Documentation Documentation Link Documentation Link
SPDX Fields 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 vulnerability report.

When searching for vulnerabilities for a given component, SBOMs may contain multiple package definitions. Vigiles scans the following:

  1. CPE
  2. Package name and version
Generate Report

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 "Upload", under "New SBOM"

Step 3: Upload the SPDX file.

CycloneDX SBOM

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

CycloneDX versions and file types supported
Version 1.1 1.2 1.3 1.4 1.5 1.6
File types and Documentation XML JSON, XML JSON , XML JSON, XML JSON, XML JSON, XML
CycloneDX Fields 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 Vulnerabilities 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 vulnerability report with id having priority. If a url is provided, a link be included in the Vulnerability report.

Patches (optional):

Patches can be included in an SBOM to automatically mark vulnerabilities as "Fixed" in Vigiles reports. These vulnerabilities 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 - Vulnerability ID
Generate Report

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 "Upload", under "New SBOM"

Step 3: Upload the CycloneDX file.

CSV SBOM

To generate a vulnerability report, follow the steps below:

Step 1: Create a BOM CSV file.

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

Start by downloading the "CSV template to get an SBOM with sample data and then modify it to add your components. A CSV SBOM consists of the following fields:

  • Package — the CPE Name (product field) that packages use when reporting CVEs
  • 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) Not Affected CVEs — a space-separated list of CVE IDs to be ignored, listed as "Not Affected" in the report
  • (optional) Notes — any additional information relevant to the CVE

CSV Example (simple):

package version
busybox 1.19.3
linux kernal 4.18.21

CSV Example (advanced):

package version patch not_affected
busybox 1.19.2
glibc 2.28 CVE-2016-10739 CVE-2019-7309
linux kernal 4.18.21 CVE-2018-16880 CVE-2019-9003 CVE-2016-8660

Step 3: Upload the CSV file.

Using the SBOM Creator

Step 1: On the Vigiles Dashboard page click on “New SBOM” and select Generate

Step 2: On the open modal select "SBOM Creator" and click the "Create" button

Step 2: Select components present in your product.

  • Step 2a: Start by clicking the "Package Name" input

  • Step 2b: Type in your package name and click "Add Package"

    • Note: the "Package Version" information is optional, and leaving it blank will report all vulnerabilities for that package.

Step 3: When you are done adding packages, click "Save".

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."

Vigiles API

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

Download the Vigiles CLI

CLI documentation

Vulnerability Reports

Once an SBOM is uploaded, Vigiles automatically generates a Vulnerability report and redirects to the SBOM Dashboard page. This page is useful for seeing a high-level overview of the SBOM's components, triaging vulnerabilities, offering remediation steps, monitoring compliance policies applied to the SBOM, and generating vulnerability reports. The Vulnerability report page is the primary avenue at which you will interact with the several security features that Vigiles has to offer.

Navigation to the Vulnerability report page can be done via the group dashboard by clicking the "Latest" button in the row of the relevant SBOM, or by clicking the same button in the SBOM Dashboard header.

For an in-depth explanation as to all the vulnerability report page has to offer, and how to navigate around it, see: the Vulnerability Report Documentation

Vulnerability Report History

You can also view previous reports by clicking the "View History" menu item on the latest vulnerability report's sidebar and selecting the vulnerability report you want. The historical vulnerability reports are labeled with the time at which they were scanned and ordered from newest to oldest. The graph will also give you a summary of changes to the vulnerability reports vulnerabilities, detailing the number of Unfixed and Fixed vulnerabilities between reports.

Search Vulnerabilites

The “Search Vulnerabillites" feature allows searching specific vulnerabilities based on vulnerability ID, package name, or description without creating an SBOM. The vulnerability information reported is from the Timesys curated database. To begin:

Step 1: Click the "Search" dropdown menu item on the Vigiles Dashboard's side menu, and select the "Vulnerabilities" item

Step 2: In the "Search By" header, you can choose between Package, Description or vulnerability ID from the dropdown

Step 3:

  • Package Search: Type in your Package name and optional package version.
  • Description Type in your search text, and select an ecosystem to search against. You can also include similar results increasing the result count based on similar words
  • Vulnerability ID Enter the vulnerability ID you wish to search by.

Managing SBOMs

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

SBOM Dashboard

The SBOM Dashboard is another helpful tool that you can use to get a better understanding of your SBOM. This page offers:

  • A searchable list of SBOM components
  • SBOM info such as File type and SBOM Engine
  • Build system info
  • A section that details any compliance violations that you have set on your SBOM
  • A brief overview of vulnerability counts, version numbers
  • The SBOM Token which can be used for CLI and API commands.

Navigation to the SBOM Dashboard can be done via the group dashboard and by clicking on the SBOM name under the "Name" column. You can also click on the SBOM name found in the header of its vulnerability report page to navigate there.

For an in-depth explanation of the SBOM Dashboard, and how to navigate around it, see: the SBOM Dashboard Documentation

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 in the "Group Settings" menu item on the Group Dashboard sidebar menu, or under the "Actions" column of the Group Dashboard in the row of the corresponding group. Once the file is downloaded, specify the path in your Yocto, Buildroot or Vigiles CLI configuration. Refer to the README files of Yocto, Buildroot Vigiles CLI 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

You can move and copy an SBOM to different groups. This is particularly helpful if the SBOM has been uploaded to a user's "Private Workspace".

On the group page in which the SBOM currently exists, under the "action" column, click on "Move SBOM" and then use the "Select group to move SBOM to" dropdown to select a different group. You can also specify the folder using the "Select folder to move SBOM to" field.

  • Selecting “Copy” results in a copy of the SBOM being added to the group instead of moving.
  • Selecting “Include previous versions” results in a copy or move of all versions of that SBOM if linking is enabled in the group

Move/Copy folder

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

On the group page in which the folder currently exists, 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 Compliance Policy" will copy the compliance policy of the copied folder if it is set

Linking SBOMs

Vigiles can link SBOMs (similar to 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, hostname, or machine (SBOM type dependent) is uploaded to that group, it automatically hides and 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 order is based on the upload date to Vigiles.

This behavior can be changed anytime by clicking on the group or folder 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."

Linking behavior

SBOMs are linked based on attributes or combinations of attributes for different SBOM types.

  • 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, status, and custom scores

Notes, status, or custom scores entered on any group/folder sbom chain can be imported into another sbom chain. On the Group page, click Import Triage Data and then choose the entry type to import in the dropdown. If a group/folder/SBOM chain does not have any entries, then it will not show up in the dropdown.

Imports can also be made through a CSV file upload by clicking on Import Triage Data, and 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, and will set status Not Affected in any vulnerabilities with data in this column.

Below are both valid examples:

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

With Notes Example: Documentation Link

cve_id package version
CVE-2020-8177 curl 7.67.0

Without Notes Example: Documentation Link

If the existing sbom chain 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 sbom chains 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

Using this feature, packages in the SBOM can be added, removed or modified.

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 supported build systems can upload the updated SBOM automatically from the command line)
  2. Tracking packages built outside your build system and/or hardware CVEs

To Edit an SBOM on the vulnerability report page:

  1. Click on "Edit SBOM"
  2. Click on the "Package Name" or "Package Version" inputs to edit,
  3. You can also add or delete packages by clicking the "Add Package" button or clicking the 'X' in the far right column.
  4. Then click "Save."
    • A summary of changes will be shown, and a new report generated. A new SBOM will be created with the same name and if “SBOM Linking" is enabled for the group, and will show up as the latest version.

CycloneDX SBOMs have an additional required field: Package Type

Compare SBOMs

This feature is useful to review the changes to packages, versions, and patches between two different SBOMs (i.e. what changed between builds or even products). It is divided by changes in packages and changes in vulnerabilities. Changes in packages will detail if a package has been added, removed or its version has been changed. Changes in vulnerabilities will show if vulnerabilities have been removed, new vulnerabilities added, or the status of the vulnerability has been altered.

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.

Converting or Downloading SBOMs

Vigiles offers the ability to convert and download SBOMs of one format to another (i.e. Yocto JSON to CycloneDX XML). This conversion will, at a minimum, preserve vital SBOM component information such as: Package Name, Version, Licenses and CVE Patches. However, most conversions will preserve as much data as possible depending on the compatibility between SBOM fields (i.e. Due to no SPDX equivalent to CycloneDX's "Package Type", that field will be omitted when performing a CycloneDX to SPDX conversion.). There is also the ability to download the original format of the SBOM, rather than a conversion.

To access the download modal either press the "Download" button in the SBOM Dashboard header or the "Download SBOM" menu item in the vulnerability report sidebar. From here you will be given a choice of Original, SPDX, SPDX Lite, and CycloneDX. All formats except for "Original" will also have a dropdown to select the version of the file.

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. You can also filter the search by entering a package version, selecting a group to search in, selecting a folder to search in or only searching the latest SBOM in an SBOM Linkage

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 or navigate to the Integration tab on your Vigiles Profile.

Jira Integration

The Jira integration allows the creation of a Jira issue from a Vulnerability 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 to log into 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://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/

Project Keys

Project keys have two scopes: group level and default.

The default project key will be filled in on the integrations page. A group-level key can be defined within the group settings option in the sidebar of the 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 will be able to generate Jira issues from a Vulnerability report.

Navigate to the vulnerability section of the vulnerability report, and click the dropdown to expand the vulnerability child row. From here, 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 Organization 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.