- Overview
- Delivering a Policy
- Supported Directives
- Policy Inheritance
- Blocked Actions
- Reporting Violations
- Not supported (yet)
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-Policyresponse 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-Onlyresponse 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 theheadare used, the policy only applies to the content following the meta element andContent-Security-Policy-Report-Onlyis not supported in meta elements. The directivesframe-ancestors,sandboxandreport-uriare 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
nonceproperty of the element (it can be set by script without changing the attribute). If the page has a policy delivered by a header, thenonceattribute 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
<scriptor<styleare 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:andwss:urls are matched without mapping them tohttp:andhttps:; therefore the sourcehttp://example.comdoes not allow a WebSocket connection tows://example.com, but'self'allowsws:andwss:urls of the page's host. -
*and'self'do not match urls without host (e.g.data:orblob:); 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()andnew 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 ajavascript: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
errorevent. -
eval()andnew Function()throw anEvalError; timers with a string are not executed. -
A blocked
XMLHttpRequestfails with a network error (the request is not sent): asynchronous requests fireerrorandloadend, synchronous requests throw aNetworkError. - A blocked
WebSocketfireserrorandclose(code 1006). navigator.sendBeacon()returnstruebut the beacon is not sent (like Chrome).- A blocked form submission does nothing; the submit event was already fired.
- A frame blocked by
frame-ancestorsorX-Frame-Optionsshowsabout: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) sandboxrequire-trusted-types-for,trusted-types-
report-to(Reporting API); no reports are sent for this directive, usereport-urior the listener instead.
Known limitations:
- HtmlUnit does not support
srcdociframes. -
javascript:urls used assrcof a frame or withwindow.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 andeval()inside a worker is checked against the policy of the page. Shared and service workers are not supported by HtmlUnit. -
frame-srcis only checked for thesrcof the frame; navigations inside the frame (e.g. links orlocationchanges) 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()returnsfalse).
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.

