svn commit: r43953 - head/en_US.ISO8859-1/books/porters-handbook/security

Warren Block wblock at FreeBSD.org
Sun Feb 16 02:24:39 UTC 2014


Author: wblock
Date: Sun Feb 16 02:24:38 2014
New Revision: 43953
URL: http://svnweb.freebsd.org/changeset/doc/43953

Log:
  Whitespace-only fixes, translators please ignore.

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml	Sun Feb 16 02:10:29 2014	(r43952)
+++ head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml	Sun Feb 16 02:24:38 2014	(r43953)
@@ -4,160 +4,159 @@
 
      $FreeBSD$
 -->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="security">
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:id="security">
+
+  <title>Security</title>
+
+  <sect1 xml: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 xml: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-noinstall">mark the port as
+      <varname>FORBIDDEN</varname></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. <varname>PORTREVISION</varname> should be bumped unless
+      <varname>PORTVERSION</varname> has changed in the course of
+      correcting the vulnerability.  That is you should bump
+      <varname>PORTREVISION</varname> 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
+      <varname>PORTVERSION</varname>.  Please refer to the
+      <link linkend="makefile-naming-revepoch">corresponding
+	section</link> for more information.</para>
+  </sect1>
+
+  <sect1 xml:id="security-notify">
+    <title>Keeping the Community Informed</title>
+
+    <sect2 xml:id="security-notify-vuxml-db">
+      <title>The VuXML Database</title>
+
+      <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.  Second, a
+	lot of users tend to upgrade installed packages 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, a security
+	advisory cannot be issued on each incident without creating a
+	flood and losing the attention of the audience when it comes
+	to really serious matters.  Therefore security vulnerabilities
+	found in ports are recorded in
+	<link xlink:href="http://vuxml.freebsd.org/">the &os;
+	  VuXML database</link>.  The Security Officer Team members
+	also monitor 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 please do not hesitate to contact the Security
+	Officer Team directly as described on the
+	<link xlink:href="http://www.freebsd.org/security/#how">&os;
+	  Security Information</link> page.</para>
+
+      <para>The VuXML database is an <acronym>XML</acronym> document.
+	Its source file <filename>vuln.xml</filename> is kept right
+	inside the port <package role="port">security/vuxml</package>.
+	Therefore the file's full pathname will be
+	<filename>PORTSDIR/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 it as a
+	template.</para>
+    </sect2>
+
+    <sect2 xml:id="security-notify-vuxml-intro">
+      <title>A Short Introduction to VuXML</title>
+
+      <para>The full-blown <acronym>XML</acronym> 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 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.  This is
+	similar to HTML.  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>
 
-    <title>Security</title>
+      <para>Now consider a realistic VuXML entry:</para>
 
-    <sect1 xml: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 xml: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-noinstall">mark the port as
-	<varname>FORBIDDEN</varname></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.
-	<varname>PORTREVISION</varname> should be bumped unless
-	<varname>PORTVERSION</varname> has changed in the course
-	of correcting the vulnerability.  That is you should
-	bump <varname>PORTREVISION</varname> 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 <varname>PORTVERSION</varname>.  Please refer to the
-	<link linkend="makefile-naming-revepoch">corresponding
-	  section</link> for more information.</para>
-    </sect1>
-
-    <sect1 xml:id="security-notify">
-      <title>Keeping the Community Informed</title>
-
-      <sect2 xml:id="security-notify-vuxml-db">
-	<title>The VuXML Database</title>
-
-	<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.  Second, a lot of users tend to upgrade installed
-	  packages 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, a security
-	  advisory cannot be issued on each incident without creating
-	  a flood and losing the attention of the audience when it
-	  comes to really serious matters.  Therefore security
-	  vulnerabilities found in ports are recorded in
-	  <link xlink:href="http://vuxml.freebsd.org/">the &os;
-	    VuXML database</link>.  The Security Officer Team members
-	  also monitor 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 please do not hesitate to contact the Security
-	  Officer Team directly as described on the <link
-	    xlink:href="http://www.freebsd.org/security/#how">&os;
-	    Security Information</link> page.</para>
-
-	<para>The VuXML database is an <acronym>XML</acronym>
-	  document.  Its source file <filename>vuln.xml</filename> is
-	  kept right inside the port
-	  <package role="port">security/vuxml</package>.  Therefore
-	  the file's full pathname will be
-	  <filename>PORTSDIR/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 it as a
-	  template.</para>
-      </sect2>
-
-      <sect2 xml:id="security-notify-vuxml-intro">
-	<title>A Short Introduction to VuXML</title>
-
-	<para>The full-blown <acronym>XML</acronym> 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 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.  This is similar to HTML.  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 consider a realistic VuXML entry:</para>
-
-	<programlisting><vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <co xml:id="co-vx-vid"/>
+      <programlisting><vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <co xml:id="co-vx-vid"/>
   <topic>Several vulnerabilities found in Foo</topic> <co xml:id="co-vx-top"/>
   <affects>
     <package>
