<?xml version="1.0" encoding="UTF-8"?>
<article version="5.0" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>CVE Checker User Guide</title>

    <author>
      <personname><firstname>Sven</firstname><surname>Vermeulen</surname></personname>

      <email>sven.vermeulen@siphos.be</email>
    </author>

    <pubdate>2012/11/25</pubdate>
  </info>

  <section>
    <title>Introduction</title>

    <para>Welcome to the CVE checker user guide. The purpose of this document
    is to guide you through the installation and usage of CVE checker. But
    before we start with that, a little warning is in place...</para>

    <para>CVE checker does not provide security for your system. It is nothing
    more than a tool that attempts to identify installed software on your
    system and match those against the online database of CVE entries. As the
    identification of installed software depends on simple rules that are
    added by the community, it is very likely that it only detects a small
    portion of the installed software on your system (especially if you are
    running software that isn't all that popular). And even if the tool
    detects the software appropriately, it still requires that the CVE entry
    mentions this software with the same vendor and product name as this tool
    detects - if not, CVE checker will not be able to match the installed
    software against the online CVE database.</para>

    <para>Okay, now that that is out of the way, let's start with the CVE
    checker installation.</para>
  </section>

  <section>
    <title>Installation</title>

    <section>
      <title>Requirements</title>

      <para>The cvechecker tool requires the following packages to be
      installed:</para>

      <itemizedlist>
        <listitem>
          <para>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)</para>
        </listitem>

        <listitem>
          <para>libconfig - a C library that offers a simple way for
          applications to read and handle configuration files</para>
        </listitem>

        <listitem>
          <para>a database or database client. Currently, cvechecker
          supports:</para>

          <itemizedlist>
            <listitem>
              <para>sqlite3 - a local, embedded yet powerful database</para>
            </listitem>

            <listitem>
              <para>mysql (through libmysql) - one of the more popular open
              source databases</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>wget - a command-line tool to fetch online resources</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Installation</title>

      <para>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).</para>

      <para>First, download the latest cvechecker package from <uri
      xlink:href="http://cvechecker.sourceforge.net">http://cvechecker.sourceforge.net</uri>
      (or <uri
      xlink:href="http://sourceforge.net/projects/cvechecker/files/">http://sourceforge.net/projects/cvechecker/files/</uri>),
      then extract it into a temporary directory:</para>

      <programlisting>~$ <command>tar xvzf cvechecker-1.O.tar.gz</command></programlisting>

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

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

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

      <para>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 <command>make postinstall</command> (you almost definitely
      need root privileges now):</para>

      <programlisting>~# <command>make postinstall</command></programlisting>
    </section>

    <section>
      <title>Initial Configuration</title>

      <para>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.</para>

      <para>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:</para>

      <programlisting>~# <command>gpasswd -a <replaceable>youruser</replaceable> cvechecker</command></programlisting>

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

      <programlisting>~# <command>su <replaceable>youruser</replaceable> -</command>
~$ <command>newgrp cvechecker</command>
~$ <command>umask 007</command></programlisting>

      <para>Now, initialize the databases by running <command>cvechecker
      -i</command>. 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).</para>

      <programlisting>~$ <command>cvechecker -i</command></programlisting>

      <section>
        <title>Configuration File</title>

        <para>The cvechecker command uses a configuration file which it looks
        for in the users' home directory (${HOME}/.cvechecker.rc) or
        /usr/local/etc/cvechecker.conf or /etc/cvechecker.conf, in that order.
        The first configuration file that parses correctly is used, the rest
        is ignored (so there is no accumulation of configurations). Below,
        you'll find an example configuration file which shows both the sqlite3
        and mysql support:</para>

        <programlisting>#
