2.1. Requirements

The cvechecker tool requires the following packages to be installed:

• libxslt - needed for the XSLT transformations (the online CVE database exists of XML files and we need to convert those to CSV so that we can easily import it into our own, local database)

• libconfig - a C library that offers a simple way for applications to read and handle configuration files

• a database or database client. Currently, cvechecker supports:

  • sqlite3 - a local, embedded yet powerful database

  • mysql (through libmysql) - one of the more popular open source databases

• wget - a command-line tool to fetch online resources

2.2. Installation

If your distribution already offers cvechecker through its package management system, I strongly advise that you use that. The installation instructions in this section assume that you do the installation manually (and should reflect the steps that the distribution package management system does for you).

First, download the latest cvechecker package from http://cvechecker.sourceforge.net (or http://sourceforge.net/projects/cvechecker/files/), then extract it into a temporary directory:

~$ tar xvzf cvechecker-1.O.tar.gz

You need to select the database you want to use. cvechecker currently supports mysql and sqlite, and this support is enabled through the ./configure --enable-sqlite3 or ./configure --enable-mysql options. You can select both too (they are not mutually exclusive) but you need to select at least one of them.

Inside the extracted folder, first run ./configure with the proper --enable-<database> options, followed by make and make install. If you use the default settings, it will install the files inside /usr/local, so you might need root privileges to perform the make install step.

~$ cd cvechecker-1.0
~$ ./configure --enable-sqlite3 
...
~$ make
...
~$ sudo -i
~# make install

Finally, create a group called cvechecker and change the permissions of the installed folders so that this group has write privileges inside the directory. These steps are performed when executing make postinstall (you almost definitely need root privileges now):

~# make postinstall

2.3. Initial Configuration

With the software now installed, you need to perform an initial configuration. This includes the setup of the databases, creation of the user you are going to use to run cvechecker and initial pull of the CVE entries from the Internet.

First, create a user that you will use to run cvechecker. The tool does not require root privileges, so I recommend not to use root. I personally use a dedicated user whose sole purpose is to, on a daily basis, pull the latest updates from the Internet, generate a report and mail that report to me. Make sure that this user is inside the cvechecker group:

~# gpasswd -a youruser cvechecker

Log on as that user, make sure his primary group is cvechecker and set the umask to 002 or higher (such as 007).

~# su youruser -
~$ newgrp cvechecker
~$ umask 007

Now, initialize the databases by running cvechecker -i. This will create the sqlite3 databases or, if MySQL is selected, create the appropriate tables and indexes in the selected MySQL database (the tool does not create a MySQL database itself).

~$ cvechecker -i

#
# Generic settings
#
dbtype = "mysql";
#dbtype = "sqlite3";
cvecache = "/var/lib/cvechecker/cache";
datadir = "/usr/share/cvechecker";
stringcmd = "/usr/bin/strings -n 3 '@file@'";
version_url = "http://cvechecker.svn.sourceforge.net/viewvc/cvechecker/versions.dat";
#userkey = "servertag";

#
# For SQLite3
#
sqlite3: {
  localdb = "/var/lib/cvechecker/local";
  globaldb = "/var/lib/cvechecker/global.db";
};

#
# For MySQL
#
mysql: {
  dbname = "cvechecker";
  dbuser = "cvechecker_rw";
  dbpass = "passwordforcvechecker_rw";
  dbhost = "mysql.company.com";
};

~# cvechecker -i

~# cvechecker -i

~$ pullcves pull

2.4. Upgrades

cvechecker tries to detect if its back-end was created with an earlier version of cvechecker and update the back-end accordingly. For sqlite3 databases, this usually isn't a problem as the tool has the rights to add tables and indexes when needed.

However, when using MySQL databases, it is very likely that the user you use is not authorized to update the back-end. To fix this, first run cvechecker on the administrative host (where a more privileged MySQL account can be used). It will update the back-ends for all users as well. When new(er) versions are made available, we will also add the necessary upgrade SQL scripts to launch so that you do not have to run cvechecker with a database owner account.