@@ -206,314 +205,300 @@
   </dates>
 </vuln></programlisting>
 
-	<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>
-
-	<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 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.</para>
-	  </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 responsibility 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></literal>,
-	      <literal><le></literal>,
-	      <literal><eq></literal>,
-	      <literal><ge></literal>, and
-	      <literal><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><ge>2.*</ge><lt>3.*</lt></literal>
-	      will selectively match every <literal>2.x</literal>
-	      version while
-	      <literal><ge>2.0</ge><lt>3.0</lt></literal>
-	      will 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><affected></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 <package> section.</para>
-	  </callout>
-
-	  <callout arearefs="co-vx-epo">
-	    <para>The version ranges should allow for
-	      <varname>PORTEPOCH</varname> and
-	      <varname>PORTREVISION</varname> if applicable.  Please
-	      remember that according to the collation rules, a
-	      version with a non-zero <varname>PORTEPOCH</varname> is
-	      greater than any version without
-	      <varname>PORTEPOCH</varname>, 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><p></literal> and
-	      <literal></p></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 <link
-		xlink:href="http://www.freebsd.org/security/#adv">&os;
-		security advisory</link>.</para>
-	  </callout>
-
-	  <callout arearefs="co-vx-fpr">
-	    <para>This is a <link
-		xlink:href="http://www.freebsd.org/support.html#gnats">&os;
-		problem report</link>.</para>
-	  </callout>
-
-	  <callout arearefs="co-vx-cve">
-	    <para>This is a
-	      <link xlink:href="http://www.cve.mitre.org/">MITRE
-		CVE</link> identifier.</para>
-	  </callout>
-
-	  <callout arearefs="co-vx-bid">
-	    <para>This is a <link
-		xlink:href="http://www.securityfocus.com/bid">SecurityFocus
-		Bug ID</link>.</para>
-	  </callout>
-
-	  <callout arearefs="co-vx-cts">
-	    <para>This is a
-	      <link xlink:href="http://www.cert.org/">US-CERT</link>
-	      security advisory.</para>
-	  </callout>
-
-	  <callout arearefs="co-vx-ctv">
-	    <para>This is a
-	      <link xlink:href="http://www.cert.org/">US-CERT</link>
-	      vulnerability note.</para>
-	  </callout>
-
-	  <callout arearefs="co-vx-ucs">
-	    <para>This is a
-	      <link xlink:href="http://www.cert.org/">US-CERT</link>
-	      Cyber Security Alert.</para>
-	  </callout>
-
-	  <callout arearefs="co-vx-uct">
-	    <para>This is a
-	      <link xlink:href="http://www.cert.org/">US-CERT</link>
-	      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 xml: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
-	  <emphasis>install</emphasis> fresh versions of the ports
-	  <package role="port">ports-mgmt/portaudit</package>,
-	  <package role="port">ports-mgmt/portaudit-db</package>,
-	  and
-	  <package role="port">security/vuxml</package>.</para>
-
-	<note>
-	  <para>To run <command>packaudit</command> you must have
-	    permission to write to its
-	    <filename>DATABASEDIR</filename>,
-	    typically <filename>/var/db/portaudit</filename>.</para>
-
-	  <para>To use a different directory set the
-	    <filename>DATABASEDIR</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>VUXMLDIR</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 an entry, it would match
-	  the previous version of the package,
-	  <literal>0.65_6</literal>:</para>
+      <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>
+
+      <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 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.</para>
+	</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 responsibility 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></literal>,
+	    <literal><le></literal>,
+	    <literal><eq></literal>,
+	    <literal><ge></literal>, and
+	    <literal><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><ge>2.*</ge><lt>3.*</lt></literal>
+	    will selectively match every <literal>2.x</literal>
+	    version while
+	    <literal><ge>2.0</ge><lt>3.0</lt></literal>
+	    will 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><affected></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
+	    <package> section.</para>
+	</callout>
+
+	<callout arearefs="co-vx-epo">
+	  <para>The version ranges should allow for
+	    <varname>PORTEPOCH</varname> and
+	    <varname>PORTREVISION</varname> if applicable.  Please
+	    remember that according to the collation rules, a version
+	    with a non-zero <varname>PORTEPOCH</varname> is greater
+	    than any version without <varname>PORTEPOCH</varname>,
+	    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><p></literal>
+	    and <literal></p></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 <link
+	      xlink:href="http://www.freebsd.org/security/#adv">&os;
+	      security advisory</link>.</para>
+	</callout>
+
+	<callout arearefs="co-vx-fpr">
+	  <para>This is a <link
+	      xlink:href="http://www.freebsd.org/support.html#gnats">&os;
+	      problem report</link>.</para>
+	</callout>
+
+	<callout arearefs="co-vx-cve">
+	  <para>This is a
+	    <link xlink:href="http://www.cve.mitre.org/">MITRE
+	      CVE</link> identifier.</para>
+	</callout>
+
+	<callout arearefs="co-vx-bid">
+	  <para>This is a <link
+	      xlink:href="http://www.securityfocus.com/bid">SecurityFocus
+	      Bug ID</link>.</para>
+	</callout>
+
+	<callout arearefs="co-vx-cts">
+	  <para>This is a
+	    <link xlink:href="http://www.cert.org/">US-CERT</link>
+	    security advisory.</para>
+	</callout>
+
+	<callout arearefs="co-vx-ctv">
+	  <para>This is a
+	    <link xlink:href="http://www.cert.org/">US-CERT</link>
+	    vulnerability note.</para>
+	</callout>
+
+	<callout arearefs="co-vx-ucs">
+	  <para>This is a
+	    <link xlink:href="http://www.cert.org/">US-CERT</link>
+	    Cyber Security Alert.</para>
+	</callout>
+
+	<callout arearefs="co-vx-uct">
+	  <para>This is a
+	    <link xlink:href="http://www.cert.org/">US-CERT</link>
+	    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 xml: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
+	<emphasis>install</emphasis> fresh versions of the ports
+	<package role="port">ports-mgmt/portaudit</package>,
+	<package role="port">ports-mgmt/portaudit-db</package>, and
+	<package role="port">security/vuxml</package>.</para>
+
+      <note>
+	<para>To run <command>packaudit</command> you must have
+	  permission to write to its <filename>DATABASEDIR</filename>,
+	  typically <filename>/var/db/portaudit</filename>.</para>
+
+	<para>To use a different directory set the
+	  <filename>DATABASEDIR</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>VUXMLDIR</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 an entry, it would match
+	the previous version of the package,
+	<literal>0.65_6</literal>:</para>
 
