summaryrefslogtreecommitdiff
path: root/Documentation/howto
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/howto')
-rw-r--r--Documentation/howto/coordinate-embargoed-releases.txt165
-rw-r--r--Documentation/howto/keep-canonical-history-correct.txt2
-rw-r--r--Documentation/howto/maintain-git.txt17
-rw-r--r--Documentation/howto/new-command.txt4
-rw-r--r--Documentation/howto/recover-corrupted-object-harder.txt2
-rw-r--r--Documentation/howto/use-git-daemon.txt2
-rw-r--r--Documentation/howto/using-merge-subtree.txt2
7 files changed, 157 insertions, 37 deletions
diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt
index 601aae8..b9cb95e 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 gives 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
diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.txt
index 35d48ef..5f800fd 100644
--- a/Documentation/howto/keep-canonical-history-correct.txt
+++ b/Documentation/howto/keep-canonical-history-correct.txt
@@ -213,4 +213,4 @@ The procedure will result in a history that looks like this:
B0--B1---------B2
------------
-See also http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html
+See also https://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index a67130d..013014b 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -104,7 +104,7 @@ by doing the following:
files in mbox format).
- Write his own patches to address issues raised on the list but
- nobody has stepped up solving. Send it out just like other
+ nobody has stepped up to solve. Send it out just like other
contributors do, and pick them up just like patches from other
contributors (see above).
@@ -231,7 +231,7 @@ by doing the following:
- Prepare 'jch' branch, which is used to represent somewhere
between 'master' and 'seen' and often is slightly ahead of 'next'.
- $ Meta/Reintegrate master..seen >Meta/redo-jch.sh
+ $ Meta/Reintegrate master..jch >Meta/redo-jch.sh
The result is a script that lists topics to be merged in order to
rebuild 'seen' as the input to Meta/Reintegrate script. Remove
@@ -256,7 +256,7 @@ by doing the following:
merged to 'next', add it at the end of the list. Then:
$ git checkout -B jch master
- $ Meta/redo-jch.sh -c1
+ $ sh Meta/redo-jch.sh -c1
to rebuild the 'jch' branch from scratch. "-c1" tells the script
to stop merging at the first line that begins with '###'
@@ -283,6 +283,11 @@ by doing the following:
$ git diff jch next
+ Then build the rest of 'jch':
+
+ $ git checkout jch
+ $ sh Meta/redo-jch.sh
+
When all is well, clean up the redo-jch.sh script with
$ sh Meta/redo-jch.sh -u
@@ -293,7 +298,7 @@ by doing the following:
- Rebuild 'seen'.
- $ Meta/Reintegrate master..seen >Meta/redo-seen.sh
+ $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh
Edit the result by adding new topics that are not still in 'seen'
in the script. Then
@@ -406,13 +411,13 @@ Preparing a "merge-fix"
A merge of two topics may not textually conflict but still have
conflict at the semantic level. A classic example is for one topic
-to rename an variable and all its uses, while another topic adds a
+to rename a variable and all its uses, while another topic adds a
new use of the variable under its old name. When these two topics
are merged together, the reference to the variable newly added by
the latter topic will still use the old name in the result.
The Meta/Reintegrate script that is used by redo-jch and redo-seen
-scripts implements a crude but usable way to work this issue around.
+scripts implements a crude but usable way to work around this issue.
When the script merges branch $X, it checks if "refs/merge-fix/$X"
exists, and if so, the effect of it is squashed into the result of
the mechanical merge. In other words,
diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
index 15a4c80..880c511 100644
--- a/Documentation/howto/new-command.txt
+++ b/Documentation/howto/new-command.txt
@@ -1,13 +1,13 @@
From: Eric S. Raymond <esr@thyrsus.com>
Abstract: This is how-to documentation for people who want to add extension
- commands to Git. It should be read alongside api-builtin.txt.
+ commands to Git. It should be read alongside builtin.h.
Content-type: text/asciidoc
How to integrate new subcommands
================================
This is how-to documentation for people who want to add extension
-commands to Git. It should be read alongside api-builtin.txt.
+commands to Git. It should be read alongside builtin.h.
Runtime environment
-------------------
diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.txt
index 8994e25..5efb4fe 100644
--- a/Documentation/howto/recover-corrupted-object-harder.txt
+++ b/Documentation/howto/recover-corrupted-object-harder.txt
@@ -68,7 +68,7 @@ Note that the "object" file isn't fit for feeding straight to zlib; it
has the git packed object header, which is variable-length. We want to
strip that off so we can start playing with the zlib data directly. You
can either work your way through it manually (the format is described in
-link:../technical/pack-format.html[Documentation/technical/pack-format.txt]),
+linkgit:gitformat-pack[5]),
or you can walk through it in a debugger. I did the latter, creating a
valid pack like:
diff --git a/Documentation/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.txt
index 7af2e52..2cad9b3 100644
--- a/Documentation/howto/use-git-daemon.txt
+++ b/Documentation/howto/use-git-daemon.txt
@@ -4,7 +4,7 @@ How to use git-daemon
=====================
Git can be run in inetd mode and in stand alone mode. But all you want is
-let a coworker pull from you, and therefore need to set up a Git server
+to let a coworker pull from you, and therefore need to set up a Git server
real quick, right?
Note that git-daemon is not really chatty at the moment, especially when
diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt
index a499a94..3bd581a 100644
--- a/Documentation/howto/using-merge-subtree.txt
+++ b/Documentation/howto/using-merge-subtree.txt
@@ -11,7 +11,7 @@ Message-ID: <BAYC1-PASMTP12374B54BA370A1E1C6E78AE4E0@CEZ.ICE>
How to use the subtree merge strategy
=====================================
-There are situations where you want to include contents in your project
+There are situations where you want to include content in your project
from an independently developed project. You can just pull from the
other project as long as there are no conflicting paths.