FreeBSD Porter's Handbook
Prev Chapter 11 Ports security Next

11.3 Keeping the community informed

11.3.1 The VuXML database

A very important and urgent step to take as early as a security vulnerability is discovered is to notify the community of port users about the jeopardy. Such notification serves two purposes. First, should the danger be really severe, it will be wise to apply an instant workaround, e.g., stop the affected network service or even deinstall the port completely, until the vulnerability is closed. Second, a lot of users tend to upgrade installed packages just occasionally. They will know from the notification that they must update the package without delay as soon as a corrected version is available.

Given the huge number of ports in the tree, a security advisory cannot be issued on each incident without creating a flood and losing the attention of the audience by the time it comes to really serious matters. Therefore security vulnerabilities found in ports are recorded in the FreeBSD VuXML database. The Security Officer Team members are monitoring it for issues requiring their intervention.

If you have committer rights, you can update the VuXML database by yourself. So you will both help the Security Officer Team and deliver the crucial information to the community earlier. However, if you are not a committer, or you believe you have found an exceptionally severe vulnerability, or whatever, please do not hesitate to contact the Security Officer Team directly as described on the FreeBSD Security Information page.

All right, you elected the hard way. As it may be obvious from its title, the VuXML database is essentially an XML document. Its source file vuln.xml is kept right inside the port security/vuxml. Therefore the file's full pathname will be PORTSDIR/security/vuxml/vuln.xml. Each time you discover a security vulnerability in a port, please add an entry for it to that file. Until you are familiar with VuXML, the best thing you can do is to find an existing entry fitting your case, then copy it and use as a template.

11.3.2 A short introduction to VuXML

The full-blown XML is complex and far beyond the scope of this book. However, to gain basic insight on the structure of a VuXML entry, you need only the notion of tags. XML tag names are enclosed in angle brackets. Each opening <tag> must have a matching closing </tag>. Tags may be nested. If nesting, the inner tags must be closed before the outer ones. There is a hierarchy of tags, i.e. more complex rules of nesting them. Sounds very similar to HTML, doesn't it? The major difference is that XML is eXtensible, i.e. based on defining custom tags. Due to its intrinsic structure, XML puts otherwise amorphous data into shape. VuXML is particularly tailored to mark up descriptions of security vulnerabilities.

Now let's consider a realistic VuXML entry:

<vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> (1)
  <topic>Several vulnerabilities found in Foo</topic> (2)
  <affects>
    <package>
      <name>foo</name> (3)
      <name>foo-devel</name>
      <name>ja-foo</name>
      <range><ge>1.6</ge><lt>1.9</lt></range> (4)
      <range><ge>2.*</ge><lt>2.4_1</lt></range>
      <range><eq>3.0b1</eq></range>
    </package>
    <package>
      <name>openfoo</name> (5)
      <range><lt>1.10_7</lt></range> (6)
      <range><ge>1.2,1</ge><lt>1.3_1,1</lt></range>
    </package>
  </affects>
  <description>
    <body xmlns="http://www.w3.org/1999/xhtml">
      <p>J. Random Hacker reports:</p> (7)
      <blockquote
        cite="http://j.r.hacker.com/advisories/1">
        <p>Several issues in the Foo software may be exploited
          via carefully crafted QUUX requests.  These requests will
          permit the injection of Bar code, mumble theft, and the
          readability of the Foo administrator account.</p>
      </blockquote>
    </body>
  </description>
  <references> (8)
    <freebsdsa>SA-10:75.foo</freebsdsa> (9)
    <freebsdpr>ports/987654</freebsdpr> (10)
    <cvename>CAN-2010-0201</cvename> (11)
    <cvename>CAN-2010-0466</cvename>
    <bid>96298</bid> (12)
    <certsa>CA-2010-99</certsa> (13)
    <certvu>740169</certvu> (14)
    <uscertsa>SA10-99A</uscertsa> (15)
    <uscertta>SA10-99A</uscertta> (16)
    <mlist msgid="[email protected]">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> (17)
    <url>http://j.r.hacker.com/advisories/1</url> (18)
  </references>
  <dates>
    <discovery>2010-05-25</discovery> (19)
    <entry>2010-07-13</entry> (20)
    <modified>2010-09-17</modified> (21)
  </dates>
</vuln>

The tag names are supposed to be self-descriptive, so we shall take a closer look only at fields you will need to fill in by yourself:

(1)
This is the top-level tag of a VuXML entry. It has a mandatory attribute, vid, specifying a universally unique identifier (UUID) for this entry (in quotes). You should generate a UUID for each new VuXML entry (and do not forget to substitute it for the template UUID unless you are writing the entry from scratch). You can use uuidgen(1) to generate a VuXML UUID; alternatively, if you are using FreeBSD 4.x, you may install the port devel/p5-Data-UUID and issue the following command:
perl -MData::UUID -le 'print lc new Data::UUID->create_str'
(2)
This is a one-line description of the issue found.
(3)
The names of packages affected are listed there. Multiple names can be given since several packages may be based on a single master port or software product. This may include stable and development branches, localized versions, and slave ports featuring different choices of important build-time configuration options.

