[ovs-dev] [PATCH 08/15] doc: Convert SECURITY to rST

Stephen Finucane stephen at that.guru
Tue Oct 18 20:03:38 UTC 2016 

This is a top-level document, so plain old rST is preferred.

Signed-off-by: Stephen Finucane <stephen at that.guru>
---
 Makefile.am                 |   2 +-
 REPORTING-BUGS.rst          |   2 +-
 SECURITY.md => SECURITY.rst | 198 +++++++++++++++++++++-----------------------
 3 files changed, 95 insertions(+), 107 deletions(-)
 rename SECURITY.md => SECURITY.rst (55%)

diff --git a/Makefile.am b/Makefile.am
index 9373a04..9be391b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -93,7 +93,7 @@ docs = \
 	README-lisp.md \
 	README-native-tunneling.md \
 	REPORTING-BUGS.rst \
-	SECURITY.md \
+	SECURITY.rst \
 	WHY-OVS.rst
 EXTRA_DIST = \
 	$(docs) \
diff --git a/REPORTING-BUGS.rst b/REPORTING-BUGS.rst
index 73e0df3..85b60ea 100644
--- a/REPORTING-BUGS.rst
+++ b/REPORTING-BUGS.rst
@@ -31,7 +31,7 @@ they can be fixed as quickly as possible.
 
 Please report bugs by sending email to bugs at openvswitch.org.
 
-For reporting security vulnerabilities, please read SECURITY.md.
+For reporting security vulnerabilities, please read SECURITY.rst.
 
 The most important parts of your bug report are the following:
 
diff --git a/SECURITY.md b/SECURITY.rst
similarity index 55%
rename from SECURITY.md
rename to SECURITY.rst
index 4cc4ed6..31155a5 100644
--- a/SECURITY.md
+++ b/SECURITY.rst
@@ -1,23 +1,22 @@
+================
 Security Process
 ================
 
-This is a proposed security vulnerability reporting and handling
-process for Open vSwitch.  It is based on the OpenStack vulnerability
-management process described at
-https://wiki.openstack.org/wiki/Vulnerability_Management.
+This is a proposed security vulnerability reporting and handling process for
+Open vSwitch. It is based on the OpenStack vulnerability management process
+described at https://wiki.openstack.org/wiki/Vulnerability\_Management.
 
 The OVS security team coordinates vulnerability management using the
-ovs-security mailing list.  Membership in the security team and
-subscription to its mailing list consists of a small number of
-trustworthy people, as determined by rough consensus of the Open
-vSwitch committers on the ovs-committers mailing list.  The Open
-vSwitch security team should include Open vSwitch committers, to
-ensure prompt and accurate vulnerability assessments and patch review.
-
-We encourage everyone involved in the security process to GPG-sign
-their emails.  We additionally encourage GPG-encrypting one-on-one
-conversations as part of the security process.
+ovs-security mailing list. Membership in the security team and subscription to
+its mailing list consists of a small number of trustworthy people, as
+determined by rough consensus of the Open vSwitch committers on the
+ovs-committers mailing list. The Open vSwitch security team should include Open
+vSwitch committers, to ensure prompt and accurate vulnerability assessments and
+patch review.
 
+We encourage everyone involved in the security process to GPG-sign their
+emails. We additionally encourage GPG-encrypting one-on-one conversations as
+part of the security process.
 
 What is a vulnerability?
 ------------------------
@@ -25,92 +24,87 @@ What is a vulnerability?
 All vulnerabilities are bugs, but not every bug is a vulnerability.
 Vulnerabilities compromise one or more of:
 
-    * Confidentiality (personal or corporate confidential data).
-    * Integrity (trustworthiness and correctness).
-    * Availability (uptime and service).
+* Confidentiality (personal or corporate confidential data).
+
+* Integrity (trustworthiness and correctness).
 
-Here are some examples of vulnerabilities to which one would expect to
-apply this process:
+* Availability (uptime and service).
 
-    * A crafted packet that causes a kernel or userspace crash
-      (Availability).
+Here are some examples of vulnerabilities to which one would expect to apply
+this process:
 
-    * A flow translation bug that misforwards traffic in a way likely
-      to hop over security boundaries (Integrity).
+* A crafted packet that causes a kernel or userspace crash (Availability).
 