# 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";
};</programlisting>

        <para>Most of the parameters (like cvecache, datadir, version_url and
        even localdb and globaldb) will most likely be set correctly already
        during the installation. However, it doesn't hurt to validate if the
        locations mentioned are correct and that the user that will be used to
        run cvechecker has the rights to write (to) files in the
        locations.</para>
      </section>

      <section>
        <title>Initialize SQLite3 Database</title>

        <para>If you opt to use the sqlite3 databases, you need to initialize
        those by running <command>cvechecker -i</command>. Because cvechecker
        uses a lot of data, it will create various database files to spread
        the data due to performance reasons. These locations are mentioned in
        the configuration file.</para>

        <programlisting>~# <command>cvechecker -i</command></programlisting>

        <para>This is all that is needed to initialize the SQLite3
        databases.</para>
      </section>

      <section>
        <title>Initialize MySQL Database</title>

        <para>If you opt to use the MySQL database, you first need to create
        the database in your MySQL server. Installing and configuring a MySQL
        server is beyond the scope of this document. Once a database is
        created (say "cvechecker"), you can either initialize it through
        <command>cvechecker -i</command> (if the user you connect to the
        database to has sufficient privileges to drop and create tables and
        indexes) or use the dump file
        <filename>mysql_cvechecker.sql</filename> available in
        /usr/share/cvechecker/.</para>

        <programlisting>~# <command>cvechecker -i</command></programlisting>

        <para>It is strongly advised that the user you
        <emphasis>use</emphasis> has limited rights. Only the initialization
        requires additional rights. When you are using cvechecker, it is
        recommended that two roles are used:</para>

        <itemizedlist>
          <listitem>
            <para>A cvechecker administrative role that has the rights to load
            new CVE and CPE data as well as version matching rules</para>
          </listitem>

          <listitem>
            <para>A cvechecker operational role that has the rights to insert
            the matching data and read the CVE and version matching
            rules</para>
          </listitem>
        </itemizedlist>

        <para>We will talk about these roles later in this document.</para>
      </section>

      <section>
        <title>Load CVE and version matching rules</title>

        <para>Our last step is to load the upstream data in the
        databases.</para>

        <para>The upstream data consists out of</para>

        <itemizedlist>
          <listitem>
            <para>CVE information (CVE identifiers together with the software
            they are referring to) which is going to be pulled from
            nvd.nist.gov, and</para>
          </listitem>

          <listitem>
            <para>version matching rules (regular expressions and other
            information needed to deduce the correct software and version
            given an application file or binary) which is going to be pulled
            from the cvechecker source code repository</para>
          </listitem>
        </itemizedlist>

        <para>These steps are automated in a tool called
        <command>pullcves</command>. This will take a very long time, so
        please be patient (loading over half a million CVE entries in a
        database is a time consuming - but one-time - activity). Future pulls
        will not take this much time as they will not redownload the CVE
        entries from all previous years (unless you ask it to).</para>

        <programlisting>~$ <command>pullcves pull</command></programlisting>
      </section>
    </section>

    <section>
      <title>Upgrades</title>

      <para>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.</para>

      <para>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.</para>
    </section>
  </section>

  <section>
    <title>Regular Runs</title>

    <para>Whenever you want to perform a regular cvechecker run, you should
    schedule five steps. If you use sqlite as the database backend, all steps
    are to be scheduled on the same system. If you use MySQL however, it is
    recommended to schedule the administrative tasks on a single system (the
    "master" that is responsible for keeping the upstream data up-to-date) and
    the operational tasks on all systems where you want to run cvechecker on
    (and gather reports from).</para>

    <para>The administrative tasks are:</para>

    <orderedlist>
      <listitem>
        <para>pull in the latest CVE entries as well as software/version
        detection rules</para>
      </listitem>
    </orderedlist>

    <para>The operational tasks are:</para>

    <orderedlist>
      <listitem>
        <para>generate a list of files to scan</para>
      </listitem>

      <listitem>
        <para>gather installed software/version information</para>
      </listitem>

      <listitem>
        <para>output which CVE entries might affect your system</para>
      </listitem>

      <listitem>
        <para>generate a report informing you about the CVE entries</para>
      </listitem>
    </orderedlist>

    <para>All these steps should be performed by the user you use to run
    cvechecker, so don't forget:</para>

    <programlisting>~$ <command>newgrp cvechecker</command>
~$ <command>umask 007</command></programlisting>

    <section>
      <title>Pull Data</title>

      <para>To pull the necessary data from the Internet, run
      <command>pullcves pull</command>:</para>

      <programlisting>~$ <command>pullcves pull</command></programlisting>
    </section>

    <section>
      <title>Generate List of Files</title>

      <para>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.</para>

      <programlisting>~$ <command>find / -type f -perm -o+x &gt; scanlist.txt</command>