Important: It is your responsibility to find all such related packages when writing a VuXML entry. Keep in mind that make search name=foo is your friend. The primary points to look for are as follows:

  • the foo-devel variant for a foo port;

  • other variants with a suffix like -a4 (for print-related packages), -without-gui (for packages with X support disabled), or similar;

  • jp-, ru-, zh-, and other possible localized variants in the corresponding national categories of the ports collection.

(4)
Affected versions of the package(s) are specified there as one or more ranges using a combination of <lt>, <le>, <eq>, <ge>, and <gt> elements. The version ranges given should not overlap.

In a range specification, * (asterisk) denotes the smallest version number. In particular, 2.* is less than 2.a. Therefore an asterisk may be used for a range to match all possible alpha, beta, and RC versions. For instance, <ge>2.*</ge><lt>3.*</lt> will selectively match every 2.x version while <ge>2.0</ge><lt>3.0</lt> will obviously not since the latter misses 2.r3 and matches 3.b.

The above example specifies that affected are versions from 1.6 to 1.9 inclusive, versions 2.x before 2.4_1, and version 3.0b1.

(5)
Several related package groups (essentially, ports) can be listed in the <affected> section. This can be used if several software products (say FooBar, FreeBar and OpenBar) grow from the same code base and still share its bugs and vulnerabilities. Note the difference from listing multiple names within a single <package> section.
(6)
The version ranges should allow for PORTEPOCH and PORTREVISION if applicable. Please remember that according to the collation rules, a version with a non-zero PORTEPOCH is greater than any version without PORTEPOCH, e.g., 3.0,1 is greater than 3.1 or even than 8.9.
(7)
This is a summary of the issue. XHTML is used in this field. At least enclosing <p> and </p> should appear. More complex mark-up may be used, but only for the sake of accuracy and clarity: No eye candy please.
(8)
This section contains references to relevant documents. As many references as apply are encouraged.
(9)
This is a FreeBSD security advisory.
(10)
This is a FreeBSD problem report.
(11)
This is a Mitre CVE identifier.
(12)
This is a SecurityFocus Bug ID.
(13)
This is a US-CERT security advisory.
(14)
This is a US-CERT vulnerability note.
(15)
This is a US-CERT Cyber Security Alert.
(16)
This is a US-CERT Technical Cyber Security Alert.
(17)
This is a URL to an archived posting in a mailing list. The attribute msgid is optional and may specify the message ID of the posting.
(18)
This is a generic URL. It should be used only if none of the other reference categories apply.
(19)
This is the date when the issue was disclosed (YYYY-MM-DD).
(20)
This is the date when the entry was added (YYYY-MM-DD).
(21)
This is the date when any information in the entry was last modified (YYYY-MM-DD). New entries must not include this field. It should be added upon editing an existing entry.

11.3.3 Testing your changes to the VuXML database

Assume you just wrote or filled in an entry for a vulnerability in the package clamav that has been fixed in version 0.65_7.

As a prerequisite, you need to install fresh versions of the ports ports-mgmt/portaudit and ports-mgmt/portaudit-db.

First, check whether there already is an entry for this vulnerability. If there were such entry, it would match the previous version of the package, 0.65_6:

% packaudit
% portaudit clamav-0.65_6

Note: To run packaudit, you must have permission to write to its DATABASEDIR, typically /var/db/portaudit.

If there is none found, you get the green light to add a new entry for this vulnerability. Now you can generate a brand-new UUID (assume it's 74a9541d-5d6c-11d8-80e3-0020ed76ef5a) and add your new entry to the VuXML database. Please verify its syntax after that as follows:

% cd ${PORTSDIR}/security/vuxml && make validate

Note: You will need at least one of the following packages installed: textproc/libxml2, textproc/jade.

Now rebuild the portaudit database from the VuXML file:

% packaudit

To verify that the <affected> section of your entry will match correct package(s), issue the following command:

% portaudit -f /usr/ports/INDEX -r 74a9541d-5d6c-11d8-80e3-0020ed76ef5a

Note: Please refer to portaudit(1) for better understanding of the command syntax.

Make sure that your entry produces no spurious matches in the output.

Now check whether the right package versions are matched by your entry:

% portaudit clamav-0.65_6 clamav-0.65_7
Affected package: clamav-0.65_6 (matched by clamav<0.65_7)
Type of problem: clamav remote denial-of-service.
Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html>

1 problem(s) found.

Obviously, the former version should match while the latter one should not.

Finally, verify whether the web page generated from the VuXML database looks like expected:

% mkdir -p ~/public_html/portaudit
% packaudit
% lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html
Prev Home Next
Fixing security vulnerabilities Up Dos and Don'ts
For questions about the FreeBSD ports system, e-mail <[email protected]>.
For questions about this documentation, e-mail <[email protected]>.