Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. These attacks are used for everything from data theft to site defacement or distribution of malware.
CSP is designed to be fully backward compatible; browsers that don't support it still work with servers that implement it, and vice-versa. Browsers that don't support CSP simply ignore it, functioning as usual, defaulting to the standard same-origin policy for web content. If the site doesn't offer the CSP header, browsers likewise use the standard same-origin policy.
Enabling CSP is as easy as configuring your web server to return the Content-Security-Policy HTTP header. (Prior to Firefox 23, the X-Content-Security-Policy header was used). See Using Content Security Policy for details on how to configure and enable CSP.
A {{ HTMLElement("meta") }} element can also be used to configure a policy. This behavior is supported since Firefox 45.
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 be loaded using HTTPS.
Using 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. 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 X-Content-Security-Policy and 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:
Content-Security-Policy: policy
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 default-src or style-src directive to restrict inline styles from being applied from a <style> element or a .style attribute
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.
Example 1
A web site administrator wants all content to come from the site's own origin (this excludes subdomains.)
Content-Security-Policy: default-src 'self'
Example 2
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
Example 3
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.
Example 4
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.
Example 5
A web site administrator of a web mail site wants to allow HTML in email, as well as images loaded from anywhere, but not JavaScript or other potentially dangerous content.
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:
Content-Security-Policy-Report-Only: policy
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 X-Content-Security-Policy-Report-Only and 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.
One powerful feature of Content Security Policy for web site administrators is the support it offers for generating and delivering reports describing attempts to attack your site. These reports are delivered by HTTP POST requests to one or more servers you specify using the report-uri policy directive. The reports are in JSON format, using the default JSON UTF-8 encoding for non-ASCII characters. This article shows you how to configure your site to use the reporting feature, as well as the format of the reports.
Browsers that support CSP always send a violation report for each attempt to violate the policy you have established if the policy contains a valid report-uri directive.
Enabling reporting
By default, violation reports aren't sent. To enable violation reporting, you need to specify the report-uri policy directive, providing at least one URI to which to deliver the reports:
Content-Security-Policy: default-src 'self'; report-uri http://reportcollector.example.com/collector.cgi
Then you need to set up your server to receive the reports; it can store or process them in whatever manner you feel is appropriate.
Note: prior to Firefox 23, the X-Content-Security-Policy header was used. This header will be deprecated in the future.
Violation report syntax
The report JSON object contains the following data:
document-uri- The URI of the document in which the violation occurred.
referrer- The referrer of the document in which the violation occurred.
blocked-uri- The URI of the resource that was blocked from loading by the Content Security Policy. If the blocked URI is from a different origin than the document-uri, then the blocked URI is truncated to contain just the scheme, host, and port.
violated-directive- The name of the policy section that was violated.
original-policy- The original policy as specified by the
Content-Security-PolicyHTTP header.
Sample violation report
http://example.com/signup.html. It uses the following policy, disallowing everything but stylesheets from cdn.example.com.Content-Security-Policy: default-src 'none'; style-src cdn.example.com; report-uri /_/csp-reports
signup.html looks like this:<!DOCTYPE html>
<html>
<head>
<title>Sign Up</title>
<link rel="stylesheet" href="css/style.css">
</head>
<body>
... Content ...
</body>
</html>
cdn.example.com, yet the website tries to load one from its own origin (http://example.com). A browser capable of enforcing CSP will send the following violation report as a POST request to http://example.com/_/csp-reports, when the document is visited:{
"csp-report": {
"document-uri": "http://example.com/signup.html",
"referrer": "",
"blocked-uri": "http://example.com/css/style.css",
"violated-directive": "style-src cdn.example.com",
"original-policy": "default-src 'none'; style-src cdn.example.com; report-uri /_/csp-reports"
}
}
As you can see, the report includes the full path to the violating resource in blocked-uri. This is not always the case. For example, when the signup.html would attempt to load CSS from http://anothercdn.example.com/stylesheet.css, the browser would not include the full path but only the origin (http://anothercdn.example.com). The CSP specification gives an explanation of this odd behaviour. In summary, this is done to prevent leaking sensitive information about cross-origin resources. Note, that even the specification got this part wrong in its example on violation reports (blocked-uri should be "http://evil.example.com").