Documentation/howto/coordinate-embargoed-releases.txt

   1 Content-type: text/asciidoc
   2 Abstract: When a critical vulnerability is discovered and fixed, we follow this
   3  script to coordinate a public release.
   4
   5 How we coordinate embargoed releases
   6 ====================================
   7
   8 To protect Git users from critical vulnerabilities, we do not just release
   9 fixed versions like regular maintenance releases. Instead, we coordinate
  10 releases with packagers, keeping the fixes under an embargo until the release
  11 date. That way, users will have a chance to upgrade on that date, no matter
  12 what Operating System or distribution they run.
  13
  14 Open a Security Advisory draft
  15 ------------------------------
  16
  17 The first step is to https://github.com/git/git/security/advisories/new[open an
  18 advisory]. Technically, it is not necessary, but it is convenient and saves a
  19 bit of hassle. This advisory can also be used to obtain the CVE number and it
  20 will give us a private fork associated with it that can be used to collaborate
  21 on a fix.
  22
  23 Release date of the embargoed version
  24 -------------------------------------
  25
  26 If the vulnerability affects Windows users, we want to have our friends over at
  27 Visual Studio on board. This means we need to target a "Patch Tuesday" (i.e. a
  28 second Tuesday of the month), at the minimum three weeks from heads-up to
  29 coordinated release.
  30
  31 If the vulnerability affects the server side, or can benefit from scans on the
  32 server side (i.e. if `git fsck` can detect an attack), it is important to give
  33 all involved Git repository hosting sites enough time to scan all of those
  34 repositories.
  35
  36 Notifying the Linux distributions
  37 ---------------------------------
  38
  39 At most two weeks before release date, we need to send a notification to
  40 distros@vs.openwall.org, preferably less than 7 days before the release date.
  41 This will reach most (all?) Linux distributions. See an example below, and the
  42 guidelines for this mailing list at
  43 https://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists[here].
  44
  45 Once the version has been published, we send a note about that to oss-security.
  46 As an example, see https://www.openwall.com/lists/oss-security/2019/12/13/1[the
  47 v2.24.1 mail];
  48 https://oss-security.openwall.org/wiki/mailing-lists/oss-security[Here] are
  49 their guidelines.
  50
  51 The mail to oss-security should also describe the exploit, and give credit to
  52 the reporter(s): security researchers still receive too little respect for the
  53 invaluable service they provide, and public credit goes a long way to keep them
  54 paid by their respective organizations.
  55
  56 Technically, describing any exploit can be delayed up to 7 days, but we usually
  57 refrain from doing that, including it right away.
  58
  59 As a courtesy we typically attach a Git bundle (as `.tar.xz` because the list
  60 will drop `.bundle` attachments) in the mail to distros@ so that the involved
  61 parties can take care of integrating/backporting them. This bundle is typically
  62 created using a command like this:
  63
  64         git bundle create cve-xxx.bundle ^origin/master vA.B.C vD.E.F
  65         tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle
  66
  67 Example mail to distros@vs.openwall.org
  68 ---------------------------------------
  69
  70 ....
  71 To: distros@vs.openwall.org
  72 Cc: git-security@googlegroups.com, <other people involved in the report/fix>
  73 Subject: [vs] Upcoming Git security fix release
  74
  75 Team,
  76
  77 The Git project will release new versions on <date> at 10am Pacific Time or
  78 soon thereafter. I have attached a Git bundle (embedded in a `.tar.xz` to avoid
  79 it being dropped) which you can fetch into a clone of
  80 https://github.com/git/git via `git fetch --tags /path/to/cve-xxx.bundle`,
  81 containing the tags for versions <versions>.
  82
  83 You can verify with `git tag -v <tag>` that the versions were signed by
  84 the Git maintainer, using the same GPG key as e.g. v2.24.0.
  85
  86 Please use these tags to prepare `git` packages for your various
  87 distributions, using the appropriate tagged versions. The added test cases
  88 help verify the correctness.
  89
  90 The addressed issues are:
  91
  92 <list of CVEs with a short description, typically copy/pasted from Git's
  93 release notes, usually demo exploit(s), too>
  94
  95 Credit for finding the vulnerability goes to <reporter>, credit for fixing
  96 it goes to <developer>.
  97
  98 Thanks,
  99 <name>
 100
 101 ....
 102
 103 Example mail to oss-security@lists.openwall.com
 104 -----------------------------------------------
 105
 106 ....
 107 To: oss-security@lists.openwall.com
 108 Cc: git-security@googlegroups.com, <other people involved in the report/fix>
 109 Subject: git: <copy from security advisory>
 110
 111 Team,
 112
 113 The Git project released new versions on <date>, addressing <CVE>.
 114
 115 All supported platforms are affected in one way or another, and all Git
 116 versions all the way back to <version> are affected. The fixed versions are:
 117 <versions>.
 118
 119 Link to the announcement: <link to lore.kernel.org/git>
 120
 121 We highly recommend to upgrade.
 122
 123 The addressed issues are:
 124 * <list of CVEs and their explanations, along with demo exploits>
 125
 126 Credit for finding the vulnerability goes to <reporter>, credit for fixing
 127 it goes to <developer>.
 128
 129 Thanks,
 130 <name>
 131 ....