====== Ubuntu - CSP (Content Security Policy) ======

The **Content-Security-Policy** HTTP response header helps you reduce XSS risks on modern browsers by declaring what dynamic resources are allowed to load via a HTTP Header.


<WRAP notice>
**NOTE**: It is known that having both **Content-Security-Policy** and **X-Content-Security-Policy** or **X-Webkit-CSP** causes unexpected behaviours on certain versions of browsers.  Please avoid using deprecated **X-*** headers.
</WRAP>

----

===== Directive Reference =====

The Content-Security-Policy header value is made up of one or more directives (defined below), multiple directives are separated with a semicolon ;

^Directive^Example Value^Description^
|default-src|'self' cdn.example.com|The <color red>default-src</color> is the default policy for loading content such as JavaScript, Images, CSS, Font's, AJAX requests, Frames, HTML5 Media. See the Source List Reference for possible values.|
|script-src|'self' js.example.com|Defines valid sources of JavaScript.|
|style-src|'self' css.example.com|Defines valid sources of stylesheets.|
|img-src|'self' img.example.com|Defines valid sources of images.|
|connect-src|'self'|Applies to <color red>XMLHttpRequest</color> (AJAX), <color red>WebSocket</color> or <color red>EventSource</color>.  If not allowed the browser emulates a 400 HTTP status code.|
|font-src|font.example.com|Defines valid sources of fonts.|
|object-src|'self'|Defines valid sources of plugins, e.g. <color red><object></color>, <color red><embed></color> or <color red><applet></color>.|
|media-src|media.example.com|Defines valid sources of audio and video, e.g. HTML5 <color red><audio></color>, <color red><video></color> elements.|
|frame-src|'self'|<color orange>[DEPRECIATED]</color>Defines valid sources for loading frames.  <color red>child-src</color> is preferred over this deprecated directive.|
|sandbox|allow-forms allow-scripts|Enables a sandbox for the requested resource similar to the <color red>iframe sandbox</color> attribute. The sandbox applies a same origin policy, prevents popups, plugins and script execution is blocked.  You can keep the sandbox value empty to keep all restrictions in place, or add values: <color red>allow-forms allow-same-origin allow-scripts allow-popups, allow-modals, allow-orientation-lock, allow-pointer-lock, allow-presentation, allow-popups-to-escape-sandbox</color>, and <color red>allow-top-navigation</color>.|
|report-uri|/some-report-uri|Instructs the browser to POST a reports of policy failures to this URI. You can also append <color red>-Report-Only</color> to the HTTP header name to instruct the browser to only send reports (does not block anything).|
|child-src|'self'|Defines valid sources for web workers and nested browsing contexts loaded using elements such as <color red><frame></color> and <color red><iframe></color>.|
|form-action|'self'|Defines valid sources that can be used as a HTML <color red><form></color> action.|
|frame-ancestors|'none'|Defines valid sources for embedding the resource using <color red><frame> <iframe> <object> <embed> <applet></color>. Setting this directive to <color red>'none'</color> should be roughly equivalent to <color red>X-Frame-Options: DENY</color>.|
|plugin-types|application/pdf|Defines valid MIME types for plugins invoked via <color red><object></color> and <color red><embed></color>.  To load an <color red><applet></color> you must specify <color red>application/x-java-applet</color>.|
|base-uri| |Restricts the URLs that can be used to specify the document base URL.|

----

===== Source List Reference =====

All of the directives that end with **-src** support similar values known as a source list. Multiple source list values can be space separated with the exception of **'none'** which should be the only value.

Domain patterns can contain both protocol and ports if you want to be specific: **<nowiki>http://*.example.com:8080</nowiki>**

