diff options
author | Achilleas Pipinellis <axil@gitlab.com> | 2020-10-08 09:35:09 +0300 |
---|---|---|
committer | dcouture <dcouture@gitlab.com> | 2020-10-22 17:06:33 +0300 |
commit | f494d1179980f1c116929f7e1c7196a99b4fcc9e (patch) | |
tree | 0fb5e6e52168fff6abd439fe9a2c231abc29ecd8 /README.md | |
parent | c9c969789347f37ded5a9c14bbc794820ca455d1 (diff) |
Add CSP headers
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 54 |
1 files changed, 54 insertions, 0 deletions
@@ -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. |