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

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

[Julia Ramer via GitGitGadget]

From: Julia Ramer <gitprplr@gmail.com>

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@gmail.com>
---
    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(-)

diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
index 601aae88e9a..43400fd6025 100644
--- a/Documentation/howto/coordinate-embargoed-releases.txt
+++ b/Documentation/howto/coordinate-embargoed-releases.txt
@@ -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 <git-security@googlegroups.com>.
+
+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@googlegroups.com>, 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 <distros@vs.openwall.org> (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 <oss-security@lists.openwall.org> (see below for details) is sent as a
+  follow-up to the <distros@vs.openwall.org> 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
-distros@vs.openwall.org, preferably less than 7 days before the release date.
+<distros@vs.openwall.org>, 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

Re: [PATCH] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

"Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Ramer <gitprplr@gmail.com>
>
> 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.

Thanks for writing this down.

> +- 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

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.

> +- 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.

Between this point in time when the tags are prepared and release
materials are made available to packagers and ...

> +- Less than a week before the release, a mail with the relevant information is
> +  sent to <distros@vs.openwall.org> (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.

... the time when we start to disclose to a bit wider audience, is
when binary packagers are expected to prepare updates for their
users.  So ...

> +
> +- 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 following two bullet items are better written before the
"Less than a week before...".

> +- 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.

It also is probably a good idea to avoid singling out GfW too much.
Folks who package Git for macOS, BSD, Debian etc. are all expected
to work on the same timeline.

> +- 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.

OK.  Thanks for being explicit about 10am Pacific.

> +- 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 various distro packagers.

> +- A mail to <oss-security@lists.openwall.org> (see below for details) is sent as a
> +  follow-up to the <distros@vs.openwall.org> 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.

;-)

Re: [PATCH] embargoed releases: also describe the git-security list and the process

[Julia Ramer]

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)

On Fri, Sep 2, 2022 at 10:24 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Julia Ramer <gitprplr@gmail.com>
> >
> > 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.
>
> Thanks for writing this down.
>
> > +- 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
>
> 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.
>
> > +- 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.
>
> Between this point in time when the tags are prepared and release
> materials are made available to packagers and ...
>
> > +- Less than a week before the release, a mail with the relevant information is
> > +  sent to <distros@vs.openwall.org> (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.
>
> ... the time when we start to disclose to a bit wider audience, is
> when binary packagers are expected to prepare updates for their
> users.  So ...
>
> > +
> > +- 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 following two bullet items are better written before the
> "Less than a week before...".
>
> > +- 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.
>
> It also is probably a good idea to avoid singling out GfW too much.
> Folks who package Git for macOS, BSD, Debian etc. are all expected
> to work on the same timeline.
>
> > +- 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.
>
> OK.  Thanks for being explicit about 10am Pacific.
>
> > +- 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 various distro packagers.
>
> > +- A mail to <oss-security@lists.openwall.org> (see below for details) is sent as a
> > +  follow-up to the <distros@vs.openwall.org> 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.
>
> ;-)
>
> --
> You received this message because you are subscribed to the Google Groups "Git Security" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to git-security+unsubscribe@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/git-security/xmqqa67h8zac.fsf%40gitster.g.

Re: [PATCH] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

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

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

Thanks.

>> > +- 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
>>
>> 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.

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.

Re: [PATCH] embargoed releases: also describe the git-security list and the process

[Julia Ramer]

[adding Veronica and Bri to TO:]

On Wed, Sep 28, 2022 at 10:12 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> >> > +- 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
> >>
> >> 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.
>
> 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.
>

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

s/coordinated release C/final B/

> 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.
>

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.

Re: [PATCH] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

Julia Ramer <prplr@github.com> writes:

