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. This article explain how to construct such headers properly, and provides examples.
Prior to Firefox 23, the
X-Content-Security-Policy HTTP header was used. Firefox 23 and later use the now-standard
Content-Security-Policy header. During the transition from the previous header to the new header, sites can send both the
Content-Security-Policy headers. In this situation, the
X-Content-Security-Policy will be ignored and the policy contained in the
Content-Security-Policy header will be used.
Specifying your policy
You can use the
Content-Security-Policy HTTP header to specify your policy, like this:
The policy is a string containing the policy directives describing your Content Security Policy.
Writing a policy
A policy is described using a series of policy directives, each of which describes the policy for a certain resource type or policy area. Your policy should include a
default-src policy directive, which is a fallback for other resource types when they don't have policies of their own. (For a complete list, see the description of the default-src directive.) A policy needs to include a default-src or script-src directive to prevent inline scripts from running, as well as blocking the use of
eval(). A policy needs to include a
style-src directive to restrict inline styles from being applied from a
<style> element or a
The syntax for a policy is a string of semicolon-separated directives, each following the syntax described in Supported policy directives.
Examples: Common use cases
This section provides examples of some common security policy scenarios.
A web site administrator wants all content to come from the site's own origin (this excludes subdomains.)
Content-Security-Policy: default-src 'self'
A web site administrator wants to allow content from a trusted domain and all its subdomains (it doesn't have to be the same domain that the CSP is set on.)
Content-Security-Policy: default-src 'self' *.trusted.com
A web site administrator wants to allow users of a web application to include images from any origin in their own content, but to restrict audio or video media to 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 origin, 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.
A web site 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
The server only permits access to documents being loaded specifically over HTTPS through the single origin 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.
Note that the
X-Content-Security-Policy-Report-Only header was used before Firefox 23. If both the
Content-Security-Policy-Report-Only are sent, the
Content-Security-Policy-Report-Only will be used and the
X-Content-Security-Policy-Report-Only will be ignored.
The UserCSP Addon also helps test and develop Content Security Policies for a site.
- Introducing Content Security Policy
- CSP policy directives
- Using CSP violation reports
- Content Security Policy recommendation bookmarklet