document the new confidential issue filter

See gitlab#145 and gitlab#23.

howto/gitlab.md

@@ -61,10 +61,24 @@ private to the members of the project the issue is reported on (the
 Keep in mind, however, that it is still possible issue information
 gets leaked in cleartext, however. For example, GitLab [sends email
 notifications in cleartext for private issue](https://gitlab.com/gitlab-org/gitlab/-/issues/5816), an known upstream
-issue. (We have [decided we cannot fix this ourselves in GitLab for
-now](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/23).) Some repositories might also have "web hooks" that notify
-IRC bots in clear text as well, although at the time of writing all
-projects are correctly configured.
+issue.
+
+We have [deployed a workaround for this](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/23) which redacts outgoing
+mail, but there's still some metadata leaking there:
+
+ * the issue number
+ * the reporter
+ * the project name
+ * the reply token (allowing someone to impersonate a reply)
+
+Some repositories might also have "web hooks" that notify IRC bots in
+clear text as well, although at the time of writing all projects are
+correctly configured. The IRC side of things, of course, might also
+leak information.
+
+Note that internal notes are currently *not* being redacted, because
+of a limitation in how GitLab fails to add a special header for those
+outgoing emails, see [issue 145](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/145).
 
 ## How to contribute code?
 
@@ -1441,6 +1455,78 @@ Update: see [service/static-shim](service/static-shim) for the chosen
 solution to deploy websites built in GitLab CI to the static mirror
 system.
 
+### Redacting GitLab confidential issues
+
+Back in 2022, we embarked in the complicated affair of making GitLab
+stop [sending email notifications in cleartext for private
+issue](https://gitlab.com/gitlab-org/gitlab/-/issues/5816). This involved [MR 101558](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101558) and [MR 122343](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122343), merged in
+GitLab 16.2 for the GitLab application side. Those add a header like:
+
+    X-GitLab-ConfidentialIssue: true
+
+To outgoing email when a confidential issue is created or commented
+on, or when an "internal note" is added.
+
+That header, in turn, is parsed by the outgoing Postfix server to
+redact those emails. This is done through a [header_checks(5)](https://www.postfix.org/header_checks.5.html) in
+`/etc/postfix/header_filter_check`:
+
+    /^X-GitLab-ConfidentialIssue:\ true/ FILTER confidential_filter:
+
+That, in turn, sends the email through a [pipe(8)](https://www.postfix.org/pipe.8.html) transport
+defined in `master.cf`:
+
+```
+confidential_filter   unix  -       n       n       -       10      pipe
+    flags=Rq user=gitlab-confidential null_sender=
+    argv=/usr/local/sbin/gitlab_confidential_filter --from ${sender} -- ${recipient}
+```
+
+... which, in turn, calls the `gitlab_confidential_filter` Python
+program which does the following:
+
+ 1. parse the email
+ 2. if it has a `X-GitLab-ConfidentialIssue: true` header, parse the
+    email to find the "signature" which links to the relevant GitLab
+    page
+ 3. prepend a message to that signature
+ 4. replace the body of the original message with that redaction
+ 5. resend the message after changing the `X-GitLab-ConfidentialIssue`
+    header to `redacted` to avoid loops
+ 
+Notes that if a filtered message does not have a
+`X-GitLab-ConfidentialIssue: true` header (which should never happen),
+it just resends the email as is, as a safety fallback.
+
+The filter also relies on other GitLab headers to find the original
+issue and synthesize a replacement body for the redaction.
+
+The replacement message is:
+
+```
+A new confidential issue was reported and its content was redacted
+from this email notification.
+```
+
+... followed by the standard boilerplate GitLab normally appends to
+outgoing email:
+
+```
+Reply to this email directly or view it on GitLab: $URL
+```
+
+New comments on issues see a slightly different message:
+
+```
+A comment was added to a confidential issue and its content was
+redacted from this email notification.
+```
+
+... followed by the same standard boilerplate.
+
+All of this is deployed by Puppet in the `profile::gitlab::app` class
+and some hacks buried in the `profile::postfix` class and its templates.
+
 ## Issues
 
 [File][] or [search][] for issues in the [gitlab project][search].