~$ <command>echo "/proc/version" &gt;&gt; scanlist.txt</command></programlisting>

      <para>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
      <parameter>-mount</parameter> (or <parameter>-xdev</parameter>) option
      of <command>find</command> to stay within the selected device
      (partition), or exclude directories (and their subdirectories), like
      so:</para>

      <programlisting>~$ <command>find / -path /mnt -prune -o -path /media -prune -o -type f -perm -o+x &gt; scanlist.txt</command> </programlisting>
    </section>

    <section>
      <title>Gather List of Installed Software/Versions</title>

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

      <programlisting>~$ <command>cvechecker -b scanlist.txt</command></programlisting>

      <section>
        <title>Integrating with a package manager</title>

        <para>You can integrate cvechecker with your package manager, telling
        cvechecker to only add (or remove) files part of an installed (or
        uninstalled) package rather than having to feed a full file system
        listing. To do so, tell your package manager to call
        <command>cvechecker -d -b &lt;file&gt;</command> after each succesfull
        installation, or <command>cvechecker -D -b &lt;file&gt;</command>
        before a desinstallation. The -d option tells cvechecker to add the
        file content to the database (rather than replace) whereas -D tells
        cvechecker to delete those entries in the database that are also in
        the file.</para>

        <para>A simple example for Gentoo would be to create a script
        (/etc/portage/bashrc) which calls other scripts based on the ebuild
        phase, such as
        <filename>/etc/portage/bashrc.d/package.postinst</filename> or
        <filename>/etc/portage/bashrc.d/package.prerm</filename>. These
        scripts can then call <command>qlist</command> to create a file
        containing the package file content which is then passed on to
        <command>cvechecker</command>.</para>

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

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

    <section>
      <title>Output Matching CVE Entries</title>

      <para>Make cvechecker output the matching CVE entries. A standard output
      might look like this:</para>

      <programlisting>~$ <command>cvechecker -r</command>
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)</programlisting>

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

      <programlisting>~$ <command>cvechecker -r -C</command>
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</programlisting>

      <para>The default behavior of <command>cvechecker</command> 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 <emphasis>higher</emphasis>
      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
      <command>cvechecker</command> wouldn't be triggered when this is the
      case, but if you add <command>-H</command> or
      <command>--reporthigher</command>, <command>cvechecker</command> will
      also report on higher versions.</para>
    </section>

    <section>
      <title>(Optional) Generate A Report</title>

      <para>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.</para>

      <programlisting>~$ <command>cvereport -d /home/john/cvereport-20100902/ /home/john/cvechecker/acknowledgements.xml</command></programlisting>

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

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

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

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

      <para>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.</para>
    </section>
  </section>

  <section>
    <title>Detected Software</title>

    <para>The tool also supports listing the detected software/version on your
    system. This allows you to verify if the tool can detect the software you
    want to track CVE reports of.</para>

    <programlisting>~$ <command>cvechecker -s</command>
Detected vendor="wpa_supplicant", product="wpa_supplicant", version="0.6.10", update="", edition="", language="" on host="localhost", userkey="localhost"
...</programlisting>

    <para>You can also request the list of files that were used by cvechecker
    to identify the software:</para>

    <programlisting>~$ <command>cvechecker -S</command>
Detected vendor="wpa_supplicant", product="wpa_supplicant", version="0.6.10", update="", edition="", language="" on host="localhost", userkey="localhost"
Files that contributed to this detection:
  - /usr/sbin/wpa_supplicant
  - /usr/bin/wpa_cli</programlisting>

    <para>These options also support the -C switch (to enable CSV-like output
    for easier parsing);</para>

    <programlisting>~$ <command>cvechecker -S -C</command>
