Our own website is about thirty pages of hand-written HTML with no build step, served from Cloudflare. That makes it the easy case for a strict Content Security Policy: there is no tag manager, no chat widget and no payment iframe to accommodate. We still had to change the code in five places to ship the policy, and when we checked the result for this article we found three gaps in our own setup.
This is a write-up of both lists. Everything below can be verified from the outside with curl.
The policy
These are the headers every page on kv.solutions is served with:
Content-Security-Policy: default-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; object-src 'none'
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=()
The first line does most of the work. default-src 'self' means scripts, styles, fonts, images and network requests are allowed only from our own origin. There is no 'unsafe-inline' and no list of trusted third parties, because there are no third parties. If an attacker manages to inject markup into a page, an inline script in that markup will not run and a script loaded from another host will not load.
Three of the other directives close doors that default-src does not cover: base-uri stops an injected <base> tag from redirecting relative links, form-action stops a form from posting somewhere else, and frame-ancestors stops the site from being embedded in another page. The fourth, object-src 'none', is deliberately stricter than the default: plugin content is not allowed even from our own origin.
What we had to change to ship it
A policy this short is cheap to write and not free to live with. Five things in the code had to change.
1. The inline script on the first page
The root page sends a visitor to their language. That was a dozen lines of JavaScript in a <script> tag, which the policy blocks. It became a separate file of about 550 bytes. The page also has to work when the script does not run at all, so it shows four plain language links underneath.
2. Every style attribute
Without 'unsafe-inline' for styles, a style="..." attribute is ignored by the browser. The site we migrated from used them freely, including for the hidden anti-spam field in the contact form. All of them became classes in the stylesheet.
3. Fonts
A font loaded from a font service is a request to another origin on every page view. We host the two font files ourselves, about 93 KB each, next to their licence text, and serve them with a one-year immutable cache.
4. Analytics
There is no analytics script on the site, so there is nothing to allow. We read the server-side statistics our hosting provider already collects. They are coarser than a tracking script and they are enough to answer the question we actually have, which is whether an article was read.
5. Structured data
This one did not need a change, and it is worth knowing why. The JSON-LD block that describes the organisation to search engines sits inline in the page. The policy does not block it, because a <script type="application/ld+json"> element is a data block: the browser never executes it, so there is nothing for the script rules to stop.
How we keep it from eroding
A strict policy tends to decay one exception at a time. Someone adds a widget, the page breaks, and 'unsafe-inline' goes in "for now". We enforce the rule earlier, at the source: a small script runs over every page before a change is published and fails if it finds an inline script, a style attribute, an inline <style> block or a resource loaded from another host. The policy in the header then only has to confirm what the code already guarantees.
Three gaps we found in our own setup
Writing this article meant checking every kind of response the site can give, not just the home page. That turned up three things.
The API response had no security headers
The headers above are configured for static files. The contact form posts to a small function, and the response of that function is generated by code, so the static configuration never applied to it:
$ curl -s -D - -o /dev/null -d "name=A" https://kv.solutions/api/contact
HTTP/2 400
content-type: application/json; charset=utf-8
cache-control: no-store
A JSON error response is a small target, but "every response" has to mean every response. The function now sets X-Content-Type-Options: nosniff and its own policy of default-src 'none'; frame-ancestors 'none', which is the right policy for something that is never meant to be rendered as a page.
HSTS did not redirect anyone
For the first hours after launch, http://kv.solutions/ answered with the page itself instead of a redirect. The Strict-Transport-Security header was present the whole time. That header is an instruction to a browser that has already visited over HTTPS; it does nothing for the first plain-HTTP request. The redirect is a separate setting at the edge, and it was off. It is on now. The domain is still not on the browser preload list, so the very first visit of a new user is protected by the redirect only.
An allowance nobody used
The first version of the policy had img-src 'self' data:. Nothing on the site uses a data: image; it was added "in case". An allowance that is not needed is only useful to an attacker, so it is gone.
How to check your own site
The mistake we made is the common one: checking the home page and stopping. Check one of each kind of response.
- A normal page:
curl -sI https://example.com/ - A page that does not exist. Error pages are often served by a different part of the stack.
- An API endpoint or form handler, with the method it actually accepts.
- A static asset such as a stylesheet.
- The plain-HTTP address. You should see a redirect, not a page.
Then open the site in a browser with the developer console visible and click through it. Every blocked resource is reported there with the directive that blocked it. Online header scanners are a reasonable first pass, with one limit to keep in mind: they grade the single address you give them.
Where this stops being easy
A static site is the best case. An application with a tag manager, embedded third-party widgets, a payment form in an iframe or server-rendered inline scripts cannot use a policy this simple. It needs nonces or hashes, an explicit list of external origins that someone keeps current, and a reporting endpoint to see what breaks. Most of the work in that situation is not writing the header; it is finding out what the application really loads and deciding what it should be allowed to load.