From f494d1179980f1c116929f7e1c7196a99b4fcc9e Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axil@gitlab.com>
Date: Thu, 8 Oct 2020 08:35:09 +0200
Subject: Add CSP headers

---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 29b5df85..e7981077 100644
--- a/README.md
+++ b/README.md
@@ -484,3 +484,57 @@ want to receive weekly reports of the search usage, search the Google doc with
 title "Email, Slack, and GitLab Groups and Aliases", search for `docsearch`,
 and add a comment with your email to be added to the alias that gets the weekly
 reports.
+
+## CSP header
+
+The GitLab docs site uses a [Content Security Policy (CSP) header](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+as an added layer of security that helps to detect and mitigate certain types of
+attacks, including Cross Site Scripting (XSS) and data injection attacks.
+Although it is a static site, and the potential for injection of scripts is very
+low, there are customer concerns around not having this header applied.
+
+It's enabled by default on <https://docs.gitlab.com>, but if you want to build the
+site on your own and disable the inclusion of the CSP header, you can do so with
+the `DISABLE_CSP` environment variable:
+
+```shell
+DISABLE_CSP=1 bundle exec nanoc compile
+```
+
+### Adding or updating domains in the CSP header
+
+The CSP header and the allowed domains can be found in the [`csp.html`](/layouts/csp.html)
+layout. Every time a new font or Javascript file is added, or maybe updated in
+case of a versioned file, you need to update the `csp.html` layout, otherwise
+it can cause the site to misbehave and be broken.
+
+### No inline scripts allowed
+
+To avoid allowing `'unsafe-line'` in the CSP, we cannot use any inline scripts.
+For example, this is prohibited:
+
+```html
+<script>
+$(function () {
+  $('[data-toggle="popover"]').popover();
+  $('.popover-dismiss').popover({
+    trigger: 'focus'
+  })
+})
+</script>
+```
+
+Instead, this should be extracted to its own files in the
+[`/content/assets/javascripts/`](/content/assets/javascripts/) directory,
+and then be included in the HTML file that you want. The example above lives
+under `/content/assets/javascripts/toggle_popover.js`, and you would call
+it with:
+
+```html
+<script src="<%= @items['/assets/javascripts/toggle_popover.*'].path %>"></script>
+```
+
+### Testing the CSP header for conformity
+
+To test that the CSP header works as expected, you can visit
+<https://cspvalidator.org/> and paste the URL that you want tested.
-- 
cgit v1.2.3