Index: head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml +++ head/en_US.ISO8859-1/books/porters-handbook/security/chapter.xml @@ -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. @@ -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 mark the port as - FORBIDDEN 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, + FORBIDDEN 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 the standard procedure for - submitting your change should be followed unless you have + submitting changes unless having rights to commit it directly to the ports tree. Being a ports committer is not enough to commit to an arbitrary port. Remember that ports usually have maintainers, - whom you should respect. + must be respected. 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. PORTREVISION should be bumped unless + one. Bump PORTREVISION unless PORTVERSION has changed in the course of - correcting the vulnerability. That is you should bump - PORTREVISION 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 + PORTREVISION 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 PORTVERSION. Please refer to the corresponding @@ -95,9 +95,9 @@ 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. + 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 security/vuxml. Therefore the file's full pathname will be PORTSDIR/security/vuxml/vuln.xml. 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. @@ -141,14 +142,14 @@ The full-blown XML format is complex, and far beyond the scope of this book. However, to gain basic - insight on the structure of a VuXML entry you need only the - notion of tags. XML 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 - eXtensible, i.e., based on defining + eXtensible, 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> 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: + shall take a closer look only at fields which needs to be fill + in: This is the top-level tag of a VuXML entry. It has a mandatory attribute, vid, 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. + UUID unless writing the entry from scratch). + use &man.uuidgen.1; to generate a VuXML UUID. @@ -234,10 +235,10 @@ important build-time configuration options. - It is your responsibility to find all such related + It is the submitter's responsibility to find all such related packages when writing a VuXML entry. Keep in mind that - make search name=foo is your friend. - The primary points to look for are as follows: + make search name=foo is helpful. + The primary points to look for are: @@ -269,8 +270,8 @@ <le>, <eq>, <ge>, and - <gt> elements. The version - ranges given should not overlap. + <gt> elements. Check the version + ranges given do not overlap. In a range specification, * (asterisk) denotes the smallest version number. In @@ -304,13 +305,13 @@ - The version ranges should allow for + The version ranges have to allow for PORTEPOCH and PORTREVISION if applicable. Please remember that according to the collation rules, a version with a non-zero PORTEPOCH is greater than any version without PORTEPOCH, - e.g., 3.0,1 is greater than + for example, 3.0,1 is greater than 3.1 or even than 8.9. @@ -318,7 +319,7 @@ This is a summary of the issue. XHTML is used in this field. At least enclosing <p> - and </p> should appear. More + and </p> has to appear. More complex mark-up may be used, but only for the sake of accuracy and clarity: No eye candy please. @@ -337,7 +338,7 @@ This is a &os; + xlink:href="http://www.freebsd.org/support.html">&os; problem report. @@ -384,7 +385,7 @@ - This is a generic URL. It should be used only if none + This is a generic URL. Only it if none of the other reference categories apply. @@ -401,37 +402,37 @@ This is the date when any information in the entry was last modified (YYYY-MM-DD). - New entries must not include this field. It should be - added upon editing an existing entry. + New entries must not include this field. Add it when + editing an existing entry. - Testing Your Changes to the VuXML Database + Testing Changes to the VuXML Database - Assume you just wrote or filled in an entry for a + Assume a new entry for a vulnerability in the package clamav that has been fixed in version 0.65_7. - As a prerequisite, you need to + As a prerequisite, install fresh versions of the ports ports-mgmt/portaudit, ports-mgmt/portaudit-db, and security/vuxml. - To run packaudit you must have + The user running packaudit must have permission to write to its DATABASEDIR, typically /var/db/portaudit. - To use a different directory set the - DATABASEDIR environment variable to a + To use a different directory, set the + DATABASEDIR environment variable to a different location. - If you are working in a directory other than - ${PORTSDIR}/security/vuxml set the - VUXMLDIR environment variable to the + If working in a directory other than + ${PORTSDIR}/security/vuxml, set the + VUXMLDIR environment variable to the directory where vuln.xml is located. @@ -444,18 +445,18 @@ &prompt.user; packaudit &prompt.user; portaudit clamav-0.65_6 - If there is none found, you have the green light to add a + If there is none found, add a new entry for this vulnerability. &prompt.user; cd ${PORTSDIR}/security/vuxml &prompt.user; make newentry - When you are done verify its syntax and formatting. + Verify its syntax and formatting: &prompt.user; make validate - You will need at least one of the following packages + At least one of these packages needs to be installed: textproc/libxml2, textproc/jade. @@ -466,8 +467,8 @@ &prompt.user; packaudit To verify that the <affected> - section of your entry will match correct package(s), issue the - following command: + section of the entry will match correct package(s), issue this + command: &prompt.user; portaudit -f /usr/ports/INDEX -r uuid @@ -476,11 +477,11 @@ understanding of the command syntax. - Make sure that your entry produces no spurious matches in + Make sure that the entry produces no spurious matches in the output. Now check whether the right package versions are matched - by your entry: + by the entry: &prompt.user; portaudit clamav-0.65_6 clamav-0.65_7 Affected package: clamav-0.65_6 (matched by clamav<0.65_7) @@ -489,8 +490,8 @@ 1 problem(s) found. - The former version should match while the latter one - should not. + The former version matches while the latter one + does not. Finally, verify whether the web page generated from the VuXML database looks like expected: