Download the PHP package opctim/symfony-csp-bundle without Composer

Symfony CSP Bundle

Ever fought with CSP headers? Me too. It always used to be a pain to configure CSP headers properly.

But setting CSP header directives is more important than ever! If you ever came across different tracking scripts, you probably also noticed how many additional fourth-party scripts are lazy loaded. This could lead to malicious JavaScript being loaded to your page, which could be catastrophic, especially when building payment gateways.

It even helps you with adding dynamic Nonce-Tokens when not using the unsafe-inline directive (which you should avoid)

Requirements

• PHP >= 7.4.33 with OpenSSL extension installed
• Symfony >= 5.4

Installation

Configuration

In your config/ directory, add / edit opctim_csp_bundle.yaml:

You can use any directives you want here! This is just a fancy way of writing the directives.

So:

becomes

The always_add option

As the name implies, this option adds the specified origins to all directives. This can be useful with when@dev:

Important: If you add 'none' as the first and only directive, this directive will be skipped for the always_add functionality. This feature was added in 1.1.4

You also can use when@dev to add origins to specific directives conditionally:

The report option

This bundle provides you with an easy way to configure the report feature of CSP, which tells browsers to tell your backend if your CSP configuration denies specific resources. There are currently two implementations in browsers - report-uri & report-to:

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-to

So, according to the MDN docs, this bundle adds the report-uri directive & the Reporting-Endpoint header to support new Browsers in the future.

This bundle provides a backwards compatible implementation, which should be supported by all browsers.

• url - optional You can pass an external URL here, which the browsers should report to.
• route - optional If you want to use your controller action to receive reports. This will use the UrlGenerator to generate an absolute url for you.
• route_params - optional You can pass additional route parameters here, if you're using the route parameter.
• chance - optional This fields' unit is percent. It specifies how high the chance should be to add the report directives to the response.

Here is some pseudocode explaining the change option:

This means, that for a chance of 100%, it will run every time. Depending on traffic of your app, it is recommended to set a chance of around 5-10%, to not get flooded by CSP log messages.

Dynamic nonce tokens

Dynamic nonce tokens can be extremely useful, to allow specific inline script tags in your Twig templates, without having to ignore security concerns, e.g. by not adding or hard-coding them ;)

Configuration syntax

Example

In opctim_csp_bundle.yaml:

On request, nonce(my-inline-script) will be transformed to e.g. nonce-25d2ec8bb6 and will later appear in the response CSP header.

Then, in your twig template you can simply use the csp_nonce('my-inline-script') function that is provided by this bundle:

The rendered result:

Hooking into the CSP header generation

A key feature of this bundle is the dynamic nonce implementation. The bundle hooks into the Symfony event system and generates fresh nonce tokens for you - on every request!

On request, the bundle prepares the CSP header directives to be written to headers on response. Here, the nonce() expressions from opctim_csp_bundle.yaml are parsed.

The bundle will add this value to the Response in the following three headers for compatibility across browsers:

• Content-Security-Policy
• X-Content-Security-Policy
• X-WebKit-CSP

If you want to modify the CSP header before it is written to the response, you can hook into the generation by subscribing to the opctim_csp_bundle.add_csp_header event:

Tests

Tests are located inside the tests/ folder and can be run with vendor/bin/phpunit: