Caddy guide · All security headers

Caddy security headers: one tested snippet for all six

All six security headers on Caddy in one tested snippet: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy and nosniff, proxies and error pages included.

  • By
  • Updated
  • 7 min read
  • Tested on Caddy 2.9, 2.10 and 2.11
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
Caddy
content-security-policy
default-src 'self'; …
strict-transport-security
max-age=31536000; …
x-frame-options
DENY
referrer-policy
strict-origin-when-cross-origin
permissions-policy
camera=(), microphone=(), …
x-content-type-options
nosniff

All 6 present on error pages too

In short5 points
  • Put the six headers in one header block inside a (security-headers) snippet, at the top of the Caddyfile, and import it in every site block. Caddy sends them on its own 404 and 502 pages without any flag.
  • Do not add defer or the > prefix to the snippet: in our test, Caddy's own 404 and 502 pages then had none of the six headers.
  • Behind reverse_proxy, drop the application's six headers and its Server header with header_down, from a second snippet. Otherwise each header is sent twice.
  • For per-path values, put the path's header lines in a route block after the import. Outside route, Caddy runs the snippet last and it overwrites them.
  • With all six passing, WebSec0 gives the headers grade 100 out of 100. Caddy's own Server header has no version, so there is no penalty to fix.

The short answer

Define one snippet with the six headers at the top of the Caddyfile, and import it in each site block:

Caddyfile
(security-headers) {
	header {
		Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests"
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Frame-Options "DENY"
		Referrer-Policy "strict-origin-when-cross-origin"
		Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()"
		X-Content-Type-Options "nosniff"
	}
}

example.com {
	import security-headers
	root * /var/www/example
	file_server
}
Shell
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy

Every configuration on this page was run on Caddy 2.9, 2.10 and 2.11 and checked with curl, on a page, a 404, a static file, a redirect, a proxied application, an application that was down and paths with their own values.

Two of these lines need a rollout before they go live in this form. The CSP blocks every script, style and connection that is not on your own origin: start it in report-only mode, as the Content-Security-Policy guide for Caddy explains. The HSTS value is a final one: start with a short max-age, as the HSTS guide for Caddy explains.

What each line does

Header Value in the snippet WebSec0 points Details
Content-Security-Policy Only your own origin, no plugins, no framing 25 CSP on Caddy
Strict-Transport-Security HTTPS only for one year, subdomains included 20 HSTS on Caddy
X-Frame-Options No framing, for browsers without frame-ancestors 15 X-Frame-Options on Caddy
Referrer-Policy Full URL on your origin, origin only elsewhere 15 Referrer-Policy on Caddy
Permissions-Policy Camera, microphone, location, devices and sensors off 15 Permissions-Policy on Caddy
X-Content-Type-Options No MIME sniffing 10 X-Content-Type-Options on Caddy

Caddy needs no always flag. In our test, the six headers were on pages, 404s from file_server and redirects made with redir. The automatic HTTP to HTTPS redirect carried none of them, which is fine: browsers ignore HSTS over plain HTTP, and that response has no page to protect.

Before you start

Find every site block, header directive and proxy in the Caddyfile:

Shell
grep -nE "^[^ \t#].*\{|header|reverse_proxy|php_fastcgi|import|route" /etc/caddy/Caddyfile

To see the order Caddy chose for your directives, convert the Caddyfile to JSON with caddy adapt --config /etc/caddy/Caddyfile --pretty.

Then check three things the snippet can break:

  • Scripts and styles your CSP does not allow. Run the policy in report-only mode first.
  • Subdomains without HTTPS. includeSubDomains makes browsers refuse them.
  • Files served with the wrong type. nosniff blocks a script or stylesheet whose Content-Type does not match.

Also remove the features your site uses from the Permissions-Policy line, such as camera for a video call page, or give those pages their own value (step 4).

Step 1: import it in every site block

The snippet must come before the site blocks that import it; otherwise caddy validate fails with File to import not found. Import it in every site that serves HTTPS, including one that only redirects:

Caddyfile
example.com {
	import security-headers
	redir https://www.example.com{uri} permanent
}

