cure53/dompurifyDOMPurify — это DOM-only, сверхбыстрый, сверхтолерантный XSS-санитайзер для HTML, MathML и SVG. DOMPurify работает с безопасным набором настроек по умолчанию, но предлагает множество возможностей конфигурации и хуков. Демо:
# 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 — это сверхбыстрый, чрезвычайно устойчивый санитайзер XSS для HTML, MathML и SVG, работающий исключительно с DOM.
Начать пользоваться им также очень просто. DOMPurify был [запущен в феврале 2014 года](https://github.com/cure53/DOMPurify/commit/a630922616927373485e0e787ab19e73e3691b2b) и с тех пор достиг версии **v3.4.17**.
DOMPurify работает на JavaScript и поддерживается во всех современных браузерах (Safari (10+), Opera (15+), Edge, Firefox и Chrome — а также практически во всём остальном, что использует Blink, Gecko или WebKit). Он не ломается в MSIE или других устаревших браузерах. Он просто ничего не делает.
**Обратите внимание, что [DOMPurify v2.5.9](https://github.com/cure53/DOMPurify/releases/tag/2.5.9) — последняя версия с поддержкой MSIE. Для важных обновлений безопасности, совместимых с MSIE, используйте [ветку 2.x](https://github.com/cure53/DOMPurify/tree/2.x).**
Наши автоматизированные тесты охватывают 9 комбинаций браузер/ОС на текущих движках (Chromium, Firefox и WebKit в Ubuntu, macOS и Windows) при каждом push, а отдельная матрица повторно прогоняет набор тестов на снимках старых движков (примерно до Chromium 110, Firefox 108 и WebKit 16.4, возрастом около трёх лет), чтобы также отлавливать регрессии в устаревших браузерах. Мы также запускаем DOMPurify на Node.js v20, v22, v24, v25 и v26 с [jsdom](https://github.com/jsdom/jsdom). Более старые версии Node, как известно, тоже работают, но, эх... без гарантий.
DOMPurify написан специалистами по безопасности, обладающими обширным опытом в веб-атаках и XSS. Не бойтесь. Для получения дополнительных сведений также прочитайте о наших [Целях безопасности и модели угроз](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model). Пожалуйста, прочитайте это. Серьёзно. А если вам нравятся кровавые подробности, страница [Классы атак и история обходов](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) каталогизирует приёмы мутации парсера, пространств имён, переопределения (clobbering) и шаблонов, от которых защищается DOMPurify.
Проект DOMPurify вдохновил на создание [HTML Sanitizer API](https://wicg.github.io/sanitizer-api/#sanitizer), который уже поставляется во [многих браузерах](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#browser_compatibility). Та же возможность сейчас стандартизируется непосредственно в [спецификации WHATWG HTML](https://html.spec.whatwg.org/#html-sanitization).
## Содержание
- [Что он делает?](#what-does-it-do)
- [Как его использовать?](#how-do-i-use-it)
- [Есть ли демо?](#is-there-a-demo)
- [Что делать, если я найду _уязвимость_?](#what-if-i-find-a-security-bug)
- [Можно несколько примеров очистки?](#some-purification-samples-please)
- [Что поддерживается?](#what-is-supported)
- [А как насчёт устаревших браузеров вроде Internet Explorer?](#what-about-legacy-browsers-like-internet-explorer)
- [А как насчёт DOMPurify и Trusted Types?](#what-about-dompurify-and-trusted-types)
- [Можно ли настроить DOMPurify?](#can-i-configure-dompurify)
- [Постоянная конфигурация](#persistent-configuration)
- [Хуки](#hooks)
- [Удалённая конфигурация](#removed-configuration)
- [Непрерывная интеграция](#continuous-integration)
- [Список рассылки по безопасности](#security-mailing-list)
- [Кто внёс вклад?](#who-contributed)
## Что он делает?
DOMPurify очищает HTML и предотвращает XSS-атаки. Вы можете передать DOMPurify, например, строку с небезопасным HTML, и он вернёт строку (если не настроено иное) с чистым HTML. DOMPurify удалит всё, что содержит опасный HTML, и тем самым предотвратит XSS-атаки и другие неприятности. К тому же он чертовски быстрый. Мы используем технологии, предоставляемые браузером, и превращаем их в XSS-фильтр. Чем быстрее ваш браузер, тем быстрее будет работать DOMPurify.
## Как его использовать?
Это просто. Просто подключите DOMPurify на своём сайте.
### Использование неминифицированной версии (доступна source-map)
```html
<script type="text/javascript" src="dist/purify.js"></script>
```
### Использование минифицированной и протестированной production-версии (source-map доступен)
```html
<script type="text/javascript" src="dist/purify.min.js"></script>
```
После этого вы можете очистить строки, выполнив следующий код:
```js
const clean = DOMPurify.sanitize(dirty);
```
Или, возможно, это, если вы любите работать с Angular или подобными:
```js
import DOMPurify from 'dompurify';
const clean = DOMPurify.sanitize('<b>hello there</b>');
```
Полученный HTML можно записать в элемент DOM с помощью `innerHTML` или в DOM с помощью `document.write()`. Это полностью на ваше усмотрение.
Обратите внимание, что по умолчанию мы разрешаем HTML, SVG **и** MathML. Если вам нужен только HTML, что может быть очень распространённым случаем, вы можете легко настроить это:
```js
const clean = DOMPurify.sanitize(dirty, { USE_PROFILES: { html: true } });
```
### Есть ли здесь потенциальные подводные камни?
Что ж, обратите внимание: если вы _сначала_ санируете HTML, а затем модифицируете его _впоследствии_, вы можете легко **свести на нет эффект санирования**. Если вы передаёте санированную разметку в другую библиотеку _после_ санирования, убедитесь, что эта библиотека не манипулирует HTML самостоятельно. См. [Security Goals & Threat Model](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model) — там описаны рецепты безопасного использования и теги/атрибуты, о которых стоит подумать дважды, а также [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) — о том, почему постобработка и изменение контекста разметки сводят санирование на нет.
### А что насчёт передачи DOM-узла вместо строки?
`DOMPurify.sanitize()` также принимает DOM-узел (`Element`, `DocumentFragment` или `Document`). Начиная с версии 3.4.14 этот путь усилен для узлов, которые не были получены от HTML-парсера: узел, построенный через DOM API или разобранный как XML/XHTML (например, через `DOMParser` с `application/xhtml+xml` и `importNode()`), может нести имена атрибутов с сохранённым регистром, такие как `ONERROR`, или rawtext-элемент вроде `<style>` с дочерним элементом или собственным закрывающим тегом внутри своего текста. Обе эти формы невидимы для строкового санитайзера, поскольку HTML-парсер никогда не может их построить, но они «вырываются наружу» при повторном разборе. Теперь DOMPurify удаляет атрибуты по их точному узлу `Attr` и считает такие деревья с буквальным текстом небезопасными, так что смешивание контекстов документов на входной стороне покрыто. По-прежнему ваша задача — не смешивать контексты на _выходной_ стороне, см. абзац выше.
### Хорошо, логично, двигаемся дальше
После санирования разметки вы также можете взглянуть на свойство `DOMPurify.removed` и узнать, какие элементы и атрибуты были отброшены. Пожалуйста, **не используйте** это свойство для принятия каких-либо решений, критичных для безопасности. Это всего лишь небольшой помощник для любопытных умов.
### Запуск DOMPurify на сервере
Технически DOMPurify также работает на стороне сервера с Node.js. Наша поддержка стремится следовать [циклу релизов Node.js](https://nodejs.org/en/about/previous-releases).
Для запуска DOMPurify на сервере требуется наличие DOM, что, вероятно, никого не удивит. Обычно инструментом выбора является [jsdom](https://github.com/jsdom/jsdom), и мы **настоятельно рекомендуем** использовать последнюю версию _jsdom_.
Почему? Потому что старые версии _jsdom_ известны своими ошибками, которые приводят к XSS, _даже если_ DOMPurify делает всё на 100% правильно. Существуют **известные векторы атак** в, например, _jsdom v19.0.0_, которые исправлены в _jsdom v20.0.0_ — и поэтому мы действительно рекомендуем держать _jsdom_ в актуальном состоянии.
Также имейте в виду, что существуют инструменты вроде [happy-dom](https://github.com/capricorn86/happy-dom), но на данный момент они **не считаются безопасными**. Сочетание DOMPurify с _happy-dom_ в настоящее время не рекомендуется и, вероятно, приведёт к XSS. О том, почему выбранный вами серверный DOM является частью вашей доверенной вычислительной базы, см. [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History).
В средах выполнения, где _jsdom_ не может работать, таких как Cloudflare Workers или Vercel Edge, [purify-edge](https://github.com/anzal1/purify-edge) — это сторонний проект, который запускает неизменённый DOMPurify на окне на основе parse5. Наш набор тестов можно прогнать против него с помощью `npm run test:purify-edge` в качестве проверки совместимости. Он не поддерживается нами, и успешный прогон не является ни одобрением, ни гарантией безопасности.
Помимо этого, вы можете спокойно использовать DOMPurify на сервере. Вероятно. Это действительно зависит от _jsdom_ или любого другого DOM, который вы используете на стороне сервера. Если вас это устраивает, вот как заставить это работать:
```bash
npm install dompurify
npm install jsdom
```
Для _jsdom_ (используйте актуальную версию) подойдёт следующее:
```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>');
```
Или даже так, если вы предпочитаете работать с импортами:
```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>');
```
Если у вас возникли проблемы с работой в вашей конкретной конфигурации, обратите внимание на замечательный проект [isomorphic-dompurify](https://github.com/kkomelin/isomorphic-dompurify), который решает множество проблем, с которыми могут столкнуться пользователи.
```bash
npm install isomorphic-dompurify
```
```js
import DOMPurify from 'isomorphic-dompurify';
const clean = DOMPurify.sanitize('<s>hello</s>');
```
## Есть ли демо?
Конечно, есть демо! [Поиграйте с DOMPurify](https://cure53.de/purify)
## Что делать, если я найду уязвимость?
Прежде всего, пожалуйста, немедленно свяжитесь с нами по [электронной почте](mailto:[email protected]), чтобы мы могли заняться исправлением. [PGP-ключ](https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0xC26C858090F70ADA)
Кроме того, вы, вероятно, имеете право на вознаграждение за найденную уязвимость! Замечательные ребята из [Fastmail](https://www.fastmail.com/) используют DOMPurify в своих сервисах и включили нашу библиотеку в свою программу bug bounty. Поэтому, если вы найдёте способ обойти или ослабить DOMPurify, пожалуйста, также загляните на их сайт и ознакомьтесь с [информацией о bug bounty](https://www.fastmail.com/about/bugbounty/).
## Можно несколько примеров очистки?
Как выглядит очищенная разметка? Что ж, [демо](https://cure53.de/purify) показывает это на большом наборе вредоносных элементов. Но давайте также покажем несколько примеров поменьше!
```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>
```
Это лишь малая часть. Полную таксономию классов атак, из которых взяты эти примеры — mutation XSS, путаница пространств имён, DOM clobbering, rawtext breakouts и другие — см. в [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History).
## Что поддерживается?
В настоящее время DOMPurify поддерживает HTML5, SVG и MathML. По умолчанию DOMPurify разрешает CSS и пользовательские data-атрибуты HTML. DOMPurify также поддерживает Shadow DOM — и рекурсивно очищает DOM-шаблоны. Это охватывает только открытые shadow roots: закрытый shadow root невозможно прочитать из скрипта, поэтому DOMPurify не может ни увидеть, ни очистить то, что находится внутри него. Строки это не затрагивает, поскольку собственный парсер DOMPurify игнорирует декларативные shadow roots (`<template shadowrootmode>`), но `setHTMLUnsafe()` и `Document.parseHTMLUnsafe()` — нет: если вы разбираете недоверенную разметку с их помощью, а затем передаёте полученные узлы в DOMPurify (`IN_PLACE`, `RETURN_DOM`, `RETURN_DOM_FRAGMENT`), любой закрытый shadow root в этой разметке вернётся неочищенным. Вместо этого передавайте недоверенную разметку в DOMPurify в виде строки. DOMPurify также позволяет очищать HTML для использования с API jQuery `$()` и `elm.html()` без известных проблем. Точный набор элементов и атрибутов, разрешённых по умолчанию, см. на вики-странице [Default TAGs & ATTRIBUTEs allow-list & blocklist](https://github.com/cure53/DOMPurify/wiki/Default-TAGs-ATTRIBUTEs-allow-list-&-blocklist).
## А как насчёт устаревших браузеров вроде Internet Explorer?
DOMPurify не делает вообще ничего. Он просто возвращает ровно ту строку, которую вы ему передали. DOMPurify предоставляет свойство `isSupported`, которое сообщает, сможет ли он выполнить свою работу, чтобы вы могли придумать собственный запасной план.
## А как насчёт DOMPurify и Trusted Types?
В версии 1.0.9 в DOMPurify была добавлена поддержка [Trusted Types API](https://github.com/w3c/webappsec-trusted-types) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API)).
В версии 2.0.0 был добавлен флаг конфигурации для управления поведением DOMPurify в этом отношении.
Когда `DOMPurify.sanitize` используется в среде, где доступен Trusted Types API, и `RETURN_TRUSTED_TYPE` установлен в `true`, он пытается вернуть значение `TrustedHTML` вместо строки (поведение для опций конфигурации `RETURN_DOM` и `RETURN_DOM_FRAGMENT` не меняется).
Обратите внимание, что для создания политики в `trustedTypes` с помощью DOMPurify требуется `RETURN_TRUSTED_TYPE: false`, поскольку `createHTML` ожидает обычную строку, а не `TrustedHTML`. Пример ниже показывает это.
```js
window.trustedTypes.createPolicy('default', {
createHTML: (to_escape) =>
DOMPurify.sanitize(to_escape, { RETURN_TRUSTED_TYPE: false }),
});
```
Если `TRUSTED_TYPES_POLICY` не передан, DOMPurify пытается создать собственную внутреннюю политику Trusted Types с именем `dompurify`. Если ваша страница уже определяет собственную политику вместе со строгим CSP (например, `trusted-types my-organization`), которая не разрешает политику с именем `dompurify`, эта попытка блокируется браузером, и в журнал выводится предупреждение `TrustedTypes policy dompurify could not be created.` вместе с нарушением CSP.
Чтобы DOMPurify не создавал свою внутреннюю резервную политику, передайте `TRUSTED_TYPES_POLICY: null`. Это правильный выбор, когда вы вызываете `DOMPurify.sanitize` изнутри `createHTML` вашей собственной политики, и это означает, что вам не нужно добавлять `dompurify` в список разрешённых `trusted-types` вашего CSP.
```js
window.trustedTypes.createPolicy('my-organization', {
createHTML: (input) =>
DOMPurify.sanitize(input, { TRUSTED_TYPES_POLICY: null }),
});
```
**Не** передавайте свою собственную политику обёртки обратно в DOMPurify в качестве её `TRUSTED_TYPES_POLICY` (например, через `DOMPurify.setConfig({ TRUSTED_TYPES_POLICY: myPolicy })`), если `createHTML` этой политики уже вызывает `DOMPurify.sanitize`. Это по определению циклическая зависимость — санитизация вызовет политику, которая санитизирует, снова вызывая DOMPurify — и DOMPurify выбросит описательный `TypeError`, чтобы предотвратить бесконечную рекурсию. Ваша собственная политика должна вызывать DOMPurify; DOMPurify не должна быть настроена на вызов вашей политики.
Если вы хотите, чтобы этот шаблон политики `default` применялся ко всей странице автоматически — так, чтобы каждый HTML-сток был санитизирован, включая устаревший код, сторонние виджеты и тысячи присваиваний `innerHTML`, которые вы не можете легко найти или переписать — обратите внимание на [DOMFortify](https://github.com/cure53/DOMFortify). Он устанавливает именно такую политику Trusted Types `default`, поддерживаемую DOMPurify, и полностью отклоняет скриптовые стоки (`eval`, `script.src`, ...). Это намеренно отдельный проект: DOMPurify остаётся сфокусированным санитайзером, а DOMFortify обрабатывает уровень принудительного применения на уровне документа, который намеренно выходит за рамки DOMPurify.
## Могу ли я настроить DOMPurify?
Да. Включённые значения конфигурации по умолчанию уже довольно хороши — но вы, конечно, можете их переопределить. Загляните в папку [`/demos`](https://github.com/cure53/DOMPurify/tree/main/demos), чтобы увидеть множество примеров того, как можно [настроить DOMPurify](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this).
Прежде чем расширять список разрешённого (`ADD_TAGS`, `ADD_ATTR`, `CUSTOM_ELEMENT_HANDLING`, …) или ослаблять значение по умолчанию, стоит просмотреть [теги и атрибуты, о которых стоит подумать дважды](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model#dangerous-tags-and-attributes-think-twice-before-allow-listing) — некоторые из них опасны неочевидным образом.
### Общие настройки
```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 });
```
### Управление нашими списками разрешений и блокировок
```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 });
```
### Управление поведением, связанным с пользовательскими элементами
```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(
```
---
[Read more](https://github.com/cure53/dompurify)