cure53/dompurifyDOMPurify - um sanitizador de XSS somente DOM, super-rápido e supertolerante para HTML, MathML e SVG. DOMPurify funciona com um padrão seguro, mas oferece muita configurabilidade e hooks. Demonstração:
# 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 é um sanitizador XSS exclusivo para DOM, super-rápido e extremamente tolerante, para HTML, MathML e SVG.
Também é muito simples de usar e começar. O DOMPurify foi [iniciado em fevereiro de 2014](https://github.com/cure53/DOMPurify/commit/a630922616927373485e0e787ab19e73e3691b2b) e, entretanto, chegou à versão **v3.4.17**.
O DOMPurify é executado como JavaScript e funciona em todos os navegadores modernos (Safari (10+), Opera (15+), Edge, Firefox e Chrome - assim como quase qualquer outro que use Blink, Gecko ou WebKit). Ele não quebra no MSIE ou em outros navegadores legados. Simplesmente não faz nada.
**Observe que o [DOMPurify v2.5.9](https://github.com/cure53/DOMPurify/releases/tag/2.5.9) é a versão mais recente com suporte ao MSIE. Para atualizações de segurança importantes compatíveis com o MSIE, use o [branch 2.x](https://github.com/cure53/DOMPurify/tree/2.x).**
Nossos testes automatizados cobrem 9 combinações de navegador/SO nos motores atuais (Chromium, Firefox e WebKit em Ubuntu, macOS e Windows) a cada push, e uma matriz separada reexecuta a suíte em snapshots de motores mais antigos (até aproximadamente Chromium 110, Firefox 108 e WebKit 16.4, cerca de três anos atrás) para que regressões em navegadores desatualizados também sejam detectadas. Também executamos Node.js v20, v22, v24, v25 e v26 com DOMPurify no [jsdom](https://github.com/jsdom/jsdom). Versões mais antigas do Node também são conhecidas por funcionar, mas, bem... sem garantias.
O DOMPurify é escrito por pessoas de segurança que têm vasta experiência em ataques web e XSS. Não tema. Para mais detalhes, leia também sobre nossos [Objetivos de Segurança e Modelo de Ameaças](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model). Por favor, leia. Sério mesmo. E se você gosta dos detalhes sangrentos, a página [Classes de Ataque e Histórico de Bypass](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) cataloga os truques de mutação de parser, namespace, clobbering e template contra os quais o DOMPurify se defende.
O projeto DOMPurify inspirou a criação da [HTML Sanitizer API](https://wicg.github.io/sanitizer-api/#sanitizer), que já está sendo distribuída em [muitos navegadores](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#browser_compatibility). A mesma capacidade agora está sendo padronizada diretamente na [especificação WHATWG HTML](https://html.spec.whatwg.org/#html-sanitization).
## Índice
- [O que ele faz?](#what-does-it-do)
- [Como eu o uso?](#how-do-i-use-it)
- [Existe uma demonstração?](#is-there-a-demo)
- [E se eu encontrar um bug de _segurança_?](#what-if-i-find-a-security-bug)
- [Alguns exemplos de sanitização, por favor?](#some-purification-samples-please)
- [O que é suportado?](#what-is-supported)
- [E quanto a navegadores legados como o Internet Explorer?](#what-about-legacy-browsers-like-internet-explorer)
- [E quanto ao DOMPurify e Trusted Types?](#what-about-dompurify-and-trusted-types)
- [Posso configurar o DOMPurify?](#can-i-configure-dompurify)
- [Configuração Persistente](#persistent-configuration)
- [Hooks](#hooks)
- [Configuração Removida](#removed-configuration)
- [Integração Contínua](#continuous-integration)
- [Lista de Discussão de Segurança](#security-mailing-list)
- [Quem contribuiu?](#who-contributed)
## O que ele faz?
O DOMPurify sanitiza HTML e previne ataques XSS. Você pode fornecer ao DOMPurify, por exemplo, uma string cheia de HTML sujo e ele retornará uma string (a menos que configurado de outra forma) com HTML limpo. O DOMPurify removerá tudo o que contiver HTML perigoso e, assim, prevenirá ataques XSS e outras ameaças. Também é incrivelmente rápido. Usamos as tecnologias que o navegador fornece e as transformamos em um filtro XSS. Quanto mais rápido for o seu navegador, mais rápido será o DOMPurify.
## Como eu o uso?
É fácil. Basta incluir o DOMPurify no seu site.
### Usando a versão não minificada (source-map disponível)
```html
<script type="text/javascript" src="dist/purify.js"></script>
```
### Usando a versão de produção minificada e testada (source-map disponível)
```html
<script type="text/javascript" src="dist/purify.min.js"></script>
```
Em seguida, você pode sanitizar strings executando o seguinte código:
```js
const clean = DOMPurify.sanitize(dirty);
```
Ou talvez isto, se você adora trabalhar com Angular ou similar:
```js
import DOMPurify from 'dompurify';
const clean = DOMPurify.sanitize('<b>hello there</b>');
```
O HTML resultante pode ser escrito em um elemento DOM usando `innerHTML` ou no DOM usando `document.write()`. Isso depende inteiramente de você.
Observe que, por padrão, permitimos HTML, SVG **e** MathML. Se você precisa apenas de HTML, o que pode ser um caso de uso muito comum, você também pode configurar isso facilmente:
```js
const clean = DOMPurify.sanitize(dirty, { USE_PROFILES: { html: true } });
```
### Existe algum potencial de foot-gun?
Bem, observe que, se você _primeiro_ sanitizar o HTML e depois modificá-lo _posteriormente_, você pode facilmente **anular os efeitos da sanitização**. Se você alimentar a marcação sanitizada com outra biblioteca _após_ a sanitização, certifique-se de que a biblioteca não mexe no HTML por conta própria. Consulte [Security Goals & Threat Model](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model) para receitas de uso seguro e as tags/atributos que merecem uma segunda reflexão, e [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) para entender por que o pós-processamento e a alteração do contexto da marcação derrotam a sanitização.
### E quanto a passar um nó DOM em vez de uma string?
`DOMPurify.sanitize()` também aceita um nó DOM (um `Element`, `DocumentFragment` ou `Document`). Desde a 3.4.14, esse caminho é reforçado para nós que não vieram do parser HTML: um nó construído com a API DOM ou analisado como XML/XHTML (por exemplo, via `DOMParser` com `application/xhtml+xml` e `importNode()`) pode carregar nomes de atributos com maiúsculas preservadas, como `ONERROR`, ou um elemento rawtext como `<style>` com um elemento filho ou sua própria tag de fechamento dentro do seu texto. Ambas as formas são invisíveis para um sanitizador de strings porque o parser HTML nunca consegue construí-las, mas elas escapam na reanálise. O DOMPurify agora remove atributos pelo seu nó `Attr` exato e trata essas árvores de texto literal como inseguras, de modo que a mistura de contextos de documento no lado da entrada está coberta. Continua sendo sua responsabilidade não misturar contextos no lado da _saída_, veja o parágrafo acima.
### Ok, faz sentido, vamos em frente
Após sanitizar sua marcação, você também pode dar uma olhada na propriedade `DOMPurify.removed` e descobrir quais elementos e atributos foram descartados. Por favor, **não use** esta propriedade para tomar decisões críticas de segurança. É apenas um pequeno auxiliar para mentes curiosas.
### Executando o DOMPurify no servidor
Tecnicamente, o DOMPurify também funciona no lado do servidor com Node.js. Nosso suporte se esforça para seguir o [ciclo de lançamentos do Node.js](https://nodejs.org/en/about/previous-releases).
Executar o DOMPurify no servidor exige que um DOM esteja presente, o que provavelmente não é surpresa. Normalmente, o [jsdom](https://github.com/jsdom/jsdom) é a ferramenta de escolha e **recomendamos fortemente** usar a versão mais recente do _jsdom_.
Por quê? Porque versões mais antigas do _jsdom_ são conhecidas por ter bugs que resultam em XSS _mesmo que_ o DOMPurify faça tudo 100% corretamente. Existem **vetores de ataque conhecidos** em, por exemplo, _jsdom v19.0.0_ que são corrigidos em _jsdom v20.0.0_ - e realmente recomendamos manter o _jsdom_ atualizado por causa disso.
Esteja também ciente de que ferramentas como [happy-dom](https://github.com/capricorn86/happy-dom) existem, mas **não são consideradas seguras** neste momento. Combinar o DOMPurify com o _happy-dom_ atualmente não é recomendado e provavelmente levará a XSS. Para entender por que o DOM do lado do servidor que você escolhe faz parte da sua base de computação confiável, consulte [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History).
Em runtimes onde o _jsdom_ não consegue rodar, como Cloudflare Workers ou Vercel Edge, o [purify-edge](https://github.com/anzal1/purify-edge) é um projeto de terceiros que executa um DOMPurify sem modificações em uma window baseada em parse5. Nossa suíte de testes pode ser executada contra ele com `npm run test:purify-edge` como verificação de compatibilidade. Ele não é mantido por nós, e uma execução bem-sucedida não é nem um endosso nem uma garantia de segurança.
Fora isso, você pode usar o DOMPurify no servidor. Provavelmente. Isso realmente depende do _jsdom_ ou de qualquer DOM que você utilize no lado do servidor. Se você puder conviver com isso, é assim que você o faz funcionar:
```bash
npm install dompurify
npm install jsdom
```
Para o _jsdom_ (use uma versão atualizada), isto deve resolver:
```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 mesmo isto, se preferir trabalhar com 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>');
```
Se você tiver problemas para fazê-lo funcionar na sua configuração específica, considere dar uma olhada no incrível projeto [isomorphic-dompurify](https://github.com/kkomelin/isomorphic-dompurify), que resolve muitos problemas que as pessoas podem encontrar.
```bash
npm install isomorphic-dompurify
```
```js
import DOMPurify from 'isomorphic-dompurify';
const clean = DOMPurify.sanitize('<s>hello</s>');
```
## Existe uma demonstração?
Claro que existe uma demonstração! [Experimente o DOMPurify](https://cure53.de/purify)
## E se eu encontrar uma falha de segurança?
Em primeiro lugar, entre em contato conosco imediatamente por [e-mail](mailto:[email protected]) para que possamos trabalhar em uma correção. [Chave PGP](https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0xC26C858090F70ADA)
Além disso, você provavelmente se qualifica para um bug bounty! O pessoal da [Fastmail](https://www.fastmail.com/) usa o DOMPurify em seus serviços e adicionou nossa biblioteca ao escopo do seu bug bounty. Então, se você encontrar uma forma de contornar ou enfraquecer o DOMPurify, dê também uma olhada no site deles e nas [informações sobre o bug bounty](https://www.fastmail.com/about/bugbounty/).
## Alguns exemplos de sanitização, por favor?
Como fica a marcação sanitizada? Bem, [a demonstração](https://cure53.de/purify) mostra isso para um grande conjunto de elementos maliciosos. Mas vamos também mostrar alguns exemplos menores!
```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>
```
Estes são apenas uma amostra. Para a taxonomia completa das classes de ataque das quais estas amostras provêm - mutation XSS, confusão de namespace, DOM clobbering, rawtext breakouts e mais - consulte [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History).
## O que é suportado?
O DOMPurify atualmente suporta HTML5, SVG e MathML. Por padrão, o DOMPurify permite CSS e atributos de dados personalizados de HTML. O DOMPurify também suporta o Shadow DOM - e sanitiza templates DOM recursivamente. Isso abrange apenas shadow roots abertos: um shadow root fechado não pode ser lido a partir de script, portanto o DOMPurify não consegue ver nem sanitizar o que está dentro dele. Strings não são afetadas, porque o próprio parser do DOMPurify ignora shadow roots declarativos (`<template shadowrootmode>`), mas `setHTMLUnsafe()` e `Document.parseHTMLUnsafe()` não o fazem: se você analisar marcação não confiável com esses métodos e depois passar os nós resultantes ao DOMPurify (`IN_PLACE`, `RETURN_DOM`, `RETURN_DOM_FRAGMENT`), qualquer shadow root fechado nessa marcação retorna sem sanitização. Em vez disso, passe a marcação não confiável ao DOMPurify como uma string. O DOMPurify também permite sanitizar HTML para uso com a API `$()` do jQuery e `elm.html()` sem problemas conhecidos. Para o conjunto exato de elementos e atributos permitidos por padrão, consulte a página wiki [Default TAGs & ATTRIBUTEs allow-list & blocklist](https://github.com/cure53/DOMPurify/wiki/Default-TAGs-ATTRIBUTEs-allow-list-&-blocklist).
## E quanto a navegadores legados como o Internet Explorer?
O DOMPurify não faz absolutamente nada. Ele simplesmente retorna exatamente a string que você forneceu. O DOMPurify expõe uma propriedade chamada `isSupported`, que informa se ele será capaz de fazer o seu trabalho, para que você possa elaborar seu próprio plano de contingência.
## E quanto ao DOMPurify e Trusted Types?
Na versão 1.0.9, o suporte à [Trusted Types API](https://github.com/w3c/webappsec-trusted-types) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API)) foi adicionado ao DOMPurify.
Na versão 2.0.0, uma flag de configuração foi adicionada para controlar o comportamento do DOMPurify em relação a isso.
Quando `DOMPurify.sanitize` é usado em um ambiente onde a Trusted Types API está disponível e `RETURN_TRUSTED_TYPE` está definido como `true`, ele tenta retornar um valor `TrustedHTML` em vez de uma string (o comportamento das opções de configuração `RETURN_DOM` e `RETURN_DOM_FRAGMENT` não muda).
Observe que, para criar uma policy em `trustedTypes` usando o DOMPurify, `RETURN_TRUSTED_TYPE: false` é necessário, pois `createHTML` espera uma string normal, não `TrustedHTML`. O exemplo abaixo mostra isso.
```js
window.trustedTypes.createPolicy('default', {
createHTML: (to_escape) =>
DOMPurify.sanitize(to_escape, { RETURN_TRUSTED_TYPE: false }),
});
```
Quando nenhuma `TRUSTED_TYPES_POLICY` é fornecida, o DOMPurify tenta criar sua própria política interna de Trusted Types chamada `dompurify`. Se sua página já define sua própria política junto com uma CSP estrita (por exemplo, `trusted-types my-organization`) que não permite uma política chamada `dompurify`, essa tentativa é bloqueada pelo navegador e registra um aviso `TrustedTypes policy dompurify could not be created.` juntamente com uma violação de CSP.
Para impedir que o DOMPurify crie sua política de fallback interna, passe `TRUSTED_TYPES_POLICY: null`. Esta é a escolha correta quando você chama `DOMPurify.sanitize` de dentro do `createHTML` da sua própria política, e significa que você não precisa adicionar `dompurify` à lista de permissões `trusted-types` da sua CSP.
```js
window.trustedTypes.createPolicy('my-organization', {
createHTML: (input) =>
DOMPurify.sanitize(input, { TRUSTED_TYPES_POLICY: null }),
});
```
**Não** passe sua própria política de encapsulamento de volta ao DOMPurify como seu `TRUSTED_TYPES_POLICY` (por exemplo, via `DOMPurify.setConfig({ TRUSTED_TYPES_POLICY: myPolicy })`) quando o `createHTML` dessa política já chama `DOMPurify.sanitize`. Isso é circular por definição - a sanitização chamaria a política, que sanitiza chamando o DOMPurify novamente - e o DOMPurify lançará um `TypeError` descritivo para evitar a recursão infinita. Sua própria política deve chamar o DOMPurify; o DOMPurify não deve ser configurado para chamar sua política.
Se você quiser que esse padrão de política `default` seja aplicado automaticamente em uma página inteira - de modo que todo sink de HTML seja sanitizado, incluindo código legado, widgets de terceiros e as milhares de atribuições `innerHTML` que você não consegue facilmente encontrar ou reescrever - dê uma olhada no [DOMFortify](https://github.com/cure53/DOMFortify). Ele instala exatamente esse tipo de política Trusted Types `default` respaldada pelo DOMPurify e recusa sinks de script (`eval`, `script.src`, ...) de imediato. É um projeto deliberadamente separado: o DOMPurify permanece um sanitizador focado, e o DOMFortify cuida da camada de imposição em todo o documento que está intencionalmente fora do escopo do DOMPurify.
## Posso configurar o DOMPurify?
Sim. Os valores de configuração padrão incluídos já são bastante bons - mas você pode, é claro, substituí-los. Confira a pasta [`/demos`](https://github.com/cure53/DOMPurify/tree/main/demos) para ver vários exemplos de como você pode [personalizar o DOMPurify](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this).
Antes de ampliar a lista de permissões (`ADD_TAGS`, `ADD_ATTR`, `CUSTOM_ELEMENT_HANDLING`, …) ou relaxar um padrão, vale a pena dar uma olhada nas [tags e atributos para pensar duas vezes](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model#dangerous-tags-and-attributes-think-twice-before-allow-listing) - alguns são perigosos de maneiras não óbvias.
### Configurações gerais
```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 });
```
### Controle nossas listas de permissões e bloqueios
```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 });
```
### Comportamento de controle relacionado a 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>
```
### Comportamento de controle relacionado a valores de 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'] });
```
### Controlar valores de atributos permitidos
```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,
});
```
### Influencie o tipo de retorno
```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 });
```
### Influencie como sanitizamos
```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',
});
```
### Influência onde sanitizamos
```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
```
Algumas coisas a saber sobre `IN_PLACE`:
- O nó raiz que você passa deve ser, ele próprio, uma tag permitida e não deve sofrer DOM-clobbering (por exemplo, um `<form>` com um filho chamado `nodeName` ou `ownerDocument`). Se sofrer, o DOMPurify remove do subárvore da raiz todos os atributos que não estão na lista de permitidos e depois lança um `TypeError`, de modo que uma raiz rejeitada nunca é devolvida armada.
- Se algo lançar uma exceção no meio da travessia, a mesma neutralização fail-closed é executada sobre a raiz e sobre cada subárvore já desanexada durante essa travessia antes de o erro se propagar.
- Nós que um hook desanexa da árvore (um padrão comum, veja [Hooks](#hooks)) são tratados como removidos. No modo `IN_PLACE`, todo elemento que estava sob a raiz quando `sanitize()` começou e já não está sob ela quando a chamada termina tem os seus atributos que não estão na lista de permitidos removidos antes de `sanitize()` retornar ou lançar uma exceção, independentemente do que o desanexou: um hook que remove o nó para o qual foi chamado, o seu pai ou outro ancestral, ou um nó noutro ponto da árvore, um hook que move uma subárvore para fora da raiz, ou um elemento personalizado que reage a uma das próprias remoções de atributos do DOMPurify. Assim, um `` que já estava a carregar quando construiu a árvore viva não pode disparar depois de `sanitize()` retornar. Da mesma forma, um nó da sua árvore que um hook ou elemento personalizado move para uma posição pela qual a travessia já passou continua a ser sanitizado antes de `sanitize()` retornar; se a árvore continuar a mudar dessa forma, o DOMPurify deixa a raiz sem atributos e lança uma exceção em vez de a devolver.
- O DOMPurify não consegue desfazer mutações do motor que já dispararam _antes_ de `sanitize()` ser chamado (um patch aplicado na conexão, um re-clone de `selectedcontent`, e assim por diante). Sanitize árvores controladas por atacantes antes de as ligar ao documento vivo, não depois.
Há ainda [mais exemplos aqui](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this), que mostram como pode executar, personalizar e configurar o DOMPurify para satisfazer as suas necessidades.
## Configuração Persistente
---
[Read more](https://github.com/cure53/dompurify)