cure53/dompurifyDOMPurify - un sanitiseur XSS uniquement DOM, ultra-rapide et ultra-tolérant, pour HTML, MathML et SVG. DOMPurify fonctionne avec une configuration sécurisée par défaut, mais offre de nombreuses options de configuration et des hooks. Démo :
# DOMPurify
[](https://www.npmjs.com/package/dompurify) [](https://github.com/cure53/DOMPurify/blob/main/LICENSE) [](https://www.npmjs.com/package/dompurify) [](https://github.com/cure53/DOMPurify/network/dependents)  [](https://cloudback.it)
[](https://www.bestpractices.dev/projects/12162) [](https://github.com/cure53/DOMPurify/actions/workflows/build-and-test.yml) [](https://scorecard.dev/viewer/?uri=github.com/cure53/DOMPurify) [](https://badge.socket.dev/npm/package/dompurify/latest) [](https://security.snyk.io/package/npm/dompurify)
DOMPurify est un assainisseur XSS dédié au DOM, ultra-rapide et extrêmement tolérant, pour HTML, MathML et SVG.
Il est également très simple à utiliser et à prendre en main. DOMPurify a été [lancé en février 2014](https://github.com/cure53/DOMPurify/commit/a630922616927373485e0e787ab19e73e3691b2b) et a, entre-temps, atteint la version **v3.4.17**.
DOMPurify s'exécute en JavaScript et fonctionne dans tous les navigateurs modernes (Safari (10+), Opera (15+), Edge, Firefox et Chrome - ainsi que presque tout ce qui utilise Blink, Gecko ou WebKit). Il ne casse pas sur MSIE ou d'autres navigateurs obsolètes. Il ne fait simplement rien.
**Notez que [DOMPurify v2.5.9](https://github.com/cure53/DOMPurify/releases/tag/2.5.9) est la dernière version prenant en charge MSIE. Pour les mises à jour de sécurité importantes compatibles avec MSIE, veuillez utiliser la [branche 2.x](https://github.com/cure53/DOMPurify/tree/2.x).**
Nos tests automatisés couvrent 9 combinaisons navigateur/OS sur les moteurs actuels (Chromium, Firefox et WebKit sous Ubuntu, macOS et Windows) à chaque push, et une matrice distincte relance la suite sur des instantanés de moteurs plus anciens (jusqu'à environ Chromium 110, Firefox 108 et WebKit 16.4, soit environ trois ans) afin que les régressions sur les navigateurs obsolètes soient également détectées. Nous exécutons aussi Node.js v20, v22, v24, v25 et v26 avec DOMPurify sur [jsdom](https://github.com/jsdom/jsdom). Les versions plus anciennes de Node sont également connues pour fonctionner, mais bon... aucune garantie.
DOMPurify est écrit par des spécialistes de la sécurité qui possèdent une vaste expérience des attaques web et du XSS. N'ayez crainte. Pour plus de détails, veuillez également lire nos [Objectifs de sécurité et modèle de menace](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model). Veuillez le lire. Vraiment. Et si vous aimez les détails macabres, la page [Classes d'attaques et historique des contournements](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) répertorie les astuces de mutation de parseur, d'espaces de noms, de clobbering et de templates contre lesquelles DOMPurify se défend.
Le projet DOMPurify a inspiré la création de l'[HTML Sanitizer API](https://wicg.github.io/sanitizer-api/#sanitizer), qui est déjà déployée dans [de nombreux navigateurs](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#browser_compatibility). La même capacité est désormais standardisée directement dans la [spécification WHATWG HTML](https://html.spec.whatwg.org/#html-sanitization).
## Table des matières
- [Que fait-il ?](#what-does-it-do)
- [Comment l'utiliser ?](#how-do-i-use-it)
- [Y a-t-il une démo ?](#is-there-a-demo)
- [Que faire si je trouve un bug de _sécurité_ ?](#what-if-i-find-a-security-bug)
- [Quelques exemples de purification, s'il vous plaît ?](#some-purification-samples-please)
- [Qu'est-ce qui est pris en charge ?](#what-is-supported)
- [Qu'en est-il des navigateurs anciens comme Internet Explorer ?](#what-about-legacy-browsers-like-internet-explorer)
- [Qu'en est-il de DOMPurify et des Trusted Types ?](#what-about-dompurify-and-trusted-types)
- [Puis-je configurer DOMPurify ?](#can-i-configure-dompurify)
- [Configuration persistante](#persistent-configuration)
- [Hooks](#hooks)
- [Configuration supprimée](#removed-configuration)
- [Intégration continue](#continuous-integration)
- [Liste de diffusion de sécurité](#security-mailing-list)
- [Qui a contribué ?](#who-contributed)
## Que fait-il ?
DOMPurify assainit le HTML et prévient les attaques XSS. Vous pouvez fournir à DOMPurify par exemple une chaîne remplie de HTML malveillant et il renverra une chaîne (sauf configuration contraire) contenant du HTML propre. DOMPurify supprimera tout ce qui contient du HTML dangereux et empêchera ainsi les attaques XSS et autres nuisances. Il est également extrêmement rapide. Nous utilisons les technologies fournies par le navigateur et les transformons en filtre XSS. Plus votre navigateur est rapide, plus DOMPurify sera rapide.
## Comment l'utiliser ?
C'est facile. Il suffit d'inclure DOMPurify sur votre site web.
### Utilisation de la version non minifiée (source-map disponible)
```html
<script type="text/javascript" src="dist/purify.js"></script>
```
### Utilisation de la version de production minifiée et testée (source-map disponible)
```html
<script type="text/javascript" src="dist/purify.min.js"></script>
```
Ensuite, vous pouvez assainir les chaînes en exécutant le code suivant :
```js
const clean = DOMPurify.sanitize(dirty);
```
Ou peut-être ceci, si vous aimez travailler avec Angular ou similaire :
```js
import DOMPurify from 'dompurify';
const clean = DOMPurify.sanitize('<b>hello there</b>');
```
Le HTML résultant peut être écrit dans un élément DOM à l'aide de `innerHTML` ou dans le DOM à l'aide de `document.write()`. Cela dépend entièrement de vous.
Notez que par défaut, nous autorisons HTML, SVG **et** MathML. Si vous n'avez besoin que de HTML, ce qui pourrait être un cas d'usage très courant, vous pouvez facilement le configurer également :
```js
const clean = DOMPurify.sanitize(dirty, { USE_PROFILES: { html: true } });
```
### Y a-t-il un potentiel de piège ?
Eh bien, veuillez noter que si vous assainissez _d'abord_ le HTML puis le modifiez _ensuite_, vous risquez facilement d'**annuler les effets de l'assainissement**. Si vous transmettez le balisage assaini à une autre bibliothèque _après_ l'assainissement, assurez-vous que la bibliothèque ne manipule pas le HTML de son propre chef. Consultez [Security Goals & Threat Model](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model) pour des recettes d'utilisation sûre et les balises/attributs qui méritent réflexion, ainsi que [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) pour comprendre pourquoi le post-traitement et le changement de contexte du balisage déjouent l'assainissement.
### Et si on passe un nœud DOM au lieu d'une chaîne ?
`DOMPurify.sanitize()` accepte également un nœud DOM (un `Element`, `DocumentFragment` ou `Document`). Depuis la version 3.4.14, ce chemin est renforcé pour les nœuds qui ne proviennent pas du parseur HTML : un nœud construit avec l'API DOM ou analysé comme XML/XHTML (par exemple via `DOMParser` avec `application/xhtml+xml` et `importNode()`) peut porter des noms d'attributs à casse préservée comme `ONERROR`, ou un élément rawtext comme `<style>` avec un élément enfant ou sa propre balise de fin à l'intérieur de son texte. Ces deux formes sont invisibles pour un assainisseur de chaînes car le parseur HTML ne peut jamais les construire, mais elles s'échappent lors du réanalyse. DOMPurify supprime désormais les attributs par leur nœud `Attr` exact et traite ces arbres de texte littéral comme non sûrs, de sorte que le mélange de contextes de document côté entrée est couvert. Il reste de votre responsabilité de ne pas mélanger les contextes côté _sortie_, voir le paragraphe ci-dessus.
### D'accord, c'est logique, passons à la suite
Après avoir assaini votre balisage, vous pouvez également consulter la propriété `DOMPurify.removed` et découvrir quels éléments et attributs ont été écartés. Veuillez **ne pas utiliser** cette propriété pour prendre des décisions critiques en matière de sécurité. Ce n'est qu'un petit assistant pour les esprits curieux.
### Exécuter DOMPurify sur le serveur
DOMPurify fonctionne techniquement aussi côté serveur avec Node.js. Notre support s'efforce de suivre le [cycle de publication de Node.js](https://nodejs.org/en/about/previous-releases).
Exécuter DOMPurify sur le serveur nécessite la présence d'un DOM, ce qui n'est probablement pas surprenant. Habituellement, [jsdom](https://github.com/jsdom/jsdom) est l'outil de choix et nous **recommandons fortement** d'utiliser la dernière version de _jsdom_.
Pourquoi ? Parce que les anciennes versions de _jsdom_ sont connues pour être boguées d'une manière qui entraîne du XSS _même si_ DOMPurify fait tout à 100 % correctement. Il existe des **vecteurs d'attaque connus** dans, par exemple, _jsdom v19.0.0_ qui sont corrigés dans _jsdom v20.0.0_ - et nous recommandons vraiment de maintenir _jsdom_ à jour pour cette raison.
Sachez également que des outils comme [happy-dom](https://github.com/capricorn86/happy-dom) existent mais **ne sont pas considérés comme sûrs** à ce stade. Combiner DOMPurify avec _happy-dom_ n'est actuellement pas recommandé et conduira probablement à du XSS. Pour comprendre pourquoi le DOM côté serveur que vous choisissez fait partie de votre base de confiance, consultez [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History).
Sur les environnements d'exécution où _jsdom_ ne peut pas s'exécuter, comme Cloudflare Workers ou Vercel Edge, [purify-edge](https://github.com/anzal1/purify-edge) est un projet tiers qui exécute un DOMPurify non modifié sur une fenêtre basée sur parse5. Notre suite de tests peut être exécutée contre lui avec `npm run test:purify-edge` comme vérification de compatibilité. Il n'est pas maintenu par nous, et une exécution réussie ne constitue ni une approbation ni une garantie de sécurité.
À part cela, vous pouvez utiliser DOMPurify sur le serveur. Probablement. Cela dépend vraiment de _jsdom_ ou du DOM que vous utilisez côté serveur. Si vous pouvez vivre avec cela, voici comment le faire fonctionner :
```bash
npm install dompurify
npm install jsdom
```
Pour _jsdom_ (veuillez utiliser une version à jour), cela devrait faire l'affaire :
```js
const createDOMPurify = require('dompurify');
const { JSDOM } = require('jsdom');
const window = new JSDOM('').window;
const DOMPurify = createDOMPurify(window);
const clean = DOMPurify.sanitize('<b>hello there</b>');
```
Ou même ceci, si vous préférez travailler avec des imports :
```js
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';
const window = new JSDOM('').window;
const purify = DOMPurify(window);
const clean = purify.sanitize('<b>hello there</b>');
```
Si vous rencontrez des problèmes pour le faire fonctionner dans votre configuration spécifique, envisagez de consulter l'excellent projet [isomorphic-dompurify](https://github.com/kkomelin/isomorphic-dompurify) qui résout de nombreux problèmes que les gens pourraient rencontrer.
```bash
npm install isomorphic-dompurify
```
```js
import DOMPurify from 'isomorphic-dompurify';
const clean = DOMPurify.sanitize('<s>hello</s>');
```
## Y a-t-il une démo ?
Bien sûr qu'il y a une démo ! [Jouez avec DOMPurify](https://cure53.de/purify)
## Que faire si je trouve une faille de sécurité ?
Tout d'abord, veuillez nous contacter immédiatement par [e-mail](mailto:[email protected]) afin que nous puissions travailler sur un correctif. [Clé PGP](https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0xC26C858090F70ADA)
De plus, vous êtes probablement éligible à une prime de bug ! Les sympathiques personnes de chez [Fastmail](https://www.fastmail.com/) utilisent DOMPurify pour leurs services et ont ajouté notre bibliothèque à leur périmètre de prime de bug. Donc, si vous trouvez un moyen de contourner ou d'affaiblir DOMPurify, veuillez également jeter un œil à leur site web et aux [informations sur la prime de bug](https://www.fastmail.com/about/bugbounty/).
## Quelques exemples de purification, s'il vous plaît ?
À quoi ressemble le balisage purifié ? Eh bien, [la démo](https://cure53.de/purify) le montre pour un grand nombre d'éléments malveillants. Mais montrons aussi quelques exemples plus petits !
```js
DOMPurify.sanitize(''); // becomes <img src="https://raw.githubusercontent.com/cure53/dompurify/main/x">
DOMPurify.sanitize('<svg><g/onload=alert(2)//<p>'); // becomes <svg><g></g></svg>
DOMPurify.sanitize('<p>abcdef</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>
```
Ce ne sont là que quelques exemples. Pour la taxonomie complète des classes d'attaques dont proviennent ces échantillons - mutation XSS, confusion d'espaces de noms, DOM clobbering, évasions rawtext, et plus encore - consultez [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History).
## Qu'est-ce qui est pris en charge ?
DOMPurify prend actuellement en charge HTML5, SVG et MathML. Par défaut, DOMPurify autorise le CSS et les attributs de données personnalisés HTML. DOMPurify prend également en charge le Shadow DOM - et assainit les modèles DOM de manière récursive. Cela ne couvre que les shadow roots ouverts : un shadow root fermé ne peut pas être lu depuis un script, donc DOMPurify ne peut ni voir ni assainir ce qu'il contient. Les chaînes de caractères ne sont pas concernées, car le parseur propre à DOMPurify ignore les shadow roots déclaratifs (`<template shadowrootmode>`), mais `setHTMLUnsafe()` et `Document.parseHTMLUnsafe()` ne le font pas : si vous analysez du balisage non fiable avec ces derniers puis passez les nœuds résultants à DOMPurify (`IN_PLACE`, `RETURN_DOM`, `RETURN_DOM_FRAGMENT`), tout shadow root fermé présent dans ce balisage est renvoyé non assaini. Passez plutôt le balisage non fiable à DOMPurify sous forme de chaîne de caractères. DOMPurify vous permet également d'assainir du HTML destiné à être utilisé avec l'API jQuery `$()` et `elm.html()` sans problème connu. Pour connaître l'ensemble exact des éléments et attributs autorisés par défaut, consultez la page wiki [Default TAGs & ATTRIBUTEs allow-list & blocklist](https://github.com/cure53/DOMPurify/wiki/Default-TAGs-ATTRIBUTEs-allow-list-&-blocklist).
## Qu'en est-il des navigateurs anciens comme Internet Explorer ?
DOMPurify ne fait absolument rien. Il renvoie simplement exactement la chaîne que vous lui avez fournie. DOMPurify expose une propriété appelée `isSupported`, qui vous indique s'il sera en mesure de faire son travail, afin que vous puissiez élaborer votre propre plan de secours.
## Qu'en est-il de DOMPurify et des Trusted Types ?
Dans la version 1.0.9, la prise en charge de l'[API Trusted Types](https://github.com/w3c/webappsec-trusted-types) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API)) a été ajoutée à DOMPurify.
Dans la version 2.0.0, un indicateur de configuration a été ajouté pour contrôler le comportement de DOMPurify à cet égard.
Lorsque `DOMPurify.sanitize` est utilisé dans un environnement où l'API Trusted Types est disponible et que `RETURN_TRUSTED_TYPE` est défini sur `true`, il tente de renvoyer une valeur `TrustedHTML` au lieu d'une chaîne (le comportement des options de configuration `RETURN_DOM` et `RETURN_DOM_FRAGMENT` ne change pas).
Notez que pour créer une politique dans `trustedTypes` à l'aide de DOMPurify, `RETURN_TRUSTED_TYPE: false` est requis, car `createHTML` attend une chaîne normale, et non un `TrustedHTML`. L'exemple ci-dessous le montre.
```js
window.trustedTypes.createPolicy('default', {
createHTML: (to_escape) =>
DOMPurify.sanitize(to_escape, { RETURN_TRUSTED_TYPE: false }),
});
```
Lorsqu'aucune `TRUSTED_TYPES_POLICY` n'est fournie, DOMPurify tente de créer sa propre politique Trusted Types interne nommée `dompurify`. Si votre page définit déjà sa propre politique accompagnée d'une CSP stricte (par exemple `trusted-types my-organization`) qui n'autorise pas une politique nommée `dompurify`, cette tentative est bloquée par le navigateur et génère un avertissement `TrustedTypes policy dompurify could not be created.` ainsi qu'une violation de CSP.
Pour empêcher DOMPurify de créer sa politique de repli interne, passez `TRUSTED_TYPES_POLICY: null`. C'est le bon choix lorsque vous appelez `DOMPurify.sanitize` depuis le `createHTML` de votre propre politique, et cela signifie que vous n'avez pas besoin d'ajouter `dompurify` à la liste d'autorisation `trusted-types` de votre CSP.
```js
window.trustedTypes.createPolicy('my-organization', {
createHTML: (input) =>
DOMPurify.sanitize(input, { TRUSTED_TYPES_POLICY: null }),
});
```
Ne transmettez **pas** votre propre politique d'enveloppement à DOMPurify en tant que `TRUSTED_TYPES_POLICY` (par exemple via `DOMPurify.setConfig({ TRUSTED_TYPES_POLICY: myPolicy })`) lorsque le `createHTML` de cette politique appelle déjà `DOMPurify.sanitize`. C'est circulaire par définition - la sanitisation appellerait la politique, qui sanitise en appelant à nouveau DOMPurify - et DOMPurify lèvera une `TypeError` descriptive pour empêcher la récursion infinie. Votre propre politique doit appeler DOMPurify ; DOMPurify ne doit pas être configuré pour appeler votre politique.
Si vous souhaitez que ce modèle de politique `default` soit appliqué automatiquement à l'ensemble d'une page - afin que chaque puits HTML soit sanitizé, y compris le code hérité, les widgets tiers et les milliers d'affectations `innerHTML` que vous ne pouvez pas facilement trouver ou réécrire - jetez un œil à [DOMFortify](https://github.com/cure53/DOMFortify). Il installe exactement une telle politique Trusted Types `default` adossée à DOMPurify et refuse catégoriquement les puits de script (`eval`, `script.src`, ...). C'est un projet délibérément distinct : DOMPurify reste un sanitizer ciblé, et DOMFortify gère la couche d'application à l'échelle du document qui est intentionnellement hors du périmètre de DOMPurify.
## Puis-je configurer DOMPurify ?
Oui. Les valeurs de configuration par défaut incluses sont déjà plutôt bonnes - mais vous pouvez bien sûr les remplacer. Consultez le dossier [`/demos`](https://github.com/cure53/DOMPurify/tree/main/demos) pour voir une série d'exemples sur la façon de [personnaliser DOMPurify](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this).
Avant d'élargir la liste d'autorisation (`ADD_TAGS`, `ADD_ATTR`, `CUSTOM_ELEMENT_HANDLING`, …) ou d'assouplir une valeur par défaut, il vaut la peine de parcourir les [balises et attributs sur lesquels il faut réfléchir à deux fois](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model#dangerous-tags-and-attributes-think-twice-before-allow-listing) - certains sont dangereux de manières peu évidentes.
### Paramètres généraux
```js
// 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.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_TEMPLATES: true });
// change how e.g. comments containing risky HTML characters are treated.
// be very careful, this setting should only be set to `false` if you really only handle
// HTML and nothing else, no SVG, MathML or the like.
// Otherwise, changing from `true` to `false` will lead to XSS in this or some other way.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_XML: false });
```
### Contrôler nos listes d'autorisation et de blocage
```js
// allow only <b> elements, very strict
const clean = DOMPurify.sanitize(dirty, { ALLOWED_TAGS: ['b'] });
// allow only <b> and <q> with style attributes
const clean = 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 together
const clean = DOMPurify.sanitize(dirty, { USE_PROFILES: { html: true } });
// allow all safe SVG elements and SVG Filters, no HTML or MathML
const clean = DOMPurify.sanitize(dirty, {
USE_PROFILES: { svg: true, svgFilters: true },
});
// allow all safe MathML elements and SVG, but no SVG Filters
const clean = DOMPurify.sanitize(dirty, {
USE_PROFILES: { mathMl: true, svg: true },
});
// change the default namespace from HTML to something different
const clean = DOMPurify.sanitize(dirty, {
NAMESPACE: 'http://www.w3.org/2000/svg',
});
// leave all safe HTML as it is and add <style> elements to block-list
const clean = DOMPurify.sanitize(dirty, { FORBID_TAGS: ['style'] });
// note: while <table> is allowed, <tbody> is always allowed too and cannot be
// forbidden - browsers insert it on their own, and forbidding it used to make
// sanitize() loop (see #365). Forbid 'table' as well to drop tables entirely.
// leave all safe HTML as it is and add style attributes to block-list
const clean = DOMPurify.sanitize(dirty, { FORBID_ATTR: ['style'] });
// extend the existing array of allowed tags and add <my-tag> to allow-list
const clean = DOMPurify.sanitize(dirty, { ADD_TAGS: ['my-tag'] });
// extend the existing array of allowed attributes and add my-attr to allow-list
const clean = DOMPurify.sanitize(dirty, { ADD_ATTR: ['my-attr'] });
// use functions to control which additional tags and attributes are allowed
const allowlist = {
one: ['attribute-one'],
two: ['attribute-two'],
};
const clean = DOMPurify.sanitize(
'<one attribute-one="1" attribute-two="2"></one><two attribute-one="1" attribute-two="2"></two>',
{
ADD_TAGS: (tagName) => {
return Object.keys(allowlist).includes(tagName);
},
ADD_ATTR: (attributeName, tagName) => {
return allowlist[tagName]?.includes(attributeName) || false;
},
}
); // <one attribute-one="1"></one><two attribute-two="2"></two>
// prohibit ARIA attributes, leave other safe HTML as is (default is true)
const clean = DOMPurify.sanitize(dirty, { ALLOW_ARIA_ATTR: false });
// prohibit HTML5 data attributes, leave other safe HTML as is (default is true)
const clean = DOMPurify.sanitize(dirty, { ALLOW_DATA_ATTR: false });
```
### Comportement de contrôle relatif aux Custom Elements
```js
// 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.
// When using a predicate function for attributeNameCheck, it can optionally receive the tagName as a second parameter
// for more granular control over which attributes are allowed for specific elements.
// The default values are very restrictive to prevent accidental XSS bypasses. Handle with great care!
const clean = DOMPurify.sanitize(
'<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
{
CUSTOM_ELEMENT_HANDLING: {
tagNameCheck: null, // no custom elements are allowed
attributeNameCheck: null, // default / standard attribute allow-list is used
allowCustomizedBuiltInElements: false, // no customized built-ins allowed
},
}
); // <div is=""></div>
const clean = 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: true, // customized built-ins are allowed
},
}
); // <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>
const clean = 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>
// Example with attributeNameCheck receiving tagName as a second parameter
const clean = DOMPurify.sanitize(
'<element-one attribute-one="1" attribute-two="2"></element-one><element-two attribute-one="1" attribute-two="2"></element-two>',
{
CUSTOM_ELEMENT_HANDLING: {
tagNameCheck: (tagName) => tagName.match(/^element-(one|two)$/),
attributeNameCheck: (attr, tagName) => {
if (tagName === 'element-one') {
return ['attribute-one'].includes(attr);
} else if (tagName === 'element-two') {
return ['attribute-two'].includes(attr);
} else {
return false;
}
},
allowCustomizedBuiltInElements: false,
},
}
); // <element-one attribute-one="1"></element-one><element-two attribute-two="2"></element-two>
```
### Contrôler le comportement relatif aux valeurs d'URI
```js
// extend the existing array of elements that can use Data URIs
const clean = 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)
const clean = DOMPurify.sanitize(dirty, { ADD_URI_SAFE_ATTR: ['my-attr'] });
```
### Contrôler les valeurs d'attributs autorisées
```js
// allow external protocol handlers in URL attributes (default is false, be careful, XSS risk)
// by default only http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
const clean = DOMPurify.sanitize(dirty, { ALLOW_UNKNOWN_PROTOCOLS: true });
// allow specific protocol handlers in URL attributes via regex (default is false, be careful, XSS risk)
// by default only (protocol-)relative URLs, http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
// Default RegExp: /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp|matrix):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;
// The example below extends the default with one additional scheme (sftp).
// Keep the pattern linear-time: it runs against attacker-controlled values.
const clean = DOMPurify.sanitize(dirty, {
ALLOWED_URI_REGEXP:
/^(?:(?:(?:f|ht)tps?|sftp|mailto|tel|callto|sms|cid|xmpp|matrix):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i,
});
```
### Influencer le type de retour
```js
// return a DOM HTMLBodyElement instead of an HTML string (default is false)
const clean = DOMPurify.sanitize(dirty, { RETURN_DOM: true });
// return a DOM DocumentFragment instead of an HTML string (default is false)
const clean = DOMPurify.sanitize(dirty, { RETURN_DOM_FRAGMENT: true });
// use the RETURN_TRUSTED_TYPE flag to turn on Trusted Types support if available
const clean = DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true }); // will return a TrustedHTML object instead of a string if possible
// use a provided Trusted Types policy
const clean = DOMPurify.sanitize(dirty, {
// supplied policy must define createHTML and createScriptURL
TRUSTED_TYPES_POLICY: trustedTypes.createPolicy('dompurify', {
createHTML(s) {
return s;
},
createScriptURL(s) {
return s;
},
}),
});
// opt out of DOMPurify's internal `dompurify` Trusted Types policy entirely
// (useful when your CSP `trusted-types` allowlist does not include `dompurify`)
const clean = DOMPurify.sanitize(dirty, { TRUSTED_TYPES_POLICY: null });
```
### Influencer la façon dont nous assainissons
```js
// return entire document including <html> tags (default is false)
const clean = DOMPurify.sanitize(dirty, { WHOLE_DOCUMENT: true });
// disable DOM Clobbering protection on output (default is true, handle with care, minor XSS risks here)
const clean = DOMPurify.sanitize(dirty, { SANITIZE_DOM: false });
// enforce strict DOM Clobbering protection via namespace isolation (default is false)
// when enabled, isolates the namespace of named properties (i.e., `id` and `name` attributes)
// from JS variables by prefixing them with the string `user-content-`
const clean = DOMPurify.sanitize(dirty, { SANITIZE_NAMED_PROPS: true });
// keep an element's content when the element is removed (default is true)
const clean = 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)
const clean = DOMPurify.sanitize(dirty, { FORCE_BODY: true });
// remove all <a> elements under <p> elements that are removed
const clean = DOMPurify.sanitize(dirty, {
FORBID_CONTENTS: ['a'],
FORBID_TAGS: ['p'],
});
// extend the default FORBID_CONTENTS list to also remove <a> elements under <p> elements
const clean = DOMPurify.sanitize(dirty, {
ADD_FORBID_CONTENTS: ['a'],
FORBID_TAGS: ['p'],
});
// change the parser type so sanitized data is treated as XML and not as HTML, which is the default
const clean = DOMPurify.sanitize(dirty, {
PARSER_MEDIA_TYPE: 'application/xhtml+xml',
});
```
### Influencer les endroits où nous assainissons
```js
// use the IN_PLACE mode to sanitize a node "in place", which is much faster depending on how you use DOMPurify
const dirty = document.createElement('a');
dirty.setAttribute('href', 'javascript:alert(1)');
const clean = DOMPurify.sanitize(dirty, { IN_PLACE: true }); // see https://github.com/cure53/DOMPurify/issues/288 for more info
```
Quelques points à connaître concernant `IN_PLACE` :
- Le nœud racine que vous passez doit lui-même être une balise autorisée et ne doit pas être victime de DOM-clobbering (par exemple un `<form>` avec un enfant nommé `nodeName` ou `ownerDocument`). Si c'est le cas, DOMPurify dépouille le sous-arbre de la racine de tout attribut non autorisé, puis lève une `TypeError`, de sorte qu'une racine rejetée n'est jamais renvoyée armée.
- Si quoi que ce soit lève une exception en cours de parcours, la même neutralisation fail-closed s'exécute sur la racine et sur chaque sous-arbre déjà détaché pendant ce parcours avant que l'erreur ne se propage.
---
[Read more](https://github.com/cure53/dompurify)