DOMPurify
DOMPurify is a DOM-only, super-fast, uber-tolerant XSS sanitizer for HTML, MathML and SVG. It's written in JavaScript and works in all modern browsers (Safari, Opera (15+), Internet Explorer (10+), Spartan, Firefox and Chrome - as well as almost anything else using Blink or WebKit). It doesn't break on IE6 or other legacy browsers. It simply does nothing there.
DOMPurify is written by security people who have vast background in web attacks and XSS. Fear not. For more details please also read about our Security Goals & Threat Model
What does it do?
DOMPurify sanitizes HTML and prevents XSS attacks. You can feed DOMPurify with string full of dirty HTML and it will return a string with clean HTML. DOMPurify will strip out everything that contains dangerous HTML and thereby prevent XSS attacks and other nastiness. It's also damn bloody fast. We use the technologies the browser provides and turn them into an XSS filter. The faster your browser, the faster DOMPurify will be.
How do I use it?
It's easy. Just include DOMPurify on your website.
<script type="text/javascript" src="purify.js"></script>
Afterwards you can sanitize strings by executing the following code:
var clean = DOMPurify.sanitize(dirty);
If you're using an AMD module loader like Require.js, you can load this script asynchronously as well:
require(['dompurify'], function(DOMPurify) {
var clean = DOMPurify.sanitize(dirty);
});
You can also grab the files straight from NPM:
(Note: DOMPurify doesn't work in Node.js yet, but runs fine with Browserify.)
npm install dompurify
var DOMPurify = require('dompurify');
var clean = DOMPurify.sanitize(dirty);
Is there a demo?
Of course there is a demo! Play with DOMPurify
Some samples please?
How does purified markup look like? Well, the demo shows it for a big bunch of nasty elements. But let's also show some smaller examples!
DOMPurify.sanitize('<img src=x onerror=alert(1)//>');
DOMPurify.sanitize('<svg><g/onload=alert(2)//<p>');
DOMPurify.sanitize('<p>abc<iframe/\/src=jAva	script:alert(3)>def');
DOMPurify.sanitize('<math><mi//xlink:href="data:x,<script>alert(4)</script>">');
DOMPurify.sanitize('<TABLE><tr><td>HELLO</tr></TABL>');
DOMPurify.sanitize('<UL><li><A HREF=//google.com>click</UL>');
What is supported?
DOMPurify currently supports HTML5, SVG and MathML. DOMPurify per default allows CSS, HTML custom data attributes. DOMPurify also supports the Shadow DOM - and sanitizes DOM templates recursively. DOMPurify also allows you to sanitize HTML for being used with the jQuery $()
and elm.html()
methods.
Can I configure it?
Yes. The included default configuration values are pretty good already - but you can of course override them. Check out the /demos
folder to see a bunch of examples on how you can customize DOMPurify.
var clean = DOMPurify.sanitize(dirty, {ALLOWED_TAGS: ['b']});
var clean = DOMPurify.sanitize(dirty, {ALLOWED_TAGS: ['b', 'q'], ALLOWED_ATTR: ['style']});
var clean = DOMPurify.sanitize(dirty, {FORBID_TAGS: ['style']});
var clean = DOMPurify.sanitize(dirty, {FORBID_ATTR: ['style']});
var clean = DOMPurify.sanitize(dirty, {ADD_TAGS: ['my-tag']});
var clean = DOMPurify.sanitize(dirty, {ADD_ATTR: ['my-attr']});
var clean = DOMPurify.sanitize(dirty, {ALLOW_DATA_ATTR: false});
var clean = DOMPurify.sanitize(dirty, {RETURN_DOM: true});
var clean = DOMPurify.sanitize(dirty, {WHOLE_DOCUMENT: true});
var clean = DOMPurify.sanitize(dirty, {SAFE_FOR_JQUERY: true});
var clean = DOMPurify.sanitize(dirty, {SANITIZE_DOM: false});
var clean = DOMPurify.sanitize(dirty, {KEEP_CONTENT: false});
Hooks
DOMPurify allows you to augment its functionality by attaching one or more functions with the DOMPurify.addHook
method to one of the following hooks:
beforeSanitizeElements
uponSanitizeElement
afterSanitizeElements
beforeSanitizeAttributes
uponSanitizeAttribute
afterSanitizeAttributes
beforeSanitizeShadowDOM
uponSanitizeShadowNode
afterSanitizeShadowDOM
It passes the currently processed DOM node, when needed a literal with verified node and attribute data and the DOMPurify configuration to the callback. Check out the MentalJS hook demo to see how the API can be used nicely.
Example:
DOMPurify.addHook('beforeSanitizeElements', function(currentNode, data, config) {
return currentNode;
});
Unit tests
To run the test suite, you need Node.js first. Install the dependencies with npm install
, then start the test server with npm test
. You can run the tests in your browser from http://localhost:8000/test/.
Security Mailing List
We maintain a mailing list that notifies whenever a security-critical release of DOMPurify was published. This means, if someone found a bypass and we fixed it with a release (which always happens when a bypass was found) a mail will go out to that list. This usually happens within minutes or few hours after learning about a bypass. The list can be subscribed to here:
https://lists.ruhr-uni-bochum.de/mailman/listinfo/dompurify-security
What's on the road-map?
We recently implemented a Hook-API allowing developers to create their own DOMPurify plugins and customize its functionality without changing the core. Thus, we are looking forward for plugins and extensions - pull requests are welcome!
Who contributed?
Several people need to be listed here! @garethheyes for invaluable help, @shafigullin for breaking the library multiple times and thereby strengthening it, @mmrupp and @irsdl for doing the same.
Big thanks also go to @asutherland, @mathias, @cgvwzq, @robbertatwork, @giutro and @fhemberger! Further, thanks @neilj for his code review and countless small optimizations, fixes and beautifications.