www.example.com {
	import security-headers
	header /assets/* Cache-Control "public, max-age=31536000, immutable"
	root * /var/www/example
	file_server
}

Each header directive acts on its own. Unlike Nginx, a line that sets another header, such as Cache-Control for /assets/, keeps the six. Our test returned Cache-Control and the six headers for /assets/app.js.

Step 2: keep defer and > out of the snippet

The Caddy header documentation offers defer, or a > prefix on a field, to set a header after the rest of the site has run. It looks like a way to override the application, but the headers then depend on how the response is written. In our test, with defer in the snippet:

Response Headers
A page from file_server All six
A 404 from file_server None
A 502 when the application was down None
A page or a 404 from the proxied application All six

A single field with >, such as header >Content-Security-Policy …, behaved the same way. Keep the snippet plain, and handle proxied applications in the proxy itself (step 3).

Step 3: hide the application’s headers behind a proxy

A plain header block runs before reverse_proxy, and Caddy keeps the application’s headers next to its own. Our test, with an application that sent weak values for all six headers:

HTTP
HTTP/2 200
server: nginx/1.30.6
content-security-policy: default-src 'self'; script-src 'self'; ...
content-security-policy: default-src *
referrer-policy: strict-origin-when-cross-origin
referrer-policy: unsafe-url

Browsers enforce both CSPs and apply the last Referrer-Policy, here unsafe-url. The application’s Server header, with its version, also reached the browser: Caddy 2.10 and 2.11 sent it instead of their own, Caddy 2.9 next to Server: Caddy (see the Server header guide). Remove them as the response comes back from the application, with a second snippet:

Caddyfile
(hide-app-headers) {
	header_down -Server
	header_down -Content-Security-Policy
	header_down -Strict-Transport-Security
	header_down -X-Frame-Options
	header_down -Referrer-Policy
	header_down -Permissions-Policy
	header_down -X-Content-Type-Options
}

app.example.com {
	import security-headers
	reverse_proxy 127.0.0.1:8080 {
		import hide-app-headers
	}
}

Our test then returned each header once, with the snippet’s value, on the application’s pages and 404s, and on Caddy’s 502 when the application was down. Without the application’s Server header, Caddy 2.9 sent its own Server: Caddy; Caddy 2.10 and 2.11 sent no Server header. php_fastcgi is built on the same proxy and, according to its documentation, accepts the same subdirectives. If the application must own one header, such as a CSP with per-request nonces, remove its line from both snippets instead.

Step 4: different values for some paths

Some pages need a different value: an embeddable widget, a password reset page, a video call. A header /embed/* … line next to the import does not work. Caddy sorts header directives by path matcher, the most specific first and the one without a matcher last, so the snippet runs after the per-path line and overwrites it. In our test, /embed/, /reset/ and /meet/ all got the default CSP, Referrer-Policy and Permissions-Policy.

Put the per-path lines in a route block after the import. Inside route, directives run in the order written:

Caddyfile
example.com {
	import security-headers
	route {
		header /embed/* Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self' https://partner.example; upgrade-insecure-requests"
		header /embed/* -X-Frame-Options
		header /reset/* Referrer-Policy "no-referrer"
		header /meet/* Permissions-Policy "camera=(self), microphone=(self), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()"
	}
	root * /var/www/example
	file_server
}

What our test returned:

Path What changes
/ The default values
/embed/ frame-ancestors 'self' https://partner.example, and no X-Frame-Options
/reset/ Referrer-Policy: no-referrer
/meet/ camera=(self), microphone=(self)

The 404 pages under /embed/ and /reset/ got the same CSP and Referrer-Policy as the pages. They kept X-Frame-Options: DENY, though: Caddy defers a line that deletes a header, and deferred lines do not run on its own error pages (step 2). That 404 is harmless: browsers ignore X-Frame-Options when the CSP has frame-ancestors, as the HTML Standard specifies.

Keep import security-headers outside route. route runs after redir in Caddy’s directive order, and in our test a redir answered without the six headers when the import was inside it.

Verify it

Check that each header appears exactly once on a page, an error page and a static file. Use your own URLs:

Shell
for url in https://example.com/ https://example.com/does-not-exist https://example.com/assets/app.js; do
  echo "$url"
  for h in content-security-policy strict-transport-security x-frame-options referrer-policy permissions-policy x-content-type-options; do
    printf '  %-26s %s\n' "$h" "$(curl -sI "$url" | grep -ci "^$h:")"
  done
done

Every count should be 1. A 0 on an error page points to defer or > in the snippet; a 2 to a proxied application without header_down. Then open your pages with the browser console for CSP, Permissions-Policy or MIME errors, and scan the site with WebSec0.

How WebSec0 grades this configuration

The six headers make up the 100 points of the WebSec0 headers grade. With the snippet above, each one passes:

Header Points Passes when
Content-Security-Policy 25 No 'unsafe-inline' in script-src, or in default-src without script-src
Strict-Transport-Security 20 max-age of at least one year with includeSubDomains
X-Frame-Options 15 DENY or SAMEORIGIN, or frame-ancestors in the CSP
Referrer-Policy 15 The applied value is not unsafe-url or no-referrer-when-downgrade
Permissions-Policy 15 It parses and disables at least one sensitive feature with ()
X-Content-Type-Options 10 The first value is nosniff

A headers grade of A+ starts at 95. The score can also change with other headers: −5 for a version in the Server header (step 3), penalties for cookies without secure attributes (−5 per cookie without Secure, −10 at most; −3 per cookie without SameSite; −3 per session cookie without HttpOnly), and −10 for Access-Control-Allow-Origin: *. Cross-origin isolation headers add bonus points: +5 for Cross-Origin-Opener-Policy: same-origin, +3 for Cross-Origin-Embedder-Policy and +2 for Cross-Origin-Resource-Policy.

The HSTS line also counts for the TLS grade: a configuration that would earn an A+ is held at A unless HSTS has a max-age of at least one year and includeSubDomains.

Troubleshooting

Symptom Likely cause Fix
File to import not found: security-headers The snippet is defined after the site block Move the snippet to the top of the Caddyfile.
Headers missing on one site That site block does not import the snippet Import it in every HTTPS site, redirects too.
Headers missing on 404 or 502 pages defer or > in the snippet Remove them, and use header_down for proxied applications.
A header appears twice The proxied application sends it too Import hide-app-headers in the reverse_proxy block.
A per-path value is ignored The per-path line is outside route, so the snippet overwrites it Put the per-path lines in a route block after the import.
Headers missing on redirects The import is inside route, which runs after redir Keep the import outside route.
Server shows the application’s version reverse_proxy passes the application’s Server header Add header_down -Server.
Scripts or styles stop loading The CSP or nosniff Check the browser console; start the CSP in report-only mode and fix MIME types.

One guide per header

Every Caddy guide

Other web servers

Security headers on other servers

Questions

Frequently asked questions

Which security headers should Caddy send?

The six that WebSec0 grades: Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, Referrer-Policy, Permissions-Policy and X-Content-Type-Options. Caddy sends none of them by default, HSTS included.

How do I add security headers to every site in a Caddyfile?

Define a (security-headers) snippet with one header block at the top of the Caddyfile, and add import security-headers to each site block, including sites that only redirect.

Does Caddy send security headers on error pages?

Yes, with a plain header block. In our test the six headers were on 404s from file_server and on 502s when the application was down. With defer or the > prefix they were not.

Why does my response have two Content-Security-Policy headers behind reverse_proxy?

Caddy sets its headers before the proxy and keeps the application's. Remove the application's copy with header_down -Content-Security-Policy inside the reverse_proxy block, and do the same for the other five.

Why is my per-path header ignored in Caddy?

Caddy sorts header directives by path, most specific first and the one without a path last, so the site-wide snippet overwrites the per-path line. Put the per-path lines in a route block after the import: route keeps the order you wrote.

Does Caddy leak its version in the Server header?

No. Caddy sends Server: Caddy without a version. A proxied application can send its own Server header with a version, which WebSec0 penalises; remove it with header_down -Server.

References

Sources

About the author

Portrait of Joshua Martinelle

Security engineer at Tenable

Security engineer at Tenable and web security researcher. He has disclosed more than 60 CVEs since 2020 and builds WebSec0.

Verify the change

Deployed it? Check it.

WebSec0 grades your TLS setup and all six security headers in a few seconds. Free, no account.

Scan your site