From owner-svn-doc-all@FreeBSD.ORG Sun Feb 16 02:24:39 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 044CBC61; Sun, 16 Feb 2014 02:24:39 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id DF31E1F71; Sun, 16 Feb 2014 02:24:38 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1G2OciE047741; Sun, 16 Feb 2014 02:24:38 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1G2Ocar047740; Sun, 16 Feb 2014 02:24:38 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402160224.s1G2Ocar047740@svn.freebsd.org> From: Warren Block Date: Sun, 16 Feb 2014 02:24:38 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 16 Feb 2014 02:24:39 -0000 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$ --> - + + + Security + + + Why Security is So Important + + 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. + + 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. + + 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. + + + + Fixing Security Vulnerabilities + + 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 + 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, + the standard procedure for + submitting your change should be followed unless you have + 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. + + + 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. PORTREVISION should be bumped 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 + the latest software version and thus already touched + PORTVERSION. Please refer to the + corresponding + section for more information. + + + + Keeping the Community Informed + + + The VuXML Database + + 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 + must update the package without delay as + soon as a corrected version is available. + + 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 + the &os; + VuXML database. The Security Officer Team members + 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 + 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 + &os; + Security Information page. + + The VuXML database is an XML document. + Its source file vuln.xml is kept right + 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 + template. + + + + A Short Introduction to VuXML + + 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. + 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 + eXtensible, 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. - Security + Now consider a realistic VuXML entry: - - Why Security is So Important - - 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. - - 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. - - 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. - - - - Fixing Security Vulnerabilities - - 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 - 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, - the standard procedure for - submitting your change should be followed unless you - have 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. - - - 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. - PORTREVISION should be bumped 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 the latest software version and thus already - touched PORTVERSION. Please refer to the - corresponding - section for more information. - - - - Keeping the Community Informed - - - The VuXML Database - - 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 must update the - package without delay as soon as a corrected version is - available. - - 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 - the &os; - VuXML database. The Security Officer Team members - 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 - 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 &os; - Security Information page. - - The VuXML database is an XML - document. Its source file vuln.xml is - kept right 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 - template. - - - - A Short Introduction to VuXML - - 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. 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 eXtensible, - 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. - - Now consider a realistic VuXML entry: - - <vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> + <vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <topic>Several vulnerabilities found in Foo</topic> <affects> <package> @@ -206,314 +205,300 @@ </dates> </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: - - - - 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 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. - - - - This is a one-line description of the issue - found. - - - - 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. - - - It is your 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: - - - - the foo-devel variant - for a foo port; - - - - other variants with a suffix like - -a4 (for print-related - packages), -without-gui (for - packages with X support disabled), or - similar; - - - - jp-, - ru-, zh-, - and other possible localized variants in the - corresponding national categories of the ports - collection. - - - - - - - Affected versions of the package(s) are specified - there as one or more ranges using a combination of - <lt>, - <le>, - <eq>, - <ge>, and - <gt> elements. The version - ranges given should not overlap. - - In a range specification, * - (asterisk) denotes the smallest version number. In - particular, 2.* is less than - 2.a. Therefore an asterisk may be - used for a range to match all possible - alpha, beta, and - RC versions. For instance, - <ge>2.*</ge><lt>3.*</lt> - will selectively match every 2.x - version while - <ge>2.0</ge><lt>3.0</lt> - will not since the latter misses - 2.r3 and matches - 3.b. - - The above example specifies that affected are - versions from 1.6 to - 1.9 inclusive, versions - 2.x before 2.4_1, - and version 3.0b1. - - - - Several related package groups (essentially, ports) - can be listed in the <affected> - 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. - - - - The version ranges should 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 - 3.1 or even than - 8.9. - - - - This is a summary of the issue. XHTML is used in - this field. At least enclosing - <p> and - </p> should appear. More - complex mark-up may be used, but only for the sake of - accuracy and clarity: No eye candy please. - - - - This section contains references to relevant - documents. As many references as apply are - encouraged. - - - - This is a &os; - security advisory. - - - - This is a &os; - problem report. - - - - This is a - MITRE - CVE identifier. - - - - This is a SecurityFocus - Bug ID. - - - - This is a - US-CERT - security advisory. - - - - This is a - US-CERT - vulnerability note. - - - - This is a - US-CERT - Cyber Security Alert. - - - - This is a - US-CERT - Technical Cyber Security Alert. - - - - This is a URL to an archived posting in a mailing - list. The attribute msgid is - optional and may specify the message ID of the - posting. - - - - This is a generic URL. It should be used only if - none of the other reference categories apply. - - - - This is the date when the issue was disclosed - (YYYY-MM-DD). - - - - This is the date when the entry was added - (YYYY-MM-DD). - - - - 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. - - - - - - Testing Your Changes to the VuXML Database - - Assume you just wrote or filled in an entry for a - vulnerability in the package clamav that - has been fixed in version 0.65_7. - - As a prerequisite, you need to - install fresh versions of the ports - ports-mgmt/portaudit, - ports-mgmt/portaudit-db, - and - security/vuxml. - - - To run packaudit you must have - permission to write to its - DATABASEDIR, - typically /var/db/portaudit. - - 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 directory where - vuln.xml is located. - - - 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, - 0.65_6: + 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: + + + + 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 + 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. + + + + This is a one-line description of the issue + found. + + + + 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. + + + It is your 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: + + + + the foo-devel variant for a + foo port; + + + + other variants with a suffix like + -a4 (for print-related packages), + -without-gui (for packages with X + support disabled), or similar; + + + + jp-, ru-, + zh-, and other possible localized + variants in the corresponding national categories of + the ports collection. + + + + + + + Affected versions of the package(s) are specified + there as one or more ranges using a combination of + <lt>, + <le>, + <eq>, + <ge>, and + <gt> elements. The version + ranges given should not overlap. + + In a range specification, * + (asterisk) denotes the smallest version number. In + particular, 2.* is less than + 2.a. Therefore an asterisk may be used + for a range to match all possible + alpha, beta, and + RC versions. For instance, + <ge>2.*</ge><lt>3.*</lt> + will selectively match every 2.x + version while + <ge>2.0</ge><lt>3.0</lt> + will not since the latter misses 2.r3 + and matches 3.b. + + The above example specifies that affected are versions + from 1.6 to 1.9 + inclusive, versions 2.x before + 2.4_1, and version + 3.0b1. + + + + Several related package groups (essentially, ports) + can be listed in the <affected> + 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. + + + + The version ranges should 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 + 3.1 or even than + 8.9. + + + + This is a summary of the issue. XHTML is used in this + field. At least enclosing <p> + and </p> should appear. More + complex mark-up may be used, but only for the sake of + accuracy and clarity: No eye candy please. + + + + This section contains references to relevant + documents. As many references as apply are + encouraged. + + + + This is a &os; + security advisory. + + + + This is a &os; + problem report. + + + + This is a + MITRE + CVE identifier. + + + + This is a SecurityFocus + Bug ID. + + + + This is a + US-CERT + security advisory. + + + + This is a + US-CERT + vulnerability note. + + + + This is a + US-CERT + Cyber Security Alert. + + + + This is a + US-CERT + Technical Cyber Security Alert. + + + + This is a URL to an archived posting in a mailing + list. The attribute msgid is optional + and may specify the message ID of the posting. + + + + This is a generic URL. It should be used only if none + of the other reference categories apply. + + + + This is the date when the issue was disclosed + (YYYY-MM-DD). + + + + This is the date when the entry was added + (YYYY-MM-DD). + + + + 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. + + + + + + Testing Your Changes to the VuXML Database + + Assume you just wrote or filled in an entry for a + vulnerability in the package clamav that + has been fixed in version 0.65_7. + + As a prerequisite, you need to + install fresh versions of the ports + ports-mgmt/portaudit, + ports-mgmt/portaudit-db, and + security/vuxml. + + + To run packaudit you must have + permission to write to its DATABASEDIR, + typically /var/db/portaudit. + + 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 + directory where vuln.xml is + located. + + + 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, + 0.65_6: - &prompt.user; packaudit + &prompt.user; packaudit &prompt.user; portaudit clamav-0.65_6 - If there is none found, you have the green light to add - a new entry for this vulnerability. + If there is none found, you have the green light to add a + new entry for this vulnerability. - &prompt.user; cd ${PORTSDIR}/security/vuxml + &prompt.user; cd ${PORTSDIR}/security/vuxml &prompt.user; make newentry - When you are done verify its syntax and - formatting. + When you are done verify its syntax and formatting. - &prompt.user; make validate + &prompt.user; make validate - - You will need at least one of the following packages - installed: - textproc/libxml2, - textproc/jade. - + + You will need at least one of the following packages + installed: textproc/libxml2, + textproc/jade. + - Now rebuild the portaudit database - from the VuXML file: + Now rebuild the portaudit database from + the VuXML file: - &prompt.user; packaudit + &prompt.user; packaudit - To verify that the <affected> - section of your entry will match correct package(s), issue - the following command: + To verify that the <affected> + section of your entry will match correct package(s), issue the + following command: - &prompt.user; portaudit -f /usr/ports/INDEX -r uuid + &prompt.user; portaudit -f /usr/ports/INDEX -r uuid - - Please refer to &man.portaudit.1; for better - understanding of the command syntax. - + + Please refer to &man.portaudit.1; for better + understanding of the command syntax. + - Make sure that your entry produces no spurious matches - in the output. + Make sure that your entry produces no spurious matches in + the output. - Now check whether the right package versions are matched - by your entry: + Now check whether the right package versions are matched + by your entry: - &prompt.user; portaudit clamav-0.65_6 clamav-0.65_7 + &prompt.user; portaudit clamav-0.65_6 clamav-0.65_7 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. - The former version should match while the latter one - should not. + The former version should match while the latter one + should not. - Finally, verify whether the web page generated from the - VuXML database looks like expected: + Finally, verify whether the web page generated from the + VuXML database looks like expected: - &prompt.user; mkdir -p ~/public_html/portaudit + &prompt.user; mkdir -p ~/public_html/portaudit &prompt.user; packaudit &prompt.user; lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html - - - + + +