Add a chapter covering some issues at the intersection of the topics

of the ports collection and security, i.e., handling security
vulnerabilities in ports, the VuXML database, etc.

PR:			docs/68605
Collaborated with:	eik
This commit is contained in:
Yaroslav Tykhiy 2004-07-26 11:40:05 +00:00
parent cbbe553f53
commit f282cd9175
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=21691
2 changed files with 530 additions and 1 deletions
en_US.ISO8859-1/books/porters-handbook

View file

@ -25,5 +25,17 @@ SRCS= book.sgml
DSLHTML?= ${.CURDIR}/freebsd.dsl
DSLPRINT?= ${.CURDIR}/freebsd.dsl
# Images from the cross-document image library
IMAGES_LIB+= callouts/1.png
IMAGES_LIB+= callouts/2.png
IMAGES_LIB+= callouts/3.png
IMAGES_LIB+= callouts/4.png
IMAGES_LIB+= callouts/5.png
IMAGES_LIB+= callouts/6.png
IMAGES_LIB+= callouts/7.png
IMAGES_LIB+= callouts/8.png
IMAGES_LIB+= callouts/9.png
IMAGES_LIB+= callouts/10.png
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

View file

@ -769,7 +769,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting>
to the version number of the port.</para>
</sect2>
<sect2>
<sect2 id="makefile-naming-revepoch">
<title><makevar>PORTREVISION</makevar> and
<makevar>PORTEPOCH</makevar></title>
@ -5440,6 +5440,523 @@ IGNORE=POINTYHAT is not supported
</chapter>
<chapter id="security">
<title>Ports security</title>
<sect1 id="security-intro">
<title>Why security is so important</title>
<para>Bugs are occasionally introduced to the software.
Arguably, the most dangerous of them are those opening
security vulnerabilities. From the technical viewpoint,
such vulnerabilities are to be closed by exterminating
the bugs that caused them. However, the policies for
handling mere bugs and security vulnerabilities are
very different.</para>
<para>A typical small bug affects only those users who have
enabled some combination of options triggering the bug.
The developer will eventually release a patch followed
by a new version of the software, free of the bug, but
the majority of users will not take the trouble of upgrading
immediately because the bug has never vexed them. A
critical bug that may cause data loss represents a graver
issue. Nevertheless, prudent users know that a lot of
possible accidents, besides software bugs, are likely to
lead to data loss, and so they make backups of important
data; in addition, a critical bug will be discovered
really soon.</para>
<para>A security vulnerability is all different. First,
it may remain unnoticed for years because often it does
not cause software malfunction. Second, a malicious party
can use it to gain unauthorized access to a vulnerable
system, to destroy or alter sensitive data; and in the
worst case the user will not even notice the harm caused.
Third, exposing a vulnerable system often assists attackers
to break into other systems that could not be compromised
otherwise. Therefore closing a vulnerability alone is
not enough: the audience should be notified of it in most
clear and comprehensive manner, which will allow to
evaluate the danger and take appropriate actions.</para>
</sect1>
<sect1 id="security-fix">
<title>Fixing security vulnerabilities</title>
<para>While on the subject of ports and packages, a security
vulnerability may initially appear in the original
distribution or in the port files. In the former case,
the original software developer is likely to release a
patch or a new version instantly, and you will
only need to update the port promptly with respect to
the author's fix. If the fix is delayed for some reason,
you should either <link linkend="dads-broken">mark the port as
<makevar>FORBIDDEN</makevar></link>
or introduce a patch file of your own to the port. In
the case of a vulnerable port, just fix the port as soon as
possible. In either case, <link linkend="port-upgrading">the
standard procedure for submitting your change</link> should
be followed unless you have rights to commit it directly
to the ports tree.</para>
<important>
<para>Being a ports committer is not enough to commit to
an arbitrary port. Remember that ports usually have
maintainers, whom you should respect.</para>
</important>
<para>Please make sure that the port's revision is bumped
as soon as the vulnerability has been closed.
That is how the users who upgrade installed packages
on a regular basis will see they need to run an update.
Besides, a new package will be built and distributed
over FTP and WWW mirrors, replacing the vulnerable one.
<makevar>PORTREVISION</makevar> should be bumped unless
<makevar>PORTVERSION</makevar> has changed in the course
of correcting the vulnerability. That is you should
bump <makevar>PORTREVISION</makevar> if you have added a
patch file to the port, but you should not if you have updated
the port to the latest software version and thus already
touched <makevar>PORTVERSION</makevar>. Please refer to the
<link linkend="makefile-naming-revepoch">corresponding section</link>
for more information.</para>
</sect1>
<sect1 id="security-notify">
<title>Keeping the community informed</title>
<sect2 id="security-notify-vuxml-db">
<title>The VuXML database</title>
<para>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 <emphasis>must</emphasis> update the package
without delay as soon as a corrected version is available.
<para>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 <ulink
url="http://vuxml.freebsd.org/">the FreeBSD VuXML
database</ulink>. The Security Officer Team members
are monitoring it for issues requiring their
intervention.</para>
<para>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 <ulink
url="http://www.freebsd.org/security/#how">FreeBSD
Security Information</ulink> page.</para>
<para>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 <filename>vuln.xml</filename>
is kept right inside the port <filename
role="package">security/vuxml</filename>. Therefore
the file's full pathname will be
<filename><envar>PORTSDIR</envar>/security/vuxml/vuln.xml</filename>.
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.</para>
</sect2>
<sect2 id="security-notify-vuxml-intro">
<title>A short introduction to VuXML</title>
<para>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
&lt;tag&gt; must have a matching closing &lt;/tag&gt;.
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 e<emphasis>X</emphasis>tensible, 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.</para>
<para>Now let's consider a realistic VuXML entry:</para>
<programlisting>&lt;vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"&gt; <co id="co-vx-vid">
&lt;topic&gt;Several vulnerabilities found in Foo&lt;/topic&gt; <co id="co-vx-top">
&lt;affects&gt;
&lt;package&gt;
&lt;name&gt;foo&lt;/name&gt; <co id="co-vx-nam">
&lt;name&gt;foo-devel&lt;/name&gt;
&lt;name&gt;ja-foo&lt;/name&gt;
&lt;range&gt;&lt;ge&gt;1.6&lt;/ge&gt;&lt;lt&gt;1.9&lt;/lt&gt;&lt;/range&gt; <co id="co-vx-rng">
&lt;range&gt;&lt;ge&gt;2.*&lt;/ge&gt;&lt;lt&gt;2.4_1&lt;/lt&gt;&lt;/range&gt;
&lt;range&gt;&lt;eq&gt;3.0b1&lt;/eq&gt;&lt;/range&gt;
&lt;/package&gt;
&lt;package&gt;
&lt;name&gt;openfoo&lt;/name&gt; <co id="co-vx-nm2">
&lt;range&gt;&lt;lt&gt;1.10_7&lt;/lt&gt;&lt;/range&gt; <co id="co-vx-epo">
&lt;range&gt;&lt;ge&gt;1.2,1&lt;/ge&gt;&lt;lt&gt;1.3_1,1&lt;/lt&gt;&lt;/range&gt;
&lt;/package&gt;
&lt;/affects&gt;
&lt;description&gt;
&lt;body xmlns="http://www.w3.org/1999/xhtml"&gt;
&lt;p&gt;J. Random Hacker reports:&lt;/p&gt; <co id="co-vx-bdy">
&lt;blockquote
cite="http://j.r.hacker.com/advisories/1"&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;/body&gt;
&lt;/description&gt;
&lt;references&gt; <co id="co-vx-ref">
&lt;freebsdsa&gt;SA-10:75.foo&lt;/freebsdsa&gt; <co id="co-vx-fsa">
&lt;freebsdpr&gt;ports/987654&lt;/freebsdpr&gt; <co id="co-vx-fpr">
&lt;cvename&gt;CAN-2010-0201&lt;/cvename&gt; <co id="co-vx-cve">
&lt;cvename&gt;CAN-2010-0466&lt;/cvename&gt;
&lt;bid&gt;96298&lt;/bid&gt; <co id="co-vx-bid">
&lt;certsa&gt;CA-2010-99&lt;/certsa&gt; <co id="co-vx-cts">
&lt;certvu&gt;740169&lt;/certvu&gt; <co id="co-vx-ctv">
&lt;uscertsa&gt;SA10-99A&lt;/uscertsa&gt; <co id="co-vx-ucs">
&lt;uscertta&gt;SA10-99A&lt;/uscertta&gt; <co id="co-vx-uct">
&lt;mlist msgid="201075606@hacker.com"&gt;http://marc.theaimsgroup.com/?l=bugtraq&amp;amp;m=203886607825605&lt;/mlist&gt; <co id="co-vx-mls">
&lt;url&gt;http://j.r.hacker.com/advisories/1&lt;/url&gt; <co id="co-vx-url">
&lt;/references&gt;
&lt;dates&gt;
&lt;discovery&gt;2010-05-25&lt;/discovery&gt; <co id="co-vx-dsc">
&lt;entry&gt;2010-07-13&lt;/entry&gt; <co id="co-vx-ent">
&lt;modified&gt;2010-09-17&lt;/entry&gt; <co id="co-vx-mod">
&lt;/dates&gt;
&lt;/vuln&gt;</programlisting>
<para>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:</para>
<calloutlist>
<callout arearefs="co-vx-vid">
<para>This is the top-level tag of a VuXML entry. It has
a mandatory attribute, <literal>vid</literal>,
specifying a universally unique identifier (UUID) for
this entry (in quotes). You should generate a UUID
for each new VuXML entry (and don't forget to substitute
it for the template UUID unless you are writing the
entry from scratch). You can use &man.uuidgen.1; in
FreeBSD 5.x, or you may install the port <filename
role="package">devel/p5-Data-UUID</filename> and issue
the following command:</para>
<programlisting>perl -MData::UUID -le 'print lc new Data::UUID-&gt;create_str'</programlisting>
</callout>
<callout arearefs="co-vx-top">
<para>This is a one-line description of the issue found.</para>
</callout>
<callout arearefs="co-vx-nam">
<para>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.</para>
<important>
<para>It is your resposibility to find all such related
packages when writing a VuXML entry. Keep in mind that
<literal>make search name=foo</literal> is your friend.
The primary points to look for are as follows:</para>
<itemizedlist>
<listitem>
<para>the <filename>foo-devel</filename> variant
for a <filename>foo</filename> port;</para>
</listitem>
<listitem>
<para>other variants with a suffix like
<literal>-a4</literal> (for print-related packages),
<literal>-without-gui</literal> (for packages with X
support disabled), or similar;</para>
</listitem>
<listitem>
<para><literal>jp-</literal>, <literal>ru-</literal>,
<literal>zh-</literal>, and other possible localized
variants in the corresponding national categories of
the ports collection.</para>
</listitem>
</itemizedlist>
</important>
</callout>
<callout arearefs="co-vx-rng">
<para>Affected versions of the package(s) are specified
there as one or more ranges using a combination of
<literal>&lt;lt&gt;</literal>, <literal>&lt;le&gt;</literal>,
<literal>&lt;eq&gt;</literal>, <literal>&lt;ge&gt;</literal>,
and <literal>&lt;gt&gt;</literal> elements. The
version ranges given should not overlap.</para>
<para>In a range specification, <literal>*</literal> (asterisk)
denotes the smallest version number. In particular,
<literal>2.*</literal> is less than <literal>2.a</literal>.
Therefore an asterisk may be used for a range to match all
possible <literal>alpha</literal>, <literal>beta</literal>,
and <literal>RC</literal> versions. For instance,
<literal>&lt;ge&gt;2.*&lt;/ge&gt;&lt;lt&gt;3.*&lt;/lt&gt;</literal>
will selectively match every <literal>2.x</literal> version while
<literal>&lt;ge&gt;2.0&lt;/ge&gt;&lt;lt&gt;3.0&lt;/lt&gt;</literal>
will obviously not since the latter misses
<literal>2.r3</literal> and matches
<literal>3.b</literal>.</para>
<para>The above example
specifies that affected are versions from <literal>1.6</literal>
to <literal>1.9</literal> inclusive, versions
<literal>2.x</literal> before <literal>2.4_1</literal>,
and version <literal>3.0b1</literal>.</para>
</callout>
<callout arearefs="co-vx-nm2">
<para>Several related package groups (essentially, ports)
can be listed in the <literal>&lt;affected&gt;</literal>
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
&lt;package&gt; section.</para>
</callout>
<callout arearefs="co-vx-epo">
<para>The version ranges should allow for
<makevar>PORTEPOCH</makevar> and
<makevar>PORTREVISION</makevar> if applicable.
Please remember that according to the collation rules,
a version with a non-zero <makevar>PORTEPOCH</makevar> is
greater than any version without
<makevar>PORTEPOCH</makevar>, e.g., <literal>3.0,1</literal>
is greater than <literal>3.1</literal> or even than
<literal>8.9</literal>.</para>
</callout>
<callout arearefs="co-vx-bdy">
<para>This is a summary of the issue.
XHTML is used in this field. At least enclosing
<literal>&lt;p&gt;</literal> and <literal>&lt;/p&gt;</literal>
should appear. More complex mark-up may be used, but only for
the sake of accuracy and clarity: No eye candy please.</para>
</callout>
<callout arearefs="co-vx-ref">
<para>This section contains references to relevant documents.
As many references as apply are encouraged.</para>
</callout>
<callout arearefs="co-vx-fsa">
<para>This is a
<ulink url="http://www.freebsd.org/security/#adv">FreeBSD
security advisory</ulink>.</para>
</callout>
<callout arearefs="co-vx-fpr">
<para>This is a
<ulink url="http://www.freebsd.org/support.html#gnats">FreeBSD
problem report</ulink>.</para>
</callout>
<callout arearefs="co-vx-cve">
<para>This is a <ulink url="http://www.cve.mitre.org/">Mitre
CVE</ulink> identifier.</para>
</callout>
<callout arearefs="co-vx-bid">
<para>This is a
<ulink url="http://www.securityfocus.com/bid">SecurityFocus
Bug ID</ulink>.</para>
</callout>
<callout arearefs="co-vx-cts">
<para>This is a
<ulink url="http://www.cert.org/">US-CERT</ulink>
security advisory.</para>
</callout>
<callout arearefs="co-vx-ctv">
<para>This is a
<ulink url="http://www.cert.org/">US-CERT</ulink>
vulnerability note.</para>
</callout>
<callout arearefs="co-vx-ucs">
<para>This is a
<ulink url="http://www.cert.org/">US-CERT</ulink>
Cyber Security Alert.</para>
</callout>
<callout arearefs="co-vx-uct">
<para>This is a
<ulink url="http://www.cert.org/">US-CERT</ulink>
Technical Cyber Security Alert.</para>
</callout>
<callout arearefs="co-vx-mls">
<para>This is a URL to an archived posting in a mailing list.
The attribute <literal>msgid</literal> is optional and
may specify the message ID of the posting.</para>
</callout>
<callout arearefs="co-vx-url">
<para>This is a generic URL. It should be used only if none of
the other reference categories apply.</para>
</callout>
<callout arearefs="co-vx-dsc">
<para>This is the date when the issue was disclosed
(<replaceable>YYYY-MM-DD</replaceable>).</para>
</callout>
<callout arearefs="co-vx-ent">
<para>This is the date when the entry was added
(<replaceable>YYYY-MM-DD</replaceable>).</para>
</callout>
<callout arearefs="co-vx-mod">
<para>This is the date when any information in the entry
was last modified (<replaceable>YYYY-MM-DD</replaceable>).
New entries must not include this field. It should be added
upon editing an existing entry.</para>
</callout>
</calloutlist>
</sect2>
<sect2 id="security-notify-vuxml-testing">
<title>Testing your changes to the VuXML database</title>
<para>Assume you just wrote or filled in an entry for a
vulnerability in the package <literal>clamav</literal>
that has been fixed in version <literal>0.65_7</literal>.</para>
<para>As a prerequisite, you need to install fresh versions of the
ports <filename role="package">security/portaudit</filename> and
<filename role="package">security/portaudit-db</filename>.</para>
<para>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,
<literal>0.65_6</literal>:</para>
<screen>&prompt.user; <userinput>packaudit</userinput>
&prompt.user; <userinput>portaudit clamav-0.65_6</userinput></screen>
<note>
<para>To run <command>packaudit</command>, you must have
permission to write to its
<filename><makevar>DATABASEDIR</makevar></filename>,
typically <filename>/var/db/portaudit</filename>.</para>
</note>
<para>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
<literal>74a9541d-5d6c-11d8-80e3-0020ed76ef5a</literal>) and
add your new entry to the VuXML database. Please verify
its syntax after that as follows:</para>
<screen>&prompt.user; <userinput>cd ${PORTSDIR}/security/vuxml && make validate</userinput></screen>
<note>
<para>You will need at least one of the following packages
installed: <filename role="package">textproc/libxml2</filename>,
<filename role="package">textproc/jade</filename>.</para>
</note>
<para>Now rebuild the <command>portaudit</command> database
from the VuXML file:</para>
<screen>&prompt.user; <userinput>packaudit</userinput></screen>
<para>To verify that the <literal>&lt;affected&gt;</literal>
section of your entry will match correct package(s), issue
the following command:</para>
<screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r 74a9541d-5d6c-11d8-80e3-0020ed76ef5a</userinput></screen>
<note>
<para>Please refer to &man.portaudit.1; for better understanding
of the command syntax.</para>
</note>
<para>Make sure that your entry produces no spurious matches
in the output.</para>
<para>Now check whether the right package versions are matched
by your entry:</para>
<screen>&prompt.user; <userinput>portaudit clamav-0.65_6 clamav-0.65_7</userinput>
Affected package: clamav-0.65_6 (matched by clamav&lt;0.65_7)
Type of problem: clamav remote denial-of-service.
Reference: &lt;http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html&gt;
1 problem(s) found.</screen>
<para>Obviously, the former version should match while the
latter one should not.</para>
<para>Finally, verify whether the web page generated from the
VuXML database looks like expected:</para>
<screen>&prompt.user; <userinput>mkdir -p ~/public_html/portaudit</userinput>
&prompt.user; <userinput>packaudit</userinput>
&prompt.user; <userinput>lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html</userinput></screen>
</sect2>
<sect2 id="security-notify-noxml">
<title>If VuXML still scares you...</title>
<para>As an easy alternative to writing VuXML, you may opt to add
a single line to a different file with much simpler syntax,
<filename><envar>PORTSDIR</envar>/security/portaudit-db/database/portaudit.txt</filename>,
which resides within the port <filename
role="package">security/portaudit-db</filename>, and
send a request for review to the Security Officer Team
as described on the <ulink
url="http://www.freebsd.org/security/#how">FreeBSD
Security Information</ulink> page.</para>
<para>A line in that file consists of four fields
separated by <literal>|</literal>, a pipe character.
The first field is a &man.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.</para>
<para>You may want take a closer look at existing entries in
<filename>portaudit.txt</filename> before adding your
first line to that file.</para>
</sect2>
</sect1>
</chapter>
<chapter id="porting-dads">
<title>Dos and Don'ts</title>