skip to content

With Cloudflare Transform Rules, how do you add security headers such as X-Frame-Options to every response on a zone?

level: juniorimportance: should knowfreq 35%

answer

  1. a pre-built switch first
  2. the Add security headers Managed Transform
  3. a response rule for the rest
  4. Set replaces, Add appends

basics

~20 s

Turn on the Add security headers Managed Transform, which adds X-Frame-Options, X-Content-Type-Options and three other headers to every response, then write Response Header Transform Rules with a Set operation for headers it omits, such as Content-Security-Policy.

solid answer

~40 s

Two no-code tools cover it. The **Add security headers** Managed Transform is a zone-wide switch that adds `x-content-type-options: nosniff`, `x-frame-options: SAMEORIGIN`, `x-xss-protection: 1; mode=block`, `referrer-policy: same-origin` and `expect-ct: max-age=86400, enforce`; it takes no expression, and **Remove "X-Powered-By" headers** sits beside it. For anything else, such as `Content-Security-Policy` or `Permissions-Policy`, write a **Response Header Transform Rule** that matches all requests and uses a *Set static* operation, which overwrites any value the origin sent. HSTS is in neither: it is its own setting among the edge certificate options. And a *Request* Header Transform Rule changes what the origin receives, so its headers never reach the browser.

code

json · 17 lines
json
{
  "expression": "true",
  "description": "Security headers the Managed Transform does not add",
  "action": "rewrite",
  "action_parameters": {
    "headers": {
      "Content-Security-Policy": {
        "operation": "set",
        "value": "default-src 'self'"
      },
      "Permissions-Policy": {
        "operation": "set",
        "value": "camera=(), microphone=()"
      }
    }
  }
}

go deeper

for a junior

Recall the two no-code tools: the Add security headers Managed Transform and a Response Header Transform Rule with a Set operation, and that HSTS is a separate edge certificate setting.

for a middle

Explain Set versus Add versus Remove, why set-cookie needs Add, and why a request header rule never shows in the browser.

for a senior

Know the edges that bite in production: cf- headers are off limits, an empty dynamic value removes a header, Cache-Control edits do not change edge caching, and rules also cover Cloudflare error pages.

for a principal

Decide which headers are a zone-wide default owned by the platform team and which are per-application rules, and how a strict Content-Security-Policy is rolled out without breaking pages.

## Two tools, no code Cloudflare can add, change or remove HTTP response headers at the edge without a Worker. Two features do it, both part of **Transform Rules**: - **Managed Transforms**: pre-built, one-step switches. Once turned on, a Managed Transform applies to every request for the zone; there is no expression to scope it. - **Response Header Transform Rules**: your own rules, each with a filter expression that picks the requests and one or more header operations. Both need the hostname's DNS record to be proxied through Cloudflare, because only proxied traffic passes through the rules. For a company retiring its Page Rules, this is also the clean replacement for any header trick a Page Rule or a small Worker used to do. ## What the Managed Transform adds The **Add security headers** Managed Transform adds these response headers and values: - `x-content-type-options: nosniff` - `x-xss-protection: 1; mode=block` - `x-frame-options: SAMEORIGIN` - `referrer-policy: same-origin` - `expect-ct: max-age=86400, enforce` It does not add `Strict-Transport-Security` or `Content-Security-Policy`. HSTS is a separate setting among the edge certificate options, and a Content Security Policy depends on what your own pages load, so you write it yourself. The neighbouring **Remove "X-Powered-By" headers** Managed Transform strips the header that advertises the origin's application stack. Cloudflare warns that security headers can block resources or trigger certificate errors, so turn them on for a staging hostname first and watch the browser console. ## Writing a Response Header Transform Rule 1. In **Rules**, create a Response Header Transform Rule. 2. Choose the requests: all incoming requests, or an expression such as `starts_with(http.request.uri.path, "/app/")`. 3. Add one operation per header: *Set static*, *Set dynamic*, *Add static*, *Add dynamic* or *Remove*. 4. Deploy, then check the headers with the browser's developer tools or `curl -I`. Through the API, the same rule lives in the zone's `http_response_headers_transform` phase with the `rewrite` action and a `headers` object in `action_parameters`, as in the example. ## Set, Add and Remove | Operation | What it does | |---|---| | Set (static or dynamic) | Replaces every header with that name, or adds it if missing | | Add (static or dynamic) | Appends a new header and keeps existing ones with the same name | | Remove | Removes every header with that name | The difference matters most for `set-cookie`. A Set operation removes every `set-cookie` already in the response, including cookies that other Cloudflare products such as Bot Management add, so use Add when you append a cookie. For a security header such as `Content-Security-Policy`, Set is usually right, because it replaces a weaker value the origin may already send. ## Limits worth knowing - You cannot add, modify or remove response headers whose names start with `cf-` or `x-cf-`, and a few others, such as `server`, cannot be changed. - A dynamic value that evaluates to an empty string or an undefined value removes the header instead of sending it empty. - Expressions are evaluated on request fields: `ip.src.country` is the visitor's country, not the origin's. - IP lists cannot be referenced in Response Header Transform Rules. - The rules also apply to Cloudflare's default error pages and to Custom Errors, so the headers survive an outage page. - Changing `cache-control`, `CDN-Cache-Control` or `Cloudflare-CDN-Cache-Control` here does not change what Cloudflare caches, because caching is decided before response headers are modified; edge caching is a Cache Rule's job. - Active Transform Rules per zone: 10 on Free, 25 on Pro, 50 on Business, 300 on Enterprise. Regular expressions need Business or Enterprise. - Rules run in list order and a later rule can overwrite an earlier one's header, but every rule matches on the field values as they were when the phase began. ## Request headers are a different rule A **Request Header Transform Rule** changes the headers Cloudflare sends to your origin, so nothing it does appears in the browser. To see its effect, read the origin's logs or use Cloudflare Trace; Logpush records the original headers, not the transformed ones. Security headers meant for browsers are therefore always response headers, set by a Managed Transform or a Response Header Transform Rule. A sensible rollout is to turn on the Managed Transform first, confirm nothing breaks, then add the stricter headers one rule at a time, starting with a Content Security Policy scoped to a single path so its effect can be read before it covers the whole zone.

  • Why use Add rather than Set when a Response Header Transform Rule writes a set-cookie header?
    Set replaces every header with that name, so Set on set-cookie deletes the cookies the origin and other Cloudflare products, such as Bot Management, already put in the response. Add appends a new set-cookie header and keeps the others.
  • A team sets Cache-Control: max-age=3600 with a Response Header Transform Rule so the edge caches HTML for an hour. Does it?
    No. Cloudflare decides how to cache before it modifies response headers, so the rule only changes what browsers receive. Edge caching is controlled by a Cache Rule or by the headers the origin itself sends.
  • Why can't you see a Request Header Transform Rule's header in the browser's network panel?
    Because it modifies the request Cloudflare sends to the origin, not anything the browser sends or receives. Check the origin's logs or simulate the request with Cloudflare Trace; Logpush shows only the original headers.

  • The Add security headers Managed Transform also sets HSTS and a Content-Security-Policy.
  • A Request Header Transform Rule adds headers the browser receives.
  • Setting Cache-Control in a Response Header Transform Rule changes how Cloudflare caches the page.
  • Using Set on set-cookie safely adds one more cookie to the response.
  • A Response Header Transform Rule can strip cf-ray or other cf- headers.