This page describes how to use the Vigiles/LinuxLink CVE monitoring tools from Timesys with a PetaLinux build environment.

Table of Contents

Introduction

The meta-timesys Yocto layer is a meta-layer provided by Timesys as part of the Vigiles and LinuxLink suite of tools.  Vigiles performs in situ scanning of the software included in a Yocto build during the build and provides detailed information about potential security vulnerabilities.  Vigiles provides an Internet link (in its log file) to the LinuxLink web site where any identified vulnerabilities can be reviewed in detail.

Vigiles (and meta-timesys) can operate in three basic modes – Free, Plus, and Prime.  The Free version of Vigiles provides detailed information about CVE’s including categorization and mitigation suggestions.  The Plus version of Vigiles extends the Free version by including CVE triage collaboration features and enhanced reporting capabilities.  The Prime version of Vigiles includes everything in the Free and Plus editions but extends this to include CVE filtering by KConfig and direct links to the Linux source tree for mitigation commits.

For users building with a native Yocto environment, Timesys provides complete instructions here - https://github.com/TimesysGit/meta-timesys .  This article adapts those instructions for use in a PetaLinux build environment.

Signing Up for a TimeSys Vigiles/LinuxLink Account

Prior to running a PetaLinux build, sign up for a Vigiles account by visiting the Timesys Vigiles web site here: https://www.timesys.com/security/vigiles-vulnerability-management-patch-monitoring/register-prime/  

After registration, you will receive a Vigiles LinuxLink API key.  This key can be located by logging into your LinuxLink account and navigating to the Preferences menu in the upper right.

Open

Open

As noted on the LinuxLink web site, it is imperative to keep this key private so note it and do not share it.  For ease-of-use, the “Download Key File” option will download a copy of the LinuxLink API key file for easier integration into the build flow.

On your Linux build host, create a sub-directory in your $HOME directory called timesys as seen below.

Place the LinuxLink API key file (by default, named “linuxlink_key”) in the timesys sub-directory.  If you require that the linuxlink_key file be stored elsewhere, ensure to update either the $KEY_FILE (environment level) or inside the PetaLinux local.conf file (additional details below).  The format of the linuxlink_key file is shown below.

The API key will be used during the build to unlock the detailed reporting.  Vigiles will still run without the API key but in a more feature-limited Demo mode.

Creating a PetaLinux Project

The PetaLinux project is created using the petalinux-create command.  In this example, we use a PetaLinux BSP for the ZCU102 evaluation board as a source.  If you’re using an XSA or HDF from a custom hardware platform, simply substitute the appropriate PetaLinux syntax.

Fetching the meta-timesys Yocto Layer

PetaLinux allows users to incorporate external community Yocto meta-layers into the standard build process.  To do so, though, you must ensure that the layer is cloned somewhere within the PetaLinux project directory structure.  It is recommended that this be done somewhere that will not be altered automatically by the tools such as <plnx-proj-root>/build or <plnx-proj-root>/images.

For ease of use, this example clones the meta-timesys layer into the <plnx-proj-root>/components/ directory.  Note that <plnx-proj-root>/components/ is ignored when using revision control with PetaLinux. If your project requires revision control, the meta-timesys layer should be cloned into <plnx-proj-root>/project-spec/.The Timesys layer is cloned with a standard git clone command but it is important to specify a specific branch corresponding to the version of Yocto being used with PetaLinux.  Below is a table of PetaLinux versions and their corresponding Yocto codenames.

Adding the meta-timesys Layer to the PetaLinux Build

After cloning the meta-layer it should be added to the project’s build by modifying the project-level configuration with the petalinux-config command with no options.  In the menuconfig, navigate to Yocto Settings --> User Layers.  In the User Layers menuconfig, press <enter> to modify the “user layer 0” option and insert the path where the meta-layer can be found.  It’s important to note that this path will be relative to the project’s root and should start with the special ${PROOT}/ variable for the path.  In this example, since the layer was cloned in the /components/ sub-directory the full path will be ${PROOT}/components/meta-timesys.  You may need to adjust your variable if you cloned the repository to a different location. After adding the path for the meta-layer, exit the project-level menuconfig and return to the terminal prompt.

The second part of adding the meta-timesys layer to your project is to edit the Yocto project configuration file to instruct it to inherit and execute the Vigiles tooling.  This is done by adding the lines below to the #User Configuration section of petalinuxbsp.conf found in <plnx-proj-root>/project-spec/meta-user/conf/petalinuxbsp.conf.  If you want to use meta-timesys with a Vigiles/LinuxLink license key, add the path to the LinuxLink license key as well.

INHERIT = "vigiles"

VIGILES_KEY_FILE = "<HOME_DIR_PATH>/timesys/linuxlink_key"

Running the PetaLinux Build with Vigiles Enabled

After adding the meta-timesys layer to the PetaLinux project as described above, the build can be run like normal using the petalinux-build command.

The build will largely look like a standard PetaLinux build with the exception that Vigiles is run at the very end and will echo terminal information into the console.

During the build, Vigiles may echo some WARNING messages in yellow to the terminal.  This is normal and does not affect the operation of the tool.

Reviewing the Vigiles Report

Once the build is complete, the terminal output from Vigiles references a unique URL that you can use to view the full report on the LinuxLink web site.

The web view of the report is fully hyperlinked and provides useful information about the exact nature of any vulnerabilities as well as details about whether they are local-only exploits or can be executed remotely.

Note: The meta-timesys layer requires an active Internet connection and may not work as expected when operating in a fully off-line mode.

In addition, Vigiles produces an ASCII text version of the report which can be reviewed locally at <plnx-proj-root>/build/vigiles/petalinux-image-minimal/petalinux-image-minimal-<timesamp>-report.txt.

Conclusion

The Vigiles and LinuxLink tools provided by the meta-timesys layer are an easy-to-use entry point to getting rapid feedback on vulnerabilities that may affect your build.  For more information, including sales and support, about Vigiles, meta-timesys, and LinuxLink, please visit Timesys on the web at http://timesys.com

Related Links

• https://www.timesys.com/

• https://github.com/TimesysGit/meta-timesys

• https://linuxlink.timesys.com/docs/wiki/engineering/LinuxLink_Key_File

• https://www.timesys.com/security/vigiles-vulnerability-management-patch-monitoring