From: Julia Ramer <gitprplr@xxxxxxxxx>
With the recent turnover on the git-security list, questions came up how
things are usually run. Rather than answering questions individually,
extend Git's existing documentation about security vulnerabilities to
describe the git-security mailing list, how things are run on that list,
and what to expect throughout the process from the time a security bug
is reported all the way to the time when a fix is released.
Signed-off-by: Julia Ramer <gitprplr@xxxxxxxxx>
---
embargoed releases: also describe the git-security list and the process
Changes since v1:
* Fixed the build
* Changed the wording based on various feedback
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1345%2Fprplr%2Fupdate_embargo_doc-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1345/prplr/update_embargo_doc-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1345
Range-diff vs v1:
1: 4d187f897d6 ! 1: 766c92e9031 embargoed releases: also describe the git-security list and the process
@@ Documentation/howto/coordinate-embargoed-releases.txt
+ security releases.
+
+The `git-security` mailing list
-+===============================
++-------------------------------
+
+Responsible disclosures of vulnerabilities, analysis, proposed fixes as
+well as the orchestration of coordinated embargoed releases all happen on the
@@ Documentation/howto/coordinate-embargoed-releases.txt
+embargo" refers to publishing the version that fixes the vulnerabilities.
+
+Audience of the `git-security` mailing list
-+-------------------------------------------
++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Anybody may contact the `git-security` mailing list by sending an email
+to <git-security@xxxxxxxxxxxxxxxx>, though the archive is closed to the
@@ Documentation/howto/coordinate-embargoed-releases.txt
+requirements.
+
+Communications
-+--------------
++~~~~~~~~~~~~~~
+
+If you are a stakeholder, it is a good idea to pay close attention to the
+discussions, as pertinent information may be buried in the middle of a lively
@@ Documentation/howto/coordinate-embargoed-releases.txt
+agreements, assessments or timelines.
+
+A bug's life: Typical timeline
-+==============================
++------------------------------
+
+- A bug is reported to the `git-security` mailing list.
+
@@ Documentation/howto/coordinate-embargoed-releases.txt
+ fork associated with the draft security advisory.
+
+- Once the review has settled and everyone involved in the review agrees that
-+ the patches are ready, the Git maintainer determines a release date as well
-+ as the release trains that are serviced. The decision regarding which versions
-+ need a backported fix is based on input from the reporter, the contributor who
-+ worked on the patches, and from stakeholders (e.g. operators of hosting sites
-+ who may want to analyze whether the given bug is exploited via any of the
-+ repositories they host).
++ the patches are ready, the Git maintainer, and others determine a release date
++ as well as the release trains that are serviced. The decision regarding which
++ versions need a backported fix is based on input from the reporter, the
++ contributor who worked on the patches, and from stakeholders (e.g. operators
++ of hosting sites who may want to analyze whether the given bug is exploited
++ via any of the repositories they host).
++
++- While the Git community does its best to accommodate the specific timeline
++ requests of the various binary packagers, the nature of the issue may preclude
++ a prolonged release schedule. For fixes deemed urgent, it may be in the best
++ interest of the Git users community to shorten the disclosure and release
++ timeline, and packagers may need to adapt accordingly.
+
+- Subsequently, branches with the fixes are pushed to private repositories that
+ are owned by the Git project, with tightly controlled access.
@@ Documentation/howto/coordinate-embargoed-releases.txt
+- The tags are created by the Git maintainer and pushed to the same
+ repositories.
+
++- The Git for Windows, Git for macOS, BSD, Debian, etc maintainers prepares the
++ corresponding release artifacts, based on the tags created that have been
++ prepared by the Git maintainer.
++
++- Git for Windows release artifacts are made available under embargo to
++ stakeholders via a mail to the `git-security` list.
++
+- Less than a week before the release, a mail with the relevant information is
-+ sent to <distros@xxxxxxxxxxxxxxx> (see below), a list used to pre-announce embargoed
-+ releases of open source projects to the stakeholders of all major Linux
-+ distributions. This includes a Git bundle of the tagged version(s), but no
-+ further specifics of the vulnerability.
++ sent to <distros@xxxxxxxxxxxxxxx> (see below), a list used to pre-announce
++ embargoed releases of open source projects to the stakeholders of all major
++ Linux distributions. This includes a Git bundle of the tagged version(s), but
++ no further specifics of the vulnerability.
+
+- Public communication is then prepared in advance of the release date. This
+ includes blog posts and mails to the Git and Git for Windows mailing lists.
+
-+- The Git for Windows maintainer prepares the corresponding release artifacts,
-+ based on the tags created that have been prepared by the Git maintainer.
-+
-+- Git for Windows release artifacts are made available under embargo to
-+ stakeholders via a mail to the `git-security` list.
-+
+- On the day of the release, at around 10am Pacific Time, the Git maintainer
+ pushes the tag and the `master` branch to the public repository, then sends
+ out an announcement mail.
@@ Documentation/howto/coordinate-embargoed-releases.txt
+- Git for Windows release is then announced via a mail to the public Git and
+ Git for Windows mailing lists as well as via a tweet.
+
-+- A mail to <oss-security@xxxxxxxxxxxxxxxxxx> (see below for details) is sent as a
-+ follow-up to the <distros@xxxxxxxxxxxxxxx> one, describing the vulnerability in
-+ detail, often including a proof of concept of an exploit.
++- Ditto for Linux distribution packagers: their releases are announced via
++ their preferred channels.
++
++- A mail to <oss-security@xxxxxxxxxxxxxxxxxx> (see below for details) is sent
++ as a follow-up to the <distros@xxxxxxxxxxxxxxx> one, describing the
++ vulnerability in detail, often including a proof of concept of an exploit.
+
+Note: The Git project makes no guarantees about timelines, but aims to keep
+embargoes reasonably short in the interest of keeping Git's users safe.
How we coordinate embargoed releases
- ====================================
-@@ Documentation/howto/coordinate-embargoed-releases.txt: what Operating System or distribution they run.
- Open a Security Advisory draft
- ------------------------------
+-====================================
++------------------------------------
+ To protect Git users from critical vulnerabilities, we do not just release
+ fixed versions like regular maintenance releases. Instead, we coordinate
+@@ Documentation/howto/coordinate-embargoed-releases.txt: date. That way, users will have a chance to upgrade on that date, no matter
+ what Operating System or distribution they run.
+
+ Open a Security Advisory draft
+-------------------------------
+-
-The first step is to https://github.com/git/git/security/advisories/new[open an
-advisory]. Technically, it is not necessary, but it is convenient and saves a
-bit of hassle. This advisory can also be used to obtain the CVE number and it
-will give us a private fork associated with it that can be used to collaborate
-on a fix.
--
++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
-Release date of the embargoed version
--------------------------------------
-
@@ Documentation/howto/coordinate-embargoed-releases.txt: what Operating System or
+associated with it that can be used to collaborate on a fix.
Notifying the Linux distributions
- ---------------------------------
+----------------------------------
++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At most two weeks before release date, we need to send a notification to
-distros@xxxxxxxxxxxxxxx, preferably less than 7 days before the release date.
@@ Documentation/howto/coordinate-embargoed-releases.txt: what Operating System or
This will reach most (all?) Linux distributions. See an example below, and the
guidelines for this mailing list at
https://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists[here].
+@@ Documentation/howto/coordinate-embargoed-releases.txt: created using a command like this:
+ tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle
+
+ Example mail to distros@xxxxxxxxxxxxxxx
+----------------------------------------
++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ ....
+ To: distros@xxxxxxxxxxxxxxx
+@@ Documentation/howto/coordinate-embargoed-releases.txt: Thanks,
+ ....
+
+ Example mail to oss-security@xxxxxxxxxxxxxxxxxx
+------------------------------------------------
++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ ....
+ To: oss-security@xxxxxxxxxxxxxxxxxx
+@@ Documentation/howto/coordinate-embargoed-releases.txt: it goes to <developer>.
+
+ Thanks,
+ <name>
+-....
++....
+ \ No newline at end of file
.../howto/coordinate-embargoed-releases.txt | 165 +++++++++++++++---
1 file changed, 138 insertions(+), 27 deletions(-)
diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
index 601aae88e9a..a01398c82b5 100644
--- a/Documentation/howto/coordinate-embargoed-releases.txt
+++ b/Documentation/howto/coordinate-embargoed-releases.txt
@@ -1,9 +1,134 @@
Content-type: text/asciidoc
-Abstract: When a critical vulnerability is discovered and fixed, we follow this
- script to coordinate a public release.
+Abstract: When a vulnerability is reported, we follow these guidelines to
+ assess the vulnerability, create and review a fix, and coordinate embargoed
+ security releases.
+
+The `git-security` mailing list
+-------------------------------
+
+Responsible disclosures of vulnerabilities, analysis, proposed fixes as
+well as the orchestration of coordinated embargoed releases all happen on the
+`git-security` mailing list at <git-security@xxxxxxxxxxxxxxxx>.
+
+In this context, the term "embargo" refers to the time period that information
+about a vulnerability is kept under wraps and only shared on a need-to-know
+basis. This is necessary to protect Git's users from bad actors who would
+otherwise be made aware of attack vectors that could be exploited. "Lifting the
+embargo" refers to publishing the version that fixes the vulnerabilities.
+
+Audience of the `git-security` mailing list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Anybody may contact the `git-security` mailing list by sending an email
+to <git-security@xxxxxxxxxxxxxxxx>, though the archive is closed to the
+public and only accessible to subscribed members.
+
+There are a few dozen subscribed members: core Git developers who are trusted
+with addressing vulnerabilities, and stakeholders (i.e. owners of products
+affected by security vulnerabilities in Git).
+
+Most of the discussions revolve around assessing the severity of the reported
+bugs (including the decision whether the report is security-relevant or can be
+redirected to the public mailing list), how to remediate the bug, determining
+the timeline of the disclosure as well as aligning priorities and
+requirements.
+
+Communications
+~~~~~~~~~~~~~~
+
+If you are a stakeholder, it is a good idea to pay close attention to the
+discussions, as pertinent information may be buried in the middle of a lively
+conversation that might not look relevant to your interests. For example, the
+tentative timeline might be agreed upon in the middle of discussing code
+comment formatting in one of the patches and whether or not to combine fixes
+for multiple, separate vulnerabilities into the same embargoed release. Most
+mail threads are not usually structured specifically to communicate
+agreements, assessments or timelines.
+
+A bug's life: Typical timeline
+------------------------------
+
+- A bug is reported to the `git-security` mailing list.
+
+- Within a couple of days, someone from the core Git team responds with an
+ initial assessment of the bug’s severity.
+
+- Other core developers - including the Git maintainer - chime in.
+
+- After discussion, if consensus is reached that the bug is not critical enough
+ to warrant any embargo, the reporter is redirected to the public Git mailing
+ list. This ends the reporter's interaction with the `git-security` list.
+
+- If the bug is critical enough for an embargo, ideas are presented on how to
+ address the vulnerability.
+
+- Usually around that time, the Git maintainer or their delegate(s) open a draft
+ security advisory in the `git/git` repository on GitHub (see below for more
+ details).
+
+- Depending on the preferences of the involved contributors and reviewers, code
+ review then happens either on the `git-security` mailing list or in a private
+ fork associated with the draft security advisory.
+
+- Once the review has settled and everyone involved in the review agrees that
+ the patches are ready, the Git maintainer, and others determine a release date
+ as well as the release trains that are serviced. The decision regarding which
+ versions need a backported fix is based on input from the reporter, the
+ contributor who worked on the patches, and from stakeholders (e.g. operators
+ of hosting sites who may want to analyze whether the given bug is exploited
+ via any of the repositories they host).
+
+- While the Git community does its best to accommodate the specific timeline
+ requests of the various binary packagers, the nature of the issue may preclude
+ a prolonged release schedule. For fixes deemed urgent, it may be in the best
+ interest of the Git users community to shorten the disclosure and release
+ timeline, and packagers may need to adapt accordingly.
+
+- Subsequently, branches with the fixes are pushed to private repositories that
+ are owned by the Git project, with tightly controlled access.
+
+- The tags are created by the Git maintainer and pushed to the same
+ repositories.
+
+- The Git for Windows, Git for macOS, BSD, Debian, etc maintainers prepares the
+ corresponding release artifacts, based on the tags created that have been
+ prepared by the Git maintainer.
+
+- Git for Windows release artifacts are made available under embargo to
+ stakeholders via a mail to the `git-security` list.
+
+- Less than a week before the release, a mail with the relevant information is
+ sent to <distros@xxxxxxxxxxxxxxx> (see below), a list used to pre-announce
+ embargoed releases of open source projects to the stakeholders of all major
+ Linux distributions. This includes a Git bundle of the tagged version(s), but
+ no further specifics of the vulnerability.
+
+- Public communication is then prepared in advance of the release date. This
+ includes blog posts and mails to the Git and Git for Windows mailing lists.
+
+- On the day of the release, at around 10am Pacific Time, the Git maintainer
+ pushes the tag and the `master` branch to the public repository, then sends
+ out an announcement mail.
+
+- Once the tag is pushed, the Git for Windows maintainer publishes the
+ corresponding tag and creates a GitHub Release with the associated release
+ artifacts (Git for Windows installer, Portable Git, MinGit, etc).
+
+- Git for Windows release is then announced via a mail to the public Git and
+ Git for Windows mailing lists as well as via a tweet.
+
+- Ditto for Linux distribution packagers: their releases are announced via
+ their preferred channels.
+
+- A mail to <oss-security@xxxxxxxxxxxxxxxxxx> (see below for details) is sent
+ as a follow-up to the <distros@xxxxxxxxxxxxxxx> one, describing the
+ vulnerability in detail, often including a proof of concept of an exploit.
+
+Note: The Git project makes no guarantees about timelines, but aims to keep
+embargoes reasonably short in the interest of keeping Git's users safe.
How we coordinate embargoed releases
-====================================
+------------------------------------
To protect Git users from critical vulnerabilities, we do not just release
fixed versions like regular maintenance releases. Instead, we coordinate
@@ -12,32 +137,18 @@ date. That way, users will have a chance to upgrade on that date, no matter
what Operating System or distribution they run.
Open a Security Advisory draft
-------------------------------
-
-The first step is to https://github.com/git/git/security/advisories/new[open an
-advisory]. Technically, it is not necessary, but it is convenient and saves a
-bit of hassle. This advisory can also be used to obtain the CVE number and it
-will give us a private fork associated with it that can be used to collaborate
-on a fix.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Release date of the embargoed version
--------------------------------------
-
-If the vulnerability affects Windows users, we want to have our friends over at
-Visual Studio on board. This means we need to target a "Patch Tuesday" (i.e. a
-second Tuesday of the month), at the minimum three weeks from heads-up to
-coordinated release.
-
-If the vulnerability affects the server side, or can benefit from scans on the
-server side (i.e. if `git fsck` can detect an attack), it is important to give
-all involved Git repository hosting sites enough time to scan all of those
-repositories.
+The first step is to https://github.com/git/git/security/advisories/new[open
+an advisory]. Technically, this is not necessary. However, it is the most
+convenient way to obtain the CVE number and it give us a private repository
+associated with it that can be used to collaborate on a fix.
Notifying the Linux distributions
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At most two weeks before release date, we need to send a notification to
-distros@xxxxxxxxxxxxxxx, preferably less than 7 days before the release date.
+<distros@xxxxxxxxxxxxxxx>, preferably less than 7 days before the release date.
This will reach most (all?) Linux distributions. See an example below, and the
guidelines for this mailing list at
https://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists[here].
@@ -65,7 +176,7 @@ created using a command like this:
tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle
Example mail to distros@xxxxxxxxxxxxxxx
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
....
To: distros@xxxxxxxxxxxxxxx
@@ -101,7 +212,7 @@ Thanks,
....
Example mail to oss-security@xxxxxxxxxxxxxxxxxx
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
....
To: oss-security@xxxxxxxxxxxxxxxxxx
@@ -128,4 +239,4 @@ it goes to <developer>.
Thanks,
<name>
-....
+....
\ No newline at end of file
base-commit: e72d93e88cb20b06e88e6e7d81bd1dc4effe453f
--
gitgitgadget
