What does it do?

How do I use it?

Using the unminified development version

<scripttype="text/javascript"src="src/purify.js"></script>

Using the minified and tested production version (source-map available)

<scripttype="text/javascript"src="dist/purify.min.js"></script>

letclean=DOMPurify.sanitize(dirty);

letclean=DOMPurify.sanitize(dirty,{USE_PROFILES:{html:true}});

Is there any foot-gun potential?

Okay, makes sense, let's move on

importDOMPurifyfrom'dompurify';varclean=DOMPurify.sanitize(dirty);

npm install dompurify

constcreateDOMPurify=require('dompurify');const{JSDOM}=require('jsdom');constwindow=newJSDOM('').window;constDOMPurify=createDOMPurify(window);constclean=DOMPurify.sanitize(dirty);

constcreateDOMPurify=require('dompurify');constjsdom=require('jsdom').jsdom;constwindow=jsdom('').defaultView;constDOMPurify=createDOMPurify(window);constclean=DOMPurify.sanitize(dirty);

Is there a demo?

What if I find asecurity bug?

Some purification samples please?

DOMPurify.sanitize('<img src=x onerror=alert(1)//>');// becomes <img src="x">DOMPurify.sanitize('<svg><g/onload=alert(2)//<p>');// becomes <svg><g></g></svg>DOMPurify.sanitize('<p>abc<iframe//src=jAva&Tab;script:alert(3)>def</p>');// becomes <p>abc</p>DOMPurify.sanitize('<math><mi//xlink:href="data:x,<script>alert(4)</script>">');// becomes <math><mi></mi></math>DOMPurify.sanitize('<TABLE><tr><td>HELLO</tr></TABL>');// becomes <table><tbody><tr><td>HELLO</td></tr></tbody></table>DOMPurify.sanitize('<UL><li><A HREF=//google.com>click</UL>');// becomes <ul><li><a href="//google.com">click</a></li></ul>

What is supported?

What about older browsers like MSIE8?

What about DOMPurify and Trusted Types?

Can I configure DOMPurify?