3.1. Pull Data

To pull the necessary data from the Internet, run pullcves pull:

~$ pullcves pull

3.2. Generate List of Files

cvechecker uses a text file which sums up the files to scan. I recommend that you provide it with a list of all executables files plus /proc/version (on Linux). The latter allows cvechecker to verify if there are kernel-related CVE entries for your Linux kernel.

~$ find / -type f -perm -o+x > scanlist.txt
~$ echo "/proc/version" >> scanlist.txt

It is strongly advised to either umount or exclude file systems on which no useful files are located (or that belong to different operating systems, like a mounted Windows partition). You can use the -mount (or -xdev) option of find to stay within the selected device (partition), or exclude directories (and their subdirectories), like so:

~$ find / -path /mnt -prune -o -path /media -prune -o -type f -perm -o+x > scanlist.txt 

3.3. Gather List of Installed Software/Versions

Import the generated scanlist.txt file in cvechecker. During the import, cvechecker will output the software/versions it detected:

~$ cvechecker -b scanlist.txt

~$ cat /etc/portage/bashrc
if [ -x "/etc/portage/bashrc.d/package.${EBUILD_PHASE}" ];
then
  source "/etc/portage/bashrc.d/package.${EBUILD_PHASE}"
fi

~$ cat /etc/portage/bashrc.d/package.prerm
TMPFILE=$(mktemp);
[ ! -f "${TMPFILE}" ] && die "Cannot create temporary file.";
qlist ${CATEGORY}/${P} > "${TMPFILE}";
cvechecker -D -b "${TMPFILE}";
rm "${TMPFILE}";

3.4. Output Matching CVE Entries

Make cvechecker output the matching CVE entries. A standard output might look like this:

~$ cvechecker -r
File "/usr/bin/kbxutil" (CPE = cpe:/a:gnupg:gnupg:2.0.15:::) on host localhost (key localhost)
  Potential vulnerability found (CVE-2010-2547)
  Full vulnerability match (incl. edition/language)
File "/usr/bin/gpgsm" (CPE = cpe:/a:gnupg:gnupg:2.0.15:::) on host localhost (key localhost)
  Potential vulnerability found (CVE-2010-2547)
  Full vulnerability match (incl. edition/language)
File "/usr/bin/watchgnupg" (CPE = cpe:/a:gnupg:gnupg:2.0.15:::) on host localhost (key localhost)
  Potential vulnerability found (CVE-2010-2547)
  Full vulnerability match (incl. edition/language)

However, if you would like to parse the output so that you can generate a better-looking report, ask cvechecker to use CSV output:

~$ cvechecker -r -C
Outputversion,File,CPE,CVE,Matchtype,Hostname,Userkey
2,/usr/bin/kbxutil,cpe:/a:gnupg:gnupg:2.0.15:::,CVE-2010-2547,1,localhost,localhost
2,/usr/bin/gpgsm,cpe:/a:gnupg:gnupg:2.0.15:::,CVE-2010-2547,1,localhost,localhost
2,/usr/bin/watchgnupg,cpe:/a:gnupg:gnupg:2.0.15:::,CVE-2010-2547,1,localhost,localhost

The default behavior of cvechecker is to only report on those CVEs who specifically target the software and version you have installed. However, you might want to be informed about software matches for CVEs that affect higher versions than the versions installed on your system. Not all CVEs contain a full list of all versions affected but rather mention only the highest version vulnerable. The default reporting within cvechecker wouldn't be triggered when this is the case, but if you add -H or --reporthigher, cvechecker will also report on higher versions.

3.5. (Optional) Generate A Report

You can use the cvechecker output to generate a report. Within the cvechecker distribution, sample reporting files are available that show you a simple method. Of course, reporting is not part of this tools' goals; the primary purpose of this step is to show you that the output can indeed be used for reporting purposes. To facilitate (simple) reporting, a cvereport script has been provided which uses the sample reports currently. In the future, this will be enhanced with distribution-specific checks.

