blob: e653775bab18ddeacb03ec16beaa6d25af5ecf3d [file] [log] [blame]
Content-type: text/asciidoc
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
-------------------------------
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 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.
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].
Once the version has been published, we send a note about that to oss-security.
As an example, see https://www.openwall.com/lists/oss-security/2019/12/13/1[the
v2.24.1 mail];
https://oss-security.openwall.org/wiki/mailing-lists/oss-security[Here] are
their guidelines.
The mail to oss-security should also describe the exploit, and give credit to
the reporter(s): security researchers still receive too little respect for the
invaluable service they provide, and public credit goes a long way to keep them
paid by their respective organizations.
Technically, describing any exploit can be delayed up to 7 days, but we usually
refrain from doing that, including it right away.
As a courtesy we typically attach a Git bundle (as `.tar.xz` because the list
will drop `.bundle` attachments) in the mail to distros@ so that the involved
parties can take care of integrating/backporting them. This bundle is typically
created using a command like this:
git bundle create cve-xxx.bundle ^origin/master vA.B.C vD.E.F
tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle
Example mail to distros@vs.openwall.org
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
....
To: distros@vs.openwall.org
Cc: git-security@googlegroups.com, <other people involved in the report/fix>
Subject: [vs] Upcoming Git security fix release
Team,
The Git project will release new versions on <date> at 10am Pacific Time or
soon thereafter. I have attached a Git bundle (embedded in a `.tar.xz` to avoid
it being dropped) which you can fetch into a clone of
https://github.com/git/git via `git fetch --tags /path/to/cve-xxx.bundle`,
containing the tags for versions <versions>.
You can verify with `git tag -v <tag>` that the versions were signed by
the Git maintainer, using the same GPG key as e.g. v2.24.0.
Please use these tags to prepare `git` packages for your various
distributions, using the appropriate tagged versions. The added test cases
help verify the correctness.
The addressed issues are:
<list of CVEs with a short description, typically copy/pasted from Git's
release notes, usually demo exploit(s), too>
Credit for finding the vulnerability goes to <reporter>, credit for fixing
it goes to <developer>.
Thanks,
<name>
....
Example mail to oss-security@lists.openwall.com
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
....
To: oss-security@lists.openwall.com
Cc: git-security@googlegroups.com, <other people involved in the report/fix>
Subject: git: <copy from security advisory>
Team,
The Git project released new versions on <date>, addressing <CVE>.
All supported platforms are affected in one way or another, and all Git
versions all the way back to <version> are affected. The fixed versions are:
<versions>.
Link to the announcement: <link to lore.kernel.org/git>
We highly recommend to upgrade.
The addressed issues are:
* <list of CVEs and their explanations, along with demo exploits>
Credit for finding the vulnerability goes to <reporter>, credit for fixing
it goes to <developer>.
Thanks,
<name>
....