/** * General settings */// strip {{ ... }} and <% ... %> to make output safe for template systems// be careful please, this mode is not recommended for production usage.// allowing template parsing in user-controlled HTML is not advised at all.// only use this mode if there is really no alternative.varclean=DOMPurify.sanitize(dirty,{SAFE_FOR_TEMPLATES:true});/** * Control our allow-lists and block-lists */// allow only <b> elements, very strictvarclean=DOMPurify.sanitize(dirty,{ALLOWED_TAGS:['b']});// allow only <b> and <q> with style attributesvarclean=DOMPurify.sanitize(dirty,{ALLOWED_TAGS:['b','q'],ALLOWED_ATTR:['style']});// allow all safe HTML elements but neither SVG nor MathML// note that the USE_PROFILES setting will override the ALLOWED_TAGS setting// so don't use them togethervarclean=DOMPurify.sanitize(dirty,{USE_PROFILES:{html:true}});// allow all safe SVG elements and SVG Filters, no HTML or MathMLvarclean=DOMPurify.sanitize(dirty,{USE_PROFILES:{svg:true,svgFilters:true}});// allow all safe MathML elements and SVG, but no SVG Filtersvarclean=DOMPurify.sanitize(dirty,{USE_PROFILES:{mathMl:true,svg:true}});// change the default namespace from HTML to something differentvarclean=DOMPurify.sanitize(dirty,{NAMESPACE:'http://www.w3.org/2000/svg'});// leave all safe HTML as it is and add <style> elements to block-listvarclean=DOMPurify.sanitize(dirty,{FORBID_TAGS:['style']});// leave all safe HTML as it is and add style attributes to block-listvarclean=DOMPurify.sanitize(dirty,{FORBID_ATTR:['style']});// extend the existing array of allowed tags and add <my-tag> to allow-listvarclean=DOMPurify.sanitize(dirty,{ADD_TAGS:['my-tag']});// extend the existing array of allowed attributes and add my-attr to allow-listvarclean=DOMPurify.sanitize(dirty,{ADD_ATTR:['my-attr']});// prohibit ARIA attributes, leave other safe HTML as is (default is true)varclean=DOMPurify.sanitize(dirty,{ALLOW_ARIA_ATTR:false});// prohibit HTML5 data attributes, leave other safe HTML as is (default is true)varclean=DOMPurify.sanitize(dirty,{ALLOW_DATA_ATTR:false});/** * Control behavior relating to Custom Elements */// DOMPurify allows to define rules for Custom Elements. When using the CUSTOM_ELEMENT_HANDLING// literal, it is possible to define exactly what elements you wish to allow (by default, none are allowed).//// The same goes for their attributes. By default, the built-in or configured allow.list is used.//// You can use a RegExp literal to specify what is allowed or a predicate, examples for both can be seen below.// The default values are very restrictive to prevent accidental XSS bypasses. Handle with great care!varclean=DOMPurify.sanitize('<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',{CUSTOM_ELEMENT_HANDLING:{tagNameCheck:null,// no custom elements are allowedattributeNameCheck:null,// default / standard attribute allow-list is usedallowCustomizedBuiltInElements:false,// no customized built-ins allowed},});// <div is=""></div>varclean=DOMPurify.sanitize('<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',{CUSTOM_ELEMENT_HANDLING:{tagNameCheck:/^foo-/,// allow all tags starting with "foo-"attributeNameCheck:/baz/,// allow all attributes containing "baz"allowCustomizedBuiltInElements:false,// customized built-ins are allowed},});// <foo-bar baz="foobar"></foo-bar><div is=""></div>varclean=DOMPurify.sanitize('<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',{CUSTOM_ELEMENT_HANDLING:{tagNameCheck:(tagName)=>tagName.match(/^foo-/),// allow all tags starting with "foo-"attributeNameCheck:(attr)=>attr.match(/baz/),// allow all containing "baz"allowCustomizedBuiltInElements:true,// allow customized built-ins},});// <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>/** * Control behavior relating to URI values */// extend the existing array of elements that can use Data URIsvarclean=DOMPurify.sanitize(dirty,{ADD_DATA_URI_TAGS:['a','area']});// extend the existing array of elements that are safe for URI-like values (be careful, XSS risk)varclean=DOMPurify.sanitize(dirty,{ADD_URI_SAFE_ATTR:['my-attr']});/** * Control permitted attribute values */// allow external protocol handlers in URL attributes (default is false, be careful, XSS risk)// by default only http, https, ftp, ftps, tel, mailto, callto, cid and xmpp are allowed.varclean=DOMPurify.sanitize(dirty,{ALLOW_UNKNOWN_PROTOCOLS:true});// allow specific protocols handlers in URL attributes via regex (default is false, be careful, XSS risk)// by default only http, https, ftp, ftps, tel, mailto, callto, cid and xmpp are allowed.// Default RegExp: /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|cid|xmpp):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;varclean=DOMPurify.sanitize(dirty,{ALLOWED_URI_REGEXP:/^(?:(?:(?:f|ht)tps?|mailto|tel|callto|cid|xmpp|xxx):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;});/** * Influence the return-type */// return a DOM HTMLBodyElement instead of an HTML string (default is false)varclean=DOMPurify.sanitize(dirty,{RETURN_DOM:true});// return a DOM DocumentFragment instead of an HTML string (default is false)varclean=DOMPurify.sanitize(dirty,{RETURN_DOM_FRAGMENT:true});// use the RETURN_TRUSTED_TYPE flag to turn on Trusted Types support if availablevarclean=DOMPurify.sanitize(dirty,{RETURN_TRUSTED_TYPE:true});// will return a TrustedHTML object instead of a string if possible/** * Influence how we sanitize */// return entire document including <html> tags (default is false)varclean=DOMPurify.sanitize(dirty,{WHOLE_DOCUMENT:true});// disable DOM Clobbering protection on output (default is true, handle with care, minor XSS risks here)varclean=DOMPurify.sanitize(dirty,{SANITIZE_DOM:false});// keep an element's content when the element is removed (default is true)varclean=DOMPurify.sanitize(dirty,{KEEP_CONTENT:false});// glue elements like style, script or others to document.body and prevent unintuitive browser behavior in several edge-cases (default is false)varclean=DOMPurify.sanitize(dirty,{FORCE_BODY:true});// change the parser type so sanitized data is treated as XML and not as HTML, which is the defaultvarclean=DOMPurify.sanitize(dirty,{PARSER_MEDIA_TYPE:'application/xhtml+xml'});/** * Influence where we sanitize */// use the IN_PLACE mode to sanitize a node "in place", which is much faster depending on how you use DOMPurifyvardirty=document.createElement('a');dirty.setAttribute('href','#"auto">There is evenmore examples here, showing how you can run, customize and configure DOMPurify to fit your needs.
Persistent Configuration
Instead of repeatedly passing the same configuration toDOMPurify.sanitize, you can use theDOMPurify.setConfig method. Your configuration will persist until your next call toDOMPurify.setConfig, or until you invokeDOMPurify.clearConfig to reset it. Remember that there is only one active configuration, which means once it is set, all extra configuration parameters passed toDOMPurify.sanitize are ignored.
Hooks
DOMPurify allows you to augment its functionality by attaching one or more functions with theDOMPurify.addHook method to one of the following hooks:
beforeSanitizeElements
uponSanitizeElement (No 's' - called for every element)
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 theMentalJS hook demo to see how the API can be used nicely.
Example:
DOMPurify.addHook('beforeSanitizeElements',function(currentNode,hookEvent,config){// Do something with the current node and return it// You can also mutate hookEvent (i.e. set hookEvent.forceKeepAttr = true)returncurrentNode;});
Continuous Integration
We are currently using Github Actions in combination with BrowserStack. This gives us the possibility to confirm for each and every commit that all is going according to plan in all supported browsers. Check out the build logs here:https://github.com/cure53/DOMPurify/actions
You can further run local tests by executingnpm test. The tests work fine with Node.js v0.6.2 and jsdom@8.5.0.
All relevant commits will be signed with the key0x24BB6BF4 for additional security (since 8th of April 2016).
Development and contributing
Installation (npm i)
We supportnpm officially. GitHub Actions workflow is configured to install dependencies usingnpm. When using deprected version ofnpm we can not fully ensure the versions of installed dependencies which might lead to unanticipated problems.
Scripts
We rely on npm run-scripts for integrating with our tooling infrastructure. We use ESLint as a pre-commit hook to ensure code consistency. Moreover, to ease formatting we useprettier while building the/dist assets happens throughrollup.
These are our npm scripts:
npm run dev to start building while watching sources for changes
npm run test to run our test suite via jsdom and karma
test:jsdom to only run tests through jsdom
test:karma to only run tests through karma
npm run lint to lint the sources using ESLint (via xo)
npm run format to format our sources using prettier to ease to pass ESLint
npm run build to build our distribution assets minified and unminified as a UMD module
npm run build:umd to only build an unminified UMD module
npm run build:umd:min to only build a minified UMD module
Note: all run scripts triggered vianpm run <script>.
There are more npm scripts but they are mainly to integrate with CI or are meant to be "private" for instance to amend build distribution files with every commit.
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
Feature releases will not be announced to this list.
Who contributed?
Many people helped and help DOMPurify become what it is and need to be acknowledged here!
JGraph 💸,Sentry 💸,jarrodldavis 💸,GrantGryczan,Lowdefy 💸,granlem,oreoshake,dcramer 💸,tdeekens ❤️,peernohell ❤️,is2ei,franktopel,NateScarlet,neilj,fhemberger,Joris-van-der-Wel,ydaniv,terjanq,filedescriptor,ConradIrwin,gibson042,choumx,0xSobky,styfle,koto,tlau88,strugee,oparoz,mathiasbynens,edg2s,dnkolegov,dhardtke,wirehead,thorn0,styu,mozfreddyb,mikesamuel,jorangreef,jimmyhchan,jameydeorio,jameskraus,hyderali,hansottowirtz,hackvertor,freddyb,flavorjones,djfarrelly,devd,camerondunford,buu700,buildog,alabiaga,Vector919,Robbert,GreLI,FuzzySockets,ArtemBernatskyy,@garethheyes,@shafigullin,@mmrupp,@irsdl,ShikariSenpai,ansjdnakjdnajkd,@asutherland,@mathias,@cgvwzq,@robbertatwork,@giutro,@CmdEngineer_,@avr4mit and especially@securitymb ❤️ &@masatokinugawa ❤️
Testing powered by

And last but not least, thanks toBrowserStack Open-Source Program for supporting this project with their services for free and delivering excellent, dedicated and very professional support on top of that.