Overview

A Content Security Policy (CSP) tells the browser which scripts, connections and frames a page is allowed to use. HtmlUnit enforces the policies of a page like real browsers do; violations block the action, fire the securitypolicyviolation event and are reported to your Java code.

This makes HtmlUnit useful to test your policies: a test page that works in HtmlUnit but violates its own policy is detected in your unit tests, without a real browser.

The matching of urls and source expressions is done by htmlunit-csp; HtmlUnit applies the result to the different places scripts, connections and frames are used.

Note: CSP support is still growing. The supported directives are listed below; all other directives are parsed but not enforced (see Not supported (yet)).

Delivering a Policy

HtmlUnit reads the policies of a page from

  • the Content-Security-Policy response header; a response may contain several of these headers and every header may contain a comma separated list of policies. All policies are enforced; an action is only allowed if all policies allow it.
  • the Content-Security-Policy-Report-Only response header; these policies never block anything, violations are only reported (event, log, listener).
  • <meta http-equiv="Content-Security-Policy" content="..."> elements. Like in browsers, only meta elements inside the head are used, the policy only applies to the content following the meta element and Content-Security-Policy-Report-Only is not supported in meta elements. The directives frame-ancestors, sandbox and report-uri are ignored in meta elements. Browsers differ in the handling of commas in the content of a meta element; like Chrome HtmlUnit splits the content into several policies when simulating Chrome/Edge, and like Firefox parses the content as one policy when simulating Firefox.

The frame-ancestors directive is only supported in the response header (like in browsers).

Supported Directives

Directive Checked for
script-src-elem inline and external <script> elements (parser inserted and created by JavaScript), javascript: urls
script-src-attr event handler attributes (e.g. onclick="...")
script-src eval(), new Function(), setTimeout() and setInterval() with a string; fallback for script-src-elem and script-src-attr
style-src-elem inline <style> elements (parser inserted and created by JavaScript), stylesheets loaded by <link rel="stylesheet"> (the error event is fired for blocked stylesheets) and @import rules (the error event is fired at the link if an import is blocked); blocked styles are not applied
style-src-attr style attributes (from the html source, innerHTML and setAttribute()); a blocked attribute stays part of the DOM but is not applied. Like the browsers, changes done by the CSSOM (e.g. element.style.color = 'red' or element.style.cssText) are not checked.
style-src fallback for style-src-elem and style-src-attr
connect-src XMLHttpRequest (including all redirect targets), fetch() (HtmlUnit uses a polyfill based on XMLHttpRequest), WebSocket, navigator.sendBeacon()
frame-src loading a page into a frame or iframe (src attribute, also if changed later), including all redirect targets; fallback is child-src. about:blank and javascript: urls are not checked. A blocked frame shows about:blank; like the error page of the browsers its content is not accessible (contentDocument is null).
img-src images (<img>, new Image(), also if the src is changed later); the violation is reported also if HtmlUnit does not download the image. A blocked image is not downloaded, the error event is fired.
object-src the data url of <object> and the src url of <embed> elements (also if added by script or if the attribute is changed later). HtmlUnit does not load the content of these elements; the url is checked anyway to report the violation (cross origin urls are reported as origin). There is no load event; when simulating Firefox the error event is fired at blocked <object> elements.
media-src the src url of <audio> and <video> elements, the <source> children (in order, until the first allowed one) and the default <track> (also if added by script or if the src is changed later, also for elements not attached to the page). HtmlUnit does not load media; the url is checked anyway to report the violation and the error event is fired at the blocked element.
worker-src creating a dedicated worker (new Worker(url), including data: and blob: urls); fallback is child-src, then script-src. A blocked worker is not started, the error event is fired at the worker.
default-src fallback for the fetch directives above (not for form-action, base-uri and frame-ancestors)
form-action form submission (submit button, form.submit(), form.requestSubmit()), including the formaction attribute of the submit button and javascript: urls as action; like Chrome, redirects are checked also (the url of the form submission is reported). There is no fallback to default-src. Forms with method dialog are not checked.
base-uri the url of the <base> element (also if created or changed by JavaScript); a blocked base url is ignored and urls are resolved against the url of the document. There is no fallback to default-src.
frame-ancestors loading a page into a frame or iframe; all ancestors up to the top window have to be allowed. A frame showing about:blank uses the origin of its parent.
upgrade-insecure-requests http: urls are upgraded to https: and ws: urls to wss: (port 80 is replaced by the default port) for images, scripts, stylesheets and @import, XMLHttpRequest/fetch(), WebSockets, navigator.sendBeacon(), workers, frames and form submissions. Top level navigations (links, location) are only upgraded for the host and port of the page. The other content security policy directives are checked against the upgraded url. Frames inherit the directive. Like the browsers, loopback hosts (localhost, 127.0.0.0/8, [::1]) are not upgraded and the directive is ignored for report only policies; like Firefox, http urls are matching https source expressions (e.g. img-src https:) also if not upgraded when simulating Firefox. Redirects are upgraded also.

