os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Improve the entry on generating new vuxml entries. This includes changes

Browse source 
to the grammar and punctuation, as well as adding details about the
mechanics of running portaudit.

This change also incorporates the changes from the PR to text no longer
relevant since 4.x days.

PR:		docs/160470
Submitted by:	eadler
This commit is contained in:
Doug Barton 2011-09-05 12:00:45 +00:00
parent 9cb008777e
commit a4edb91a3e
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=37641
1 changed files with 43 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

80
en_US.ISO8859-1/books/porters-handbook/book.sgml
View file

@ -9897,60 +9897,60 @@ as .putsy.conf and edit it.</programlisting>
<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
<para>A very important and urgent step to take as early after
a security vulnerability is discovered as possible 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.
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
only 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>
<para>Given the huge number of ports in the tree,
<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
the audience when 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
also monitor it for issues requiring their
intervention.</para>
<para>If you have committer rights, you can update the VuXML
<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
vulnerability 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
<para>As may be obvious
from its title the VuXML database is 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.
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>
it and use it 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
<para>The full-blown XML format 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
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
@ -9958,7 +9958,7 @@ as .putsy.conf and edit it.</programlisting>
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,
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>
@ -10014,7 +10014,7 @@ as .putsy.conf and edit it.</programlisting>
&lt;/dates&gt;
&lt;/vuln&gt;</programlisting>
<para>The tag names are supposed to be self-descriptive,
<para>The tag names are supposed to be self-explanatory
so we shall take a closer look only at fields you will need
to fill in by yourself:</para>
@ -10027,12 +10027,7 @@ as .putsy.conf and edit it.</programlisting>
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 &man.uuidgen.1; to
generate a VuXML UUID; alternatively, if you are using
FreeBSD 4.x, 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>
generate a VuXML UUID.</para>
</callout>
<callout arearefs="co-vx-top">
@ -10223,26 +10218,37 @@ as .putsy.conf and edit it.</programlisting>
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">ports-mgmt/portaudit</filename> and
<filename role="package">ports-mgmt/portaudit-db</filename>.</para>
<para>As a prerequisite, you need to <emphasis>install</emphasis> fresh versions of the
ports <filename role="package">ports-mgmt/portaudit</filename>,
<filename role="package">ports-mgmt/portaudit-db</filename>, and
<filename role="package">security/vuxml</filename>.</para>
<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>
<para>To use a different directory set the
<filename><makevar>DATABASEDIR</makevar></filename>
environment variable to a different location.</para>
<para>If you are working in a directory other than
<filename>${PORTSDIR}/security/vuxml</filename> set the
<filename><makevar>VUXMLDIR</makevar></filename>
environment variable to the directory where
<filename>vuln.xml</filename> is located.</para>
</note>
<para>First, check whether there already is an entry for this
vulnerability. If there were such entry, it would match the
vulnerability. If there were such an 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
<para>If there is none found, you have 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