CSP Integrity
What is CSP Integrity?
CSP Integrity is a powerful addition to CSP that allows you to gather integrity metadata for scripts that are running on your site.
Whether you have an existing CSP in place or not, it will only take seconds to configure and enable CSP Integrity, and you can begin collecting valuable data about the scripts running on your pages.
Enable Integrity Metadata
If you already have an existing CSP header in place, you will need to add the new 'report-sha256' keyword to the script-src directive:
script-src example.com other-example.com 'report-sha256'
If you do not have an existing CSP header, you can simply add a new one with just the new keyword:
Content-Security-Policy-Report-Only: script-src 'report-sha256'
Enable the Reporting API
Once you have enabled Integrity Metadata above, you will need to tell the browser where to send the new data. For this, we will use the Reporting API. You can visit the docs page for the Reporting API for more details, but all that is required is the addition of a new response header:
Report-To: {"group":"default","max_age":31536000,"endpoints":[{"url":"{URL}"}],"include_subdomains":true}
This defines a new reporting group called default, and you can find the URL value on the Setup page of your account. You can now add this to your CSP so that Integrity Metadata is sent to your account.
report-to default;
This means your finished policy will look like this:
Content-Security-Policy-Report-Only: script-src 'report-sha256'; report-to default
Viewing Integrity Metadata
You can check the Usage Metrics table on your account Home page to see when Integrity Metadata telemetry has been received and processed, when it will show as 'Accepted' in the table. You can then head to the CSP Integrity page and view that data.
On the Reports page, you can view and search through all data using the column headings as with any of our other products. You will now be able to see Integrity Metadata for all files that we received the telemetry for.
Verified Files
Using the hash of the file as a fingerprint, we are able to cross-reference each fingerprint against our database of almost 13,000,000 verified JavaScript files to identify the file that was loaded. If we find a match for the fingerprint, the file will show as verified along with the name of the library it is from.
This allows for quick and easy auditing of the 3rd-party dependencies in use across your site, and to ensure that files are actually what they are presenting as by checking for name mismatches.
JavaScript Vulnerabilities
In addition to the above, we also have a database of known JavaScript Vulnerabilities that we can search once a file has been identified. If a known vulnerability is identified in a file that you are loading, the file will be flagged with an issue.
Clicking on this warning will give further information about the vulnerability and provide a link to the relevant source of the vulnerability information.
Quick Tips and FAQ
CSP Integrity is different to our usual features as a report/event will be sent if a script is successfully loaded, rather than blocked. This can cause more events to be sent than you might usually expect, so we have introduced an automatic downsample to support our customers. CSP Integrity will be downsampled at a rate of 1/10 events counting towards your quota as Accepted, with the other 9/10 counting as Filtered, meaning you won't be billed for them.
Q: Can I have both the report-uri and report-to value set in my CSP?
A: Yes, you can (and should) have both of these values set for maximum compatibility. It will not cause duplication of events, the browser will choose only one to send events.
Q: Do I need to build a full CSP?
A: No, if you only wish to collect Integrity Metadata, the sample policy above is sufficient.
Q: Will this use a lot of events?
A: No, we're going to downsample CSP Integrity reports for all customers at a rate of 1/10, so whilst it will of course use some event quota, it should not use excessive amounts.
Q: Is integrity metadata sent for scripts that load, or scripts that are blocked?
A: Integrity metadata is only sent for scripts that load on your page. If a script is blocked, it is not requested, so there is no file to provide integrity metadata for.
Useful Links
https://scotthelme.co.uk/capture-javascript-integrity-metadata-using-csp