-    * An OpenFlow protocol bug that allows a controller to read
-      arbitrary files from the file system (Confidentiality).
+* A flow translation bug that misforwards traffic in a way likely to hop over
+  security boundaries (Integrity).
 
-    * Misuse of the OpenSSL library that allows bypassing certificate
-      checks (Integrity).
+* An OpenFlow protocol bug that allows a controller to read arbitrary files
+  from the file system (Confidentiality).
 
-    * A bug (memory corruption, overflow, ...) that allows one to
-      modify the behaviour of OVS through external configuration
-      interfaces such as OVSDB (Integrity).
+* Misuse of the OpenSSL library that allows bypassing certificate checks
+  (Integrity).
 
-    * Privileged information is exposed to unprivileged users
-      (Confidentiality).
+* A bug (memory corruption, overflow, ...) that allows one to modify the
+  behaviour of OVS through external configuration interfaces such as OVSDB
+  (Integrity).
 
-If in doubt, please do use the vulnerability management process.  At
-worst, the response will be to report the bug through the usual
-channels.
+* Privileged information is exposed to unprivileged users (Confidentiality).
 
+If in doubt, please do use the vulnerability management process. At worst, the
+response will be to report the bug through the usual channels.
 
 Step 1: Reception
 -----------------
 
-To report an Open vSwitch vulnerability, send an email to the
-ovs-security mailing list (see "Contact" at the end of this document).
-A security team member should reply to the reporter acknowledging that
-the report has been received.
+To report an Open vSwitch vulnerability, send an email to the ovs-security
+mailing list (see contact_ at the end of this document). A security team
+member should reply to the reporter acknowledging that the report has been
+received.
 
-Please consider reporting the information mentioned in
-REPORTING-BUGS.rst, where relevant.
+Consider reporting the information mentioned in `REPORTING-BUGS.rst
+<REPORTING-BUGS.rst>`, where relevant.
 
-Reporters may ask for a GPG key while initiating contact with the
-security team to deliver more sensitive reports.
+Reporters may ask for a GPG key while initiating contact with the security team
+to deliver more sensitive reports.
 
 The Linux kernel has its own vulnerability management process:
 https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SecurityBugs
-Handling of vulnerabilities that affect both the Open vSwitch tree and
-the upstream Linux kernel should be reported through both processes.
-Please send your report as a single email to both the kernel and OVS
-security teams to allow those teams to most easily coordinate among
-themselves.
-
+Handling of vulnerabilities that affect both the Open vSwitch tree and the
+upstream Linux kernel should be reported through both processes.  Send your
+report as a single email to both the kernel and OVS security teams to allow
+those teams to most easily coordinate among themselves.
 
 Step 2: Assessment
 ------------------
 
-The security team should discuss the vulnerability.  The reporter
-should be included in the discussion (via "CC") to an appropriate
-degree.
-
-The assessment should determine which Open vSwitch versions are
-affected (e.g. every version, only the latest release, only unreleased
-versions), the privilege required to take advantage of the
-vulnerability (e.g. any network user, any local L2 network user, any
-local system user, connected OpenFlow controllers), the severity of
-the vulnerability, and how the vulnerability may be mitigated (e.g. by
-disabling a feature).
+The security team should discuss the vulnerability. The reporter should be
+included in the discussion (via "CC") to an appropriate degree.
 
-The treatment of the vulnerability could end here if the team
-determines that it is not a realistic vulnerability.
+The assessment should determine which Open vSwitch versions are affected (e.g.
+every version, only the latest release, only unreleased versions), the
+privilege required to take advantage of the vulnerability (e.g. any network
+user, any local L2 network user, any local system user, connected OpenFlow
+controllers), the severity of the vulnerability, and how the vulnerability may
+be mitigated (e.g. by disabling a feature).
 
+The treatment of the vulnerability could end here if the team determines that
+it is not a realistic vulnerability.
 
 Step 3a: Document
-----------------
+-----------------
 
