embargoed releases: also describe the git-security list and the process

From: Julia Ramer <[email protected]>

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.

---
embargoed releases: also describe the git-security list and the process

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1345%2Fprplr%2Fupdate_embargo_doc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1345/prplr/update_embargo_doc-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1345

 .../howto/coordinate-embargoed-releases.txt   | 143 +++++++++++++++---
 1 file changed, 122 insertions(+), 21 deletions(-)

index 601aae88e9a..43400fd6025 100644
@@ -1,6 +1,121 @@
 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 <[email protected]>.
+
+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 <[email protected]>, 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 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).
+
+- 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.
+
+- Less than a week before the release, a mail with the relevant information is
+  sent to <[email protected]> (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.
+
+- 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.
+
+- A mail to <[email protected]> (see below for details) is sent as a
+  follow-up to the <[email protected]> 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
 ====================================

@@ -14,30 +129,16 @@ 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
[email protected], preferably less than 7 days before the release date.
+<[email protected]>, 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].

base-commit: e72d93e88cb20b06e88e6e7d81bd1dc4effe453f

gitgitgadget

Thanks for writing this down.

s/maintainer determines/& and others determine/ or "stakeholders discuss and agree on". You might want to mention that the schedule for disclosure and release tend to be constrained by so called patch Tuesday, which is the least flexible among various binary packagers.

Hi Junio,

Here is a fixup, could you please apply this to the jr/embargoed-releases-doc branch?

-- snip --
From 32927af92e9ee7a0e22f90d8c162fca317ad6f6e Mon Sep 17 00:00:00 2001
From: Johannes Schindelin <[email protected]>
Date: Sat, 3 Sep 2022 11:23:03 +0200
Subject: [PATCH] fixup! embargoed releases: also describe the git-security
list and the process

This fixes the build.

---
 .../howto/coordinate-embargoed-releases.txt    | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

index 43400fd6025..b6799647536 100644
@@ -4,7 +4,7 @@ Abstract: When a vulnerability is reported, we follow these guidelines to
  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

@@ -17,7 +17,7 @@ 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 <[email protected]>, though the archive is closed to the

@@ -34,7 +34,7 @@ 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

@@ -46,7 +46,7 @@ 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.
 

@@ -118,7 +118,7 @@ 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

@@ -127,7 +127,7 @@ 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, this is not necessary. However, it is the most

@@ -135,7 +135,7 @@ 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
 <[email protected]>, preferably less than 7 days before the release date.

@@ -166,7 +166,7 @@ created using a command like this:
 	tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle
 
 Example mail to [email protected]
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: [email protected]

@@ -202,7 +202,7 @@ Thanks,
 ....
 
 Example mail to [email protected]
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: [email protected]

--
2.37.0.rc2.windows.1.7.g45a475aeb84
-- snap --

Sadly, our CI definitions are too flaky to enforce that. We had looked into that, but even though the Perforce situation seems to be a _lot_ better these days than it used to be, even the several weeks of broken FreeBSD builds simply preclude making them a prerequisite.

