Vigiles User Guide

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, and Factory.

How does Vigiles work?

Vigiles reports vulnerabilities by analyzing the components in a manifest (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 manifest, there are three options:

  1. Automatic generation: Vigiles directly integrates with build systems (Yocto, Buildroot and Timesys Factory) to generate and upload the software manifest 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 manifest wizard: Vigiles provides a UI where components can be selected to create a Software BOM.

Once the manifest is uploaded/created, Vigiles scans the packages listed in the manifest 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 manifest

To try Vigiles without having to upload your product manifest, a sample manifest 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 manifest 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 manifest 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 manifest 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 manifest” 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 manifest 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 manifest 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 manifest 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 manifest” 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 manifest 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 manifest” on the Vigiles Dashboard page.

 

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

Step 2: Create a BOM CSV file.

Start by clicking on the ‘CVS template' button to get a working CSV template with sample data and then modify it to add your components. A CSV manifest 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 Manifest Wizard

To generate a vulnerability report, follow the steps below:

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

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 manifest gets saved to the “Private Workspace”. To save the manifest 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 manifest/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.

Report interpretation

Once a manifest/Software BOM 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 which are applicable but already addressed
    • Yocto/Buildroot/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 Common Vulnerability Scoring System (CVSS) score greater than 7. The CVSS score (0 to 10 range) is an industry standard which 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 and Buildroot 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 manifest/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 and Buildroot users, the kernel/u-boot config is automatically uploaded by default along with the manifest 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 manifest level, so if a new manifest 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 manifests under that product)
  • Notes do not get lost on rescan or with the upload of a new manifest
  • 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 manifests under that product)
  • Whitelisted status does not get lost on rescan or with the upload of new manifest
  • 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 manifests under that product)
  • Custom scores are not lost on rescan or with the upload of a new manifest
  • 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 manifest 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 manifest/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 manifest. There are 3 ways to inform Vigiles of changes to the manifest:

  1. Running a Vigiles check from the command line automatically results in uploading the latest version of the manifest and generating a new report. Older manifests are still available for viewing/generating reports online.
  2. Use the "Upload manifest" feature on the web to upload the latest manifest
  3. Use the "Edit Manifest" 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, 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 manifests (think of it as automatic manifest revision control) which is enabled by default when a new Product is created. If manifest 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 manifests are uploaded to that product, notifications are sent based on the latest manifest). If linking is disabled (e.g. in the "Private Workspace") then the notification is at manifest level and needs to be subscribed on every new manifest 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 manifests (SBOM)

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

Create Product

On the Vigiles Dashboard, click on “Create Product” and provide a name, then click "Save." This will create a product to which manifests 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 manifests can be uploaded to. This is a way to separate your manifests within the same product. Folders can be nested, and manifest linking is available as a setting in each folder separately.

Upload manifest to a product

Web Upload

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

Alternatively, on the Vigiles Dashboard, when choosing:

  • Upload Manifest: Select the desired product from ‘Select product to upload manifest to' dropdown.
  • Create Manifest: 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 manifest is uploaded to the “Private workspace”. To upload the manifest 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.

Move/Copy manifest

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

On the product page in which the manifest currently exits, under the "action" column, click on "move" and then use the "Select product to move manifest 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 manifest if linking is enabled in the product (see next section)

Vigiles offers linking manifests (think of it as automatic manifest revision control) which is enabled by default when a new Product is created. When a new version of a manifest 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 manifest. 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 manifests in a product based on upload date."

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

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 manifest

Packages in the manifest 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 manifest (mostly for BOM CSV and Create Manifest users, since for supported build system users the updated manifest can be automatically uploaded from the command line)
  2. Tracking packages built outside of your build system and/or hardware CVEs

To Edit a manifest on the CVE Dashboard page, click on "Edit Manifest" 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 manifest is created with the same name but if “Link manifest” is enabled for the product it will show up as the latest version.

Compare Manifests

This feature is useful to review changes between two different manifests (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 manifest to new
    • CVEs newly introduced in new manifest

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

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

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 manifest, view the manifest history, use the manifest editor for this manifest, 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 manifest. 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 manifest 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 manifests uploaded it. Team members can also contribute/collaborate by uploading manifests, 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 manifests to that product then you are only allowed to Delete the product.
    Note: "Private Workspace" can not be shared with other users.

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

  1. View the CVE report for the sample manifest to get familiar with Vigiles
  2. Create a product on the Vigiles Dashboard
    1. Share the product (if part of a team)
  3. Upload or create a manifest in the product
    1. Yocto / Buildroot / Factory
      1. Clone the appropriate repository to generate a manifest
      2. Download a LinuxLink API key
      3. Download a Dashboard config
      4. Run the appropriate command to do a cve check
    2. BOM - CSV
    3. Create Manifest Wizard
  4. Review the report
  5. Subscribe for notifications
  6. Prioritize vulnerabilities using filters and custom scores
  7. Triage vulnerabilities — add notes/whitelist
  8. Remediate vulnerabilities
    1. Update packages / Backport patches / Mitigate based on Vigiles information
  9. Re-generate the report with the new manifest
    1. Supported build system users re-run cve the check from the desktop for auto upload
    2. Others use "Edit Manifest" or "Upload Manifest" actions
  10. Download reports for compliance / release notes

Footnotes

 

1Common 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 in the dropdown, 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.