Outputversion,Vendor,Product,Version,Update,Edition,Language,Hostname,Userkey,Files
2,wpa_supplicant,wpa_supplicant,0.6.10,,,,localhost,localhost,/usr/sbin/wpa_supplicant /usr/bin/wpa_cli </programlisting>
  </section>

  <section>
    <title>Watch Lists</title>

    <para>With cvechecker, you can also "pretend" to have particular software
    (or hardware or operating systems) installed on your system. By feeding
    this so-called watchlist to cvechecker, it will add these titles to the
    database and assume they are also installed on the system.</para>

    <para>It is recommended to use the watch lists simultaneously with the
    binary file listing. If you use it separately, don't forget to use the
    delta options. Otherwise, all detected software versions will be cleared
    from the database.</para>

    <programlisting>~$ <command>cvechecker -b binlist.txt -w watchlist.txt</command>
~$ <command>cvechecker -w watchlist.txt --deltaonly</command></programlisting>
  </section>

  <section>
    <title>Configuring cvechecker</title>

    <para>The cvechecker tool uses a configuration file to find out where to
    store its intermediate and final data (such as downloaded XML files, CSV
    files, database files).</para>

    <para>The tool first looks for .cvechecker.rc inside the users' home
    directory. If it can't find it, it will look for
    /usr/local/etc/cvechecker.conf and, if that file doesn't exist either,
    /etc/cvechecker.conf.</para>

    <section>
      <title>Configuration File Format</title>

      <para>The cvechecker configuration file currently requires 6
      configuration items:</para>

      <programlisting>#
