Content Security Policy
Extensions developed with WebExtension APIs have a Content Security Policy (CSP) applied to them by default. This restricts the sources from which they can load code such as <script> and disallows potentially unsafe practices such as using
eval(). This article briefly explains what a CSP is, what the default policy is and what it means for an extension, and how an extension can change the default CSP.
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> </head> <body> <!--Some HTML content here--> <!-- Include a third-party script. See also https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity. --> <script src="https://code.jquery.com/jquery-2.2.4.js" integrity="sha256-iT6Q9iMJYuQiMWNd9lDyBUStIq/8PuOW33aOqmvFpqI=" crossorigin="anonymous"></script> <!-- Include my popup's own script--> <script src="popup.js"></script> </body> </html>
Compared to a website, extensions have access to additional privileged APIs, so if they are compromised by malicious code, the risks are greater. For this reason:
- a fairly strict content security policy is applied to extensions by default. See default content security policy.
- the extension's author can change the default policy using the
content_security_policymanifest.json key, but there are restrictions on the policies that are allowed. See
Default content security policy
The default content security policy for extensions using Manifest V2 is:
"script-src 'self'; object-src 'self';"
While for extensions using Manifest V3, the default content security policy is:
"script-src 'self'; upgrade-insecure-requests;"
These policies are applied to any extension that has not explicitly set its own content security policy using the
content_security_policy manifest.json key. It has the following consequences:
Location of script and object resources
Under the default CSP, you can only load code that is local to the extension. The CSP limits
script-src to secure sources only, which covers <script> resources, ES6 modules and web workers. In browsers that support obsolete plugins, the
object-src directive is also restricted. For more information on object-src in extensions, see the WECG issue Remove object-src from the CSP (at least in MV3)).
For example, consider a line like this in an extension's document:
This doesn't load the requested resource: it fails silently, and any object that you expect to be present from the resource is not found. There are two main solutions to this:
- download the resource, package it in your extension, and refer to this version of the resource.
- allow the remote origin you need using the
content_security_policykey or, in Manifest V3, the
eval() and friends
setTimeout("alert('Hello World!');", 500);
const f = new Function("console.log('foo');");
<script> tags and inline event handlers, meaning that the following are not permitted:
<script> console.log("foo"); </script>
<div onclick="console.log('click')">Click me!</div>
If you are currently using code like
<body onload="main()"> to run your script when the page has loaded, listen for DOMContentLoaded or load instead.
Extensions wishing to use WebAssembly require
'wasm-unsafe-eval' to be specified in the
From Firefox 102 and Chrome 103,
'wasm-unsafe-eval' can be included in the
content_security_policy manifest.json key to enable the use of WebAssembly in extensions.
Manifest V2 extensions in Firefox can use WebAssembly without
'wasm-unsafe-eval' in their CSP for backward compatibility. However, this behavior isn't guaranteed, see Firefox bug 1770909. Extensions using WebAssembly are therefore encouraged to declare
'wasm-unsafe-eval' in their CSP.
For Chrome, extensions cannot use WebAssembly in version 101 or earlier. In 102, extensions can use WebAssembly (the same behavior as Firefox 101 and earlier). From version 103, extensions can use WebAssembly if they include
'wasm-unsafe-eval' in the
content_security_policy in the manifest key.
Upgrade insecure network requests in Manifest V3
Extensions should use
wss: when communicating with external servers. To encourage this as the standard behavior, the default Manifest V3 CSP includes the
upgrade-insecure-requests directive. This directive automatically upgrades network requests to
http: to use
While requests are automatically updated, it is still recommended to use
https:-URLs in the extension's source code where possible. In particular, entries in the
host_permissions section of manifest.json should start with
*:// instead of only
Manifest V3 Extensions that need to make
ws: requests can opt out of this behavior by overriding the default CSP using the
content_security_policy manifest.json key with a policy that excludes the
upgrade-insecure-requests directive. However, to comply with the security requirements of the Add-on Policies, all user data must be transmitted securely.
CSP for content scripts
In Manifest V2, content scripts have no CSP. As of Manifest V3, content scripts share the default CSP as extensions. It is currently not possible to specify a separate CSP for content scripts (source).