content_security_policy

Type String
Mandatory No
Manifest version 2 or higher
Example Manifest V2:
"content_security_policy": "default-src 'self'"
Manifest V3:
"content_security_policy": {
  "extension_pages": "default-src 'self'"
}

Extensions have a content security policy applied to them by default. The default policy restricts the sources from which they can load code (such as <script> resources), and disallows potentially unsafe practices such as the use of eval(). See Default content security policy to learn more about the implications of this.

You can use the "content_security_policy" manifest key to loosen or tighten the default policy. This key is specified in just the same way as the Content-Security-Policy HTTP header. See Using Content Security Policy for a general description of CSP syntax.

For example, you can use this key to:

  • Restrict permitted sources for other types of content, such as images and stylesheets, using the appropriate policy directive.
  • Allow the extension to take advantage of WebAssembly by including the 'wasm-unsafe-eval' source in the script-src directive.
  • Loosen the default script-src policies (Manifest V2 only):

There are restrictions on the policy you can specify here:

  • The script-src directive must include at least the 'self' keyword, and may only contain secure sources. The set of permitted secure sources differ between Manifest V2 and Manifest V3.
  • The policy may include just default-src (without script-src) if its sources meet the requirement for the script-src directive.
  • The object-src keyword may be required in some browsers that support obsolete plugins. If required, it should be set to a secure source such as 'none'. This may be required for browsers up until 2022 (more information).
  • Directives that reference code – script-src, script-src-elem, worker-src, and default-src (if used as fallback) share the same secure source requirement. There are no restrictions on CSP directives that cover non-script content, such as img-src.

In Manifest V3, all CSP sources that refer to external or non-static content are forbidden. The only permitted values are 'none', 'self', and 'wasm-unsafe-eval'. In Manifest V2, a source for a script directive is considered secure if it passes the following criteria:

  • Wildcard hosts are not permitted, such as "script-src 'self' *".
  • Remote sources must use https: schemes.
  • Remote sources must not use wildcards for any domains in the public suffix list (so "*.co.uk" and "*.blogspot.com" are not allowed, although "*.foo.blogspot.com" is allowed).
  • All sources must specify a host.
  • The only permitted schemes for sources are: blob:, filesystem:, moz-extension:, https:, and wss:.
  • The only permitted keywords are: 'none', 'self', 'unsafe-eval', and 'wasm-unsafe-eval'.

Manifest V2 syntax

In Manifest V2 there is one content security policy specified against the key, like this:

"content_security_policy": "default-src 'self'"

Manifest V3 syntax

In Manifest V3, the content_security_policy key is an object that may have any of the following properties, all optional:

Name Type Description
extension_pages String The content security policy used for extension pages. The script-src and worker-src directives may only have these values:
  • 'self'
  • 'none'
  • 'wasm-unsafe-eval'/code>
sandbox String The content security policy used for sandboxed extension pages.

Example

Valid examples

Note: Valid examples demonstrate the correct use of keys in CSP. However, extensions with 'unsafe-eval', remote script, blob, or remote sources in their CSP are not allowed for Firefox extensions as per the add-on policies and due to major security issues.

Note: The examples below include the script-src directive because this was required in older browser versions. This directive is optional in modern browsers without obsolete plugins (more information).

Require that all types of content should be packaged with the extension:

  • Manifest V2
    "content_security_policy": "default-src 'self'"
    
  • Manifest V3
    "content_security_policy": {
      "extension_pages": "default-src 'self'"
    }
    

Allow remote scripts from "https://example.com":

  • Manifest V2
    "content_security_policy": "script-src 'self' https://example.com; object-src 'self'"
    
  • Manifest V3 does not allow remote URLs in script-src of extension_pages.

Allow remote scripts from any subdomain of "jquery.com":

  • Manifest V2
    "content_security_policy": "script-src 'self' https://*.jquery.com; object-src 'self'"
    
  • Manifest V3 does not allow remote URLs in script-src of extension_pages.

Allow eval() and friends:

  • Manifest V2
    "content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self';"
    
  • Manifest V3 does not allow 'unsafe-eval' in script-src.

Allow the inline script: "<script>alert('Hello, world.');</script>":

  • Manifest V2
    "content_security_policy": "script-src 'self' 'sha256-qznLcsROx4GACP2dm0UCKCzCG+HiZ1guq6ZZDob/Tng='; object-src 'self'"
    
  • Manifest V3 does not allow CSP hashes in script-src of extension_pages.

Keep the rest of the policy, but also require that images should be packaged with the extension:

  • Manifest V2
    "content_security_policy": "script-src 'self'; object-src 'self'; img-src 'self'"
    
  • Manifest V3
    "content_security_policy": {
      "extension_pages": "script-src 'self'; object-src 'self'; img-src 'self'"
    }
    

Enable the use of WebAssembly:

  • Manifest V2 For backward compatibility, Manifest V2 extensions in Firefox can use WebAssembly without the use of 'wasm-unsafe-eval'. However, this behavior isn't guaranteed, see bug 1770909. Extensions using WebAssembly are therefore encouraged to declare 'wasm-unsafe-eval' in their CSP. See WebAssembly on the Content Security Policy page for more information.
    "content_security_policy": "script-src 'self' 'wasm-unsafe-eval'"
    
  • Manifest V3
    "content_security_policy": {
      "extension_pages": "script-src 'self' 'wasm-unsafe-eval'"
    }
    

Invalid examples

Policy that omits the "object-src" directive (only invalid in browsers that support obsolete plugins; more information):

"content_security_policy": "script-src 'self' https://*.jquery.com;"

Policy that omits the "self" keyword in the "script-src" directive:

"content_security_policy": "script-src https://*.jquery.com; object-src 'self'"

Scheme for a remote source is not https:

"content_security_policy": "script-src 'self' http://code.jquery.com; object-src 'self'"

Wildcard is used with a generic domain:

"content_security_policy": "script-src 'self' https://*.blogspot.com; object-src 'self'"

Source specifies a scheme but no host:

"content_security_policy": "script-src 'self' https:; object-src 'self'"

Directive includes the unsupported keyword 'unsafe-inline':

"content_security_policy": "script-src 'self' 'unsafe-inline'; object-src 'self'"

Browser compatibility

BCD tables only load in the browser