Boost Site Security & Mitigate Attacks with a Content Security Policy (CSP) was originally published on Dec 11, 2013 and has recently been updated on Aug 6, 2020 to reflect emerging trends.
A Content Security Policy (CSP) is a great way to reduce or completely remove Cross Site Scripting (XSS) vulnerabilities. With one, you can effectively disallow inline and external scripts from untrusted sources. You define the policy via an HTTP header with rules for all types of assets.
Content-Security-Policy: default-src 'self'; script-src 'self' https://www.google-analytics.com;
The example above allows assets (JS, CSS, images, etc.) from the default source — the same origin (
'self'). Scripts are also allowed from Google Analytics to make the tracking code work. Everything else is disallowed.
What is a Content Security Policy (CSP)?
Content Security Policy (CSP) is a policy to mitigate against cross-site scripting issues, and we all know that cross-site scripting is bad.
There’s work involved; you’ll need to learn how to do fundamental tasks differently…
I’m not going to try and convince you that CSP is a warm-and-fuzzy new policy. There’s work involved; you’ll need to learn how to do fundamental tasks differently, but will boost site security exponentially.
Mitigating cross site scripting
A primary goal of CSP is to mitigate and report XSS attacks. XSS attacks exploit the browser’s trust of the content received from the server. Malicious scripts are executed by the victim’s browser because the browser trusts the source of the content, even when it’s not coming from where it seems to be coming from.
CSP makes it possible for server administrators to reduce or eliminate the vectors by which XSS can occur by specifying the domains that the browser should consider to be valid sources of executable scripts. A CSP compatible browser will then only execute scripts loaded in source files received from those whitelisted domains, ignoring all other script (including inline scripts and event-handling HTML attributes).
As an ultimate form of protection, sites that want to never allow scripts to be executed can opt to globally disallow script execution.
Mitigating packet sniffing attacks
In addition to restricting the domains from which content can be loaded, the server can specify which protocols are allowed to be used; for example (and ideally, from a security standpoint), a server can specify that all content must be loaded using HTTPS.
A complete data transmission security strategy includes not only enforcing HTTPS for data transfer, but also marking all cookies with the secure flag and providing automatic redirects from HTTP pages to their HTTPS counterparts.
Sites may also use the
Strict-Transport-Security HTTP header to ensure that browsers connect to them only over an encrypted channel.
Implementing a Content Security Policy (CSP)
Configuring Content Security Policy involves adding the
Content-Security-Policy HTTP header to a web page and giving it values to control resources the user agent is allowed to load for that page.
For example, a page that uploads and displays images could allow images from anywhere, but restrict a form action to a specific endpoint. A properly designed Content Security Policy helps protect a page against a cross site scripting attack.
Specifying your policy
You can use the
Content-Security-Policy HTTP header to define your policy, where ‘policy’ is the directive:
The policy is a string containing the policy directives describing your Content Security Policy.
Writing a policy
CSPs are made up of one or more directives, multiple directives are separated with a semi-colin
;. Your policy should include a
default-src policy directive, which is a fallback for any resource type that you don’t explicitly establish (for a complete list, see the description of the
A policy needs to include a
script-src directive to prevent inline scripts from running, as well as blocking the use of
eval(). In addition, it also needs to include a
style-src directive to restrict inline styles from being applied from a
style element or a
style attribute. restrict inline styles from being applied from a
style element or a style attribute.
Content Security Policy Browser Support
CSP is designed to be fully backward compatible; browsers that don’t support it sill work with servers that implement it, and vice-versa. If one is implemented and the browser doesn’t support it, it will simply ignore it. Instead, it will default to the standard same-origin policy for web content.
For more browsers and version support, take a look at caniuse.com/contentsecuritypolicy.
Content Security Policy Examples
Here's some common scenarios that arise when writing your security policy:
A web site administrator wants all content to come from the site's own domain, excluding even subdomains.
Content-Security-Policy: default-src 'self'
A web site administrator wants to allow content from a trusted domain and all its subdomains.
Content-Security-Policy: default-src 'self' *.mydomain.com
A web site administrator wants to allow users of a web application to include images from any domain in their custom content, but to restrict audio or video media to come only from trusted providers, and all scripts only to a specific server that hosts trusted code.
Content-Security-Policy: default-src 'self'; img-src *; media-src media1.com media2.com; script-src userscripts.example.com
Here, by default, content is only permitted from the document's original host, with the following exceptions:
- Images may loaded from anywhere (note the "*" wildcard).
- Media is only allowed from media1.com and media2.com (and not from subdomains of those sites).
- Executable script is only allowed from userscripts.example.com.
An administrator for an online banking site wants to ensure that all its content is loaded using SSL, in order to prevent attackers from eavesdropping on requests.
Content-Security-Policy: default-src https://onlinebanking.jumbobank.com
Content-Security-Policy: default-src 'self' *.mailsite.com; img-src *
Note that this example doesn't specify a
script-src; with the example CSP, this site uses the setting specified by the
default-src directive, which means that scripts can be loaded only from the originating server.
Testing Your Policy
To ease deployment, CSP can be deployed in "report-only" mode. The policy is not enforced, but any violations are reported to a provided URI. Additionally, a report-only header can be used to test a future revision to a policy without actually deploying it.
You can use the
Content-Security-Policy-Report-Only HTTP header to specify your policy, like this:
If both a
Content-Security-Policy-Report-Only header and a
Content-Security-Policy header are present in the same response, both policies are honored. The policy specified in
Content-Security-Policy headers is enforced while the
Content-Security-Policy-Report-Only policy generates reports but is not enforced.
The UserCSP Addon also helps test and develop Content Security Policies for a site.
CSP Directive Reference
|Defines valid sources of stylesheets.|
|Defines valid sources of images.|
|Applies to |
|Defines valid sources of fonts.|
|Defines valid sources of plugins, eg |
|Defines valid sources of audio and video, eg HTML5 |
|Defines valid sources for loading frames.|
|Enables a sandbox for the requested resource similar to the |
|Instructs the browser to POST a reports of policy failures to this URI. You can also append |
CSP 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 seperated with the exception of
none which should be the only value.
|Wildcard, allows anything.|
|Prevents loading resources from any source.|
|Allows loading resources from the same origin (same scheme, host and port).|
|Allows loading resources via the data scheme (eg Base64 encoded images).|
|Allows loading resources from the specified domain name.|
|Allows loading resources from the any subdomain under |
|Allows loading resources only over HTTPS matching the given domain.|
|Allows loading resources only over HTTPS on any domain.|
|Allows use of inline source elements such as style attribute, onclick, or script tag bodies (depends on the context of the source it is applied to)|