frame-protection 1.0.0

Frame Protection Check v1.0.0

Status

• Version: 1.0.0
• Check identifier: frame-protection
• Input contract: agent-page-scan-input@1.0.0
• Output contract: agent-check-result@1.0.0
• Scope: page

Abstract

This check validates whether a browser-rendered HTML document limits who may embed it in a frame. It treats an enforcing Content-Security-Policy frame-ancestors directive as the modern full-pass control and treats X-Frame-Options: DENY or SAMEORIGIN as a legacy baseline that returns warning when no enforcing frame-ancestors directive is present. When browser-observed response evidence is available, it also reviews sampled same-origin HTML document responses for equivalent protection.

Motivation

Clickjacking and UI redressing attacks embed a target page in a hostile frame and trick a user into interacting with it. Frame protection matters most for sign-in, account, checkout, payment, admin, authorization, settings, form, and authenticated-data pages.

Normative Model

Content-Security-Policy: frame-ancestors ... is the modern browser control for restricting which ancestors may embed a protected resource using frame, iframe, object, or embed.

Important CSP behavior:

• frame-ancestors 'none' blocks all embedding.
• frame-ancestors 'self' allows same-origin embedding.
• explicit scheme and host sources can allow selected embedding partners.
• every ancestor in the embedding chain must match the source list.
• frame-ancestors does not fall back to default-src.
• frame-ancestors must be delivered in an enforcing CSP response header.
• frame-ancestors in a meta CSP is ignored.
• frame-ancestors in Content-Security-Policy-Report-Only reports but does not block.
• if an enforcing CSP policy contains frame-ancestors, modern browser processing uses that policy instead of X-Frame-Options.

X-Frame-Options is a legacy control. DENY and SAMEORIGIN are valid baseline values. ALLOW-FROM is obsolete in modern browsers and does not satisfy this check.

Applicability

The check applies to the scanned page response and expects a browser-rendered HTML document, especially pages with sensitive or meaningful user interaction.

Redirects, no-body responses, non-HTML assets, JSON API responses, binary downloads, fonts, images, CSS, JavaScript, and plain text responses fail this check when scanned as the primary page response.

Pages intentionally designed for third-party embedding should use a narrow explicit frame-ancestors allowlist. They are not required to use DENY or 'none'.

Pass Criteria

An applicable HTML response fully passes when it has one of:

• enforcing CSP with parseable frame-ancestors 'none'
• enforcing CSP with parseable frame-ancestors 'self'
• enforcing CSP with a narrow explicit list of trusted origins

X-Frame-Options: DENY or X-Frame-Options: SAMEORIGIN satisfies the legacy baseline but returns warning when no enforcing CSP frame-ancestors directive is present.

The strongest posture is an enforcing frame-ancestors directive, optionally paired with a compatible XFO fallback for older browsers.

Warning Criteria

Warnings include:

• protection relies only on X-Frame-Options with no enforcing frame-ancestors
• CSP frame-ancestors and XFO express different policies
• enforcing frame-ancestors allows broad sources such as https:
• XFO is invalid, obsolete, or conflicting while enforcing frame-ancestors still protects modern browsers
• Chrome-observed same-origin HTML documents have missing, invalid, or broad frame protection
• the response body is renderable but not clearly an HTML document

Failure Criteria

Failures include:

• scanned response is not a browser-rendered HTML document
• applicable HTML response has neither enforcing frame-ancestors nor valid XFO
• frame-ancestors is malformed or empty
• frame-ancestors 'none' is combined with other sources
• frame-ancestors appears only in report-only CSP
• frame-ancestors appears only in meta CSP
• XFO is the only protection and uses ALLOW-FROM
• XFO is the only protection and is invalid
• XFO contains multiple conflicting effective values
• enforcing frame-ancestors uses *, effectively allowing arbitrary embedding

Evidence Model

The check emits step-level evidence for:

• final URL, status, content type, HTML likelihood, and applicability
• enforcing CSP presence and policy count
• report-only CSP presence and policy count
• meta CSP frame-ancestors presence
• parsed frame-ancestors values, mode, validity, broad sources, and explicit origins
• XFO presence, values, normalized values, parsed directive, obsolete ALLOW-FROM, and duplicate/conflicting values
• CSP/XFO interaction and which mechanism controls modern browser behavior
• sampled same-origin Chrome-observed HTML document responses, when available

Evidence must not include cookies, authorization headers, credentials, complete HTML, full response header dumps, or unrelated sensitive values.

Validation And Scoring Steps

• applicability (0.15): classify whether the scanned response is a browser-rendered HTML document.
• csp-frame-ancestors (0.35): parse enforcing, report-only, and meta CSP and evaluate frame-ancestors.
• x-frame-options (0.25): parse XFO values, duplicate values, obsolete ALLOW-FROM, and legacy fallback quality.
• conflict-review (0.10): compare modern CSP behavior with legacy XFO behavior.
• observed-responses (0.15): when Chrome evidence exists, review sampled same-origin HTML document responses.

Standard Behavior

If an applicable page has restrictive enforcing frame-ancestors, it passes.

If an applicable page lacks frame-ancestors but has X-Frame-Options: DENY or SAMEORIGIN, it passes the legacy baseline with a warning that CSP frame-ancestors is preferred.

If frame-ancestors appears only in report-only or meta CSP, it does not count as protection.

If no valid frame protection is present on an applicable HTML page, the check fails.

Non-Standard And Real-World Behavior

Many security scanners accept either XFO or CSP frame-ancestors. This check distinguishes modern protection from legacy fallback because CSP supports multiple trusted embedding origins and is the browser-preferred control when both mechanisms are present.

JavaScript frame-busting and SameSite cookies can reduce clickjacking impact in some situations, but neither replaces browser frame blocking for this check.

Non-Goals And Limitations

This check does not:

• prove immunity to all clickjacking or UI redressing attacks
• execute interactive attack simulations
• inspect authenticated routes unless they are part of the scan
• prove every route has frame protection without route sampling
• require DENY for intentionally embeddable pages
• treat JavaScript frame-busting as sufficient protection
• treat SameSite cookies as equivalent to frame protection
• treat default-src, frame-src, or child-src as protection for the current page being embedded
• treat report-only or meta frame-ancestors as enforced protection

References

• www.w3.org/TR/CSP3/#directive-frame-ancestors
• html.spec.whatwg.org/multipage/browsing-the-web.html#the-x-frame-options-header
• www.rfc-editor.org/rfc/rfc7034
• developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options
• developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors
• cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html

frame-protection v1.0.0 Changelog

Initial release.

• Evaluates enforcing CSP frame-ancestors for modern frame protection.
• Accepts X-Frame-Options: DENY and SAMEORIGIN as legacy baseline protection.
• Rejects report-only or meta-delivered frame-ancestors as unenforced.
• Rejects obsolete X-Frame-Options: ALLOW-FROM as baseline protection.
• Reviews sampled same-origin HTML document responses when browser response evidence is available.