SECURITY.rst

   1 ================
   2 Security Process
   3 ================
   4
   5 This is a proposed security vulnerability reporting and handling process for
   6 Open vSwitch. It is based on the OpenStack vulnerability management process
   7 described at https://wiki.openstack.org/wiki/Vulnerability\_Management.
   8
   9 The OVS security team coordinates vulnerability management using the
  10 ovs-security mailing list. Membership in the security team and subscription to
  11 its mailing list consists of a small number of trustworthy people, as
  12 determined by rough consensus of the Open vSwitch committers on the
  13 ovs-committers mailing list. The Open vSwitch security team should include Open
  14 vSwitch committers, to ensure prompt and accurate vulnerability assessments and
  15 patch review.
  16
  17 We encourage everyone involved in the security process to GPG-sign their
  18 emails. We additionally encourage GPG-encrypting one-on-one conversations as
  19 part of the security process.
  20
  21 What is a vulnerability?
  22 ------------------------
  23
  24 All vulnerabilities are bugs, but not every bug is a vulnerability.
  25 Vulnerabilities compromise one or more of:
  26
  27 * Confidentiality (personal or corporate confidential data).
  28
  29 * Integrity (trustworthiness and correctness).
  30
  31 * Availability (uptime and service).
  32
  33 Here are some examples of vulnerabilities to which one would expect to apply
  34 this process:
  35
  36 * A crafted packet that causes a kernel or userspace crash (Availability).
  37
  38 * A flow translation bug that misforwards traffic in a way likely to hop over
  39   security boundaries (Integrity).
  40
  41 * An OpenFlow protocol bug that allows a controller to read arbitrary files
  42   from the file system (Confidentiality).
  43
  44 * Misuse of the OpenSSL library that allows bypassing certificate checks
  45   (Integrity).
  46
  47 * A bug (memory corruption, overflow, ...) that allows one to modify the
  48   behaviour of OVS through external configuration interfaces such as OVSDB
  49   (Integrity).
  50
  51 * Privileged information is exposed to unprivileged users (Confidentiality).
  52
  53 If in doubt, please do use the vulnerability management process. At worst, the
  54 response will be to report the bug through the usual channels.
  55
  56 Step 1: Reception
  57 -----------------
  58
  59 To report an Open vSwitch vulnerability, send an email to the ovs-security
  60 mailing list (see contact_ at the end of this document). A security team
  61 member should reply to the reporter acknowledging that the report has been
  62 received.
  63
  64 Consider reporting the information mentioned in `REPORTING-BUGS.rst
  65 <REPORTING-BUGS.rst>`__, where relevant.
  66
  67 Reporters may ask for a GPG key while initiating contact with the security team
  68 to deliver more sensitive reports.
  69
  70 The Linux kernel has its own vulnerability management process:
  71 https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SecurityBugs
  72 Handling of vulnerabilities that affect both the Open vSwitch tree and the
  73 upstream Linux kernel should be reported through both processes.  Send your
  74 report as a single email to both the kernel and OVS security teams to allow
  75 those teams to most easily coordinate among themselves.
  76
  77 Step 2: Assessment
  78 ------------------
  79
  80 The security team should discuss the vulnerability. The reporter should be
  81 included in the discussion (via "CC") to an appropriate degree.
  82
  83 The assessment should determine which Open vSwitch versions are affected (e.g.
  84 every version, only the latest release, only unreleased versions), the
  85 privilege required to take advantage of the vulnerability (e.g. any network
  86 user, any local L2 network user, any local system user, connected OpenFlow
  87 controllers), the severity of the vulnerability, and how the vulnerability may
  88 be mitigated (e.g. by disabling a feature).
  89
  90 The treatment of the vulnerability could end here if the team determines that
  91 it is not a realistic vulnerability.
  92
  93 Step 3a: Document
  94 -----------------
  95
  96 The security team develops a security advisory document. The security team may,
  97 at its discretion, include the reporter (via "CC") in developing the security
  98 advisory document, but in any case should accept feedback from the reporter
  99 before finalizing the document. When the document is final, the security team
 100 should obtain a CVE for the vulnerability from a CNA
 101 (https://cve.mitre.org/cve/cna.html).
 102
 103 The document credits the reporter and describes the vulnerability, including
 104 all of the relevant information from the assessment in step 2.  Suitable
 105 sections for the document include:
 106
 107 ::
 108
 109     * Title: The CVE identifier, a short description of the
 110       vulnerability.  The title should mention Open vSwitch.
 111
 112       In email, the title becomes the subject.  Pre-release advisories
 113       are often passed around in encrypted email, which have plaintext
 114       subjects, so the title should not be too specific.
 115
 116     * Description: A few paragraphs describing the general
 117       characteristics of the vulnerability, including the versions of
 118       Open vSwitch that are vulnerable, the kind of attack that
 119       exposes the vulnerability, and potential consequences of the
 120       attack.
 121
 122       The description should re-state the CVE identifier, in case the
 123       subject is lost when an advisory is sent over email.
 124
 125     * Mitigation: How an Open vSwitch administrator can minimize the
 126       potential for exploitation of the vulnerability, before applying
 127       a fix.  If no mitigation is possible or recommended, explain
 128       why, to reduce the chance that at-risk users believe they are
 129       not at risk.
 130
 131     * Fix: Describe how to fix the vulnerability, perhaps in terms of
 132       applying a source patch.  The patch or patches themselves, if
 133       included in the email, should be at the very end of the advisory
 134       to reduce the risk that a reader would stop reading at this
 135       point.
 136
 137     * Recommendation: A concise description of the security team's
 138       recommendation to users.
 139
 140     * Acknowledgments: Thank the reporters.
 141
 142     * Vulnerability Check: A step-by-step procedure by which a user
 143       can determine whether an installed copy of Open vSwitch is
 144       vulnerable.
 145
 146       The procedure should clearly describe how to interpret the
 147       results, including expected results in vulnerable and
 148       not-vulnerable cases.  Thus, procedures that produce clear and
 149       easily distinguished results are preferred.
 150
 151       The procedure should assume as little understanding of Open
 152       vSwitch as possible, to make it more likely that a competent
 153       administrator who does not specialize in Open vSwitch can
 154       perform it successfully.
 155
 156       The procedure should have minimal dependencies on tools that are
 157       not widely installed.
 158
 159       Given a choice, the procedure should be one that takes at least
 160       some work to turn into a useful exploit.  For example, a
 161       procedure based on "ovs-appctl" commands, which require local
 162       administrator access, is preferred to one that sends test
 163       packets to a machine, which only requires network connectivity.
 164
 165       The section should say which operating systems it is designed
 166       for.  If the procedure is likely to be specific to particular
 167       architectures (e.g. x86-64, i386), it should state on which ones
 168       it has been tested.
 169
 170       This section should state the risks of the procedure.  For
 171       example, if it can crash Open vSwitch or disrupt packet
 172       forwarding, say so.
 173
 174       It is more useful to explain how to check an installed and
 175       running Open vSwitch than one built locally from source, but if
 176       it is easy to use the procedure from a sandbox environment, it
 177       can be helpful to explain how to do so.
 178
 179     * Patch: If a patch or patches are available, and it is practical
 180       to include them in the email, put them at the end.  Format them
 181       as described in CONTRIBUTING.md, that is, as output by "git
 182       format-patch".
 183
 184       The patch subjects should include the version for which they are
 185       suited, e.g. "[PATCH branch-2.3]" for a patch against Open
 186       vSwitch 2.3.x.  If there are multiple patches for multiple
 187       versions of Open vSwitch, put them in separate sections with
 188       clear titles.
 189
 190       Multiple patches for a single version of Open vSwitch, that must
 191       be stacked on top of each other to fix a single vulnerability,
 192       are undesirable because users are less likely to apply all of
 193       them correctly and in the correct order.
 194
 195       Each patch should include a Vulnerability tag with the CVE
 196       identifier, a Reported-by tag or tags to credit the reporters,
 197       and a Signed-off-by tag to acknowledge the Developer's
 198       Certificate of Origin.  It should also include other appropriate
 199       tags, such as Acked-by tags obtained during review.
 200
 201 CVE-2016-2074 is an example advisory document, available at:
 202 http://openvswitch.org/pipermail/announce/2016-March/000082.html
 203
 204 Step 3b: Fix
 205 ------------
 206
 207 Steps 3a and 3b may proceed in parallel.
 208
 209 The security team develops and obtains (private) reviews for patches that fix
 210 the vulnerability. If necessary, the security team pulls in additional
 211 developers, who must agree to maintain confidentiality.
 212
 213 Step 4: Embargoed Disclosure
 214 ----------------------------
 215
 216 The security advisory and patches are sent to downstream stakeholders, with an
 217 embargo date and time set from the time sent. Downstream stakeholders are
 218 expected not to deploy or disclose patches until the embargo is passed.
 219
 220 A disclosure date is negotiated by the security team working with the bug
 221 submitter as well as vendors. However, the Open vSwitch security team holds the
 222 final say when setting a disclosure date. The timeframe for disclosure is from
 223 immediate (esp. if it's already publicly known) to a few weeks. As a basic
 224 default policy, we expect report date to disclosure date to be 10 to 15
 225 business days.
 226
 227 Operating system vendors are obvious downstream stakeholders. It may not be
 228 necessary to be too choosy about who to include: any major Open vSwitch user
 229 who is interested and can be considered trustworthy enough could be included.
 230 To become a downstream stakeholder, email the ovs-security mailing list.
 231
 232 If the vulnerability is already public, skip this step.
 233
 234 Step 5: Public Disclosure
 235 -------------------------
 236
 237 When the embargo expires, push the (reviewed) patches to appropriate branches,
 238 post the patches to the ovs-dev mailing list (noting that they have already
 239 been reviewed and applied), post the security advisory to appropriate mailing
 240 lists (ovs-announce, ovs-discuss), and post the security advisory on the Open
 241 vSwitch webpage.
 242
 243 When the patch is applied to LTS (long-term support) branches, a new version
 244 should be released.
 245
 246 The security advisory should be GPG-signed by a security team member with a key
 247 that is in a public web of trust.
 248
 249 .. _contact:
 250
 251 Contact
 252 =======
 253
 254 Report security vulnerabilities to the ovs-security mailing list:
 255 security@openvswitch.org
 256
 257 Report problems with this document to the ovs-bugs mailing list:
 258 bugs@openvswitch.org