diff options
author | dcouture <dcouture@gitlab.com> | 2020-11-14 00:33:31 +0300 |
---|---|---|
committer | dcouture <dcouture@gitlab.com> | 2020-11-14 00:33:31 +0300 |
commit | 21e6e49ea68799a8d942cde078faa2614eb0d6bd (patch) | |
tree | 7f8903bb7ab0660b240886b9f729342f2725daae /README.md | |
parent | 98f967ef0b1f697277203bba981e64aa8913447d (diff) |
Add CSP meta tag
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 54 |
1 files changed, 54 insertions, 0 deletions
@@ -486,3 +486,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. |