Security Goals & Threat Model

This page explains what DOMPurify is meant for, what it protects against and what it cannot (yet) cover.

Overall Goals

• Be simple: Take a string as parameter, remove anything in there that can cause XSS, return that sanitized string for safe usage.
• Be tolerant: Many existing XSS filters are successful in preventing XSS but remove too much harmless markup. DOMPurify has the goal to allow as much as possible and slice out only what is capable of executing JavaScript (including JScript, VBScript, Flash, other plugin code).
• Be compatible: DOMPurify aims to be as compatible as possible while still meeting the first two goals. Currently, DOMPurify is compatible with all modern browsers.
  • Edit Feb. 2023 DOMPurify 3.x stopped supporting MSIE to be able to move forward. DOMPurify 2.x still supports MSIE but might not support all latest features.
  • In MSIE9 and 8, DOMPurify will try to use Microsoft's toStaticHTML() method to produce sanitized HTML strings.
  • That means that DOMPurify is technically compatible with MSIE8 but we cannot make any guarantees about the output being secure or not.
  • In MSIE7 and older, DOMPurify will do nothing and degrade silently. See also: toStaticHTML
  • In MSIE7 or even 6, you have bigger problems than XSS. Believe us.
• Be fast: DOMPurify aims to show good performance but we will never prioritize performance over security or compatibility.
• Be open and logical: DOMPurify will have as few lines of browser-specific witch-craft as possible. Pull requests are very welcome but will always be reviewed thoroughly and might be rejected.

Security Goals

• Prevent XSS Attacks: DOMPurify is built to prevent XSS attacks from happening whenever you deal with user-controlled HTML in the browser. There's great server-side XSS filters too but DOMPurify is meant to be used when those are not reliable, not available or otherwise not an option. If you find a way to sneak in JavaScript or similar (JScript, VBScript, Flash and other plugin code) please let us know, that's a bug and a bypass and we will fix it!
• Prevent DOM Clobbering Attacks: DOMPurify also aims to prevent DOM Clobbering Attacks. That means, if someone tries to mess up your DOM by for example using <img src=x name=getElementById> with user controlled HTML to overwrite your precious document.getElementById() method, DOMPurify will prevent that. If you find a way where this is still possible please let us know, that's a bug and a bypass and we will fix it! See also: DOM Clobbering, DOM Clobbering 2
• Prevent XSS via jQuery: DOMPurify is aware of the "smart" HTML parsing that jQuery does and prevents jQuery-specific XSS in case you tell it to via configuration flag (SAFE_FOR_JQUERY). If you process user controlled HTML with jQuery methods ($, $.html, etc.), make sure you sanitize them with DOMPurify first. If you find a way around that please let us know, that's a bug and a bypass and we will fix it! See also: jPurify
• Prevent Structural Damage: The HTML string or document returned by DOMPurify is sane HTML and doesn't miss closing tags or other bits that might ruin your website's structure or even leak data. If you find a way to do that anyway, it's a bug and we will fix it. Please let us know. See also: Dangling Open Tags
• Be safe from Prototype Pollution: DOMPurify should work as expected even if the website around it is affected by a Prototype Pollution issue. We try to make sure that the properties and methods we use internally are safe and deliver reliable output. See also: Prototype Pollution

Non-Goals

• DOMPurify will NOT protect you against faulty use or flipping of markup context. If you for example take a bit of HTML, sanitize it, then throw it into an SVG or any other XML-based markup, crazy things might happen and you will likely have a bypass. If you sanitize HTML, make sure to use it in HTML. If you sanitize SVG, make sure you use it inside an SVG. Stick to the context you are working with and all will be fine!
• DOMPurify will NOT protect against CSS-based XSS attacks that work in ancient IE/Mozilla/Opera browsers or similarly ancient IE document modes. If you want to prevent attacks using @import in <style> elements or x:expression(alert(1)) in <style> or style attributes, please remove them from the allow-list using the config options! As a matter of fact, DOMPurify will not even work (a.k.a fall-back to toStaticHTML) in these older modes and browsers where those attacks are possible as they are considered legacy and should not be used. See also: H5SC CSS Attacks
• DOMPurify will NOT protect you against HTTP leaks, meaning HTML that somehow requests external resources. There are too many ways of doing that and our tests showed that it cannot be done reliably. There are however plans to create a plugin that might get close to be able to do that. It is hard though.
  • Edit Oct. 2015 We do provide a demo hook that attempts to proxy all HTTP leaks: source code
• DOMPurify will NOT protect your from anything just so. You have to actively feed it a string (or document) and will get a string (or document if you specified that via configuration flag). That result will then be clean and safe according to the goals mentioned above. Just including DOMPurify in your website or project will not do anything, you have to actually call it and work with it.
• DOMPurify will NOT prevent you from XSS caused by crazy library features as for example AngularJS has. We implemented a protective coat to protect against jQuery-XSS but cannot cover all other libraries. If you are using a library that has crazy XSS vulnerabilities or you are not sure if that is the case please talk to us. See also: JSMVCOMFG, mustache-security, jPurify
  • Edit Oct. 2015 We provide a configuration flag called SAFE_FOR_TEMPLATES now. It aggressively scrubs {{ and <% expressions.
  • Edit May 2017 We are aware that there are crazy client-side frameworks that enable JavaScript execution from attributes where this should really not happen. And so should you be. We cannot and will not protect against these edge cases but we are happy to help evaluating together with you and check if you are affected and what to do if so. Please send a ticket our way if you aren't 100% sure.

Will DOMPurify help in my specific case?

We don't know that. But we are usually quite nice and you can just file a ticket and ask us :) Better ask and be sure than guess and be vulnerable.