Update: Cross-Site Request Forgery Prevention Cheat Sheet - add Fetch Metadata

[mkhanas]

What is missing or needs to be updated?

The CSRF Cheat Sheet currently lacks any mention of Fetch Metadata (Sec-Fetch-*) headers. Sec-Fetch-Site (and related Sec-Fetch-* headers) let servers determine the context of a request (e.g. same-origin, same-site, none, cross-site) and therefore provide a reliable way to block obvious cross-site requests before they reach application logic.

While modern browsers provide these headers and many sources recommend using them as a CSRF mitigation:

1. Other OWASP cheat sheets (for example, Cookie Theft Mitigation and XS-Leaks) already mention Sec-Fetch-*. The CSRF Cheat Sheet should likewise document this technique as a defense-in-depth option.
2. Public guidance ([MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF), [[web.dev](https://web.dev/articles/fetch-metadata)](https://web.dev/articles/fetch-metadata)) and active community discussion (for example, Go issue [#73626](net/http: add CrossOriginForgeryHandler golang/go#73626)) highlight growing adoption and interest in using Fetch Metadata to reduce CSRF risk.
3. Early adopters and libraries (e.g., [tower-sec-fetch](https://github.com/matteojoliveau/tower-sec-fetch)) demonstrate practical implementations and demand for canonical guidance.

developers following the OWASP CSRF Cheat Sheet do not currently have OWASP-backed guidance on how to apply Fetch Metadata (Sec-Fetch-*) checks safely and correctly, or how to combine them with existing defenses (SameSite, tokens, Origin/Referer checks).

How should this be resolved?

Add a subsection “Fetch Metadata (Sec-Fetch-*) — an additional defense-in-depth control” under the Defense-in-Depth Techniques section. The subsection should:

1. Explain the concept
   • What Sec-Fetch-Site, Sec-Fetch-Mode, Sec-Fetch-Dest, and Sec-Fetch-User are and why Sec-Fetch-Site is most relevant for CSRF protection.
2. Describe recommended policy
   • If Sec-Fetch-Site is present and equals cross-site, reject non-safe state-changing requests (POST/PUT/PATCH/DELETE) unless explicitly whitelisted.
   • Allow same-origin and (optionally) same-site depending on your subdomain trust model.
   • Treat absence of Sec-Fetch-* headers as unknown (legacy UA or non-browser client) and fall back to Origin/Referer and/or CSRF token validation — do not fail open.
3. Provide a short example to illustrate common patterns:
4. Recommend rollout guidance
   • Start with a logging / report-only mode to detect legitimate traffic that would be blocked.
   • Monitor coverage and ensure fallbacks cover clients that do not send Sec-Fetch-*.

I already have a PR prepared, so you can assign this issue to me, and I will submit a PR. Thank you!

[jmanico]

So long as we position this as:

• Use CSRF tokens (or equivalent framework mechanisms) as primary protection
• use Fetch Metadata as resource-isolation/defense-in-depth with careful exemptions and cache headers.

[mkhanas]

Thanks — agreed.
I’ll ensure the text clearly states CSRF tokens remain the primary protection, and present Sec-Fetch (Sec-Fetch-*) strictly as a defense-in-depth.

I’ll also add a short Vary/cache note linking the fetch metadata headers spec: https://w3c.github.io/webappsec-fetch-metadata/#vary

[nickchomey]

Sorry if it isn't appropriate for me to comment here, but I wonder why this change explicitly says

It is important to note that Fetch Metadata headers should be implemented as an additional layer defense in depth concept. This attribute should not replace a CSRF tokens (or equivalent framework protections).

Plenty of places (including seemingly the Golang standard library) are suggesting that this is an alternative/replacement for traditional CSRF tokens.

Given how much a fetch header approach can simplify CSRF protection, I think it would be helpful if the OWASP docs could explain exactly why this is insufficient, especially since this PR positions Sec-Fetch-Site as your first and primary line of defense against CSRF, only optionally falling back to Origin, tokens or something else if you don't choose to fail-safe.

Is it really just for this reason - that a small minority of browsers don't support Sec-Fetch-Site or Origin headers? Or is there some other more nuanced reason? The CORS and http/https gotchas don't seem to be sufficient to say that this really only should be defense-in-depth on top of tokens.

Any clarity would be appreciated!

https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#use-fetch-metadata-headers-to-verify-nature-of-the-request

[jmanico]

Fetch Metadata is great, but it’s a coarse signal, not a cryptographic intent signal. It reduces cross-site noise and blocks whole classes of drive-by requests, but it can’t prove user intent or bind a request to your origin session artifact the way CSRF tokens (or per-request nonces) do. That’s why OWASP positions it as defense-in-depth, not a replacement.

If you would like, I can go into more detail.

[nickchomey]

My impression is that when it comes to CSRF protection, we just want to prevent malicious off-site/origin links from tricking logged-in users of our site from inadvertently mutating the state that they are authorized for. Is there any legitimate "user intent" for such an off-site mutation request?

And, again, the Sec-Fetch-Site section says:

1.1 If Sec-Fetch-Site is present: 1.1. Treat cross-site as untrusted for state-changing actions. By default, reject non-safe methods (POST / PUT / PATCH / DELETE) when Sec-Fetch-Site: cross-site.
1.2. Allow same-origin. Treat same-site as allowed only if your threat model trusts sibling subdomains; otherwise handle same-site conservatively (for example, require additional validation).
1.3. Allow none for user-driven top-level navigations (bookmarks, typed URLs, explicit form submits) where appropriate.
2. If Sec-Fetch-* headers are absent: choose a fallback based on risk and compatibility requirements: 2.1. Fail-safe (recommended for sensitive endpoints): treat absence as unknown and block the request. 2.2. Fail-open (compatibility-first): fallback to other security measure (CSRF tokens, validate Origin/Referer, and/or require additional validation).
3.1 To ensure that your site can still be linked from other sites, you have to allow simple (HTTP GET) top-level navigation.
3.2 Whitelist explicit cross-origin flows. If certain endpoints intentionally accept cross-origin requests (CORS JSON APIs, third-party integrations, webhooks), explicitly exempt those endpoints from the global Sec-Fetch deny policy and secure them with proper CORS configuration, authentication, and logging.

So, it seems like it is saying it is a viable front-line defense - especially if you fail-safe and block requests missing those (eg Sec-Fetch-Site and Origin) headers. I see no problem with this for my use-case, and therefore no need for traditional CSRF tokens.

I would very much appreciate whatever detail you are willing to go into to explain why this is not actually appropriate, whether it is in general or in just specific cases.

Thanks!

[jmanico]

Thanks for the thoughtful pushback — and +1 that Fetch Metadata is a big win. The reason I suggest it as a defense-in-depth (not a token replacement) comes down to what signal it provides:

• Fetch Metadata exposes coarse rules about request context (e.g., Sec-Fetch-Site: cross-site | same-site | same-origin, plus mode/dest/user). This is fantastic for blocking obvious cross-site noise, but it does not prove user intent or bind a request to a page that rendered a form in your origin. CSRF tokens are unpredictable, per-session/per-request secrets that bind a state-changing request to an authenticated origin flow. That cryptographic binding is the gap.

• Same-site subdomain attackers (subdomains hijacked via subdomain takeover, misconfig, partner tenant, or a shared hosting zone) remain in-scope for CSRF when security settings using Fetch Metadata only block "cross-site" requests (from totally different domains).

• Even strong Fetch-Metadata guidance says to fall back when headers are absent/unknown (legacy UAs like Safari from 2023, non-browser clients, automation) to Origin/Referer checks and/or CSRF tokens and recommends fail-safe only for endpoints where you can tolerate breakage. In other words, you end up needing the traditional defenses anyway for compatibility-safe coverage.

• Most sites have intentional cross-origin traffic: webhook endpoints, CORS APIs, third-party integrations, top-level navigations, etc. Those need explicit exceptions under a metadata-first policy. A token approach keeps endpoints protected while leaving machine-to-machine flows authenticated via keys/signatures rather than cookie sessions.

• The spec and mainstream docs describe Fetch Metadata as letting servers decide a priori whether to service requests based on how they were made. Even proposals (like Go’s CrossOriginForgeryHandler) are framed as easy, default noise-reduction for non-safe methods in modern browsers, not a universal replacement for token patterns across all clients and threat models.

I am admittedly using edited AI to help me with this response. Please keep pushing back if any of this is wrong or similar.

[kwwall]

@jmanico wrote,

Thanks for the thoughtful pushback — and +1 that Fetch Metadata is a big win. The reason I suggest it as a defense-in-depth (not a token replacement) comes down to what signal it provides:
8<----- Snip ----->8
I am admittedly using edited AI to help me with this response. Please keep pushing back if any of this is wrong or similar.

Wow, Jim, if you ever need help being more verbose, you don't have to resort to using generative AI; just drop me a line instead. I've been practicing that my whole career.

But seriously, I think you make a lot of valid points and I'm almost in 100% agreement. The only point there I have a very slight nit to pick is with this statement from your first bullet, which potentially could be misunderstood. Let me take a crack; you wrote:

... CSRF tokens are unpredictable, per-session/per-request secrets that bind a state-changing request to an authenticated origin flow. That cryptographic binding is the gap.

While it's a good idea that CSRF tokens are generated using a CSRNG, they don't strictly require that to ensure unpredictability, especially if the application uses a different CSRF token "per request". So the point of the cryptographic binding might be misunderstood by some as referring to the use of a CSRNG (vs a PRNG) to generate the CSRF tokens. I want to be clear that this is not what I think Jim's reference to "cryptographic binding" is referring to here. (I'm sure our AI overlords will correct me if I wrong. :) What I think Jim's reference here is referring to is the common association of the CSRF token with the HTTP session (which we all probably generally accept that its associated session ID MUST be created in cryptographically secure manner). The cryptographically strong session ID is frequently tied to the CSRF token value because that's where it is usually stored (in the HTTP session object or something associated with it) and the authentication protocol itself needs to be cryptographically sound as well.

(See Jim; never waste an opportunity to be even more verbose! 😉)