Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types

Reduce the DOM XSS attack surface of your application.

Mar 25, 2020

Available in: English, Español, Português, Русский, 中文, 日本語, and 한국어

Why should you care? #

DOM-based cross-site scripting (DOM XSS) is one of the most common web security vulnerabilities, and it's very easy to introduce it in your application. Trusted Types give you the tools to write, security review, and maintain applications free of DOM XSS vulnerabilities by making the dangerous web API functions secure by default. Trusted Types are supported in Chrome 83, and a polyfill is available for other browsers. See Browser compatibility for up-to-date cross-browser support information.

Background #

For many years DOM XSS has been one of the most prevalent—and dangerous—web security vulnerabilities.

There are two distinct groups of cross-site scripting. Some XSS vulnerabilities are caused by the server-side code that insecurely creates the HTML code forming the website. Others have a root cause on the client, where the JavaScript code calls dangerous functions with user-controlled content.

To prevent server-side XSS, don't generate HTML by concatenating strings and use safe contextual-autoescaping templating libraries instead. Use a nonce-based Content Security Policy for additional mitigation against the bugs as they inevitably happen.

Now a browser can also help prevent the client-side (also known as DOM-based) XSSes with Trusted Types.

API introduction #

Trusted Types work by locking down the following risky sink functions. You might already recognize some of them, as browsers vendors and web frameworks already steer you away from using these features for security reasons.

Script manipulation:
<script src> and setting text content of <script> elements.
Generating HTML from a string:

innerHTML, outerHTML,insertAdjacentHTML, <iframe> srcdoc, document.write, document.writeln, and DOMParser.parseFromString
Executing plugin content:
<embed src>, <object data> and <object codebase>
Runtime JavaScript code compilation:
eval, setTimeout, setInterval, new Function()

Trusted Types require you to process the data before passing it to the above sink functions. Just using a string will fail, as the browser doesn't know if the data is trustworthy:

Don't

anElement.innerHTML  = location.href;

With Trusted Types enabled, the browser throws a TypeError and prevents use of a DOM XSS sink with a string.

To signify that the data was securely processed, create a special object - a Trusted Type.

anElement.innerHTML = aTrustedHTML;

With Trusted Types enabled, the browser accepts a TrustedHTML object for sinks that expect HTML snippets. There are also TrustedScript and TrustedScriptURL objects for other sensitive sinks.

Trusted Types heavily reduce the DOM XSS attack surface of your application. It simplifies security reviews, and allows you to enforce the type-based security checks done when compiling, linting, or bundling your code at runtime, in the browser.

How to use Trusted Types #

Prepare for Content Security Policy violation reports #

You can deploy a report collector (such as the open-source go-csp-collector), or use one of the commercial equivalents. You can also debug the violations in the browser:

document.addEventListener('securitypolicyviolation',
    console.error.bind(console));

Add a report-only CSP header #

Add the following HTTP Response header to documents that you want to migrate to Trusted Types.

Content-Security-Policy-Report-Only: require-trusted-types-for 'script'; report-uri //my-csp-endpoint.example

Now all the violations are reported to //my-csp-endpoint.example, but the website continues to work. The next section explains how //my-csp-endpoint.example works.

Identify Trusted Types violations #

From now on, every time Trusted Types detect a violation, a report will be sent to a configured report-uri. For example, when your application passes a string to innerHTML, the browser sends the following report:

{
"csp-report": {
    "document-uri": "https://my.url.example",
    "violated-directive": "require-trusted-types-for",
    "disposition": "report",
    "blocked-uri": "trusted-types-sink",
    "line-number": 39,
    "column-number": 12,
    "source-file": "https://my.url.example/script.js",
    "status-code": 0,
    "script-sample": "Element innerHTML <img src=x"
}
}

This says that in https://my.url.example/script.js on line 39 innerHTML was called with the string beginning with <img src=x. This information should help you narrow down which parts of code may be introducing DOM XSS and need to change.

Fix the violations #

There are a couple of options for fixing a Trusted Type violation. You can remove the offending code, use a library, create a Trusted Type policy or, as a last resort, create a default policy.

Rewrite the offending code #

Perhaps the non-conforming functionality is not needed anymore or can be rewritten in a modern way without using the error-prone functions?

Don't

el.innerHTML = '<img src=xyz.jpg>';

el.textContent = '';
const img = document.createElement('img');
img.src = 'xyz.jpg';
el.appendChild(img);

Use a library #

Some libraries already generate Trusted Types that you can pass to the sink functions. For example, you can use DOMPurify to sanitize an HTML snippet, removing XSS payloads.

import DOMPurify from 'dompurify';
el.innerHTML = DOMPurify.sanitize(html, {RETURN_TRUSTED_TYPE: true});

DOMPurify supports Trusted Types and will return sanitized HTML wrapped in a TrustedHTML object such that the browser does not generate a violation.

Create a Trusted Type policy #

Sometimes it's not possible to remove the functionality, and there is no library to sanitize the value and create a Trusted Type for you. In those cases, create a Trusted Type object yourself.

For that, first create a policy. Policies are factories for Trusted Types that enforce certain security rules on their input:

if (window.trustedTypes && trustedTypes.createPolicy) { // Feature testing
  const escapeHTMLPolicy = trustedTypes.createPolicy('myEscapePolicy', {
    createHTML: string => string.replace(/\</g, '&lt;')
  });
}

This code creates a policy called myEscapePolicy that can produce TrustedHTML objects via its createHTML() function. The defined rules will HTML-escape < characters to prevent the creation of new HTML elements.

Use the policy like so:

const escaped = escapeHTMLPolicy.createHTML('<img src=x onerror=alert(1)>');
console.log(escaped instanceof TrustedHTML);  // true
el.innerHTML = escaped;  // '&lt;img src=x onerror=alert(1)>'

Use a default policy #

Sometimes you can't change the offending code. For example, this is the case if you're loading a third-party library from a CDN. In that case, use a default policy:

if (window.trustedTypes && trustedTypes.createPolicy) { // Feature testing
  trustedTypes.createPolicy('default', {
    createHTML: (string, sink) => DOMPurify.sanitize(string, {RETURN_TRUSTED_TYPE: true})
  });
}

The policy with a name default is used wherever a string is used in a sink that only accepts Trusted Type.

Switch to enforcing Content Security Policy #

When your application no longer produces violations, you can start enforcing Trusted Types:

Content-Security-Policy: require-trusted-types-for 'script'; report-uri //my-csp-endpoint.example

Voila! Now, no matter how complex your web application is, the only thing that can introduce a DOM XSS vulnerability, is the code in one of your policies - and you can lock that down even more by limiting policy creation.