>> In this hypothetical timeline:
>>
>>     A---B-B-B-B-B-B-B-B---C
>>
>>               D0----E0           D1----E1 (next month)
>> ...
>> If the coordinated release C falls after the deadline D0 for the
>> upcoming "monthly security updates" (not singling out Microsoft by
> ...
> If I am understanding this particular scenario, I believe you intended:
>
> s/coordinated release C/final B/

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".

> 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.

Exellent.  Thanks.

Re: [PATCH] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

"Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
> index 601aae88e9a..43400fd6025 100644
> --- a/Documentation/howto/coordinate-embargoed-releases.txt
> +++ b/Documentation/howto/coordinate-embargoed-releases.txt
> @@ -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
> +===============================

Dissapointingly, addition of these two new "=====" underlined
sections breaks the documentation build, which broke mi build
locally as well as GitHub CI [*1*]

 * https://github.com/git/git/runs/8162258928?check_suite_focus=true#step:4:658

Fix should hopefully be trivial, keep the original title line 

    How we coordinate embargoed releases
    ====================================

intact, and make these two new sections underlined with "-----",
demoting their subsections one level down accordingly.

But I care more about procedural gap because this should have been
something the submitter could have noticed at their end.  I somehow
trusted that GitGitGadget would run preflight CI tests before
accepting /submit, but if not, perhaps we should?

Thanks.

Re: [PATCH] embargoed releases: also describe the git-security list and the process

[Johannes Schindelin]

Hi Junio,

On Fri, 2 Sep 2022, Junio C Hamano wrote:

> "Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
> > index 601aae88e9a..43400fd6025 100644
> > --- a/Documentation/howto/coordinate-embargoed-releases.txt
> > +++ b/Documentation/howto/coordinate-embargoed-releases.txt
> > @@ -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
> > +===============================
>
> Dissapointingly, addition of these two new "=====" underlined
> sections breaks the documentation build, which broke mi build
> locally as well as GitHub CI [*1*]
>
>  * https://github.com/git/git/runs/8162258928?check_suite_focus=true#step:4:658
>
> Fix should hopefully be trivial, keep the original title line
>
>     How we coordinate embargoed releases
>     ====================================
>
> intact, and make these two new sections underlined with "-----",
> demoting their subsections one level down accordingly.

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 <johannes.schindelin@gmx.de>
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.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 .../howto/coordinate-embargoed-releases.txt    | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
index 43400fd6025..b6799647536 100644
--- a/Documentation/howto/coordinate-embargoed-releases.txt
+++ b/Documentation/howto/coordinate-embargoed-releases.txt
@@ -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 <git-security@googlegroups.com>, 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
 <distros@vs.openwall.org>, 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 distros@vs.openwall.org
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 ....
 To: distros@vs.openwall.org
@@ -202,7 +202,7 @@ Thanks,
 ....

 Example mail to oss-security@lists.openwall.com
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 ....
 To: oss-security@lists.openwall.com
--
2.37.0.rc2.windows.1.7.g45a475aeb84
-- snap --

> But I care more about procedural gap because this should have been
> something the submitter could have noticed at their end.  I somehow
> trusted that GitGitGadget would run preflight CI tests before
> accepting /submit, but if not, perhaps we should?

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

Re: [PATCH] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Hi Junio,
>
> On Fri, 2 Sep 2022, Junio C Hamano wrote:
>
>> "Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:
>>
>> > diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
>> > index 601aae88e9a..43400fd6025 100644
>> > --- a/Documentation/howto/coordinate-embargoed-releases.txt
>> > +++ b/Documentation/howto/coordinate-embargoed-releases.txt
>> > @@ -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
>> > +===============================
>>
>> Dissapointingly, addition of these two new "=====" underlined
>> sections breaks the documentation build, which broke mi build
>> locally as well as GitHub CI [*1*]
>>
>>  * https://github.com/git/git/runs/8162258928?check_suite_focus=true#step:4:658
>>
>> Fix should hopefully be trivial, keep the original title line
>>
>>     How we coordinate embargoed releases
>>     ====================================
>>
>> intact, and make these two new sections underlined with "-----",
>> demoting their subsections one level down accordingly.
>
> Here is a fixup, could you please apply this to the
> `jr/embargoed-releases-doc` branch?

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

[PATCH v2] embargoed releases: also describe the git-security list and the process

[Julia Ramer via GitGitGadget]

From: Julia Ramer <gitprplr@gmail.com>

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@gmail.com>
---
    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@googlegroups.com>, 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@vs.openwall.org> (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@vs.openwall.org> (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@lists.openwall.org> (see below for details) is sent as a
     -+  follow-up to the <distros@vs.openwall.org> 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@lists.openwall.org> (see below for details) is sent
     ++  as a follow-up to the <distros@vs.openwall.org> 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@vs.openwall.org, 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@vs.openwall.org
     +----------------------------------------
     ++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     + 
     + ....
     + To: distros@vs.openwall.org
     +@@ Documentation/howto/coordinate-embargoed-releases.txt: Thanks,
     + ....
     + 
     + Example mail to oss-security@lists.openwall.com
     +------------------------------------------------
     ++~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     + 
     + ....
     + To: oss-security@lists.openwall.com
     +@@ 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@googlegroups.com>.
+
+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@googlegroups.com>, 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@vs.openwall.org> (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@lists.openwall.org> (see below for details) is sent
+  as a follow-up to the <distros@vs.openwall.org> 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@vs.openwall.org, preferably less than 7 days before the release date.
+<distros@vs.openwall.org>, 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@vs.openwall.org
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: distros@vs.openwall.org
@@ -101,7 +212,7 @@ Thanks,
 ....
 
 Example mail to oss-security@lists.openwall.com
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: oss-security@lists.openwall.com
@@ -128,4 +239,4 @@ it goes to <developer>.
 
 Thanks,
 <name>
-....
+....
\ No newline at end of file

base-commit: e72d93e88cb20b06e88e6e7d81bd1dc4effe453f
-- 
gitgitgadget

Re: [PATCH v2] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

"Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Ramer <gitprplr@gmail.com>
>
> 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@gmail.com>
> ---

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(-)

diff --git c/Documentation/howto/coordinate-embargoed-releases.txt w/Documentation/howto/coordinate-embargoed-releases.txt
index a01398c82b..80af5de297 100644
--- c/Documentation/howto/coordinate-embargoed-releases.txt
+++ w/Documentation/howto/coordinate-embargoed-releases.txt
@@ -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 <distros@vs.openwall.org> (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 <oss-security@lists.openwall.org> (see below for details) is sent
   as a follow-up to the <distros@vs.openwall.org> 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
+....

Re: [PATCH v2] embargoed releases: also describe the git-security list and the process

[Taylor Blau]

On Wed, Oct 19, 2022 at 11:53:18AM -0700, Junio C Hamano wrote:
> "Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Julia Ramer <gitprplr@gmail.com>
> >
> > 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@gmail.com>
> > ---
>
> Thanks for an update that is excellently written.

Yes, indeed.

>  - 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.

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.

>  + 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.

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.

>  - 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.

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

> 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.

All looks good to me, thanks.

Thanks,
Taylor

Re: [PATCH v2] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> -- 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.

The "including" here looks even less clear.  Does somebody other
than me and I should respond?  That is not what I wanted to say.
Hence ...

> -- Other core developers - including the Git maintainer - chime in.
> +- Other core developers chime in.

... 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.

> -- 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.

"prepares" -> "prepare".

>  - Less than a week before the release, a mail with the relevant information is
>    sent to <distros@vs.openwall.org> (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.

The bundle contains enough information to recreate these tagged
versions under embargo, hence the release notes for these releases
that discloses the vulnerability.  Perhaps drop "but no further..."?

Re: [PATCH v2] embargoed releases: also describe the git-security list and the process

[Taylor Blau]

[-cc git-security]

On Wed, Oct 19, 2022 at 01:16:00AM +0000, Julia Ramer via GitGitGadget wrote:

> +Audience of the `git-security` mailing list
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Anybody may contact the `git-security` mailing list by sending an email
> +to <git-security@googlegroups.com>, 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).

Everything in this section looks good. Though I wonder whether readers
will wonder how one subscribes to the list. You sort of address this
earlier in the proposed document, but I think it's worth clarifying here
to indicate the differences between subscribing to a public list like
this one, and the invite-only git-security list.

Perhaps something like:

    [...] the archive is closed to the public, and only accessible to
    invited members.

    There are a few dozen such members: [...]

which is basically just s/subscribed/invited, but I think it adds some
worthwhile clarity.

> +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.

Looks good, though I am unsure what "priorities and requirements" refers
to specifically. Could you elaborate?

> +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.

A few nitpicks on this and the above bullet point:

  - The git-security list isn't for bug reports, though there can be a
    security component to something that looks like a bug report.

    Perhaps to be clearer we should swap "bug" for "potential
    vulnerability"?

  - On "within a couple of days", I think that this is aspirationally
    true, though not always the case. Perhaps, "as soon as possible"
    instead? That's vague enough that I wouldn't worry about somebody
    reading this document >2 days after submitting a potential
    vulnerability wondering why nobody has gotten back to them ;-).

  - Finally, consider replacing "core Git team" with "member of the
    git-security list".

> +- 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.

There's a third option, too, which is using the private git/cabal
repository. Anybody who is a member of the @git/security team on GitHub
has access to this repository. And it is often a convenient option for
coordinating releases that contain fixes for more than one
vulnerability.

There aren't any hard and fast rules for which approach should be used
in a given circumstance, but I think it's worth mentioning it as another
option.

For my own $.02, I often find it useful to *start* by sending patches to
the git-security list inline with the thread so that the original
reporter (who is more often than not *not* a member of the @git/security
team) can participate in review (or at least look at the patches).

The private forks tied to a security advisory are often convenient
(assuming that the reporter has a GitHub account) since they provide a
shared workspace. But I think we usually avoid them when working on
preparing a release for more than one vulnerability.

> +- 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.

I strongly agree with the above two points.

> +- 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.

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.

> +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.

This is all good. I would add some of the things we need to figure out
before opening a security advisory, too. By the time we want to open a
security advisory, we need to have the following information decided
upon:

  - Affected version(s)
  - Patched version(s)
  - Impact
  - Potential workaround(s), if any
  - Credit for finding and fixing the vulnerability

Determining which versions to patch is more-or-less up to the person
preparing those patches. Affected versions is usually "everything", or
"everything since xyz patch was merged". Impact is up for debate, though
usually whoever opens the security advisory writes this, and then
discussion occurs on the git-security as to its accuracy ;-).

Obtaining permission to give credit to the original reporter (and
anybody that they wish to include who was also involved in the
discovery) is important to do at this step, too.

Thanks,
Taylor

Re: [PATCH v2] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

Taylor Blau <me@ttaylorr.com> writes:

>> +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.
>
> A few nitpicks on this and the above bullet point:
>
>   - The git-security list isn't for bug reports, though there can be a
>     security component to something that looks like a bug report.
>
>     Perhaps to be clearer we should swap "bug" for "potential
>     vulnerability"?

Good point and good idea.

>   - On "within a couple of days", I think that this is aspirationally
>     true, though not always the case. Perhaps, "as soon as possible"
>     instead? That's vague enough that I wouldn't worry about somebody
>     reading this document >2 days after submitting a potential
>     vulnerability wondering why nobody has gotten back to them ;-).

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".

>   - Finally, consider replacing "core Git team" with "member of the
>     git-security list".

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 ;-)

> The private forks tied to a security advisory are often convenient
> (assuming that the reporter has a GitHub account) since they provide a
> shared workspace. But I think we usually avoid them when working on
> preparing a release for more than one vulnerability.

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.

Re: [PATCH v2] embargoed releases: also describe the git-security list and the process

[Taylor Blau]

On Wed, Oct 19, 2022 at 05:15:03PM -0400, Taylor Blau wrote:
> > +- 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.
>
> There's a third option, too, which is using the private git/cabal
> repository. Anybody who is a member of the @git/security team on GitHub
> has access to this repository. And it is often a convenient option for
> coordinating releases that contain fixes for more than one
> vulnerability.
>
> There aren't any hard and fast rules for which approach should be used
> in a given circumstance, but I think it's worth mentioning it as another
> option.
>
> For my own $.02, I often find it useful to *start* by sending patches to
> the git-security list inline with the thread so that the original
> reporter (who is more often than not *not* a member of the @git/security
> team) can participate in review (or at least look at the patches).
>
> The private forks tied to a security advisory are often convenient
> (assuming that the reporter has a GitHub account) since they provide a
> shared workspace. But I think we usually avoid them when working on
> preparing a release for more than one vulnerability.

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

[PATCH v3] embargoed releases: also describe the git-security list and the process

[Julia Ramer via GitGitGadget]

From: Julia Ramer <gitprplr@gmail.com>

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.

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Julia Ramer <gitprplr@gmail.com>
---
    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 <gitster@pobox.com>
     +    Helped-by: Taylor Blau <me@ttaylorr.com>
          Signed-off-by: Julia Ramer <gitprplr@gmail.com>
      
       ## 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 <distros@vs.openwall.org> (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 <oss-security@lists.openwall.org> (see below for details) is sent
      +  as a follow-up to the <distros@vs.openwall.org> 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: oss-security@lists.openwall.com
     -@@ 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(-)

diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
index 601aae88e9a..7cd8f6241c2 100644
--- a/Documentation/howto/coordinate-embargoed-releases.txt
+++ b/Documentation/howto/coordinate-embargoed-releases.txt
@@ -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 <git-security@googlegroups.com>.
+
+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@googlegroups.com>, 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 <distros@vs.openwall.org> (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 <oss-security@lists.openwall.org> (see below for details) is sent
+  as a follow-up to the <distros@vs.openwall.org> 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
-distros@vs.openwall.org, preferably less than 7 days before the release date.
+<distros@vs.openwall.org>, 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 distros@vs.openwall.org
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: distros@vs.openwall.org
@@ -101,7 +220,7 @@ Thanks,
 ....
 
 Example mail to oss-security@lists.openwall.com
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: oss-security@lists.openwall.com

base-commit: e72d93e88cb20b06e88e6e7d81bd1dc4effe453f
-- 
gitgitgadget

Re: [PATCH v3] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

"Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Ramer <gitprplr@gmail.com>
>
> 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.
>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Helped-by: Taylor Blau <me@ttaylorr.com>
> Signed-off-by: Julia Ramer <gitprplr@gmail.com>
> ---

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

> +Typical timeline
> +----------------

A much better section title; I like it.

> +- 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.

Here, we name "the git/cabal repository" but the word never appears
again in the document, we later refer to the same thing "private
repositories that are owned by the Git project, with tightly
controlled access", but to outsiders, it is not clear that they are
the same thing.  Perhaps writing

    ..., or the git/cabal repository (private repository owned by
    the Git project with tightly controlled access).

here, and replacing the later reference with just "the git/cabal
repository", would be sufficient.

> +  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.

Mark-up glitch.  This one is formatted as a <pre>...text...</pre>
under the above bullet point.  Logically this is still a part of the
above bullet point (i.e. its second paragraph), so we'd need to
replace the blank line above this second paragraph with a line with
single '+' and nothing else on it, and de-dent this second paragraph.

Or we can make it a separate bullet point, which may make it simpler
to read in the source form.

> +- 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

We typically know how involved the final changes would be (i.e. the
minimum time it would take for us and involved others to prepare the
release) way before all the t's are crossed and i's are dotted in
the patches, so setting the release date may be done much earlier.

> +- 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.

I briefly wondered if we need to say something about stakeholders
other than packagers (e.g. hosting sites), but it would probably be
obvious to readers that those who can deploy before releasing their
version of the sources have enough flexibility to cope better, so
the above would be fine.

> +- Subsequently, branches with the fixes are pushed to private repositories that
> +  are owned by the Git project, with tightly controlled access.

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

> +- The tags are created by the Git maintainer and pushed to the same
> +  repositories.

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.

> +- Less than a week before the release, a mail with the relevant information is
> +  sent to <distros@vs.openwall.org> (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.

I am not sure how much value it adds to have ", but no further..."
at the end.  Anybody who sees this e-mail has the Git bundle, which
is relative to the last stable release, and can be used to create
the full source of the releases by anybody who has access to the
public Git repositories.  The source includes the release notes in
the Documentation/RelNotes/ directory that describe everything to
know about the vulnerabilities the releases address.

    ... This includes a Git bundle of the tagged version(s), using
    which the full source code for the releases can be created by
    the recipients to prepare their release artifacts in a clone of
    the public Git repository.

Re: [PATCH v3] embargoed releases: also describe the git-security list and the process

[Julia Ramer]

On Fri, Oct 21, 2022 at 9:42 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> > +- 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.
>
> Here, we name "the git/cabal repository" but the word never appears
> again in the document, we later refer to the same thing "private
> repositories that are owned by the Git project, with tightly
> controlled access", but to outsiders, it is not clear that they are
> the same thing.  Perhaps writing
>
>     ..., or the git/cabal repository (private repository owned by
>     the Git project with tightly controlled access).
>
> here, and replacing the later reference with just "the git/cabal
> repository", would be sufficient.

Fixed in the next version!

> > +  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.
>
> Or we can make it a separate bullet point, which may make it simpler
> to read in the source form.

Fixed, thanks for pointing that out.

> > +- 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
>
> We typically know how involved the final changes would be (i.e. the
> minimum time it would take for us and involved others to prepare the
> release) way before all the t's are crossed and i's are dotted in
> the patches, so setting the release date may be done much earlier.

Distilled into s/ready/nearing the finish line/

>
> > +- Less than a week before the release, a mail with the relevant information is
> > +  sent to <distros@vs.openwall.org> (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.
>
> I am not sure how much value it adds to have ", but no further..."
> at the end.  Anybody who sees this e-mail has the Git bundle, which
> is relative to the last stable release, and can be used to create
> the full source of the releases by anybody who has access to the
> public Git repositories.  The source includes the release notes in
> the Documentation/RelNotes/ directory that describe everything to
> know about the vulnerabilities the releases address.

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

Re: [PATCH v3] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

Julia Ramer <prplr@github.com> writes:

>> > +- 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
>>
>> We typically know how involved the final changes would be (i.e. the
>> minimum time it would take for us and involved others to prepare the
>> release) way before all the t's are crossed and i's are dotted in
>> the patches, so setting the release date may be done much earlier.
>
> Distilled into s/ready/nearing the finish line/

Excellent.

>> > +- Less than a week before the release, a mail with the relevant information is
>> > +  sent to <distros@vs.openwall.org> (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.
> ...
> I think it makes sense to just remove the entire last sentence, as the
> relevant information is referenced in the parenthetical "(see below)".

Very sensible.

Thanks.

Re: [PATCH v3] embargoed releases: also describe the git-security list and the process

[Taylor Blau]

On Fri, Oct 21, 2022 at 07:41:49AM +0000, Julia Ramer via GitGitGadget wrote:
> ---
> .../howto/coordinate-embargoed-releases.txt   | 175 +++++++++++++++---
> 1 file changed, 147 insertions(+), 28 deletions(-)

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.

> +- The security-list members start a discussion to give an initial

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

> +  assessment of the severity of the reported potential vulnerability.
> +  We aspire to do so within a few days.

Well put.

> +- 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.

There is some slightly odd wrapping between this and adjacent bullet
points. It looks like the width of these lines is slightly shorter than
the others.

> +- 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

There are a few extra spaces between "from stakeholders." and "Operators"

Thanks,
Taylor

[1]: https://lore.kernel.org/git/xmqqo7u5m8ku.fsf@gitster.g/

Re: [PATCH v3] embargoed releases: also describe the git-security list and the process

[Julia Ramer]

Thanks, I incorporated all suggestions into the next version.

On Fri, Oct 21, 2022 at 5:11 PM Taylor Blau <me@ttaylorr.com> wrote:
>
> On Fri, Oct 21, 2022 at 07:41:49AM +0000, Julia Ramer via GitGitGadget wrote:
> > ---
> > .../howto/coordinate-embargoed-releases.txt   | 175 +++++++++++++++---
> > 1 file changed, 147 insertions(+), 28 deletions(-)
>
> 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.
>
> > +- The security-list members start a discussion to give an initial
>
> s/security-list members/members of the git-security list/.
>
> > +  assessment of the severity of the reported potential vulnerability.
> > +  We aspire to do so within a few days.
>
> Well put.
>
> > +- 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.
>
> There is some slightly odd wrapping between this and adjacent bullet
> points. It looks like the width of these lines is slightly shorter than
> the others.
>
> > +- 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
>
> There are a few extra spaces between "from stakeholders." and "Operators"
>
> Thanks,
> Taylor
>
> [1]: https://lore.kernel.org/git/xmqqo7u5m8ku.fsf@gitster.g/

[PATCH v4] embargoed releases: also describe the git-security list and the process

[Julia Ramer via GitGitGadget]

From: Julia Ramer <gitprplr@gmail.com>

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.

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Julia Ramer <gitprplr@gmail.com>
---
    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 <distros@vs.openwall.org> (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: oss-security@lists.openwall.com
     +@@ 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(-)

diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
index 601aae88e9a..e653775bab1 100644
--- a/Documentation/howto/coordinate-embargoed-releases.txt
+++ b/Documentation/howto/coordinate-embargoed-releases.txt
@@ -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 <git-security@googlegroups.com>.
+
+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@googlegroups.com>, 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 <distros@vs.openwall.org> (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 <oss-security@lists.openwall.org> (see below for details) is sent
+  as a follow-up to the <distros@vs.openwall.org> 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
-distros@vs.openwall.org, preferably less than 7 days before the release date.
+<distros@vs.openwall.org>, 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 distros@vs.openwall.org
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: distros@vs.openwall.org
@@ -101,7 +216,7 @@ Thanks,
 ....
 
 Example mail to oss-security@lists.openwall.com
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ....
 To: oss-security@lists.openwall.com
@@ -128,4 +243,4 @@ it goes to <developer>.
 
 Thanks,
 <name>
-....
+....
\ No newline at end of file

base-commit: e72d93e88cb20b06e88e6e7d81bd1dc4effe453f
-- 
gitgitgadget

Re: [PATCH v4] embargoed releases: also describe the git-security list and the process

[Junio C Hamano]

"Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Ramer <gitprplr@gmail.com>
>
> 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.
>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Helped-by: Taylor Blau <me@ttaylorr.com>
> Signed-off-by: Julia Ramer <gitprplr@gmail.com>
> ---
>     embargoed releases: also describe the git-security list and the process
>     
>     Changes since v3:
>     
>      * minor formatting corrections
>      * clarified the language based on v3 feedback

Thanks, this version I am happy with.