Date: Tue, 16 Sep 2014 11:58:50 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45615 - head/en_US.ISO8859-1/books/porters-handbook/security Message-ID: <201409161158.s8GBwoHU024492@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mat (ports committer) Date: Tue Sep 16 11:58:50 2014 New Revision: 45615 URL: http://svnweb.freebsd.org/changeset/doc/45615 Log: igor -Ry and some other rewording and fixes. Differential Revision: https://reviews.freebsd.org/D651 Reviewed by: wblock Sponsored by: Absolight 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 Tue Sep 16 10:03:58 2014 (r45614) +++ head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml Tue Sep 16 11:58:50 2014 (r45615) @@ -40,8 +40,8 @@ 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 + vulnerability alone is not enough: notify the audience + of it in most clear and comprehensive manner, which will allow to evaluate the danger and take appropriate actions.</para> </sect1> @@ -53,21 +53,21 @@ 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 + instantly. Update the port promptly with respect to the author's fix. If the fix is delayed for - some reason, you should either + some reason, 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, + <varname>FORBIDDEN</varname></link> or introduce a patch file + to the port. In the case of a vulnerable port, just + fix the port as soon as possible. In either case, follow <link linkend="port-upgrading">the standard procedure for - submitting your change</link> should be followed unless you have + submitting changes</link> unless having 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> + must be respected.</para> </important> <para>Please make sure that the port's revision is bumped as soon @@ -75,11 +75,11 @@ 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 + one. Bump <varname>PORTREVISION</varname> 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 + correcting the vulnerability. That is, bump + <varname>PORTREVISION</varname> if adding a patch file + to the port, but do not bump it if updating the port to the latest software version and thus already touched <varname>PORTVERSION</varname>. Please refer to the <link linkend="makefile-naming-revepoch">corresponding @@ -95,9 +95,9 @@ <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 + notification serves two purposes. First, if the danger is really severe it will be wise to apply an instant workaround. - E.g., stop the affected network service or even deinstall the + For example, 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 @@ -114,6 +114,7 @@ also monitor it for issues requiring their intervention.</para> + <!-- XXX: Too much "you" in there --> <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 @@ -129,10 +130,10 @@ 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 + time a security vulnerability is discovered in a port, please + add an entry for it to that file. Until familiar with + VuXML, the best thing to do is to find an existing entry + fitting the case at hand, then copy it and use it as a template.</para> </sect2> @@ -141,14 +142,14 @@ <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. + insight on the structure of a VuXML entry only the notion of + tags is needed. 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 + tags, that is, 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 + e<emphasis>X</emphasis>tensible, that is, 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 @@ -206,18 +207,18 @@ </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> + shall take a closer look only at fields which needs to be fill + in:</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 + quotes). 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> + UUID unless writing the entry from scratch). + use &man.uuidgen.1; to generate a VuXML UUID.</para> </callout> <callout arearefs="co-vx-top"> @@ -234,10 +235,10 @@ important build-time configuration options.</para> <important> - <para>It is your responsibility to find all such related + <para>It is the submitter's 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> + <literal>make search name=foo</literal> is helpful. + The primary points to look for are:</para> <itemizedlist> <listitem> @@ -269,8 +270,8 @@ <literal><le></literal>, <literal><eq></literal>, <literal><ge></literal>, and - <literal><gt></literal> elements. The version - ranges given should not overlap.</para> + <literal><gt></literal> elements. Check the version + ranges given do not overlap.</para> <para>In a range specification, <literal>*</literal> (asterisk) denotes the smallest version number. In @@ -304,13 +305,13 @@ </callout> <callout arearefs="co-vx-epo"> - <para>The version ranges should allow for + <para>The version ranges have to 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 + for example, <literal>3.0,1</literal> is greater than <literal>3.1</literal> or even than <literal>8.9</literal>.</para> </callout> @@ -318,7 +319,7 @@ <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 + and <literal></p></literal> has to appear. More complex mark-up may be used, but only for the sake of accuracy and clarity: No eye candy please.</para> </callout> @@ -337,7 +338,7 @@ <callout arearefs="co-vx-fpr"> <para>This is a <link - xlink:href="http://www.freebsd.org/support.html#gnats">&os; + xlink:href="http://www.freebsd.org/support.html">&os; problem report</link>.</para> </callout> @@ -384,7 +385,7 @@ </callout> <callout arearefs="co-vx-url"> - <para>This is a generic URL. It should be used only if none + <para>This is a generic URL. Only it if none of the other reference categories apply.</para> </callout> @@ -401,37 +402,37 @@ <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> + New entries must not include this field. Add it when + editing an existing entry.</para> </callout> </calloutlist> </sect2> <sect2 xml:id="security-notify-vuxml-testing"> - <title>Testing Your Changes to the VuXML Database</title> + <title>Testing Changes to the VuXML Database</title> - <para>Assume you just wrote or filled in an entry for a + <para>Assume a new 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 + <para>As a prerequisite, <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 + <para>The user running <command>packaudit</command> 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 + <para>To use a different directory, set the + <varname>DATABASEDIR</varname> 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 + <para>If working in a directory other than + <filename>${PORTSDIR}/security/vuxml</filename>, set the + <varname>VUXMLDIR</varname> environment variable to the directory where <filename>vuln.xml</filename> is located.</para> </note> @@ -444,18 +445,18 @@ <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 + <para>If there is none found, add a new entry for this vulnerability.</para> <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>Verify its syntax and formatting:</para> <screen>&prompt.user; <userinput>make validate</userinput></screen> <note> - <para>You will need at least one of the following packages + <para>At least one of these packages needs to be installed: <package role="port">textproc/libxml2</package>, <package role="port">textproc/jade</package>.</para> </note> @@ -466,8 +467,8 @@ <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> + section of the entry will match correct package(s), issue this + command:</para> <screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r <replaceable>uuid</replaceable></userinput></screen> @@ -476,11 +477,11 @@ understanding of the command syntax.</para> </note> - <para>Make sure that your entry produces no spurious matches in + <para>Make sure that the entry produces no spurious matches in the output.</para> <para>Now check whether the right package versions are matched - by your entry:</para> + by the 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<0.65_7) @@ -489,8 +490,8 @@ Reference: <http://www.freebsd.org/po 1 problem(s) found.</screen> - <para>The former version should match while the latter one - should not.</para> + <para>The former version matches while the latter one + does not.</para> <para>Finally, verify whether the web page generated from the VuXML database looks like expected:</para>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409161158.s8GBwoHU024492>