~$ cvereport -d /home/john/cvereport-20100902/ /home/john/cvechecker/acknowledgements.xml

The default report will use the default cvechecker report. If you want to report using higher version matches as well, use -D instead of -d.

Below is a sample acknowledgements XML file. Its use should be self-explanatory:

<?xml version="1.0" encoding="UTF-8"?>
<acknowledgements>
  <!-- I chose to use the CVE number as id for the resolution/comment text, but this is not mandatory -->
  <resolution id="CVE-2008-4101">Has been solved by security update #17 (vim-1.7-b3)</resolution>
  <comment id="CVE-2010-2547">Under investigation, bug opened on distributions bug site (#332329)</comment>
  <!-- The @comment or @resolution should refer to one of the above descriptions. 
         Its use however is optional (you don't need to give comments) -->
  <file name="/usr/bin/kbxutil" cve="CVE-2010-2547" state="acknowledged" comment="CVE-2010-2547" />
  <file name="/usr/bin/vim" cve="CVE-2008-4101" state="irrelevant" resolution="CVE-2008-4101" />
</acknowledgements>

The final document (report.html) can then be mailed, published or in any other way sent to you.

If the report shows new CVE entries matching your system, investigate those CVE entries by first acknowledging and, if necessary, either update the software on your system or mark the entry as irrelevant.

6.1. Configuration File Format

The cvechecker configuration file currently requires 6 configuration items:

#
# Generic settings
#
dbtype = "mysql";
#dbtype = "sqlite3";
cvecache = "/var/lib/cvechecker/cache";
datadir = "/usr/share/cvechecker";
stringcmd = "/usr/bin/strings -n 3 '@file@'";
version_url = "http://cvechecker.svn.sourceforge.net/viewvc/cvechecker/versions.dat";
#userkey = "servertag";

#
# For SQLite3
#
sqlite3: {
  localdb = "/var/lib/cvechecker/local";
  globaldb = "/var/lib/cvechecker/global.db";
}

#
# For MySQL
#
mysql: {
  dbname = "cvechecker";
  dbuser = "cvechecker_rw";
  dbpass = "passwordforcvechecker_rw";
  dbhost = "mysql.company.com";
};

These items describe the following resources:

• dbtype tells the cvechecker application which back-end to use. Currently, "sqlite", "sqlite3" and "mysql" are supported (sqlite and sqlite3 result in the same back-end)

• cvecache is a (cvechecker writeable) directory where pullcves will download all XML files and store the transformed XML2CSV files (containing the CVE entry data). Although it is not used anymore after being imported into the local databases, pullcves relies on the availability of the XML files to find out if it needs to (re)download and import CVE entries. So if you want to clean out the directory, make (empty) files named after the XML files so that pullcves does not redownload and reimport the CVE entry data (not that this will render the application unusable, but it takes a while)

• datadir is a directory where cvechecker-related files are stored, including the XSLT transformation files used to convert CVE XML files in CSV files as well as the sample reporting files as used in this document

• stringcmd is the command that cvechecker launches against a file to get the files' content. Currently, this is the only supported method for cvechecker to identify the software/version.

• version_url is the location where pullcves can find the latest software/version matching rules to identify installed software on the system.

• userkey is an optional setting which is used for server-side RDBMS support. When set, the data is stored with this particular key (next to the systems' hostname) as owner. This allows for multiple cvechecker runs on the same system (hostname + userkey) with different usages, but also to map cvechecker runs in larger organizations with that systems server tag/serial number/asset tag.

  If not set, userkey is set to the hostname of the system (so data is owned by "hostname + hostname").

• sqlite3: combines all sqlite specific settings, which are:

  • localdb is a (cvechecker writeable) directory where cvechecker will store its sqlite3 databases containing the CPE data (identification information of software/versions) as well as the local systems' matching file/software pairs and all downloaded CVE entries

  • globaldb is a (cvechecker writeable) sqlite3 database containing the software/version matching rules and CPEs associated with these rules

• mysql: combines all mysql specific settings, which are:

  • dbname is the name of the cvechecker database

  • dbuser is the user that cvechecker uses to connect to the database

  • dbpass is the password that cvechecker uses to connect to the database and authenticate itself

  • dbhost is the hostname where the database resides

If you need to change parameters, make sure that the file containing the changed values contains all configuration directives (and not just the changed one). cvechecker does not "fall back" to other configuration files if a parameter is missing.

6.2. MySQL Database Usage

When you use cvechecker with MySQL, then the following sections might be of use to you...

7.1. Syntax

The syntax of the versions.dat file is as follows:

,[filestart],1,[fileexpression],[contentexpression],[ao],[vendor],[product],[version],[update],[edition],[language]

The first comma is also used to inform cvechecker about the used column separator. If by any chance a field requires a comma as content, another separator can be chosen - just start the line with the chosen separator character.

The other fields have the following description:

• filestart is a substring used by cvechecker to quickly find possible matches. A filename that starts with filestart will be considered for further evaluation.

• 1 is used to inform cvechecker about the used version matching methodology. Currently only 1 is supported and means that it uses the strings command output.

• fileexpression is a regular expression used by cvechecker to find out if the file really needs to be scanned. Usually, the expression is just the filename, but for some binaries (like perl5.8.8) or libraries (like libconfig.so.1.2.8) having a matching regular expression allows cvechecker to identify these files as being part of a supported match-rule

• contentexpression is a regular expression used against the strings command output to find (and obtain) the version, update, edition and language of the software. It uses regular expression groups to obtain the necessary information

• 'a' or 'o' tells cvechecker if the detected software is an application (a) or operating system (o)

• vendor tells cvechecker what the vendor is of the file

• product tells cvechecker what the product is to which the file belongs

• version tells cvechecker what the detected version is of the product

• update, if applicable, tells cvechecker the specific update of the software

• edition, if applicable, tells cvechecker the specific edition of the software

• language, if applicable, tells cvechecker the specific language of the software

The parts starting from the [ao] field are also known as the CPE or Common Platform Enumeration. See http://cpe.mitre.org for more information.

Some example lines are:

,gzip,1,gzip,^([0-9]\.[0-9][0-9]*),a,gnu,gzip,\1,,,
,vim,1,vim,VIM - Vi IMproved ([0-9\.]+) ,a,vim,vim,\1,,,
,ncftp,1,ncftp,^.*NcFTP ([0-9\.]+)/([0-9]+) .*,a,ncftp_software,ncftp,\1,\2,,

7.2. Validating 'versions.dat'

To validate the matching rules, you can ask cvechecker to tell you if, and what CPE data it detects from a specific file:

~$ cvechecker -f /usr/bin/vim
  - Found match for /urs/bin/vim:    cpe:/a:vim:vim:7.2:::

In the above case, it detected for the /usr/bin/vim file vim (product) from vim (vendor) versino 7.2. It was not able to deduce any specific releases/edition/language (but that is not mandatory anyway).

If you want to add additional rules, make sure that the dat-file you will be importing contains the previous rules as well - cvechecker will drop all previous rules while importing new ones.

~$ cvechecker -l /usr/local/var/cvechecker/cache/versions.dat
Loading in new version data file...

7.3. Helping with version rules management

The version matching rules are at the core of the cvechecker tool. Without them, the tool is not able to detect much of anything on your system. To allow you to contribute to the version matching rules, the project also contains a tool called cverules.

The cverules command, which currently only supports Gentoo systems but should be easily portable towards other distributions or even platforms, will attempt to generate version matching rules for cvechecker that are currently not part of the project but which should give additional matches on your system.

For instance, if cvechecker currently doesn't know how to detect OpenLDAP versions, but you have OpenLDAP on your system, then cverules might be able to deduce a (generic put working) expression for the version matching rules which will allow cvechecker to identify OpenLDAP. If you then send the output of the cverules to the cvechecker project, then these additional rules will be added to the version matching rules so that your next pullcves pull will pull in these additional rules.