Download the PHP package spatie/laravel-csp without Composer

Set content security policy headers in a Laravel app

[](https://packagist.org/packages/spatie/laravel-csp)   [](https://packagist.org/packages/spatie/laravel-csp)

By default, all scripts on a webpage are allowed to send and fetch data to any site they want. This can be a security problem. Imagine one of your JavaScript dependencies sends all keystrokes, including passwords, to a third party website.

It's very easy for someone to hide this malicious behaviour, making it nearly impossible for you to detect it (unless you manually read all the JavaScript code on your site). For a better idea of why you really need to set content security policy headers, read this excellent blog post by David Gilbertson.

Setting Content Security Policy headers helps solve this problem. These headers dictate which sites your site is allowed to contact. This package makes it easy for you to set the right headers.

This readme does not aim to fully explain all the possible usages of CSP and its directives. We highly recommend that you read Mozilla's documentation on the Content Security Policy before using this package. Another good resource to learn about CSP, is this edition of the Larasec newsletter by Stephen Rees-Carter.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

You can publish the config-file with:

This is the contents of the file which will be published at config/csp.php:

You can add CSP headers to all responses of your app by registering Spatie\Csp\AddCspHeaders::class as global middleware in bootstrap/app.php.

Alternatively you can apply the middleware on the route or route group level.

You can also pass a preset class as a parameter to the middleware:

The given preset will override the ones configured in the config/csp.php config file for that specific route or group of routes.

Alternatively, you can register your CSP policies as a meta tag using our Blade directives.

Usage

This package ships with a few commonly used presets to get your started. We're happy to receive PRs for more services!

Register the presets you want to use for your application in config/csp.php under the presets or report_only_presets key.

If you have app-specific needs or the service you're integrated isn't included in this package, you can create your own preset as explained below. You can also register global directives in the configuration file using a tuple notation.

Here you may also create multiple directive & value combinations by padding multiple values in the tuple.

Creating a preset

An example of a CSP directive is script-src. If this has the value 'self' www.google.com then your site can only load scripts from its own domain or www.google.com. You'll find a list with all CSP directives at Mozilla's excellent developer site.

According to the spec certain directive values need to be surrounded by quotes. Examples of this are 'self', 'none' and 'unsafe-inline'. When using add function you're not required to surround the directive value with quotes manually. We will automatically add quotes. Script/style hashes, as well, will be auto-detected and surrounded with quotes.

You may also use the same keywords for multiple directives by passing an array of directives.

Or multiple keywords for one or more directives.

There are also a few cases where you don't have to or don't need to specify a value, eg. upgrade-insecure-requests, block-all-mixed-content, ... In this case you can use the following value:

This will output a CSP like this:

The presets key of the csp config file is set to [\Spatie\Csp\Presets\Basic::class] by default. This class allows your site to only use images, scripts, form actions of your own site.

You can allow fetching scripts from www.google.com by writing a custom preset.

Don't forget to update the presets key in the csp config file to the class name of your preset.

Using inline scripts and styles

When using CSP you must specifically allow the use of inline scripts or styles. The recommended way of doing that with this package is to use a nonce. A nonce is a number that is unique per request. The nonce must be specified in the CSP headers and in an attribute on the html tag. This way an attacker has no way of injecting malicious scripts or styles.

First you must add the nonce to the right directives in your policy:

Next you must add the nonce to the html:

There are few other options to use inline styles and scripts. Take a look at the CSP docs on the Mozilla developer site to know more.

Integration with Vite

When building assets, Laravel's Vite plugin can generate a nonce that you can retrieve with Vite::cspNonce. You can use in your own NonceGenerator.

Don't forget to specify the fully qualified class name of your NonceGenerator in the nonce_generator key of the csp config file.

Alternatively, you can instruct Vite to use a specific value that it should use as nonce.

Outputting a CSP Policy as a meta tag

In rare circumstances, a large site may have so many external connections that the CSP header actually exceeds the max header size. Or you might be generating a static page with Laravel and don't have control over the headers when the response is sent. Thankfully, the CSP specification allows for outputting information as a meta tag in the head of a webpage.

This package provides a @cspMetaTag blade directive that you may place in the <head> of your site. This will render a header for all configured presets (both default and report-only).

You may also use this tag to render a specific preset.

Or use the @cspMetaTagReportOnly tag to render a specific preset in report-only mode.

Reporting CSP errors

In the browser

Instead of outright blocking all violations, you can put configure a CSP policy in report only mode by registering presets in the report_only_presets configuration option. In this case all requests will be made, but all violations will display in your favourite browser's console.

To an external url

Any violations against the policy can be reported to a given url. You can set that url in the report_uri key of the csp config file. A great service that is specifically built for handling these violation reports is http://report-uri.io/.

Testing

You can run all the tests with:

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you've found a bug regarding security please mail [email protected] instead of using the issue tracker.

Credits

• Freek Van der Herten
• Sebastian De Deyne
• Thomas Verhelst
• All Contributors

License

The MIT License (MIT). Please see License File for more information.