Content Security Policy (CSP)
An web browser is an enormously powerful and versatile piece of software, which is able to load resources from all over the internet to make up a website. This makes it a security nightmare! Extra code can be included in your website in a variety of ways, especially in the web 2.0 world we live in, where web page content is created by users.
Content Security Policy (CSP) attempts to address these issues by allowing a website to say exactly what resources to load onto a website. Website owners should, in theory, know exactly what resources are needed by their website, so why not tell the web browser not to load anything else?
How to set it up
A CSP policy is set up by sending a HTTP Header in a certain format. An example is shown below:
Header always set Content-Security-Policy: "default-src 'self' https:; script-src 'self'; style-src 'self';"
There are a variety of different settings you can send in this header and Scott Helme has an great CSP Cheat Sheet of the settings you can use, which allows you to build up a complicated policy.
Other major options include the ability to add a reporting mechanism for any policy violations to send JSON reports to a specified URL:
Header always set Content-Security-Policy: "default-src 'self' https:; \ script-src 'self'; style-src 'self'; \ report-uri https://www.tunetheweb.com/api/report/csp-report.json;"
This allows you to monitor if parts of your website are being blocked, by either an incorrect policy, or because of an incorrect browser implementation.
There is also the option of running in report only mode, which send back reports, but will not block resources from being loaded:
Header always set Content-Security-Policy-Report-Only: "default-src 'self' https:; \ script-src 'self'; style-src 'self'; \ report-uri https://www.tunetheweb.com/api/report/csp-report.json;"
This is highly recommended before you implement CSP, to test out your policy is correct and will not inadvertently block resources your website needs. This is especially if you run a large website, with many pages, and you can't be 100% sure that your policy covers every resource on every page.
Either reporting method (whether block and report with Content-Security-Policy or just report with Content-Security-Policy-Report-Only), requires a service to be set up to listen to the reports. Check out report-uri for this, to save you setting up your own one, though setting up your own is as simple as creating something that listens for JSON POST requests and then actions them. A simple example NodeJS service to list to CSP and HPKP and just log these to a log file is shown below:
However I should offer a warning about setting up a report-uri option: they are very, very noisy. Lots of browser extensions inject content into the page, which of course CSP blocks, but then reports back to your report-uri URL. Now reports are only really useful if there is something for you to action based off of (e.g. to act as a warning of an incorrect CSP policy), but for browser extension reports there's not much you can do except ignore them (which is easier said than done and adds risk of a real alert being incorrectly identified as a false positive), or allow them to reduce the noise (which leads to a more lax policy than you really want to have). Neither is great.
Also see note below about Chrome and Safari having a bug when both Content-Security-Policy and Content-Security-Policy-Report-Only headers are used at the same time.
Header always set Content-Security-Policy: "default-src 'self' https:; \ script-src 'self' 'unsafe-inline' https://www.google-analytics.com;"
However that opens up your website to all <script> tags anywhere on the page. CSP 2 adds the options for hashes, where you can calculate a hash based on the text of the script, and then allow that hash rather than all inline scripts using unsafe-inline. The new policy would look like this:
Header always set Content-Security-Policy: "default-src 'self' https:; script-src 'self' \ 'sha256-iLa0hRPsoDjvxFYYu-uNM5UI6luIzGqIS_ir0v4_XH0=' https://www.google-analytics.com;"
The easiest way to find the hash needed btw, is to load the page in Google Chrome with the policy without the has, and look at the Console in Developer Tools which helpfully will tell you the hash you need to add to your policy:
Another option, similar to using hashes, is to use a randomly generated nonce value. This is slightly trickier to set up, depending on the technology on your website, but would involve generating a random number, and setting that random number as a parameter to the script tag (<script nonce-RANDOMNUMBER>), and then adding that random number to the CSP header returned when that page is requested.
Note that when you specify a hash or a nonce, most browsers, will then automatically remove any unsafe-eval option from your policy under the assumption that you don't need both. This can cause problems if you want to start adding hashes and you've a few to get to on your site - it becomes an all or nothing option. Firefox has an even worse implementation, whereby including hashes turns off unsafe-eval, but hashes are not supported meaning all inline scripts are suddenly turned off! This bug (tracked here and which looks to be fixed now), basically stopped you being able to use hashes at all, even for browsers that do support them properly like Chrome. Firefox also prints an error saying the same thing happens for nonces, but then it goes ahead and loads the resource anyway!
<FilesMatch "\.(htm|html|php)$"> <IfModule mod_headers.c> Header always set Content-Security-Policy: "default-src 'self' https:; \ script-src 'self'; style-src 'self';" </IfModule> </FilesMatch>
This assumes you are only returning .htm, .html or .php files, but this can be extended to as many extensions as you need. I haven't found a way to send this header based on the returned MIME type (e.g. text/html).
Web server support is not necessary, as it just has to send back a header you set and not actually know anything about that. Web browser support of CSP is mixed. Although CSP 1.0 is reasonably supported by modern browsers only Chrome and Opera support most of CSP 2, which give the more secure features which such as hash-source, nonce source, which allow you to remove the use of unsafe-eval.
The issue discussed above, with Firefox not supporting hashes, but then automatically removing the unsafe-inline policy if you specify any hashes, is a terrible implementation and effectively removes the ability to use hashes in any browser (unless you want to get into browser sniffing).
Chrome and Safari also seem to have issues with implementing both "Content-Security-Policy" and "Content-Security-Policy-Report-Only" policies at the same time, if they are different, which leads to weird errors like this, where it asks for the hash that is clearly already in the policy!:
Removing either header fixes the issue.
CSP 2.0 is pretty bleeding edge, and the bugs will probably be fixed soon, but doesn't exactly make it easy to use or inspire confidence when mainstream and modern browsers like Firefox and Chrome have these issues. Who knows how smaller less mainstream browsers will act.
Evven with that, support depends, not just on your browser, but also on what third part content you have loaded. This website used to load two Twitter items (a "Tweet this page" icon, and a "Follow me" icon) and they needed unsafe-inline scripts to work (shame on Twitter and I hope you fix this!). I actually ended up replacing the official Twitter ones with my own for a few reasons including this. I also use the Disqus commenting tool which requires unsafe-inline CSS styling, and finally Google Custom Search which requires unsafe-eval and unsafe-inline on the script src (shame on Google!). This removes most of the policies you would ideally want to set up, and this is a very simple website with basically static content other than those plug-ins. The more plug-ins you have, the more lax you are likely to have to make your policy. This is especially relevant if you are loading content that is liable to change (for example advertisements which might display different content frequently).
The major downside, is that it's difficult to set up correctly unless you know all the resources used across your website. There are tools to try to help you create your CSP policy, but even they take effort. And as soon as you are loading third party content (e.g. advertisements) then a policy mike be almost impossible to implement without risking blocking some of those third party resources.
Even if you do know the resources used by your site, you probably want to clean it up to put in a safe policy, so there may be a big effort required in that. If you have no third party items on your site, then removing your own inline-scripts, to prevent the need of unsafe-inline is fairly easy in principal (just move them to .js files and load them). However this could take a lot of effort and also may produce a small performance hit (as this will cause additional network requests to load .js files that may previously have loaded inline). It is good to do this clean up, but until you do across the entire site, you will need to include the unsafe-inline option, which is one of the main ways XSS is implemented. If you do have 3rd party content (as is likely!) then this takes even more effort or may not be possible - as mentioned above, this site requires unsafe-inline on scripts (for Twitter plug-in) and styles (for Disqus) and even unsafe-eval (for Google Custom Search), which kind of defeats the point! Eventually, once support is there for CSP 2 in all browsers, those might be able to be replaced by hashes, or for 3rd parties to write plug-ins with CSP in mind.
The other issues is that even if you do get your policy set up correctly, and everything works, there is no guarantee that a third party item will not change something and break your site in future. Whether this causes your site real issues depends on what those resources are. It could be as simple as a bit of animation not work, or suddenly you start blocking all your advertisements because Google changes the way AdWords loads, or set up a new domain, which could have a major impact to the revenue of your site. Then again the alternative point of view is that if you are loading third party content then you have effectively given up the control of what is loaded in you site, and so CSP is not really for you but that seems a little defeatist.
The limited support of CSP 2 at the time of writing as discussed above, effectively means most sites will require unsafe-inline - which massively limits the usefulness of CSP for now. Additionally the current bugs can easily break a site. For example, if you have a working policy, and want to test out a new more secure one, then adding a reporting policy, might seem like a safe and sensible thing to do but will break your current site on Chrome at least.
Policies may also get quite large. The correct policy for this site looks like this:
Header always set Content-Security-Policy-Report-Only: "default-src 'none'; \ base-uri 'self'; font-src 'self' https://a.disquscdn.com; \ script-src 'self' https://www.google-analytics.com https://cse.google.com \ https://www.google.com https://www.googleapis.com https://tunetheweb.disqus.com \ https://a.disquscdn.com https://translate.googleapis.com https://translate.google.com \ https://cdn.ampproject.org https://www.gstatic.com; style-src 'unsafe-inline' 'self' https:; frame-ancestors 'none'; form-action 'none'; \ img-src 'self' https: data:; connect-src 'self' https://www.google-analytics.com;\ child-src 'self' https://disqus.com; frame-src 'self' https://disqus.com; media-src 'none'; \ object-src 'none'; report-uri https://www.tunetheweb.com/api/report/csp-report.json;"
This is a bit of a mouthful to say the least, and adds 750 characters to every request to my site. Now I do suggest you limit just to page requests as detailed above but that's still quite a lot of extra load. And this is a pretty simple site so that policy could easily grow and grow! This could end up with people choose the lowest common denominator and going with a very lax policy like, say, the following instead:
Header always set Content-Security-Policy: "default-src 'self' https: 'unsafe-inline' 'unsafe-eval';\ report-uri https://www.tunetheweb.com/api/report/csp-report.json;"
There is almost no benefit in this policy, except perhaps to limit resources to https: resources only (which most browsers will no anyway).
I've a longer blog on some of the dangers of CSP and other security headers.
CSP is a very interesting security tool, which goes a long way to resolving Cross Site Scripting attacks (XSS) and puts some level of control of what you allow in your website back to website owners. However it is not without it's risks. Even scripts and tools from the largest and most net-savy companies like Google and Twitter currently would require a very lax CSP policy which many would consider defeats a lot of the point of having any CSP policy. This will improve over time, and browser support is increasing every day. However, for now I would suggest a very lax policy, and you should definitely run in Report-Only mode initially. A very lax policy I started with, before I tightened it up with a lot of effort, is given below and would make a good general policy as an initial step into CSP (changing the report-uri to your own reporting uri, obviously):
Header always set Content-Security-Policy-Report-Only: "default-src 'self' https: 'unsafe-inline' 'unsafe-eval'; \ img-src 'self' https: data:; \ form-action 'self'; \ frame-ancestors 'none'; \ report-uri https://your-report-uri;"
This should allow most scripts still to work, and basically only allow https assets, forms to be posted to yourself, no framing but reporting.
A more strict CSP policy should be aimed for, but may be difficult to achieve. However really secure sites, like internet banking sites, that do not (or at least should not!) host any third part content, should be easier to lock down and ultimately it's those sites that will benefit most from this. For the rest of us it's I think it's a matter of a watch this space for now.
Want to read more?
More resources on CSP:
- Dangers of CSP and other Security Headers.
- Content Security Policy Level 2 W3C Candidate Recommendation.
- Scott Helme's CSP Cheat Sheet.
- Report-uri: A report webtool written by Scott Helme for HPKP or CSP reports.
- Report-uri.io Policy generator tool.
This page was originally created on and last edited on .Tweet