# 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";
};</programlisting>

      <para>These items describe the following resources:</para>

      <itemizedlist>
        <listitem>
          <para>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)</para>
        </listitem>

        <listitem>
          <para>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)</para>
        </listitem>

        <listitem>
          <para>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</para>
        </listitem>

        <listitem>
          <para>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.</para>
        </listitem>

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

        <listitem>
          <para>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.</para>

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

        <listitem>
          <para>sqlite3: combines all sqlite specific settings, which
          are:</para>

          <itemizedlist>
            <listitem>
              <para>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</para>
            </listitem>

            <listitem>
              <para>globaldb is a (cvechecker writeable) sqlite3 database
              containing the software/version matching rules and CPEs
              associated with these rules</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>mysql: combines all mysql specific settings, which are:</para>

          <itemizedlist>
            <listitem>
              <para>dbname is the name of the cvechecker database</para>
            </listitem>

            <listitem>
              <para>dbuser is the user that cvechecker uses to connect to the
              database</para>
            </listitem>

            <listitem>
              <para>dbpass is the password that cvechecker uses to connect to
              the database and authenticate itself</para>
            </listitem>

            <listitem>
              <para>dbhost is the hostname where the database resides</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <warning>
        <para>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.</para>
      </warning>
    </section>

    <section>
      <title>MySQL Database Usage</title>

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

      <section>
        <title>User Roles</title>

        <para>When using MySQL database(s), it is recommended to use two
        separate roles:</para>

        <itemizedlist>
          <listitem>
            <para>The cvechecker administrative role should have the rights to
            SELECT, INSERT, UPDATE and DELETE data from tb_versionmatch,
            tb_cve, tb_cpe, tb_cpe_versions, tb_cpe_parents, tb_binmatch and
            tb_systems</para>
          </listitem>

          <listitem>
            <para>The cvechecker operational role should have the rights
            to</para>

            <itemizedlist>
              <listitem>
                <para>SELECT, INSERT, UPDATE and DELETE data from
                tb_binmatch</para>
              </listitem>

              <listitem>
                <para>SELECT and INSERT data into tb_cpe, tb_cpe_versions and
                tb_cpe_parents</para>
              </listitem>

              <listitem>
                <para>SELECT data from tb_cve and tb_binmatch</para>
              </listitem>
            </itemizedlist>

            <para>If the database supports row-level security, you can
            configure the operational role on tb_binmatch with the additional
            security setting of "WHERE HOSTNAME='hostname' AND
            USERDEFKEY='userdefkey'" where hostname and userdefkey are the
            clients' hostname and userdefined key (userkey) setting (which
            defaults to the hostname again if no userkey is set).</para>
          </listitem>
        </itemizedlist>

        <para>A third role "could" be created (which allows cvechecker to
        (re)initialize its databases using <command>cvechecker -i</command>)
        but this should only be activated during the (re)initialization and
        locked again when the change is finished.</para>
      </section>

      <section>
        <title>InnoDB or MyISAM?</title>

        <para>The cvechecker tool currently uses InnoDB tables. The main
        (only) reason for this is that the tool uses foreign key definitions
        to keep referential integrity within the database. However, untrained
        administrators might find InnoDB a lot slower to work with than
        MyISAM. It is perfectly possible to use MyISAM tables instead of
        InnoDB (cvechecker does not use the cascading delete functionality
        within foreign key definitions):</para>

        <orderedlist>
          <listitem>
            <para>Change the mysql_cvechecker.sql file by removing all
            references to FOREIGN KEY ... statements as well as
            ENGINE=InnoDB.</para>
          </listitem>

          <listitem>
            <para>Load the (changed) SQL file in the MySQL database</para>
          </listitem>

          <listitem>
            <para>Do <emphasis>not</emphasis> use cvechecker -i (as that runs
            hardcoded SQL statements which will transition to InnoDB
            again).</para>
          </listitem>
        </orderedlist>

        <para>If you want to convert when data is already present, the easiest
        method in my opinion is to dump the information to a .sql file, change
        the .sql file and load it back in. However, other methods exist as
        well - which ones I leave as an excercise in Internet search engines
        for those interested ;-)</para>
      </section>
    </section>
  </section>

  <section>
    <title>Software Matching Rules</title>

    <para>The software matching rules, as identified inside the versions.dat
    file, is pulled in and imported in the cvechecker database by
    pullcves.</para>

    <section>
      <title>Syntax</title>

      <para>The syntax of the versions.dat file is as follows:</para>

      <programlisting>,[filestart],1,[fileexpression],[contentexpression],[ao],[vendor],[product],[version],[update],[edition],[language]</programlisting>

      <para>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.</para>

      <para>The other fields have the following description:</para>

      <itemizedlist>
        <listitem>
          <para>filestart is a substring used by cvechecker to quickly find
          possible matches. A filename that starts with filestart will be
          considered for further evaluation.</para>
        </listitem>

        <listitem>
          <para>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.</para>
        </listitem>

        <listitem>
          <para>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</para>
        </listitem>

        <listitem>
          <para>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</para>
        </listitem>

        <listitem>
          <para>'a' or 'o' tells cvechecker if the detected software is an
          application (a) or operating system (o)</para>
        </listitem>

        <listitem>
          <para>vendor tells cvechecker what the vendor is of the file</para>
        </listitem>

        <listitem>
          <para>product tells cvechecker what the product is to which the file
          belongs</para>
        </listitem>

        <listitem>
          <para>version tells cvechecker what the detected version is of the
          product</para>
        </listitem>

        <listitem>
          <para>update, if applicable, tells cvechecker the specific update of
          the software</para>
        </listitem>

        <listitem>
          <para>edition, if applicable, tells cvechecker the specific edition
          of the software</para>
        </listitem>

        <listitem>
          <para>language, if applicable, tells cvechecker the specific
          language of the software</para>
        </listitem>
      </itemizedlist>

      <para>The parts starting from the [ao] field are also known as the CPE
      or Common Platform Enumeration. See <uri
      xlink:href="http://cpe.mitre.org">http://cpe.mitre.org</uri> for more
      information.</para>

      <para>Some example lines are:</para>

      <programlisting>,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,,</programlisting>
    </section>

    <section>
      <title>Validating 'versions.dat'</title>

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

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

      <para>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).</para>

      <para>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.</para>

      <programlisting>~$ <command>cvechecker -l /usr/local/var/cvechecker/cache/versions.dat</command>
Loading in new version data file...</programlisting>
    </section>

    <section>
      <title>Helping with version rules management</title>

      <para>The version matching rules are at the core of the
      <command>cvechecker</command> 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
      <command>cverules</command>.</para>

      <para>The <command>cverules</command> 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.</para>

      <para>For instance, if cvechecker currently doesn't know how to detect
      OpenLDAP versions, but you have OpenLDAP on your system, then
      <command>cverules</command> 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
      <command>cverules</command> to the cvechecker project, then these
      additional rules will be added to the version matching rules so that
      your next <command>pullcves pull</command> will pull in these additional
      rules.</para>
    </section>
  </section>
</article>
