Quick Start

Get CSP reporting working in 5 minutes.

1. Create a Site in HeaderHawk

Sign up at app.headerhawk.com
Create a new site, and give it the host your pages are served from
Its setup panel opens as soon as the site is created. To open it again, choose the site in the site switcher at the top of the dashboard, then Set up this site, or choose its row under Settings → Sites. Copy the Endpoint — the full URL, already carrying your site’s ingest code as the first part of the host:

https://your-ingest-code.ingest.us.headerhawk.com/r

Paste the whole URL. The ingest code is the only site-specific part, and it is the value every example below writes as your-ingest-code. A site created before ingest codes moved into the host also has an earlier URL, https://ingest.us.headerhawk.com/r/ followed by an 8-character code, which the setup panel names under this one; headers that already use it keep working. On the Professional plan and above you can give the site a report host name of your own, such as acme-shop, in the same panel, and copy that URL instead. On the Business plan and above it can receive reports on a hostname of your own domain, such as csp.example.com.

A site keeps reports only from the hosts it lists. A host is either exact (example.com) or a wildcard (*.example.com), and a wildcard matches every subdomain, at any depth, but not example.com itself. To cover a host and all its subdomains, tick Also accept all subdomains beside it, which lists both: beside example.com it adds *.example.com, and beside dev.example.com it adds *.dev.example.com. It always means the subdomains of the host you typed, so for a whole domain, type the domain itself (example.com), not www.example.com. If one CSP header covers several hosts, add each to the site under Settings → Sites → Edit — otherwise reports from the others arrive and are discarded, and the endpoint returns success either way, so nothing in the browser will tell you. A site’s setup panel reports anything discarded for this reason, and lets you allow the host from there.

2. Add CSP Headers

Choose your platform:

3. Start Policy Discovery

A site starts with discovery rather than a policy you write. For the site you add when you sign up, the last step of signing up starts it, for two weeks, and shows two headers to add; for a site you add later, starting it is the first step its Overview offers. The site’s setup panel shows the same pair at the top of its Response headers block:

Reporting-Endpoints: headerhawk="https://your-ingest-code.ingest.us.headerhawk.com/r", headerhawk-discovery="https://your-ingest-code.ingest.us.headerhawk.com/r/discovery"
Content-Security-Policy-Report-Only: default-src 'none'; script-src 'report-sample'; style-src 'report-sample'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; report-uri https://your-ingest-code.ingest.us.headerhawk.com/r/discovery; report-to headerhawk-discovery

The policy is report-only and allows nothing, so it blocks nothing: each visitor’s browser reports every script, style, image, font, frame and connection your pages load. After a week, HeaderHawk proposes a policy built from what they reported, with the evidence behind each source. Build a Policy From Your Traffic covers the run and the proposal in full.

4. Check Your Headers

Once the headers are pasted, choose Check my headers, on the Overview’s step or beside the block in the site’s setup panel. HeaderHawk fetches the site’s page once and says, for each line of the block whether it is served, different (served, but not as written, with what differs: another site’s ingest code, a report-to group that Reporting-Endpoints does not define, a missing report-uri, or the discovery policy served as the enforcing Content-Security-Policy, which blocks everything) or missing. A header served twice, or as one value joined by a comma, counts. It does not wait for a visitor, so a CDN or framework that drops or rewrites the header shows up straight away rather than as a silence.

The page is https:// and the site’s first host that is not a wildcard; give another page’s URL in the setup panel, which must be on one of the site’s hosts. Redirects are followed only while they stay on those hosts, and a header that only a redirect serves is pointed out, because a browser keeps only the headers of the page it lands on. The request says HeaderHawkScanner in its user agent. Each site can be checked ten times an hour, and your sites thirty times between them, and every member of the team but a viewer can run it.

When every line is served and reports still do not arrive, the cause is in the browser, which a fetch cannot see: a content blocker, or a page on a host the site does not list.

5. Follow Your Next Step

The Overview shows the site’s next step: review the proposal, deploy it in report-only, enforce it, and then the report types beyond CSP, one at a time, each when your reports say the last step has settled. Your Next Step describes each stage. The setup panel’s block follows the step, so copy it again when the step changes.

6. Or Write the Policy Yourself

Every report type and the starter policy are under All report types in the site’s setup panel. The starter policy allows only your own origin:

Reporting-Endpoints: headerhawk="https://your-ingest-code.ingest.us.headerhawk.com/r"
Content-Security-Policy-Report-Only: default-src 'self'; report-uri https://your-ingest-code.ingest.us.headerhawk.com/r; report-to headerhawk

Its first reports name each third-party script, font and API your pages use. Add the origins you trust to the policy, and rename the header to Content-Security-Policy once its reports are clean. Each type’s switch there asks browsers for exactly the types switched on, script hashes ('report-sha256') included, so copy the block again after changing one. Browser Report Types describes each type and the header that requests it.

Next Steps

Understand CSP concepts - Learn how CSP works
CSP directive reference - Tune your policy
Troubleshooting - Fix common issues