README

This plugin allows you to manage the Content Security Policy of your website via October's backend.

You should know what a CSP is and how it works to use this plugin. You can read more about this topic on MDN.

Features

The OFFLINE.CSP plugin provides the following features:

The Content-Security-Policy can be configured in the backend
Preview your CSP before saving it
Policy violations are automatically logged and can be viewed in the backend
A per-request nonce is generated and can be used on demand
The nonce can optionally be injected into all <script>, <link> and <style> tags automatically
Your CSP is patched automatically so it does not break the backend functionality (unsafe-eval and unsafe-inline are required)

Getting started

Install the plugin and visit the CSP page in the backend settings. Configure the CSP according to your needs.

By default, a strict policy is set. We suggest you make your page work with this preset for optimal security.

We suggest that you start in Report only mode. This will generate console messages and a log entry for each validation of the CSP.

You can visit the log via the backend settings. You will find a log entry for every violation generated by your site. Tune your CSP until no more violations are logged.

Now you are ready to disable the Report only mode and actually block violating requests.

Adding the CSP as a meta tag

If you don't want to add the CSP header to every response, you can opt-in for certain pages by adding this meta tag:

<meta http-equiv="content-security-policy" content="{{ csp_meta() }}">

Make sure to disable the global response header in the backend settings first. Also note, that the reporting of violations is not supported using the meta tag method (they are logged to your browser console but not to the database).

Test your CSP

You can test the strength of your CSP using Google's CSP validator or the Mozilla Observatory.

Using the nonce on demand

You can access the nonce for the current request using the csp_nonce() helper function:

<script nonce="{{ csp_nonce() }}"></script>
<style nonce="{{ csp_nonce() }}"></style>

You can enable or disable the automatic injection of the nonce via the backend settings.

Modifying the CSP dynamically

Sometimes, you need to change your CSP configuration for a single page only. You can listen for the offline.csp.extend event and modify the CSP settings to your needs.

// Add this to your Plugin.php's boot method.
\Event::listen('offline.csp.extend', function (&$settings, $controller) {
     // Check for a certain page. You could also use ->fileName here.
    if (starts_with($controller->getPage()->url, '/needs-unsafe-eval')) {
        // Add the unsafe-eval option to the script_src configuration.
        $settings['script_src'][] = 'unsafe-eval';
    }
});

When things break

A misconfigured CSP can break your site. Make sure to work in Report only mode until you have fine-tuned your site to your CSP.

If for any reason you are unable to access your site after you enabled the CSP, you can run the following console command to disable the CSP header injection completely:

php artisan csp:disable

Integration with October's Turbo Router

If you are using October's Turbo Router together with a nonce, your assets will be included on every Turbo requests since Turbo thinks it is a new asset because of the new nonce attribute.

A possible solution to this problem is to send a X-Turbo-Nonce header with every request. If this header is present, the CSP plugin will re-cycle the nonce and return new content with the old nonce.

Please note that this does reduce the security of the nonce feature since a nonce becomes long-lived over multiple requests.

Example implementation

Add a csp-nonce meta tag to your head section:

<meta name="csp-nonce" content="{{ csp_nonce() }}">

Listen for the ajax:request-start event and add the X-Turbo-Nonce header to every request:

window.addEventListener('ajax:request-start', (event: CustomEvent) => {
    const request = event.detail.xhr

    // Ignore everything not in OPENED state.
    if (request.readyState !== 1) {
        return
    }

    const nonce = document.querySelector<HTMLMetaElement>('meta[name=\'csp-nonce\']')
    event.detail.xhr.setRequestHeader('X-Turbo-Nonce', nonce.content)
});

offline / oc-csp-plugin

Maintainers

Details