In this instance, it is still my fault that the breakage was ignored before submitting: Julia had asked me whether she should wait for the PR build to finish, and I claimed that there is no need to wait because it is a documentation-only change (and I erroneously assumed that this document would not be built because it is not shown on https://git-scm.com/docs).

Ciao,
Dscho

Thanks but no thanks. The contents change is needed so I will wait for an updated patch from the author.

Taking these responses one by one:

All of Junio's edits and call-outs are reasonable and I'll incorporate them into the next version.

Julia
(she/her)

[moving git-security@ to BCC; those who have been following the thread, please switch to the main list]

Thanks.

By the way, this "we account for patch Tuesday" is not "the only 800 pound gorilla in the room inherently has rights to dictate their terms". It is merely that "other packagers are being nice and extra accomodating", and when another even less flexible packager requests a prolonged schedule, we might accomodate their needs, depending on the nature of the issue.

On the other hand, the git users community may not be able to wait for the next month to apply an unusually urgent fix, and a binary packager with a coarse release granularity may have to be creative on such an occasion.

In this hypothetical timeline:

    A---B-B-B-B-B-B-B-B---C

              D0----E0           D1----E1 (next month)

where

A: problem reported
B: solution proposed, discussed, and finalized
C: public coordinated disclosure and release date

Dn: cut-off date for "monthly security updates" for a packager
En: date "monthly security updates" is issued by a packager

the wider Git user community may not be able to afford to wait until date E1 of the next month by delaying C, even if date D0 for this month's "security updates" for a particular packager comes before the solution gets finalized.

If the coordinated release C falls after the deadline D0 for the upcoming "monthly security updates" (not singling out Microsoft by mentioning "patch Tuesdays" anymore, as this applies generally to anybody whose release granularity is more coarse than other distros find comfortahble for security fixes) for a packager, but if an early round of proposed fix is seen, they can independently make their own judgement to include the non-final fix in their binary release at their cut-off date D0, while withholding the source at least to the agreed upon coordinate disclosure date C, for example.

They may later want to update to the final fix by date D1 to be included in their next "monthly security updates" on date E1, which would be an extra work, but that is the cost of running a coarse release schedule.

I do not know how to concisely phrase the above to fit in the framework of your document, but some of the above issues were brought up elsewhere, so I thought I'd better share it here.

Thanks.

[adding Veronica and Bri to TO:]

If I am understanding this particular scenario, I believe you intended:

s/coordinated release C/final B/

I can take a stab at concisely phrasing this to fit within this framework, first paragraph for context, second is the addition:

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.

From: Julia Ramer <[email protected]>

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.

---
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 <[email protected]>, 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 <[email protected]> (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 <[email protected]> (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 <[email protected]> (see below for details) is sent as a -+ follow-up to the <[email protected]> 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 <[email protected]> (see below for details) is sent
++ as a follow-up to the <[email protected]> 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
[email protected], 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 [email protected]
+----------------------------------------
++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ ....
+ To: [email protected]
+@@ Documentation/howto/coordinate-embargoed-releases.txt: Thanks,
+ ....
+
+ Example mail to [email protected]
+------------------------------------------------
++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ ....
+ To: [email protected]
+@@ 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(-)

index 601aae88e9a..a01398c82b5 100644
@@ -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 <[email protected]>.
+
+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 <[email protected]>, 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 <[email protected]> (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 <[email protected]> (see below for details) is sent
+  as a follow-up to the <[email protected]> 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
[email protected], preferably less than 7 days before the release date.
+<[email protected]>, 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 [email protected]
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: [email protected]

@@ -101,7 +212,7 @@ Thanks,
 ....
 
 Example mail to [email protected]
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: [email protected]

@@ -128,4 +239,4 @@ it goes to <developer>.
 
 Thanks,
 <name>
-....
+....
\ No newline at end of file

base-commit: e72d93e88cb20b06e88e6e7d81bd1dc4effe453f

gitgitgadget

Thanks for sharp eyes. You're correct. As long as the final B comes before the deadline of a packager, then they should be able to work within their own constraint. If the final B comes after their deadline, and they still want to include the fix in E0, then the package needs to be "creative".

Exellent. Thanks.

Thanks for an update that is excellently written.

I had only some minor points and random thoughts while reading it. I do not know if all of them need to result in further changes to the document, though.

+ The 'stakeholders' are explained twice in a bit different terms. The former (owners of products affected by vulnerabilities) description is more broad than the latter and would be more appropriate in general. Perhaps dropping the latter would give us more clarity?

- Would a reader, who has "stake" in the healty and secure Git, be helped if we spell out that they are welcome to ask joining the security list and how? It feels a bit too obvious after reading "anybody may contact", which is both the right way to self nominate for the membership and the natural thing I expect such a reader would do, so we may not need to.

+ The packager whose release artifacts can be exchanged among security list participants under embargo is not limited to Git for Windows, even though we've only seen exchanges between Victoria and Veronica this cycle for that particular distribution.

- The world is not limited to only Windows, mac and Linux. Windows is not all that special.

+ The project maintainer is special in only two ways (tagging and producing release tarballs); in all the other contexts, treat him just like any other contributors.

- There may be ways to improve on the lack of formal process to record decisions (e.g. a capable project secretary can notice that stakeholders agreed on a proposed release date, and send a separate message summarizing only that fact so that it would not be missed by casual bystanders), but that is something we should work on elsewhere, not as part of the effort to document the current practice.

- I wonder if we want to record the name that is used to refer to the "private repository controlled by the project" on the security mailing list somewhere in the documentation. If you are a stakeholder, being on the mailing list *and* having access to that repository are two things we need to make sure you have to partcipate in the coordinated embargoed releases.

+ Usually the fixes affect 'maint' and its tip is pointed by one of the tags for the security update release, and 'master' is updated to contain 'maint', but on the 'master' track there is no tag for the security update. Other integration branches like 'next' and 'seen' are also updated to contain the fix.

+ The "How we coordinate embargoed releases" section looked a bit odd to appear this late in the document. Shouldn't it be moved way higher, even before we start talking about the security list? After all, the security mailing list is a means to the end that the section talks about (i.e. we sometimes need embargoed release process working behind closed doors).

Here is a patch that summarises some of the above on top of your patch. I only tried to address the bullet items with "+" in front in the above list.

 .../howto/coordinate-embargoed-releases.txt        | 52 ++++++++++++----------
 1 file changed, 28 insertions(+), 24 deletions(-)

index a01398c82b..80af5de297 100644
@@ -3,6 +3,15 @@ Abstract: When a vulnerability is reported, we follow these guidelines to
  assess the vulnerability, create and review a fix, and coordinate embargoed
  security releases.
 
+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
+releases with packagers, keeping the fixes under an embargo until the release
+date. That way, users will have a chance to upgrade on that date, no matter
+what Operating System or distribution they run.
+
 The `git-security` mailing list
 -------------------------------
 

@@ -50,10 +59,11 @@ 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.
+- Within a couple of days, someone from the core Git team, including
+  the Git maintainer, responds with an initial assessment of the
+  bug’s severity.
 
-- Other core developers - including the Git maintainer - chime in.
+- Other core developers 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

@@ -74,9 +84,11 @@ A bug's life: Typical timeline
   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
+  contributor who worked on the patches, and from stakeholders.   Operators
   of hosting sites who may want to analyze whether the given bug is exploited
-  via any of the repositories they host).
+  via any of the repositories they host, and binary packagers who want to
+  make sure their product gets patched adequately against the vulnerability,
+  for example, may want to give their input at this stage.
 
 - 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

@@ -90,18 +102,19 @@ A bug's life: Typical timeline
 - 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
+- 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.
+- The release artifacts prepared by various binary packagers can be
+  made available to stakeholders under embargo via a mail to the
+  `git-security` list.
 
 - Less than a week before the release, a mail with the relevant information is
   sent to <[email protected]> (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.
+  distributions of Linux as well as other OSes. 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.

@@ -117,8 +130,8 @@ A bug's life: Typical timeline
 - 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.
+- Ditto for distribution packagers for Linux and other platforms:
+  their releases are announced via their preferred channels.
 
 - A mail to <[email protected]> (see below for details) is sent
   as a follow-up to the <[email protected]> one, describing the

@@ -127,17 +140,8 @@ A bug's life: Typical timeline
 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
-releases with packagers, keeping the fixes under an embargo until the release
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Opening a Security Advisory draft
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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

@@ -239,4 +243,4 @@ it goes to <developer>.
 
 Thanks,
 <name>
-....
\ No newline at end of file
+....

[-cc git-security]

For what it's worth, GitHub does usually prepare a public blog post, but I don't think we've typically shared them with the git-security list ahead of time. Not because there's anything sensitive in there (I personally would have no problem sharing them with git-security ahead of time if there was interest), but just because nobody has asked. It may be worth clarifying which communications we expect to have reviewed by the git-security list during this period and which we do not.

Yes, indeed.

My personal feeling is in agreement with yours, which is that it is probably obvious, so I don't think it's worth spelling out explicitly here.

I agree, I think that mentioning Git for Windows in this document is not strictly necessary (e.g., if there were a new "Git for Foo" that came out tomorrow, I would not consider this document out-of-date), but I likewise wouldn't object to it.

This repository (git/cabal) is already well-documented on the mailing list, so I would have no problem including its name here, too.

All looks good to me, thanks.

Thanks,
Taylor

Good point and good idea.

The purpose of giving a "Typical" timeline is primarily to guide readers what to expect once they raise an issue, and to bind us with at least "aspirational" deadline (which is not a bad thing), isn't it? Saying "As soon as possible" there is the same as not saying anything at all, even though in reality it sometimes may be "when somebody feels like it is worth looking into" ;-)

Depending on the nature of vulnerability, the time it takes to reach a satisfactory conclusion may range from a few days to a few weeks, so we may not be able to give even a "Typical" timeline, but I do not think it is unreasonable to hold us to a few days turnaround time at least for an initial reaction.

That's a roundabout way to say "I think the original text is good".

I am torn.

The folks who are deep into core git development may have better ability to assess the severity of a particular bug and the complexity of possible solutions than others, but platform stakeholders know how Git is used within their system and how old the target track they wish to be updated better than us. So in that sense, limiting assessment to core developers may not be ideal.

But on the other hand, the initial report to the list are seen only by the security list participants and nobody else, so by definition, any response would come from them ;-)

Yes, it is convenient for simple things, but not necessarily the best option when we need to roll it upwards to produce releases for multiple maintenance tracks.

The rest of your comments and suggestions address all good points.

Thanks.

... I wonder if it would be better to consolidate the above two into one bullet point, e.g.

- The security-list members start a discussion to give an initial assessment of the severity of potential vulnerability reported. We aspire to do so within a few days.

"prepares" -> "prepare".

Here is some proposed language that I think would encompass everything both you and I wrote here:

Code review can take place in a variety of different locations, depending on context. These are: patches sent inline on the git-security list, a private fork on GitHub associated with the draft security advisory, or the git/cabal repository.

Contributors working on a fix should consider beginning by sending patches on the list (inline with the original thread), since they are accessible to all subscribers, along with the original reporter. A typical review cycle often takes place here.

Then, depending on if there are one or multiple security advisories, contributors should move their patches to either the private fork associated with the security advisory on GitHub, or the git/cabal repository. It is in either one of these locations that release branches (based on maint) are prepared.

When there is a single security vulnerability, using the fork associated with the security advisory is convenient as it centralizes discussion, review, and release mechanics at a single location. When there are multiple such vulnerabilities, no single temporary fork is appropriate, so it is instead encouraged to use the private git/cabal repository (visibility of which is granted to members of the @git/security team on GitHub).

Thanks,
Taylor

From: Julia Ramer <[email protected]>

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.

---
embargoed releases: also describe the git-security list and the process

Changes since v2:

* squashed Junio's patch with very minor modifications
* incorporated further feedback since v2

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-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1345/prplr/update_embargo_doc-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1345

Range-diff vs v2:

1: 766c92e9031 ! 1: 96250f139a9 embargoed releases: also describe the git-security list and the process
@@ Commit message
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.

+ Helped-by: Junio C Hamano <[email protected]>
+ Helped-by: Taylor Blau <[email protected]>

## Documentation/howto/coordinate-embargoed-releases.txt ##
@@ Documentation/howto/coordinate-embargoed-releases.txt
+Abstract: When a vulnerability is reported, we follow these guidelines to
+ assess the vulnerability, create and review a fix, and coordinate embargoed
+ security releases.
-+
+
+ 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
+@@ Documentation/howto/coordinate-embargoed-releases.txt: releases with packagers, keeping the fixes under an embargo until the release
+ 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 git-security mailing list
+-------------------------------
+
@@ Documentation/howto/coordinate-embargoed-releases.txt
+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
++issue (including the decision whether the report is security-relevant or can be
++redirected to the public mailing list), how to remediate the issue, determining
+the timeline of the disclosure as well as aligning priorities and
+requirements.
+
@@ Documentation/howto/coordinate-embargoed-releases.txt
+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.
++Typical timeline
++----------------
+
-+- Within a couple of days, someone from the core Git team responds with an
-+ initial assessment of the bug’s severity.
++- A potential vulnerability is reported to the git-security mailing list.
+
-+- Other core developers - including the Git maintainer - chime in.
++- The security-list members start a discussion to give an initial
++ assessment of the severity of the reported potential vulnerability.
++ We aspire to do so within a few days.
+
-+- After discussion, if consensus is reached that the bug is not critical enough
++- After discussion, if consensus is reached that it 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
++- If it is deemed 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.
++- Code review can take place in a variety of different locations,
++ depending on context. These are: patches sent inline on the
++ git-security list, a private fork on GitHub associated with the
++ draft security advisory, or the git/cabal repository.
++
++ Contributors working on a fix should consider beginning by sending
++ patches to the git-security list (inline with the original thread),
++ since they are accessible to all subscribers, along with the original
++ reporter.
+
+- 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).
++ contributor who worked on the patches, and from stakeholders. Operators
++ of hosting sites who may want to analyze whether the given issue is exploited
++ via any of the repositories they host, and binary packagers who want to
++ make sure their product gets patched adequately against the vulnerability,
++ for example, may want to give their input at this stage.
+
+- 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
@@ 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
++- The Git for Windows, Git for macOS, BSD, Debian, etc. maintainers prepare 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.
++- The release artifacts prepared by various binary packagers can be
++ made available to stakeholders under embargo via a mail to the
++ git-security list.
+
+- Less than a week before the release, a mail with the relevant information is
+ sent to <[email protected]> (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.
++ distributions of Linux as well as other OSes. 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.
@@ 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.
+
-+- Ditto for Linux distribution packagers: their releases are announced via
-+ their preferred channels.
++- Ditto for distribution packagers for Linux and other platforms:
++ their releases are announced via their preferred channels.
+
+- A mail to <[email protected]> (see below for details) is sent
+ as a follow-up to the <[email protected]> one, describing the
@@ Documentation/howto/coordinate-embargoed-releases.txt
+
+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
-@@ 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
---------------------------------------
--
--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.
++
++Opening a Security Advisory draft
++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++
+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
@@ Documentation/howto/coordinate-embargoed-releases.txt: Thanks,

....
To: [email protected]
-@@ Documentation/howto/coordinate-embargoed-releases.txt: it goes to <developer>. -
- Thanks,
- <name>
--....
-+....
- \ No newline at end of file

 .../howto/coordinate-embargoed-releases.txt   | 175 +++++++++++++++---
 1 file changed, 147 insertions(+), 28 deletions(-)

index 601aae88e9a..7cd8f6241c2 100644
@@ -1,9 +1,10 @@
 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.
 
 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

@@ -11,33 +12,151 @@ releases with packagers, keeping the fixes under an embargo until the release
 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 `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 <[email protected]>.
+
+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 <[email protected]>, 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
+issue (including the decision whether the report is security-relevant or can be
+redirected to the public mailing list), how to remediate the issue, 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.
+
+Typical timeline
+----------------
+
+- A potential vulnerability is reported to the `git-security` mailing list.
+
+- The security-list members start a discussion to give an initial
+  assessment of the severity of the reported potential vulnerability.
+  We aspire to do so within a few days.
+
+- After discussion, if consensus is reached that it 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 it is deemed 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).
+
+- Code review can take place in a variety of different locations,
+  depending on context. These are: patches sent inline on the
+  git-security list, a private fork on GitHub associated with the
+  draft security advisory, or the git/cabal repository.
+
+  Contributors working on a fix should consider beginning by sending
+  patches to the git-security list (inline with the original thread),
+  since they are accessible to all subscribers, along with the original
+  reporter.
+
+- 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.   Operators
+  of hosting sites who may want to analyze whether the given issue is exploited
+  via any of the repositories they host, and binary packagers who want to
+  make sure their product gets patched adequately against the vulnerability,
+  for example, may want to give their input at this stage.
+
+- 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 prepare the
+  corresponding release artifacts, based on the tags created that have been
+  prepared by the Git maintainer.
+
+- The release artifacts prepared by various binary packagers can be
+  made available to stakeholders under embargo via a mail to the
+  `git-security` list.
+
+- Less than a week before the release, a mail with the relevant information is
+  sent to <[email protected]> (see below), a list used to pre-announce
+  embargoed releases of open source projects to the stakeholders of all major
+  distributions of Linux as well as other OSes. 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 distribution packagers for Linux and other platforms:
+  their releases are announced via their preferred channels.
+
+- A mail to <[email protected]> (see below for details) is sent
+  as a follow-up to the <[email protected]> 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.
+
+Opening a Security Advisory draft
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
[email protected], preferably less than 7 days before the release date.
+<[email protected]>, 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 +184,7 @@ created using a command like this:
 	tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle
 
 Example mail to [email protected]
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: [email protected]

@@ -101,7 +220,7 @@ Thanks,
 ....
 
 Example mail to [email protected]
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: [email protected]

base-commit: e72d93e88cb20b06e88e6e7d81bd1dc4effe453f

gitgitgadget

Thanks. Everything looks good, except for a few minor things.

A much better section title; I like it.

... with the fixes are pushed to the git/cabal repository.

Just like "review can take place in multiple places; contributors are encouraged to start from ..." was made into a single bullet point, "branches are privately published to git/cabal; tags are added to the same repository." may flow well in the same single bullet. I dunno.

This version looks great, thanks for your work polishing it up based on mine and Junio's review. I agree with what Junio said downthread in [1], and left a few minor nitpicks of my own.

So, I don't have much to add beyond what Junio wrote. I suspect that between my feedback below and his in [1], that should be enough to get v4 ready to be queued.

s/security-list members/members of the git-security list/.

Fixed in the next version!

Fixed, thanks for pointing that out.

Distilled into s/ready/nearing the finish line/

I think it makes sense to just remove the entire last sentence, as the relevant information is referenced in the parenthetical "(see below)".

Thanks, I incorporated all suggestions into the next version.

From: Julia Ramer <[email protected]>

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.

---
embargoed releases: also describe the git-security list and the process

Changes since v3:

* minor formatting corrections
* clarified the language based on v3 feedback

Changes since v2:

* squashed Junio's patch with very minor modifications
* incorporated further feedback since v2

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-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1345/prplr/update_embargo_doc-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/1345

Range-diff vs v3:

1: 96250f139a9 ! 1: b6ecc919dbb embargoed releases: also describe the git-security list and the process
@@ Documentation/howto/coordinate-embargoed-releases.txt: releases with packagers,

-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 git-security mailing list
+-------------------------------
+
@@ Documentation/howto/coordinate-embargoed-releases.txt: releases with packagers,
+redirected to the public mailing list), how to remediate the issue, determining +the timeline of the disclosure as well as aligning priorities and +requirements.
-+
+
+-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.
+Communications
+~~~~~~~~~~~~~~
-+
+
+-Release date of the embargoed version
+--------------------------------------
+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
@@ Documentation/howto/coordinate-embargoed-releases.txt: releases with packagers,
+for multiple, separate vulnerabilities into the same embargoed release. Most +mail threads are not usually structured specifically to communicate +agreements, assessments or timelines.
-+
+
+-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.
+Typical timeline
+----------------
-+
+
+-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.
+- A potential vulnerability is reported to the git-security mailing list. +
-+- The security-list members start a discussion to give an initial ++- The members of the git-security list start a discussion to give an initial
+ assessment of the severity of the reported potential vulnerability.
+ We aspire to do so within a few days.
+
@@ Documentation/howto/coordinate-embargoed-releases.txt: releases with packagers,
+ details).
+
+- Code review can take place in a variety of different locations,
-+ depending on context. These are: patches sent inline on the
-+ git-security list, a private fork on GitHub associated with the -+ draft security advisory, or the git/cabal repository.
++ depending on context. These are: patches sent inline on the git-security list, ++ a private fork on GitHub associated with the draft security advisory, or the ++ git/cabal repository.
+
-+ Contributors working on a fix should consider beginning by sending -+ patches to the git-security list (inline with the original thread), -+ since they are accessible to all subscribers, along with the original -+ reporter.
++- Contributors working on a fix should consider beginning by sending ++ patches to the git-security list (inline with the original thread), since they ++ are accessible to all subscribers, along with the original reporter.
+
+- 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. Operators
-+ of hosting sites who may want to analyze whether the given issue is exploited -+ via any of the repositories they host, and binary packagers who want to -+ make sure their product gets patched adequately against the vulnerability, -+ for example, may want to give their input at this stage.
++ the patches are nearing the finish line, 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. Operators of hosting sites who may want to analyze whether the ++ given issue is exploited via any of the repositories they host, and binary ++ packagers who want to make sure their product gets patched adequately against ++ the vulnerability, for example, may want to give their input at this stage.
+
+- 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
@@ Documentation/howto/coordinate-embargoed-releases.txt: releases with packagers,
+ 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. ++- Subsequently, branches with the fixes are pushed to the git/cabal repository.
+
-+- The tags are created by the Git maintainer and pushed to the same -+ repositories.
++- The tags are created by the Git maintainer and pushed to the same repository.
+
+- The Git for Windows, Git for macOS, BSD, Debian, etc. maintainers prepare the
+ corresponding release artifacts, based on the tags created that have been
@@ Documentation/howto/coordinate-embargoed-releases.txt: releases with packagers,
+- Less than a week before the release, a mail with the relevant information is
+ sent to <[email protected]> (see below), a list used to pre-announce
+ embargoed releases of open source projects to the stakeholders of all major
-+ distributions of Linux as well as other OSes. This includes a Git bundle -+ of the tagged version(s), but no further specifics of the vulnerability. ++ distributions of Linux as well as other OSes.
+
+- 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.
@@ Documentation/howto/coordinate-embargoed-releases.txt: Thanks,

....
To: [email protected]
+@@ 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, 140 insertions(+), 25 deletions(-)

index 601aae88e9a..e653775bab1 100644
@@ -1,9 +1,10 @@
 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.
 
 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

@@ -11,33 +12,147 @@ releases with packagers, keeping the fixes under an embargo until the release
 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 `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 <[email protected]>.
+
+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 <[email protected]>, 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
+issue (including the decision whether the report is security-relevant or can be
+redirected to the public mailing list), how to remediate the issue, determining
+the timeline of the disclosure as well as aligning priorities and
+requirements.
 
-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.
+Communications
+~~~~~~~~~~~~~~
 
-Release date of the embargoed version
--------------------------------------
+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.
 
-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.
+Typical timeline
+----------------
 
-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.
+- A potential vulnerability is reported to the `git-security` mailing list.
+
+- The members of the git-security list start a discussion to give an initial
+  assessment of the severity of the reported potential vulnerability.
+  We aspire to do so within a few days.
+
+- After discussion, if consensus is reached that it 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 it is deemed 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).
+
+- Code review can take place in a variety of different locations,
+  depending on context. These are: patches sent inline on the git-security list,
+  a private fork on GitHub associated with the draft security advisory, or the
+  git/cabal repository.
+
+- Contributors working on a fix should consider beginning by sending
+  patches to the git-security list (inline with the original thread), since they
+  are accessible to all subscribers, along with the original reporter.
+
+- Once the review has settled and everyone involved in the review agrees that
+  the patches are nearing the finish line, 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. Operators of hosting sites who may want to analyze whether the
+  given issue is exploited via any of the repositories they host, and binary
+  packagers who want to make sure their product gets patched adequately against
+  the vulnerability, for example, may want to give their input at this stage.
+
+- 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 the git/cabal repository.
+
+- The tags are created by the Git maintainer and pushed to the same repository.
+
+- The Git for Windows, Git for macOS, BSD, Debian, etc. maintainers prepare the
+  corresponding release artifacts, based on the tags created that have been
+  prepared by the Git maintainer.
+
+- The release artifacts prepared by various binary packagers can be
+  made available to stakeholders under embargo via a mail to the
+  `git-security` list.
+
+- Less than a week before the release, a mail with the relevant information is
+  sent to <[email protected]> (see below), a list used to pre-announce
+  embargoed releases of open source projects to the stakeholders of all major
+  distributions of Linux as well as other OSes.
+
+- 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 distribution packagers for Linux and other platforms:
+  their releases are announced via their preferred channels.
+
+- A mail to <[email protected]> (see below for details) is sent
+  as a follow-up to the <[email protected]> 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.
+
+Opening a Security Advisory draft
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
[email protected], preferably less than 7 days before the release date.
+<[email protected]>, 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 +180,7 @@ created using a command like this:
 	tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle
 
 Example mail to [email protected]
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: [email protected]

@@ -101,7 +216,7 @@ Thanks,
 ....
 
 Example mail to [email protected]
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: [email protected]

@@ -128,4 +243,4 @@ it goes to <developer>.
 
 Thanks,
 <name>
-....
+....
\ No newline at end of file

base-commit: e72d93e88cb20b06e88e6e7d81bd1dc4effe453f

gitgitgadget

Excellent.

Very sensible.

Thanks.

Thanks, this version I am happy with.