UI redress

Clickjacking and frame-ancestors

Clickjacking is your page, loaded in an invisible frame over something the visitor wanted to click. Their session and their click, aimed at a button they cannot see.

frame-ancestors says who may embed you. Its reports are the only CSP reports about somebody else's site instead of your own.

Framing leaves no trace on your servers, like every problem client-side security covers.

What the attack is

An attacker's page loads yours in an <iframe>, makes it nearly transparent, and lines one of your controls up under something enticing on theirs. The visitor clicks what they can see, and the browser delivers the click to your page, with their session attached.

Nothing is injected or intercepted. Every control on your side behaves normally, because the visitor did click your button.

The defence is to refuse framing by anyone you did not name. It takes one directive in your Content-Security-Policy header, and on most sites the right value is frame-ancestors 'none'.

Why frame-ancestors supersedes X-Frame-Options

Four reasons. The third is why it matters here.

It can name more than one origin
X-Frame-Options had DENY and SAMEORIGIN, and an ALLOW-FROM that Chrome and Safari never implemented, so a site with one partner that embedded it had no working option. frame-ancestors takes a source list of origins, schemes and wildcards.
It checks the whole ancestor chain
A frame inside a frame inside a page has three ancestors, and frame-ancestors checks all of them. Browsers handled nested chains under X-Frame-Options differently, so SAMEORIGIN meant different things in different places.
It reports, and X-Frame-Options does not
X-Frame-Options blocks without a word: the frame stays blank and you never learn it was attempted. frame-ancestors sends a violation report, so you can see when someone frames you.
Where both are present, the enforcing one wins
A browser that supports frame-ancestors ignores X-Frame-Options when an enforcing policy sets both. A report-only policy does not override the old header, which is what you want while you read reports: X-Frame-Options keeps blocking, and frame-ancestors tells you who is knocking.

What the report looks like

Read the two URL fields carefully. They are the other way round from every other directive.

Someone framed a transfer page on an app whose policy only allows itself.
{
  "csp-report": {
    "document-uri": "https://app.example.com/settings/transfer",
    "referrer": "",
    "violated-directive": "frame-ancestors",
    "effective-directive": "frame-ancestors",
    "original-policy": "default-src 'self'; frame-ancestors 'self'; report-uri https://k3x9mp2nq7ab.ingest.us.headerhawk.com/r",
    "disposition": "report",
    "blocked-uri": "https://free-prizes.example/",
    "status-code": 200,
    "script-sample": ""
  }
}

How it appears in HeaderHawk

frame-ancestors blocking free-prizes.example

  • The report comes from your page, the one that refused to be framed, so document-uri is your page and blocked-uri is the would-be embedder. Everywhere else in CSP, blocked-uri is something you tried to load.
  • A frame-ancestors issue is either a partner you forgot to allow or somebody who should not be embedding you, and the URL usually tells you which.
  • Some browsers send an empty value. HeaderHawk records that as the host unknown, so an issue titled 'frame-ancestors blocking unknown' means the browser withheld the embedder, not that there wasn't one.
  • disposition: report means the framing succeeded. Enforcing is what keeps the frame blank.

Field by field: the frame-ancestors reference.

What HeaderHawk does with it

Framing reports are few and worth reading, the opposite of most CSP traffic. Each embedder becomes one issue, frame-ancestors plus the host that tried, with a report count, the pages of yours that were framed, and first- and last-seen times. One page framed again and again is a target, and which page tells you what the attacker wants clicked.

A window reported by two or more browser families alerts at once. A few reports from one browser go into a daily or weekly digest, which is right here: one report from one browser is as likely to be a researcher, a translation proxy or an embedded preview as an attack.

Each report gives the embedder URL as sent, the page that refused, the full policy in force, and the browser and operating system. That is the evidence for adding a partner to the allowlist, and the embedder's domain usually tells you whether to worry.

Where CSP alone is not enough

Framing reports tell you about attempts. They say nothing about whether you are protected, and that gap is wider here than on any other page in this section.

  • Reports cannot tell you that protection went missing. If frame-ancestors disappears from a route, or a CDN rule stops passing it through, nothing reports, and that looks just like a quiet week. On the Professional plan and above, each page you mark is scanned daily, and a change to its Content-Security-Policy or X-Frame-Options raises an alert. Unmarked routes, and every page on the Free and Team plans, are only as visible as their reports.
  • A report only exists if your page was framed. Silence means nobody framed you, nobody framed you in a browser that reports, or your page is not sending the directive, and you cannot tell which.
  • A phishing page that copies your interface never touches your origin. frame-ancestors governs embedding, not a replica on somebody else's domain.
  • frame-ancestors does not fall back to default-src. A policy of default-src 'none' with no frame-ancestors can be embedded by anyone, and it is easy to read as tight.
  • It is ignored in a <meta> policy. Set in HTML instead of a header, the directive does nothing and reports nothing, and the rest of the policy still works, so nothing looks wrong.
  • Some browsers withhold the embedder's URL, so you learn you were framed without learning by whom.
  • Report-only mode prevents nothing. The framing happened and you got a report. Only an enforcing policy in your own header stops it.
  • Framing is not the whole of clickjacking defence. SameSite cookies, re-authentication on sensitive actions, and keeping irreversible operations more than one click away are all outside CSP's reach.

Where to go next

  • The frame-ancestors reference has the syntax, the valid source expressions and the browser support.
  • frame-src is the mirror image: what your page may embed, not who may embed it.
  • CSP and XSS covers the directive most people reach for first, and what it does not reach.

Find out who is framing you

Add frame-ancestors in report-only mode and watch for two weeks before you enforce it. Partners you forgot about show up first.