-	<screen>&prompt.user; <userinput>packaudit</userinput>
+      <screen>&prompt.user; <userinput>packaudit</userinput>
 &prompt.user; <userinput>portaudit clamav-0.65_6</userinput></screen>
 
-	<para>If there is none found, you have the green light to add
-	  a new entry for this vulnerability.</para>
+      <para>If there is none found, you have the green light to add a
+	new entry for this vulnerability.</para>
 
-	<screen>&prompt.user; <userinput>cd ${PORTSDIR}/security/vuxml</userinput>
+      <screen>&prompt.user; <userinput>cd ${PORTSDIR}/security/vuxml</userinput>
 &prompt.user; <userinput>make newentry</userinput></screen>
 
-	<para>When you are done verify its syntax and
-	  formatting.</para>
+      <para>When you are done verify its syntax and formatting.</para>
 
-	<screen>&prompt.user; <userinput>make validate</userinput></screen>
+      <screen>&prompt.user; <userinput>make validate</userinput></screen>
 
-	<note>
-	  <para>You will need at least one of the following packages
-	    installed:
-	    <package role="port">textproc/libxml2</package>,
-	    <package role="port">textproc/jade</package>.</para>
-	</note>
+      <note>
+	<para>You will need at least one of the following packages
+	  installed: <package role="port">textproc/libxml2</package>,
+	  <package role="port">textproc/jade</package>.</para>
+      </note>
 
-	<para>Now rebuild the <command>portaudit</command> database
-	  from the VuXML file:</para>
+      <para>Now rebuild the <command>portaudit</command> database from
+	the VuXML file:</para>
 
-	<screen>&prompt.user; <userinput>packaudit</userinput></screen>
+      <screen>&prompt.user; <userinput>packaudit</userinput></screen>
 
-	<para>To verify that the <literal><affected></literal>
-	  section of your entry will match correct package(s), issue
-	  the following command:</para>
+      <para>To verify that the <literal><affected></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 uuid</userinput></screen>
+      <screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r uuid</userinput></screen>
 
-	<note>
-	  <para>Please refer to &man.portaudit.1; for better
-	    understanding of the command syntax.</para>
-	</note>
+      <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>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>
+      <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>
+      <screen>&prompt.user; <userinput>portaudit clamav-0.65_6 clamav-0.65_7</userinput>
 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.</screen>
 
-	<para>The former version should match while the latter one
-	  should not.</para>
+      <para>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>
+      <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>
+      <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>
-    </sect1>
-  </chapter>
+    </sect2>
+  </sect1>
+</chapter>
 


More information about the svn-doc-all mailing list