Security Headers: A Practical Reference
HSTS, CSP, X-Content-Type-Options and the rest. Learn what each security header does and how to set it without breaking your site.
By Velloreth
Why headers matter
Security headers are a cheap layer. They cost nothing at runtime, they are set once in the server or the CDN configuration, and they close whole classes of attack that would otherwise need application code.
They are not a substitute for correct code. A Content Security Policy does not fix an XSS bug; it limits the damage. But the cost-to-benefit ratio is among the best available, and a site without them is leaving an easy win on the table.
Strict-Transport-Security
What it does: tells the browser to use HTTPS for this domain for a given period, and to refuse a plain HTTP connection.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
Why it matters: without it, a first request over HTTP can be intercepted and redirected, and a cookie can be sent in the clear. With it, the browser upgrades the request before it leaves.
The caution: a browser that has seen the header will refuse HTTP for the max-age period, and there is no way to revoke it from the server. Add it only after HTTPS works on every subdomain, and start with a short max-age while you confirm.
includeSubDomains extends the policy to every subdomain. A subdomain that does not support HTTPS will become unreachable, so check before adding it.
preload submits the domain to a list built into browsers, which applies the policy even on the first visit. It is a commitment, and removal from the list takes months.
Content-Security-Policy
What it does: restricts where scripts, styles, images, fonts and other resources can load from, and blocks inline script unless it is explicitly allowed.
Content-Security-Policy:
default-src 'self';
script-src 'self' 'nonce-abc123';
style-src 'self' 'unsafe-inline';
img-src 'self' data:;
object-src 'none';
base-uri 'self';
frame-ancestors 'none';
Why it matters: an injected script is blocked unless it matches the policy, which turns many XSS payloads into a console error. It is the strongest header and the one most likely to break a site.
A nonce is the modern approach. The server generates a random value per response, includes it in the policy, and adds it to each legitimate script tag. An injected script does not have the nonce.
unsafe-inline defeats much of the protection. A policy that allows inline script lets an injected <script> run. It is a common shortcut and it removes the main benefit.
Deploy in report-only first. The Content-Security-Policy-Report-Only header reports violations without blocking, which lets you find the legitimate resources before enforcing.
Content-Security-Policy-Report-Only: default-src 'self'; report-uri /csp-report
X-Content-Type-Options
What it does: stops the browser from guessing a content type.
X-Content-Type-Options: nosniff
Why it matters: without it, a browser may treat a file as a different type than the server declared. A text file that a browser decides is HTML can execute a script, which is a stored XSS vector for an upload endpoint.
It has no downside. Set it on every response.
Referrer-Policy
What it does: controls how much of the current URL is sent in the Referer header on an outgoing request.
Referrer-Policy: strict-origin-when-cross-origin
Why it matters: a full URL can contain a session token, an email address, or an internal path. Sending it to a third party leaks it.
The common values: no-referrer sends nothing, same-origin sends the full URL only to the same origin, strict-origin-when-cross-origin sends the origin to a cross-origin destination and the full URL to the same origin. The last is the modern default and a good choice.
X-Frame-Options and frame-ancestors
What they do: prevent the page from being embedded in a frame, which is a clickjacking defence.
X-Frame-Options: DENY
Content-Security-Policy: frame-ancestors 'none'
Why it matters: without it, an attacker can embed your page in a transparent frame and trick a user into clicking a button they cannot see.
frame-ancestors is the modern replacement and is more flexible, because it can allow specific origins. X-Frame-Options is still needed for older browsers, and the two can be set together.
Permissions-Policy
What it does: disables browser features the site does not use, such as the camera, the microphone and geolocation.
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()
Why it matters: a third-party script that is compromised cannot use a feature the policy has disabled. It reduces the capability available to an injected script.
Set it to deny by default and enable only what the site needs.
Cross-Origin headers
Cross-Origin-Opener-Policy isolates the browsing context, which prevents a cross-origin window from holding a reference to yours.
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy controls who can embed your resources.
Cross-Origin-Resource-Policy: same-origin
Cross-Origin-Embedder-Policy requires that embedded resources opt in, which is what enables SharedArrayBuffer and high-resolution timers.
Cross-Origin-Embedder-Policy: require-corp
These are stricter and more likely to break an embed. Add them when the site does not embed third-party content, and test carefully.
Setting the headers
In a static host’s config file. Cloudflare Pages, Netlify and Vercel all read a _headers file.
/*
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
X-Frame-Options: DENY
Permissions-Policy: camera=(), microphone=(), geolocation=()
In a reverse proxy. Nginx and Caddy can add a header to every response.
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
In the application. A middleware can set the headers, which is useful when they depend on the route.
Testing
Inspect the response with curl.
curl -sI https://example.com | grep -iE 'strict-transport|content-security|x-content-type|referrer|x-frame|permissions'
Use a scanner. The Mozilla Observatory and securityheaders.com grade a configuration and explain each header.
Test the deployed site. A proxy or a CDN can add, remove or override a header, so the local configuration is not the truth. Check the response from the real domain.
Watch the console. A Content Security Policy violation appears in the browser console with the blocked resource, which is the fastest way to find what a policy broke.
Common mistakes
Adding HSTS before HTTPS works everywhere. A subdomain without HTTPS becomes unreachable, and the policy cannot be revoked from the server.
A CSP with unsafe-inline. The policy then allows the exact thing it was meant to stop.
Enforcing a CSP without a report-only phase. The site breaks in production, and the cause is a blocked resource that is not obvious.
Setting the headers only in the application. A static asset served directly by the CDN does not pass through the application, so it does not get the headers.
Forgetting the error responses. A 404 or a 500 should carry the same headers as a 200. In Nginx, the always flag is what makes that happen.
Assuming the headers are set because the config says so. Check the deployed response.
A quotable summary
Security headers are a cheap, high-value layer set by the server and enforced by the browser. Set Strict-Transport-Security after HTTPS works everywhere, X-Content-Type-Options: nosniff on every response, a Referrer-Policy, and a Content-Security-Policy deployed in report-only mode first. Add frame-ancestors or X-Frame-Options for clickjacking, and Permissions-Policy to disable unused features. Test the deployed response, because a proxy or a CDN can change a header.
Related reading
For the policy details, see content-security-policy-guide and for the attack it mitigates, xss-prevention-guide. For the broader context, cookies-explained and cors-explained.