Skip to content
Velloreth
Cybersecurity 6 min read

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

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.

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.

Frequently asked questions

What are security headers?
Security headers are HTTP response headers that tell the browser how to handle a page more safely. They can force HTTPS, restrict where scripts and styles can load from, stop a browser from guessing a content type, and limit how much information is sent in a referrer. They are set by the server and enforced by the browser.
Which security headers should every site set?
At a minimum: Strict-Transport-Security, X-Content-Type-Options: nosniff, Referrer-Policy, and a Content-Security-Policy. Add X-Frame-Options or the frame-ancestors directive to prevent clickjacking, and Permissions-Policy to disable features the site does not use.
What does HSTS do?
Strict-Transport-Security tells the browser to use HTTPS for this domain for a given period, and to refuse a plain HTTP connection. It prevents a downgrade attack and a cookie being sent over HTTP. Add it only after HTTPS works on every subdomain, because a browser that has seen it will refuse HTTP for the max-age period.
What is the difference between X-Frame-Options and frame-ancestors?
Both prevent your page from being embedded in a frame, which is a clickjacking defence. X-Frame-Options is the older header and is still needed for older browsers. The frame-ancestors directive in a Content Security Policy is the modern replacement and is more flexible, because it can allow specific origins.
Can security headers break my site?
Yes, and a Content Security Policy is the one most likely to. A policy that is too strict blocks a legitimate script, style or image, and the page renders incorrectly. Deploy the policy in report-only mode first, collect the violations, and enforce it once the reports are clean.
How do I test my security headers?
Use curl to inspect the response headers, and an online scanner such as the Mozilla Observatory or securityheaders.com to grade the configuration. Test the deployed site rather than the local configuration, because a proxy or a CDN can add, remove or override a header.