The CSP Wizard¶
The CSP Wizard was created to take the pain out of building a robust Content Security Policy for your site. By using your reports to build the policy for you, the Wizard can get you up and running in no time!
If you'd prefer, you can watch our short webinar: Getting Started With CSP and the CSP Wizard!
Getting Started¶
Using the Wizard is easy, you can get started with just a few easy steps and don't worry, whilst using the Wizard there's no risk of breaking anything on your site.
Content-Security-Policy-Report-Only: default-src 'none'; script-src 'report-sha256'; form-action 'none'; frame-ancestors 'none'; report-uri {REPORT_URI}; report-to wizard
Reporting-Endpoints: default="{REPORTING_API_URL}", wizard="{REPORTING_API_URL}/wizard"
Report-To: {"group":"default","max_age":31536000,"endpoints":[{"url":"{REPORTING_API_URL}"}],"include_subdomains":true},{"group":"wizard","max_age":31536000,"endpoints":[{"url":"{REPORTING_API_URL}/wizard"}],"include_subdomains":true}
To deploy these headers on your website, you will need to add your own values to the example. You can find them on the Setup page in your account: set the 'Disposition' to 'Wizard' and copy the reporting directives and the Reporting API headers, then deploy the headers on your website. report-uri and report-to both send reports to the Wizard, and a browser uses only one of them, so you will not receive duplicate reports. 'report-sha256' sends CSP Integrity data about every script that runs on your pages through the Reporting API. Those reports count towards your quota at the sampled rate. Here are some examples on how to do that depending on your platform or language of choice. Please note that your values are unique to you, and you should not use those found in the examples here:
PHP¶
header("Content-Security-Policy-Report-Only: default-src 'none'; script-src 'report-sha256'; form-action 'none'; frame-ancestors 'none'; report-uri https://demo.report-uri.com/r/d/csp/wizard; report-to wizard");
header('Reporting-Endpoints: default="https://demo.report-uri.com/a/d/g", wizard="https://demo.report-uri.com/a/d/g/wizard"');
header('Report-To: {"group":"default","max_age":31536000,"endpoints":[{"url":"https://demo.report-uri.com/a/d/g"}],"include_subdomains":true},{"group":"wizard","max_age":31536000,"endpoints":[{"url":"https://demo.report-uri.com/a/d/g/wizard"}],"include_subdomains":true}');
Nginx¶
add_header Content-Security-Policy-Report-Only "default-src 'none'; script-src 'report-sha256'; form-action 'none'; frame-ancestors 'none'; report-uri https://demo.report-uri.com/r/d/csp/wizard; report-to wizard";
add_header Reporting-Endpoints 'default="https://demo.report-uri.com/a/d/g", wizard="https://demo.report-uri.com/a/d/g/wizard"';
add_header Report-To '{"group":"default","max_age":31536000,"endpoints":[{"url":"https://demo.report-uri.com/a/d/g"}],"include_subdomains":true},{"group":"wizard","max_age":31536000,"endpoints":[{"url":"https://demo.report-uri.com/a/d/g/wizard"}],"include_subdomains":true}';
Apache¶
Header set Content-Security-Policy-Report-Only "default-src 'none'; script-src 'report-sha256'; form-action 'none'; frame-ancestors 'none'; report-uri https://demo.report-uri.com/r/d/csp/wizard; report-to wizard"
Header set Reporting-Endpoints "default=\"https://demo.report-uri.com/a/d/g\", wizard=\"https://demo.report-uri.com/a/d/g/wizard\""
Header set Report-To "{\"group\":\"default\",\"max_age\":31536000,\"endpoints\":[{\"url\":\"https://demo.report-uri.com/a/d/g\"}],\"include_subdomains\":true},{\"group\":\"wizard\",\"max_age\":31536000,\"endpoints\":[{\"url\":\"https://demo.report-uri.com/a/d/g/wizard\"}],\"include_subdomains\":true}"
IIS¶
Open IIS Manager and navigate to the level you want to manage, In Features View, double-click HTTP Response Headers. On the HTTP Response Headers page, in the Actions pane, click Add. In the Add Custom HTTP Response Header dialog box use the following name and value and then click OK. Repeat for each of the three headers.
Name: Content-Security-Policy-Report-Only
Value: default-src 'none'; script-src 'report-sha256'; form-action 'none'; frame-ancestors 'none'; report-uri https://demo.report-uri.com/r/d/csp/wizard; report-to wizard
Name: Reporting-Endpoints
Value: default="https://demo.report-uri.com/a/d/g", wizard="https://demo.report-uri.com/a/d/g/wizard"
Name: Report-To
Value: {"group":"default","max_age":31536000,"endpoints":[{"url":"https://demo.report-uri.com/a/d/g"}],"include_subdomains":true},{"group":"wizard","max_age":31536000,"endpoints":[{"url":"https://demo.report-uri.com/a/d/g/wizard"}],"include_subdomains":true}
Creating your policy¶
In the My Policies section of your account you can maintain many different policies and choose which one the CSP Wizard will work with. For now, use the default policy which will have been created for you and give it a name using the 'Rename' button. Once you have given your policy a name the next step is to handle updates suggested by the Wizard.
Head to the Wizard page and here you should see the changes required for your policy. For each report sent to the Wizard it will analyse the cause and suggest the necessary change to your policy. You can make an addition to your CSP if this particular resource should be allowed to load by pressing the associated 'Allow' button. If the resource should not be allowed to load then use the 'Block' button to ensure it is blocked in your policy.
In the above example if you were intending to have iframes from www.youtube.com on your site you would click the 'Allow' button. If you did not want iframes to load containing disqus.com then you would click 'Block'.
Filters and the Wizard¶
The reports you send to the Wizard pass through your Filters in the same way as your other reports. A report from a domain that isn't on your list of sites to collect reports for, or one caught by your browser extension or unactionable report filters, won't be offered as a change to your policy.
If you expected to see a change in the Wizard and it isn't there, the Filters page is the first place to look.
Recommendations¶
We would advise that you run the CSP Wizard on your site for at least 7 days to ensure that you cover all of your traffic and all of your users. You can process the list of changes at any time during the period you're running the Wizard on your site.
If you Allow or Block an item by mistake, you can click the View Blocked or View Allowed buttons at the bottom of the page to view all items you have blocked and allowed. If one of the entries was made in error you can reset it and then correctly block or allow it as required.
Once you have processed all entries in the Wizard and you aren't receiving new items the policy in My Policies will be ready to deploy to your site in Report Only mode for testing. When you deploy it, add your reporting directives from the Setup page and keep 'report-sha256' in its script-src, so you continue to receive reports and CSP Integrity data.
Using the Reporting API¶
The examples above send reports to the CSP Wizard through the Reporting API as well as report-uri. This section explains how the Reporting API headers are built. You will need to define a new reporting endpoint for the Wizard alongside the default one. The standard Reporting API headers look like this, and you can find the correct URL value on the Setup page in your account:
Reporting-Endpoints: default="{REPORTING_API_URL}"
Report-To: {"group":"default","max_age":31536000,"endpoints":[{"url":"{REPORTING_API_URL}"}],"include_subdomains":true}
To add an endpoint for the CSP Wizard, add a wizard entry to each header. The Wizard's endpoint is the same URL with /wizard appended. In Reporting-Endpoints the entries are comma-separated, and in Report-To each group is its own JSON object, also comma-separated. The order is not important.
Reporting-Endpoints: default="{REPORTING_API_URL}", wizard="{REPORTING_API_URL}/wizard"
Report-To: {"group":"default","max_age":31536000,"endpoints":[{"url":"{REPORTING_API_URL}"}],"include_subdomains":true},{"group":"wizard","max_age":31536000,"endpoints":[{"url":"{REPORTING_API_URL}/wizard"}],"include_subdomains":true}
The wizard endpoint's URL tells us to send those reports to the Wizard for processing. You can now use it in your CSPRO header.
Content-Security-Policy-Report-Only: default-src 'none'; script-src 'report-sha256'; form-action 'none'; frame-ancestors 'none'; report-uri {REPORT_URI}; report-to wizard
We recommend using the report-uri and report-to values together for maximum backwards compatibility. This will not result in any additional reports being sent as the browser will use either report-uri or report-to, not both.
Useful Links¶
https://scotthelme.co.uk/report-uri-csp-wizard/
https://scotthelme.co.uk/content-security-policy-an-introduction/
https://scotthelme.co.uk/csp-cheat-sheet/
Start Monitoring with Report URI¶
Already have an account? Jump straight into the CSP Wizard.
New to Report URI? Create an account, then head to the CSP Wizard from your account to build your policy automatically.