Date: Sun, 16 Feb 2014 02:24:38 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43953 - head/en_US.ISO8859-1/books/porters-handbook/security Message-ID: <201402160224.s1G2Ocar047740@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402160224.s1G2Ocar047740>