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 two response headers:
Reporting-Endpoints: default="{URL}"
Report-To: {"group":"default","max_age":31536000,"endpoints":[{"url":"{URL}"}],"include_subdomains":true}
Reporting-Endpoints is the current version of the header and Report-To is the earlier one, so setting both covers the widest range of browsers. Together they define a reporting endpoint 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.
Downloading Archived Files¶
For a growing collection of the scripts we see, we keep an archived copy of the exact file that matched the reported hash. When we hold a copy for a fingerprint, a Download link is shown on the report so you can retrieve the precise file that was loaded, which is useful for auditing or investigating a script after the fact.
The link appears whenever we already hold a matching copy, which covers most established third-party libraries. Very new or rarely-seen scripts may not be archived yet, and dynamically-generated scripts whose content changes on every request can't be archived at all, so a download link won't always be present.
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 version of the library containing a file you are loading has a published advisory, the file will be flagged with an issue. The advisory may concern a different file in that library, so check whether it applies to the code you load.
Clicking on this warning will list the advisories and the version that resolves them, with a link to the source of each advisory.
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 CSP Integrity reports are sampled by default. 1 in 10 is accepted and stored, and counts towards your quota in full. The other 9 in 10 are recorded as Sampled and count towards your quota at 10%, so CSP Integrity uses a little under a fifth of the quota its full volume would.
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: It will use some of your event quota, because a report is sent for every script on every page view. The default sampling keeps that to a little under a fifth of the full volume, and you can change the sample rate on the Filters page.
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
https://www.w3.org/TR/CSP3/#potentially-report-hash
https://scotthelme.co.uk/csp-cheat-sheet/
Start Monitoring with Report URI¶
Already using us for CSP? Find your report-uri value on Setup, or view your CSP Integrity reports.
New to Report URI? Your 30-day trial includes CSP Integrity along with every other feature; keeping it afterwards needs an Ultimate or Enterprise plan.