SECURITY.md

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