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.

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.

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:

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) in FreeBSD
5.x, or 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'

This is a one-line description of the issue found.

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.

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.

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.

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.

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.

This section contains references to relevant documents. As many references as apply
are encouraged.

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:

As an easy alternative to writing VuXML, you may opt to add a single line to a
different file with much simpler syntax, PORTSDIR/security/portaudit-db/database/portaudit.txt, which
resides within the port security/portaudit-db, and send a request for review to the
Security Officer Team as described on the FreeBSD Security Information page.

A line in that file consists of four fields separated by |,
a pipe character. The first field is a pkg_version(1) pattern
expression matching the vulnerable packages. The second field contains URLs to relevant
information, separated by space characters. The third field is a one-line description of
the issue. The fourth and last field is the entry's UUID.

You may want take a closer look at existing entries in portaudit.txt before adding your first line to that file.