^Source Value^Example^Description^
|*|img-src *|Wildcard, allows any URL except data: blob: filesystem: schemes.|
|'none'|object-src 'none'|Prevents loading resources from any source.|
|'self'|script-src 'self'|Allows loading resources from the same origin (same scheme, host and port).|
|data:|img-src 'self' data:|Allows resources to be inlined with base64 (e.g. Base64 encoded images).|
|domain.example.com|img-src domain.example.com|Allows loading resources from the specified domain name.|
|*.example.com|img-src *.example.com|Allows loading resources from any subdomain under <color red>example.com</color>.|
|<nowiki>https://cdn.com</nowiki>|img-src <nowiki>https://cdn.com</nowiki>|Allows loading resources only over HTTPS matching the given domain.|
|https:|img-src <nowiki>https:</nowiki>|Allows loading resources only over HTTPS on any domain.  Forces HTTPS.|
|'unsafe-inline'|script-src 'unsafe-inline'|Allows inline <color red><script></color> and <color red><style></color> and <color red>onclick</color> elements. This can be further secured by specifying a hash of the code.|
|'unsafe-eval'|script-src 'unsafe-eval'|Allows unsafe dynamic code evaluation such as JavaScript <color red>eval()</color>.|

----

===== How it Works =====

The **default-src**, as the name suggests, sets the default source list for the remaining directives.  If a directive isn't explicitly included in the CSP header, it will fall back to using the values in the **default-src** list.

All directives follow the same pattern:

  * **self** is used to refer to the current domain.
  * one or more URLs can be specified in a space-separated list.
  * **none** indicates that nothing should be loaded for a given directive e.g. object-src 'none' indicates that no plugins—such as Flash or Java—should be loaded.

----

===== Content-Security-Policy Examples =====

Here a few common scenarios for content security policies:

==== Allow everything but only from the same origin ====

At its simplest, we could define a CSP to load resources only from the current domain as follows:

<code bash>
default-src 'self';
</code>

----

==== Only Allow Scripts from the same origin ====

<code bash>
script-src 'self';
</code>

----

==== Allow Same Origin, Google Analytics, and Google AJAX CDN ====

<code bash>
script-src 'self' www.google-analytics.com ajax.googleapis.com;
</code>

----

==== Starter Policy ====

This policy allows images, scripts, AJAX, and CSS from the same origin, and does not allow any other resources to load (eg object, frame, media, etc).  It is a good starting point for many sites.

<code bash>
default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';
</code>

----

==== Mixed Content Policy ====

In order to prevent mixed content (resources being loaded over http, from a document loaded over https), one can use the value "https:" as a directive value.

<code bash>
Content-Security-Policy: default-src https:; connect-src https:; font-src https: data:; frame-src https:; 
img-src https: data:; media-src https:;  object-src https:; script-src 'unsafe-inline' 'unsafe-eval' https:; 
style-src 'unsafe-inline' https:;
</code>

The policy prevents mixed content, allows for scheme "data:" in font-src and img-src, allows for unsafe-inline and unsafe-eval for script-src, and unsafe-inline for style-src.

Mixed Content has two categories: Active and Passive. Passive content consists of "resources which cannot directly interact with or modify other resources on a page: images, fonts, audio, and video for example", whereas active content is "content which can in some way directly manipulate the resource with which a user is interacting.

An example to block only passive mixed content:

<code bash>
Content-Security-Policy: img-src https: data:; font-src https: data:; media-src https:;
</code>

An example to block only active mixed content:

<code bash>
Content-Security-Policy: script-src https:; style-src https:; object-src https:; connect-src https:; frame-src https:; 
</code>

----

===== Prevent Clickjacking =====

