Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 36 ยท Permissions and Security

Content Security Policy for Extensions

Learn the default Content Security Policy of Manifest V3 extensions, why inline scripts and eval are blocked, how to fix common violations, and how to loosen the policy only where it is safe.

A Content Security Policy (CSP) is a rule set that tells the browser which scripts, styles, images and connections a page may use. Websites use it to limit damage from injected code. Extensions have one too, and in Manifest V3 it is deliberately strict: your extension cannot run remote code, and it cannot run inline script or eval either. This is the reason many snippets copied from old tutorials fail with "Refused to execute inline script".

The default policy

If you do nothing, extension pages (popup, options, side panel, offscreen documents) use this policy:

Text
script-src 'self'; object-src 'self';

In plain words: scripts may only come from files packaged inside your extension. Nothing from a CDN, nothing inline, nothing built from strings. The worker and content scripts follow the same idea, and you cannot weaken it for scripts from the network. You can only tighten it or add safe extras.

You customize it in the manifest:

JSON
{
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'; img-src 'self' data: https://images.example.com"
  }
}

Chrome rejects policies that allow remote scripts, 'unsafe-eval' or 'unsafe-inline' for scripts in extension pages. The only relaxations allowed for scripts are 'wasm-unsafe-eval' (to run WebAssembly) and a few localhost sources while developing.

Common violations and their fixes

Inline event handlers and script tags

HTML
<!-- Blocked in an extension page -->
<button onclick="save()">Save</button>
<script>save();</script>
HTML
<!-- Fixed: external file, listener added in code -->
<button id="save">Save</button>
<script src="popup.js"></script>
JavaScript
// popup.js
document.getElementById("save").addEventListener("click", save);

eval and new Function

eval("2 + 2") and new Function("return 1") are blocked. Parse data with JSON.parse, and replace string-built code with real functions or a lookup table.

Remote libraries and CDNs

HTML
<!-- Blocked: remote script -->
<script src="https://cdn.example.com/lib.js"></script>

Download the file, put it in your extension and reference it locally. The review team also needs to be able to read all the code you ship.

Inline styles are fine

The default policy does not restrict style attributes or <style> tags for scripts-only rules, but if you add your own style-src, include what you use.

Remote data is fine, remote code is not

The rule targets code. Fetching JSON, images or text from your server is allowed (with the right host_permissions). Loading JavaScript, or data that you then execute as code, is not. A template engine that compiles templates with new Function violates the policy; one that interprets templates as data does not.

Safe replacements for eval

Content scripts and the page's own CSP

Two policies exist side by side, and people confuse them:

  • Your content script runs in an isolated world under the extension's rules. The website's CSP does not stop the script from running.
  • If your content script inserts a <script> tag into the page, that code runs in the page's world and is subject to the website's CSP, and it is remote or inline code from the store's point of view. Avoid it; if you need the page's own variables, use chrome.scripting.executeScript with world: "MAIN" and a packaged function.
JavaScript
// service-worker.js (real extension code)
chrome.scripting.executeScript({
  target: { tabId },
  world: "MAIN",
  func: () => document.title       // a packaged function, not a string of code
});

Sandboxed pages: the escape hatch

If a library truly needs eval (some charting or template tools), you can place it in a sandboxed page. A sandbox page has no access to extension APIs and a different policy, and talks to the rest of the extension through postMessage.

JSON
{
  "sandbox": { "pages": ["sandbox.html"] },
  "content_security_policy": {
    "sandbox": "sandbox allow-scripts; script-src 'self' 'unsafe-eval'"
  }
}

The sandbox is embedded as an <iframe> in a normal page, which sends it input and receives the result. Use this only when no alternative exists: it is more code to maintain and review.

Reading the console

A violation prints a message such as "Refused to execute inline event handler because it violates the following Content Security Policy directive". Open the DevTools of the page that broke (right-click the popup, choose Inspect) and fix the file named in the message. See Debugging every context.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the default Manifest V3 policy allow for scripts in extension pages?

    script-src 'self' means only bundled files; inline scripts, remote scripts and eval are blocked.
  2. 2. A popup has <button onclick="save()">. What is the fix?

    Inline handlers are not allowed. Attach listeners from a packaged script.
  3. 3. Which of these is allowed?

    Remote data is allowed with host permissions. Remote code is not.
  4. 4. Where can a library that needs eval run?

    Sandboxed pages may relax the policy but have no access to extension APIs and talk through postMessage.

Summary

  • Extension pages default to script-src 'self': no inline code, no eval, no remote scripts.
  • Replace inline handlers with listeners, eval with data and lookup tables, CDN libraries with packaged copies.
  • Remote data is fine; remote code is not.
  • Use world: "MAIN" with a packaged func for page-world work and sandboxed pages only as a last resort.

Next: Secure Messaging and Untrusted Input