CSP-safe design #

This page is for designers whose templates must work under a Content Security Policy (CSP). A strict policy stops an injected script from running even where a template forgets to escape a value. The administration sends one; public sites can switch one on. The settings are described in Content Security Policy.

Contents #

1. The policy in brief
2. The three rules for designs
3. Replacement patterns
4. The nonce: the rare exception
5. Auditing a design

The policy in brief #

site.ini [ContentSecurityPolicy] with Mode=auto (default) sends a report-only policy on administration siteaccesses and none on public sites; report-only and enforce can be set per siteaccess. The default directives allow only the site's own origin:

Directives[script-src]='self'
Directives[style-src]='self'
Directives[img-src]='self' data: blob:
Directives[font-src]='self' data:
Directives[connect-src]='self'

So: scripts and styles only from files on the same host; no inline <script>, no onclick="", no <style> blocks or style="" attributes once the policy is enforced.

The three rules for designs #

1. No inline JavaScript: no <script> with code, no on*= attributes, no javascript: links (No inline JavaScript).
2. No inline CSS: no <style> blocks, no style="" attributes (No inline CSS).
3. No third-party origins you have not planned: fonts, scripts, styles, frames from other hosts each need a directive change (External resources and CDNs).

Replacement patterns #

The nonce: the rare exception #

With [ContentSecurityPolicy] Nonce=enabled (default) the policy carries a fresh nonce per request for the directives in NonceDirectives[] (script-src). The template operator csp_nonce() prints it:

<script nonce="{csp_nonce()}">/* code a template truly cannot move into a file */</script>

Never print csp_nonce() inside a {cache-block} or a view-cached template: the cached copy would carry another request's nonce and the script would be blocked (comments in settings/site.ini and kernel/common/expcontentsecuritypolicyoperator.php). That is why files are always the better choice.

Auditing a design #

1. Run the site with Mode=report-only for a while and read the reports: the browser console shows them, and with ReportEndpoint=enabled the kernel writes them to var/log/csp.log, listed in Setup > Log files.

2. For administration designs and extensions, the design tests find inline code in templates:

   php vendor/bin/phpunit tests/tests/design/AdminContentSecurityPolicyTest.php
   php vendor/bin/phpunit tests/tests/design/ExtensionInlineScriptsTest.php

3. Search your own design:

   grep -rn -E "<script>|<script [^>]*>[^<]|on(click|load|change|submit)=|javascript:|<style|style=\"" extension/mytheme/design

4. When nothing is reported for the pages you use, switch the siteaccess to Mode=enforce.

Related pages #

• No inline CSS
• No inline JavaScript
• Checklist: CSP
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.