The X-Frame-Options header (DENY, SAMEORIGIN) is supported as well; like in browsers it is ignored if the page has a policy with a frame-ancestors directive.

Redirects are checked also: the targets of redirects of stylesheets (including @import), scripts, images, frames, form submissions and XMLHttpRequest/fetch() have to be allowed by the policy; for stylesheets, scripts and images the url of the original request is reported.

Source Expressions

All source expressions of CSP Level 3 are supported: 'self', 'none', *, schemes (e.g. data:), hosts with optional scheme, port and path (e.g. https://*.example.com:8443/api/), nonces ('nonce-...'), hashes ('sha256-...', 'sha384-...', 'sha512-...'), 'unsafe-inline', 'unsafe-eval', 'unsafe-hashes', 'strict-dynamic' and 'report-sample'.

Some details following the browsers:

  • 'unsafe-inline' is ignored if the directive contains a nonce or a hash.
  • The nonce is taken from the nonce property of the element (it can be set by script without changing the attribute). If the page has a policy delivered by a header, the nonce attribute is hidden when the element is added to the page (getAttribute('nonce') returns an empty string, the property still returns the nonce); like Firefox, report only policies do not hide the nonce when simulating Firefox.
  • Elements having an attribute name or value containing <script or <style are not nonceable (the nonce is ignored).
  • With 'strict-dynamic' scripts created by a trusted script are allowed; host sources and parser inserted scripts without nonce or hash are blocked.
  • ws: and wss: urls are matched without mapping them to http: and https:; therefore the source http://example.com does not allow a WebSocket connection to ws://example.com, but 'self' allows ws: and wss: urls of the page's host.
  • * and 'self' do not match urls without host (e.g. data: or blob:); list the scheme instead.

Policy Inheritance

Like the browsers, documents with a local scheme url (about:blank, data:, blob:) inherit a copy of the policy of the document creating them:

  • frames and iframes inherit the policy of the parent document
  • windows opened by window.open() inherit the policy of the opener
  • 'self' refers to the origin of the creator; policies added later (e.g. by meta elements) are not shared between the documents
  • like the browsers, eval() and new Function() use the policy of the window they belong to (e.g. frame.contentWindow.eval() is checked against the policy of the frame)
  • the content written by document.open()/write()/close() and the result of a javascript: url keep the policy of the replaced document

Documents loaded from http(s) urls never inherit the policy; they only use the policies delivered with their own response.

Blocked Actions

A blocked action behaves like in the browsers:

  • Blocked scripts and event handlers are not executed; a blocked external script fires the error event.
  • eval() and new Function() throw an EvalError; timers with a string are not executed.
  • A blocked XMLHttpRequest fails with a network error (the request is not sent): asynchronous requests fire error and loadend, synchronous requests throw a NetworkError.
  • A blocked WebSocket fires error and close (code 1006).
  • navigator.sendBeacon() returns true but the beacon is not sent (like Chrome).
  • A blocked form submission does nothing; the submit event was already fired.
  • A frame blocked by frame-ancestors or X-Frame-Options shows about:blank.

Reporting Violations

Every violation (of an enforced or a report only policy) is reported in these ways.

Log

Violations are logged with level WARN (logger org.htmlunit.html.ContentSecurityPolicy; frame-ancestors violations: org.htmlunit.WebClient), see Logging.

securitypolicyviolation Event

The securitypolicyviolation event is fired at the element causing the violation (if connected to the document) or at the document. It provides the properties documentURI, blockedURI, effectiveDirective, violatedDirective, originalPolicy, sourceFile, sample, disposition, statusCode, lineNumber and columnNumber.

Browsers fire the event asynchronously; HtmlUnit fires it after the current script has finished to provide a deterministic order.

report-uri

If the policy contains a report-uri directive, HtmlUnit sends the report as POST request with content type application/csp-report and the JSON body ({"csp-report": {"document-uri": ..., "blocked-uri": ..., ...}}) to every uri of the directive. Like the browsers, the reports are sent async (after the current script); report-uri is ignored in meta elements and if the policy also contains a report-to directive. When simulating Firefox the report uses the Firefox format (sorted keys, absolute report uris in original-policy). Violations of frame-ancestors are not reported this way.

Java Listener

To check violations in your Java code, register a ContentSecurityPolicyViolationListener at the WebClient. The listener is called for every violation, also if JavaScript is disabled (e.g. for frame-ancestors). The ContentSecurityPolicyViolation passed to the listener provides the same information as the event; isReportOnly() tells you if the action was blocked or only reported.

The CollectingContentSecurityPolicyViolationListener collects all violations; use it to make your tests fail if a page violates its policy:


@Test
public void noCspViolations() throws Exception {
    try (final WebClient webClient = new WebClient()) {
        final CollectingContentSecurityPolicyViolationListener cspListener =
                new CollectingContentSecurityPolicyViolationListener();
        webClient.setContentSecurityPolicyViolationListener(cspListener);

        final HtmlPage page = webClient.getPage("https://www.example.com/");
        // interact with the page
        ...

        assertEquals("[]", cspListener.getViolations().toString());
    }
}

Or implement the listener yourself, e.g. to log the violations of your application:


webClient.setContentSecurityPolicyViolationListener((page, violation) -> {
    System.out.println(page.getUrl() + ": " + violation);
});

The listener is called while HtmlUnit processes the page (e.g. while parsing or while a script is executed); it should not throw exceptions or modify the page.

Not supported (yet)

The following parts of CSP are not enforced by HtmlUnit; the directives are parsed but ignored:

  • font-src, manifest-src; HtmlUnit does not load fonts and manifests (the browsers are loading them only on demand)
  • sandbox
  • require-trusted-types-for, trusted-types
  • report-to (Reporting API); no reports are sent for this directive, use report-uri or the listener instead.

Known limitations:

  • HtmlUnit does not support srcdoc iframes.
  • javascript: urls used as src of a frame or with window.open() are not checked.
  • Workers do not have a policy of their own (from the worker response or inherited for data:/blob: workers); importScripts() is not checked and eval() inside a worker is checked against the policy of the page. Shared and service workers are not supported by HtmlUnit.
  • frame-src is only checked for the src of the frame; navigations inside the frame (e.g. links or location changes) are not checked.
  • The violation event for eval() has no column number (the JavaScript engine does not provide it).
  • Where browsers differ, HtmlUnit follows Chrome (e.g. Firefox throws an exception for a blocked WebSocket and sendBeacon() returns false).

Scripts executed by your Java code (e.g. HtmlPage.executeJavaScript() or Selenium's executeScript()) are not subject to the policy of the page, like scripts executed by browser extensions or the developer tools.