# 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.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/security-headers/caddy/
Updated: 2026-11-03
Tested on: Caddy 2.9, 2.10 and 2.11

## In short

- 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
}
```

```sh
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](/guides/content-security-policy/caddy/)
explains. The HSTS value is a final one: start with a short `max-age`, as the
[HSTS guide for Caddy](/guides/strict-transport-security/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](/guides/content-security-policy/caddy/) |
| Strict-Transport-Security | HTTPS only for one year, subdomains included | 20 | [HSTS on Caddy](/guides/strict-transport-security/caddy/) |
| X-Frame-Options | No framing, for browsers without `frame-ancestors` | 15 | [X-Frame-Options on Caddy](/guides/x-frame-options/caddy/) |
| Referrer-Policy | Full URL on your origin, origin only elsewhere | 15 | [Referrer-Policy on Caddy](/guides/referrer-policy/caddy/) |
| Permissions-Policy | Camera, microphone, location, devices and sensors off | 15 | [Permissions-Policy on Caddy](/guides/permissions-policy/caddy/) |
| X-Content-Type-Options | No MIME sniffing | 10 | [X-Content-Type-Options on Caddy](/guides/x-content-type-options/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:

```sh
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](https://caddyserver.com/docs/caddyfile/directives/header)
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](/guides/server/)).
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](https://html.spec.whatwg.org/multipage/document-lifecycle.html#the-x-frame-options-header)
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:

```sh
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](/guides/set-cookie/) (−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: *`](/guides/access-control-allow-origin/). [Cross-origin isolation headers](/guides/cross-origin-isolation/) 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. |

## 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`.

## Sources

- [Caddyfile directive: header](https://caddyserver.com/docs/caddyfile/directives/header), Caddy
- [Caddyfile directive: reverse_proxy (header_down)](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#headers), Caddy
- [Caddyfile directive: route](https://caddyserver.com/docs/caddyfile/directives/route), Caddy
- [Caddyfile directives: directive order](https://caddyserver.com/docs/caddyfile/directives#directive-order), Caddy
- [Caddyfile concepts: snippets](https://caddyserver.com/docs/caddyfile/concepts#snippets), Caddy
- [HTML Standard: the X-Frame-Options header](https://html.spec.whatwg.org/multipage/document-lifecycle.html#the-x-frame-options-header), WHATWG
