bnomei/kirby3-security-headers

Kirby 3 Plugin for easier Security Headers setup

Kirby Content Security Policy Header

, _(*1)

Kirby Plugin for easier Content Security Policy (CSP) Headers setup., _(*2)

Installation

• unzip master.zip as folder site/plugins/kirby3-security-headers or
• git submodule add https://github.com/bnomei/kirby3-security-headers.git site/plugins/kirby3-security-headers or
• composer require bnomei/kirby3-security-headers

Default CSP Headers

The following headers will be applied by default, you do not need to set them explicitly. They provide a good starting point for most websites and ensure a sane level of security., _(*3)

X-Powered-By:                 "" # unset
X-Frame-Options:              "SAMEORIGIN"
X-XSS-Protection:             "1; mode=block"
X-Content-Type-Options:       "nosniff"
Strict-Transport-Security:    "max-age=31536000; includeSubdomains"
Referrer-Policy:              "no-referrer-when-downgrade"
Permissions-Policy:           "interest-cohort=()" # flock-off
# + various Feature-Policies...

[!TIP] See \Bnomei\SecurityHeaders::HEADERS_DEFAULT for more details., _(*4)

Zero Configuration? Almost.

Installing the plugin is enough to protect your website. A route:before-hook takes care of sending the CSP headers automatically. But you will most likely need to customize the CSP headers when using third-party services like, _(*5)

• Content Delivery Networks (CDN),
• analytic scripts like Google-Tag-Manager/Fathom/Matomo/Piwik/Plausible/Umami,
• embedding external media like from Youtube/Vimeo/Instagram/X,
• external newsletter sign-up forms from Brevo/Mailchimp/Mailjet/Mailcoach,
• any other third-party service not hosted on your domain or subdomain or
• when using inline <script> and/or <style>.

[!TIP] The plugin will automatically disable itself on local setups to not get in your way while developing. To test the CSP headers locally, you can use the 'bnomei.securityheaders.enabled' => true, option to enforce sending the headers., _(*6)

Customizing CSP Headers & Nonces

You can customize the CSP headers by providing a custom Loader and/or Setter via the Kirby config., _(*7)

Loader

The Loader is used to initially create the CSP-Builder object with a given set of mostly static data. You can provide a path to a file, return an array or null to create blank CSP-Builder object., _(*8)

[!TIP] See \Bnomei\SecurityHeaders::LOADER_DEFAULT for more details., _(*9)

[!WARNING] Consider using a custom loader ONLY if you find yourself adding a lot of configurations in the Setter. The default loader is already quite extensive and should cover most use-cases., _(*10)

Setter

The Setter is applied after the Loader. Use it to add dynamic stuff like rules for external services, hashes and nonces., _(*11)

/site/config/config.php, _(*12)

 function ($instance) {
        // https://github.com/paragonie/csp-builder
        // #build-a-content-security-policy-programmatically
        /** @var ParagonIE\CSPBuilder\CSPBuilder $csp */
        $csp = $instance->csp();
        
        // allowing all inline scripts and styles is
        // not recommended, try using nonces instead
        // $csp->setAllowUnsafeEval('script-src', true);
        // $csp->setAllowUnsafeInline('script-src', true);
        // $csp->setAllowUnsafeInline('style-src', true);
        
        // youtube
        $csp->addSource('frame', 'https://www.youtube.com');
        $csp->addSource('frame', 'https://youtube.com');
        $csp->addSource('image', 'https://ggpht.com');
        $csp->addSource('image', 'https://youtube.com');
        $csp->addSource('image', 'https://ytimg.com');
        $csp->addSource('script', 'https://google.com');
        $csp->addSource('script', 'https://youtube.com');

        // vimeo
        $csp->addSource('frame', 'player.vimeo.com');
        $csp->addSource('image', 'i.vimeocdn.com');
        $csp->addSource('script', 'f.vimeocdn.com');
        $csp->addSource('source', 'player.vimeo.com');
        $csp->addSource('style', 'f.vimeocdn.com');
    },
    // other options...
];
```

> [!TIP]
> You can define nonces in the `Setter`-option and later retrieved using `$page->nonce(...)` or `$page->nonceAttr(...)`.
> But the plugin also provides a single nonce for frontend use out of the box.

## Nonces

For convenience the plugin also provides you with a single
*frontend nonce* to use as attribute in ``, `

[!NOTE] This plugin automatically registers the nonce that Kirby creates for its panel (in case that ever might be needed)., _(*13)

Disabling the plugin

The CSP headers will be sent before Kirby renders HTML using a route:before hook but the plugin will be automatically disabled if one the following conditions apply:, _(*14)

• Kirby determines it is a local setup or
• The plugins setting bnomei.securityheaders.enabled is set to false.

[!WARNING] By default, CSP headers are never sent for any Kirby Panel, API and Media routes., _(*15)

Legacy headers

It is known that having both Content-Security-Policy and X-Content-Security-Policy or X-Webkit-CSP causes unexpected behaviors on certain versions of browsers. Please avoid using deprecated X-* headers [1]. [2], _(*16)

It is also recommended that you use Content-Security-Policy instead of XSS filtering. [3] [4], _(*17)

Settings

Dependencies

• paragonie/csp-builder

Disclaimer

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue., _(*18)

License

MIT, _(*19)

It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech., _(*20)