- Put the six headers in one
headerblock inside a(security-headers)snippet, at the top of the Caddyfile, andimportit in every site block. Caddy sends them on its own 404 and 502 pages without any flag. - Do not add
deferor 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 itsServerheader withheader_down, from a second snippet. Otherwise each header is sent twice. - For per-path values, put the path's
headerlines in arouteblock after the import. Outsideroute, 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
Serverheader 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:
(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
}caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddyEvery 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:
grep -nE "^[^ \t#].*\{|header|reverse_proxy|php_fastcgi|import|route" /etc/caddy/CaddyfileTo 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.
includeSubDomainsmakes browsers refuse them. - Files served with the wrong type.
nosniffblocks a script or stylesheet whoseContent-Typedoes 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:
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/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-urlBrowsers 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:
(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:
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:
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
doneEvery 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
Content-Security-Policy
Guide ↗Add a Content-Security-Policy header in Caddy, reuse it with a snippet, override it on one path and avoid a second policy behind reverse_proxy. Tested Caddyfiles.
Strict-Transport-Security
Guide ↗Enable HSTS on Caddy: add Strict-Transport-Security to the site block, keep it off plain HTTP, cover redirects and avoid a second header behind reverse_proxy. Tested.
X-Frame-Options
Guide ↗Set X-Frame-Options on Caddy with the header directive, pair it with CSP frame-ancestors, drop the application's copy behind reverse_proxy and allow one path. Tested.
Referrer-Policy
Guide ↗Set Referrer-Policy on Caddy with the header directive, use no-referrer on sensitive paths with route, and stop a proxied app's weaker value from winning. Tested configs.
Permissions-Policy
Guide ↗Set Permissions-Policy on Caddy with the header directive, quote origins with backticks, enable a feature on one path and stop a proxied app's policy winning. Tested.
X-Content-Type-Options
Guide ↗Set X-Content-Type-Options: nosniff on Caddy with the header directive, check the MIME types file_server sends and type files without an extension. Tested configs.
Other web servers
Security headers on other servers
Apache
Guide ↗All six security headers on Apache in one tested file: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy and nosniff, error pages and proxies included.
Nginx
Guide ↗All six security headers on Nginx in one tested snippet: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy and nosniff, error pages included.
Traefik
Guide ↗All six security headers on Traefik in one tested headers middleware: CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy and nosniff, labels or file.
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
