svn commit: r45615 - head/en_US.ISO8859-1/books/porters-handbook/security
Mathieu Arnold
mat at FreeBSD.org
Tue Sep 16 11:58:51 UTC 2014
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>
More information about the svn-doc-head
mailing list