silverstripeltd / silverstripe-csp
A module for CSP headers in Silverstripe.
Installs: 5 339
Dependents: 1
Suggesters: 0
Security: 0
Stars: 9
Watchers: 18
Forks: 3
Open Issues: 4
Type:silverstripe-vendormodule
Requires
- php: ^8.1
- silverstripe/cms: ^5
- silverstripe/framework: ^5
Requires (Dev)
README
Make your site like super secure with CSP headers and SRI tags on your scripts.
This module is not currently supported, it will frequently change and break APIs.
Requirements
- SilverStripe ^5 (4.11+ available in previous tags)
Installation
First you install it, then you configure it. Like lego!
composer require silverstripeltd/silverstripe-csp
Documentation
First you're going to want to create a Policy you'll likely want to extend the Basic policy as a good starting ground.
This will look something like:
class ContentSecurityPolicy extends Basic { public function configure(): void { parent::configure(); } }
You can then start adding in fragments. These are small pieces of code that resemble a CSP for a service. For example YouTube's is:
class YouTube implements Fragment { public static function addTo(Policy $policy): void { $policy ->addDirective(Directive::SCRIPT, [ 'www.youtube.com', 's.ytimg.com', ]) ->addDirective(Directive::FRAME, "*.youtube.com"); } }
If you need to add a new fragment or update an existing one please make a pull request to the repo. You've either found a potential issue for all our projects using this, or you're adding a new service which other projects can benefit from
Adding fragments to your policy looks like this (in configure func from above):
public function configure(): void { parent::configure(); $this->addFragments([YouTube::class]); }
Usually you'll define private const FRAGMENTS = []
and add them in there so it's clear at the beginning what fragments you're adding.
To set the report to url, we usually use an env var named CSP_REPORT_TO
. The expiry time can also be set using CSP_REPORT_TO_TTL
this tells the browser how long it should remember the url for.
You can also call $this->reportTo()
in your policies configure func if required (perhaps you want the report URI based on the policy applied).
Reporting can be sent to multiple urls if required, CSP_REPORT_TO
supports CSV, or the directive can be used with an array.
To add the policy to the list of applied policies you'll want to add some yaml config:
Silverstripe\CSP\CSPMiddleware: policies: - 'Silverstripe\CSP\Policies\CMS' - 'App\ContentSecurityPolicy'
In the above we've added it to be checked after the CMS policy that is included by default.
To make the policy report only you can either add the env var CSP_REPORT_ONLY='enabled'
or code it in your policy, for example:
public function configure(): void { parent::configure(); if (Director::isDev()) { $this->reportOnly(); } }
Google Tag Manager / Adservices whitelist
Google uses localised regional domains for visitors for image tracker loading, which can pile up report violations with google.com|.co.nz|.com.au
etc in your reporting tool.
To resolve this and rather than specifying all of Google's listed support domains (see https://www.google.com/supported_domains)
A white list config can be set to the GTM fragment to whitelist all https:
URLs on the img-src
directive, for example:
Silverstripe\CSP\Fragments\GoogleTagManager: whitelist_google_regional_domains: true
See also ImagesOverHTTPs::class for more basic cover of https images.
SRI
We also support SRI in this module, you can enable this via yaml:
Silverstripe\CSP\CSPMiddleware: sri_enabled: true
This will add SRI hashes to resources added through the requirements. It will not do this to the resources added through insertHeadTags
. It will also not create this for files that are dynamically created (e.g. tinymce files)
We won't add SRI hashes for external resources, if this is required then you should be adding them in yourself after being provided them by the external resource (we don't do this as we can't control when or how often those are recalculated)
dev/build will clear the SRI records (we keep these to ensure we don't generate them per request). This has been added through the DevBuildExtension
Todo list:
- Add the ability to hash inline scripts (this would sit in
CSPBackend
) - Add Google analytics and tag manager (this will happen shortly)
- Add unit tests
Maintainers
- Adrian adrhumphreys@gmail.com
Bugtracker
Bugs are tracked in the issues section of this repository. Before submitting an issue please read over existing issues to ensure yours is unique.
If the issue does look like a new bug:
- Create a new issue
- Describe the steps required to reproduce your issue, and the expected outcome. Unit tests, screenshots and screencasts can help here.
- Describe your environment as detailed as possible: SilverStripe version, Browser, PHP version, Operating System, any installed SilverStripe modules.
Please report security issues to the module maintainers directly. Please don't file security issues in the bugtracker.
Development and contribution
If you would like to make contributions to the module please ensure you raise a pull request and discuss with the module maintainers.
License
See License