-The security team develops a security advisory document.  The security
-team may, at its discretion, include the reporter (via "CC") in
-developing the security advisory document, but in any case should
-accept feedback from the reporter before finalizing the document.
-When the document is final, the security team should obtain a CVE for
-the vulnerability from a CNA (https://cve.mitre.org/cve/cna.html).
+The security team develops a security advisory document. The security team may,
+at its discretion, include the reporter (via "CC") in developing the security
+advisory document, but in any case should accept feedback from the reporter
+before finalizing the document. When the document is final, the security team
+should obtain a CVE for the vulnerability from a CNA
+(https://cve.mitre.org/cve/cna.html).
 
-The document credits the reporter and describes the vulnerability,
-including all of the relevant information from the assessment in step
-2.  Suitable sections for the document include:
+The document credits the reporter and describes the vulnerability, including
+all of the relevant information from the assessment in step 2.  Suitable
+sections for the document include:
+
+::
 
     * Title: The CVE identifier, a short description of the
       vulnerability.  The title should mention Open vSwitch.
@@ -205,58 +199,54 @@ including all of the relevant information from the assessment in step
       tags, such as Acked-by tags obtained during review.
 
 CVE-2016-2074 is an example advisory document, available at:
-	http://openvswitch.org/pipermail/announce/2016-March/000082.html
-
+http://openvswitch.org/pipermail/announce/2016-March/000082.html
 
 Step 3b: Fix
 ------------
 
 Steps 3a and 3b may proceed in parallel.
 
-The security team develops and obtains (private) reviews for patches
-that fix the vulnerability.  If necessary, the security team pulls in
-additional developers, who must agree to maintain confidentiality.
-
+The security team develops and obtains (private) reviews for patches that fix
+the vulnerability. If necessary, the security team pulls in additional
+developers, who must agree to maintain confidentiality.
 
 Step 4: Embargoed Disclosure
 ----------------------------
 
-The security advisory and patches are sent to downstream stakeholders,
-with an embargo date and time set from the time sent.  Downstream
-stakeholders are expected not to deploy or disclose patches until
-the embargo is passed.
+The security advisory and patches are sent to downstream stakeholders, with an
+embargo date and time set from the time sent. Downstream stakeholders are
+expected not to deploy or disclose patches until the embargo is passed.
 
-A disclosure date is negotiated by the security team working with the
-bug submitter as well as vendors.  However, the Open vSwitch security
-team holds the final say when setting a disclosure date.  The timeframe
-for disclosure is from immediate (esp. if it's already publicly known)
-to a few weeks.  As a basic default policy, we expect report date to
-disclosure date to be 10 to 15 business days.
+A disclosure date is negotiated by the security team working with the bug
+submitter as well as vendors. However, the Open vSwitch security team holds the
+final say when setting a disclosure date. The timeframe for disclosure is from
+immediate (esp. if it's already publicly known) to a few weeks. As a basic
+default policy, we expect report date to disclosure date to be 10 to 15
+business days.
 
-Operating system vendors are obvious downstream stakeholders.  It may
-not be necessary to be too choosy about who to include: any major Open
-vSwitch user who is interested and can be considered trustworthy
-enough could be included.  To become a downstream stakeholder, email
-the ovs-security mailing list.
+Operating system vendors are obvious downstream stakeholders. It may not be
+necessary to be too choosy about who to include: any major Open vSwitch user
+who is interested and can be considered trustworthy enough could be included.
+To become a downstream stakeholder, email the ovs-security mailing list.
 
 If the vulnerability is already public, skip this step.
 
-
 Step 5: Public Disclosure
 -------------------------
 
-When the embargo expires, push the (reviewed) patches to appropriate
-branches, post the patches to the ovs-dev mailing list (noting that
-they have already been reviewed and applied), post the security
-advisory to appropriate mailing lists (ovs-announce, ovs-discuss), and
-post the security advisory on the Open vSwitch webpage.
+When the embargo expires, push the (reviewed) patches to appropriate branches,
+post the patches to the ovs-dev mailing list (noting that they have already
+been reviewed and applied), post the security advisory to appropriate mailing
+lists (ovs-announce, ovs-discuss), and post the security advisory on the Open
+vSwitch webpage.
 
-When the patch is applied to LTS (long-term support) branches, a new
-version should be released.
+When the patch is applied to LTS (long-term support) branches, a new version
+should be released.
 
-The security advisory should be GPG-signed by a security team member
-with a key that is in a public web of trust.
+The security advisory should be GPG-signed by a security team member with a key
+that is in a public web of trust.
 
+.. _contact:
 
 Contact
 =======
@@ -266,5 +256,3 @@ security at openvswitch.org
 
 Report problems with this document to the ovs-bugs mailing list:
 bugs at openvswitch.org
-
-Visit http://openvswitch.org/ to learn more about Open vSwitch.
-- 
2.7.4

More information about the dev mailing list