The established way of preventing clickjacking involves the use of the header X-Frame-Options (see: [[https://www.owasp.org/index.php/Clickjacking_Defense_Cheat_Sheet|Clickjacking_Defense_Cheat_Sheet]]). However, CSP 2.0 has a new directive **frame-ancestors**.

To prevent all framing of your content use:

<code bash>
Content-Security-Policy: frame-ancestors 'none'
</code>


To allow for your site only, use:

<code bash>
Content-Security-Policy: frame-ancestors 'self'
</code>


To allow for trusted domain (my-trusty-site.com), do the following:

<code bash>
Content-Security-Policy: frame-ancestors my-trusty-site.com 
</code>

<WRAP warning>
**WARNING:**  Not supported in all browsers yet.

Also, keep in mind the following (from the [[https://w3c.github.io/webappsec/specs/content-security-policy/#frame-ancestors-and-frame-options|CSP Spec]]):

<code>
The frame-ancestors directive MUST be ignored when monitoring a policy, and when a contained in a policy defined via a meta element.
</code>

In other words, this will not work when CSP is in a **<meta>** tag, and will not work when using **Content-Security-Policy-Report-Only**.

When a report is generated, the **blocked-uri** will only have a value if it is the same origin as the page. 
</WRAP>

----

===== Re-factoring inline code =====

By default CSP disables any unsigned JavaScript code placed inline in the HTML source, such as this:

<code bash>
<script>var foo = "314"<script>
</code>


The inline code can be enabled by specifying its SHA256 hash in the CSP header:

<code bash>
Content-Security-Policy: script-src 'sha256-gPMJwWBMWDx0Cm7ZygJKZIU2vZpiYvzUQjl5Rh37hKs='
</code>


This particular script's hash can be calculated using the following command:

<code bash>
echo -n 'var foo = "314"' | openssl sha256 -binary | openssl base64
</code>


Some browsers (e.g. Chrome) will also display the hash of the script in JavaScript console warning when blocking an unsigned script.

The inline code can be also simply moved to a separate JavaScript file:

<code bash>
<script>var foo = "314"<script>
</code>

becomes:

<code bash>
<script src="app.js"></script>
</code>

with 'app.js' containing the 'var foo = "314"' code.

The inline code restriction also applies to inline event handlers, so that the following construct will be blocked under CSP:

<code bash>
<button id="button1" onclick="doSomething()">
</code>

This should be replaced by `addEventListener' calls:

<code bash>
document.getElementById("button1").addEventListener('click', doSomething);
</code>

Variable assignment in inline scripts. Rather than do this:

<code bash>
<script>var foo = "314";<script>
</code>

Leverage HTML5's custom data attributes by setting the value as follows:

<code bash>
<body data-foo="314”>
   ...
</body>
</code>

And access the value by doing:

<code bash>
var itemID = document.body.getAttribute("data-foo”);
</code>

----

===== Content-Security-Policy Error Messages =====

In Chrome when a Content Security Policy Script Violation happens you get a message like this one in the Chrome Developer Tools:

<code bash>
Refused to load the script 'script-uri' because it violates the following Content Security Policy directive: "your CSP directive".
</code>

In Firefox you might see messages like this in the Web Developer Tools:

<code bash>
Content Security Policy: A violation occurred for a report-only CSP policy ("An attempt to execute inline scripts has been blocked"). The behavior was allowed, and a CSP report was sent.
</code>


----

===== Server Side Configuration =====

Any server side programming environment should allow you to send back a custom HTTP response header. You can also use your web server to send back the header.

==== Apache Content-Security-Policy Header ====

Add the following to your httpd.conf in your **VirtualHost** or in an **.htaccess** file:

<code bash>
Header set Content-Security-Policy "default-src 'self';"
</code>

----

==== Nginx Content-Security-Policy Header ====

In your **server {}** block add:

<code bash>
add_header Content-Security-Policy "default-src 'self';";
</code>

You can also append **always** to the end to ensure that nginx sends the header reguardless of response code.

----

==== IIS Content-Security-Policy Header ====

You can use the HTTP Response Headers GUI in IIS Manager or add the following to your web.config:

<code bash>
<system.webServer>
  <httpProtocol>
    <customHeaders>
      <add name="Content-Security-Policy" value="default-src 'self';" />
    </customHeaders>
  </httpProtocol>
</system.webServer>
</code>

----

===== Other Examples of CSP =====

==== Facebook ====

This is how Facebook implements CSP (line breaks added for readability).

<code bash>
default-src *;
script-src https://*.facebook.com http://*.facebook.com https://*.fbcdn.net http://*.fbcdn.net *.facebook.net *.google-analytics.com *.virtualearth.net *.google.com 127.0.0.1:* *.spotilocal.com:* 'unsafe-inline' 'unsafe-eval' https://*.akamaihd.net http://*.akamaihd.net *.atlassolutions.com;
style-src * 'unsafe-inline';
connect-src https://*.facebook.com http://*.facebook.com https://*.fbcdn.net http://*.fbcdn.net *.facebook.net *.spotilocal.com:* https://*.akamaihd.net wss://*.facebook.com:* ws://*.facebook.com:* http://*.akamaihd.net https://fb.scanandcleanlocal.com:* *.atlassolutions.com http://attachment.fbsbx.com https://attachment.fbsbx.com;
</code>

Note how Facebook makes use of wildcards for both subdomains, as well as port numbers in connect-src.

----

==== Twitter ====

This is how Twitter implements CSP.

<code bash>
default-src https:;
connect-src https:;
font-src https: data:;
frame-src https: twitter:;
frame-ancestors https:;
img-src https: data:;
media-src https:;
object-src https:;
script-src 'unsafe-inline' 'unsafe-eval' https:;
style-src 'unsafe-inline' https:;
report-uri https://twitter.com/i/csp_report?a=NVQWGYLXFVZXO2LGOQ%3D%3D%3D%3D%3D%3D&ro=false;
</code>

Notice how the directives all contain https:, thus enforcing SSL.

----

===== Capturing CSP Violations with report-uri =====

Any violation of your CSP will be logged to the browser console.  Whilst that may be fine when your site is under development, it's not really practical when you deploy your CSP to production.

Instead, you can use the **report-uri** to log all CSP violations.  This directive takes a URL as its value, and makes an HTTP POST request to this URL when a CSP violation is detected.  The request body contains a JSON object that is populated with details of the violation.

To illustrate this, suppose we have a CSP as follows:

<code bash>
Content-Security-Policy:    default-src 'self'; 
                            report-uri: https://example.com/csp/report;
</code>

This means the browser is only permitted to load resources from our own domain.  However, our site uses Google Analytics, so it attempts to load JavaScript from www.google-analytics.com.  This violates our CSP, so the following JSON is submitted via a HTTP POST request to our report-uri:

<code bash>
{
    "csp-report": {
        "blocked-uri:" "http://ajax.googleapis.com"
        "document-uri:" "http://example.com/index.html"
        "original-policy": "default-src 'self'; report-uri http://example.com/csp/report"
        "referrer:" ""
        "violated-directive": "default-src 'self'"
    }
}
</code>

----

===== Content-Security-Policy-Report-Only =====

If you're thinking of implementing CSP, you can take your CSP for a dry run by using the **Content-Security-Policy-Report-Only** HTTP header instead of **Content-Security-Policy**.  This works just the same way as the CSP header, but it only reports on violations without actually enforcing the policy by blocking restricted resources.  You can even use both headers at the same time, enforcing one policy while monitoring the effect any changes might have in the other.

----

===== Test =====

https://securityheaders.io/

https://report-uri.io/home/tools

----

===== References =====

Want more info on CSP, checkout these links:

  * [[http://www.w3.org/TR/CSP1/|CSP 1.0 Spec]]
  * [[http://www.w3.org/TR/CSP2/|CSP Level 2 Spec (W3C Candidate Recommendation, 21 July 2015)]]
  * [[https://w3c.github.io/webappsec/specs/content-security-policy/|Latest Revision]]
  * [[https://content-security-policy.com/presentations/|CSP Presentations / Slides]]
  * [[https://hacks.mozilla.org/2016/02/implementing-content-security-policy/|Mozilla Tutorial: Implementing Content Security Policy]]
  * [[https://developer.mozilla.org/en-US/docs/Web/Security/CSP/CSP_policy_directives|Mozilla MDN Docs]]

  * https://content-security-policy.com/
  * https://content-security-policy.com/browser-test/
  * https://www.sitepoint.com/improving-web-security-with-the-content-security-policy/
  * http://www.cspplayground.com/csp_validator

  * https://www.owasp.org/index.php/Content_Security_Policy_Cheat_Sheet

  * http://caniuse.com/#feat=contentsecuritypolicy2