html-sanitize: Модуль NGINX для санитации HTML 5 с разрешенными элементами, атрибутами и CSS

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

• RedHat Enterprise Linux 7, 8, 9 и 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 и Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-html-sanitize

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-html-sanitize

Включите модуль, добавив следующее в начало файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_html_sanitize_module.so;

Этот документ описывает nginx-module-html-sanitize v0.2.6, выпущенный 7 марта 2026 года.

---

Пример

Вот пример конфигурации nginx в соответствии с https://dev.w3.org/html5/html-author/#the-elements:

server {
    listen 8888;

    location = /sanitize {
        # Явно установить кодировку utf-8
        add_header Content-Type "text/html; charset=UTF-8";

        client_body_buffer_size 10M;
        client_max_body_size 10M;

        html_sanitize on;

        # Проверьте https://dev.w3.org/html5/html-author/#the-elements

        # Корневой элемент
        html_sanitize_element html;

        # Метаданные документа
        html_sanitize_element head title base link meta style;

        # Скрипты
        html_sanitize_element script noscript;

        # Секции
        html_sanitize_element body section nav article aside h1 h2 h3 h4 h5 h6 header footer address;

        # Группировка контента
        html_sanitize_element p hr br pre dialog blockquote ol ul li dl dt dd;

        # Семантика текстового уровня
        html_sanitize_element a q cite em strong small mark dfn abbr time progress meter code var samp kbd sub sup span i b bdo ruby rt rp;

        # Изменения
        html_sanitize_element ins del;

        # Встраиваемый контент
        htlm_sanitize_element figure img iframe embed object param video audio source canvas map area;

        # Табличные данные
        html_sanitize_element table caption colgroup col tbody thead tfoot tr td th;

        # Формы
        html_sanitize_element form fieldset label input button select datalist optgroup option textare output;

        # Интерактивные элементы
        html_sanitize_element details command bb menu;

        # Разное
        html_sanitize_element legend div;

        html_sanitize_attribute *.style;
        html_sanitize_attribute a.href a.hreflang a.name a.rel;
        html_sanitize_attribute col.span col.width colgroup.span colgroup.width;
        html_sanitize_attribute data.value del.cite del.datetime;
        html_sanitize_attribute img.align img.alt img.border img.height img.src img.width;
        html_sanitize_attribute ins.cite ins.datetime li.value ol.reversed ol.stasrt ol.type ul.type;
        html_sanitize_attribute table.align table.bgcolor table.border table.cellpadding table.cellspacing table.frame table.rules table.sortable table.summary table.width;
        html_sanitize_attribute td.abbr td.align td.axis td.colspan td.headers td.rowspan td.valign td.width;
        html_sanitize_attribute th.abbr th.align th.axis th.colspan th.rowspan th.scope th.sorted th.valign th.width;

        html_sanitize_style_property color font-size;

        html_sanitize_url_protocol http https tel;
        html_sanitize_url_domain *.google.com google.com;

        html_sanitize_iframe_url_protocol http https;
        html_sanitize_iframe_url_domain  facebook.com *.facebook.com;
    }
}

Рекомендуется использовать следующую команду для санитации HTML5:

$ curl -X POST -d "<h1>Hello World </h1>" http://127.0.0.1:8888/sanitize?element=2&attribute=1&style_property=1&style_property_value=1&url_protocol=1&url_domain=0&iframe_url_protocol=1&iframe_url_domain=0

<h1>Hello World </h1>

Эта строка запроса element=2&attribute=1&style_property=1&style_property_value=1&url_protocol=1&url_domain=0&iframe_url_protocol=1&iframe_url_domain=0 означает следующее:

• element=2: выводить разрешенный элемент по html_sanitize_element
• attribute=1: выводить любые атрибуты по html_sanitize_attribute
• style_property=1: выводить любые свойства стиля по html_sanitize_style_property
• style_property_value=1: проверять значение стиля для функции url и функции expression, чтобы избежать XSS-инъекций по style_property_value
• url_protocol=1: проверять разрешенные url_protocol для абсолютного URL по html_sanitize_url_protocol
• url_domain=0: не проверять домен URL для абсолютного URL
• iframe_url_protocol=1: то же самое, что и url_protocol, но только для iframe.src по html_sanitize_iframe_url_protocol
• iframe_url_domain=0: то же самое, что и url_domain, но только для iframe.src по html_sanitize_iframe_url_domain

С помощью ngx_http_html_sanitize_module мы можем указать, следует ли выводить элементы HTML5, атрибуты и свойства встроенного CSS с помощью directive и querystring следующим образом:

Разрешенные элементы

• отключить элемент:

если мы не хотим выводить никакие элементы, мы можем сделать это следующим образом:

curl -X POST -d "<h1>h1</h1>" http://127.0.0.1:8888/sanitize?element=0

• включить элемент:

если мы хотим выводить любые элементы, мы можем сделать это следующим образом:

$ curl -X POST -d "<h1>h1</h1><h7>h7</h7>" http://127.0.0.1:8888/sanitize?element=1

<h1>h1</h1><h7>h7</h7>

• включить разрешенные элементы:

если мы хотим выводить разрешенные элементы, мы можем сделать это следующим образом:

$ curl -X POST -d "<h1>h1</h1><h7>h7</h7>" http://127.0.0.1:8888/sanitize?element=1

<h1>h1</h1>

Разрешенные атрибуты

• отключить атрибут:

если мы не хотим выводить никакие атрибуты, мы можем сделать это следующим образом:

curl -X POST -d "<h1 ha=\"ha\">h1</h1>" "http://127.0.0.1:8888/sanitize?element=1&attribute=0"

<h1>h1</h1>

• включить атрибут:

если мы хотим выводить любые атрибуты, мы можем сделать это следующим образом:

$ curl -X POST -d "<h1 ha=\"ha\">h1</h1>" "http://127.0.0.1:8888/sanitize?element=1&attribute=1"

<h1 ha="ha">h1</h1>

• включить разрешенные атрибуты:

если мы хотим выводить разрешенные атрибуты, мы можем сделать это следующим образом:

$ curl -X POST -d "<img src=\"/\" ha=\"ha\" />" "http://127.0.0.1:8888/sanitize?element=1&attribute=2"

<img src="/" />

Разрешенные свойства стиля

• отключить свойство стиля:

если мы не хотим выводить никакие свойства стиля, мы можем сделать это следующим образом:

# Это не будет выводить никакие свойства стиля
curl -X POST -d "<h1 style=\"color:red;\">h1</h1>" "http://127.0.0.1:8888/sanitize?element=1&attribute=1&style_property=0"

<h1>h1</h1>

• включить свойство стиля:

если мы хотим выводить любые свойства стиля, мы можем сделать это следующим образом:

$ curl -X POST -d "<h1 style=\"color:red;text-align:center;\">h1</h1>" "http://127.0.0.1:8888/sanitize?element=1&attribute=1&style_property=1"

<h1 style="color:red;text-align:center">h1</h1>

• включить разрешенные свойства стиля:

если мы хотим выводить разрешенные свойства стиля, мы можем сделать это следующим образом:

$ curl -X POST -d "<h1 style=\"color:red;text-align:center;\" >h1</h1>" "http://127.0.0.1:8888/sanitize?element=1&attribute=1&style_property=2"

<h1 style="color:red;">h1</h1>

Описание

В настоящее время реализация ngx_http_html_sanitize_module основана на gumbo-parser и katana-parser. Мы создали комбинацию на его основе и запустили ее на nginx как централизованную веб-службу, поддерживаемую профессиональными специалистами по безопасности для устранения языковых различий. Если мы хотим добиться более высокой производительности (здесь бенчмарк), рекомендуется написать библиотеку на уровне языка, оборачивающую чистую C-библиотеку, чтобы преодолеть накладные расходы на сетевую передачу.

Бенчмарк

Тестирование с помощью wrk -s benchmarks/shot.lua -d 60s "http://127.0.0.1:8888" на Intel(R) Xeon(R) CPU E5-2630 v3 @ 2.40GHz и 64GB памяти

Название	Размер	Средняя задержка	QPS
hacker_news.html	30KB	9.06ms	2921.82
baidu.html	76KB	13.41ms	1815.75
arabic_newspapers.html	78KB	16.58ms	1112.70
bbc.html	115KB	17.96ms	993.12
xinhua.html	323KB	33.37ms	275.39
google.html	336KB	26.78ms	351.54
yahoo.html	430KB	29.16ms	323.04
wikipedia.html	511KB	57.62ms	160.10
html5_spec.html	7.7MB	1.63s	2.00

Директивы

html_sanitize

синтаксис: html_sanitize on | off

по умолчанию: html_sanitize on

контекст: location

Указывает, включен ли обработчик санитации HTML в контексте location.

html_sanitize_hash_max_size

синтаксис: html_sanitize_hash_max_size size

по умолчанию: html_sanitize_hash_max_size 2048

контекст: location

Устанавливает максимальный размер хеш-таблиц для элементов, атрибутов, свойств стиля, url_protocol, url_domain, iframe_url_protocol, iframe_url_domain.

html_sanitize_hash_bucket_size

синтаксис: html_sanitize_hash_bucket_size size

по умолчанию: html_sanitize_hash_bucket_size 32|64|128

контекст: location

Устанавливает размер ведра для элементов, атрибутов, свойств стиля, url_protocol, url_domain, iframe_url_protocol, iframe_url_domain. Значение по умолчанию зависит от размера кэш-линии процессора.

html_sanitize_element

синтаксис: html_sanitize_element element ...

по умолчанию: -

контекст: location

Устанавливает разрешенные элементы HTML5, когда включены разрешенные элементы, устанавливая режим белого списка для querystring element следующим образом:

html_sanitize_element html head body;

html_sanitize_attribute

синтаксис: html_sanitize_attribute attribute ...

по умолчанию: -

контекст: location

Устанавливает разрешенные атрибуты HTML5, когда включены разрешенные элементы, устанавливая режим белого списка для querystring attribute следующим образом:

html_sanitize_attribute a.href h1.class;

PS: формат атрибута должен быть таким же, как element.attribute и поддерживает *.attribute (префикс с звездочкой) и element.* (суффикс с звездочкой).

html_sanitize_style_property

синтаксис: html_sanitize_style_property property ...

по умолчанию: -

контекст: location

Устанавливает разрешенные CSS-свойства, когда включены разрешенные элементы, устанавливая режим белого списка для querystring style_property следующим образом:

html_sanitize_style_property color background-color;

html_sanitize_url_protocol

синтаксис: html_sanitize_url_protocol [protocol] ...

по умолчанию: -

контекст: location

Устанавливает разрешенный URL-протокол для linkable attribute, когда URL является абсолютным, а не относительным, и включает проверку URL-протокола, устанавливая режим проверки querystring url_protocol следующим образом:

html_sanitize_url_protocol http https tel;

html_sanitize_url_domain

синтаксис: html_sanitize_url_domain domain ...

по умолчанию: -

контекст: location

Устанавливает разрешенный домен URL для linkable attribute, когда URL является абсолютным, а не относительным, и включает проверку URL-протокола, проверку домена URL, устанавливая режим проверки querystring url_protocol и режим проверки querystring url_domain[#url_domain] следующим образом:

html_sanitize_url_domain *.google.com google.com;

html_sanitize_iframe_url_protocol

синтаксис: html_sanitize_iframe_url_protocol [protocol] ...

по умолчанию: -

контекст: location

То же самое, что и html_sanitize_url_protocol, но только для атрибута iframe.src.

html_sanitize_iframe_url_protocol http https tel;

html_sanitize_iframe_url_domain

синтаксис: html_sanitize_iframe_url_domain [protocol] ...

по умолчанию: -

контекст: location

То же самое, что и html_sanitize_url_domain, но только для атрибута iframe.src.

html_sanitize_iframe_url_domain *.facebook.com facebook.com;

linkable_attribute

Разрешенные атрибуты:

• a.href
• blockquote.cite
• q.cite
• del.cite
• img.src
• ins.cite
• iframe.src
• CSS URL function

Querystring

Строка запроса из URL запроса используется для управления внутренними действиями ngx_http_html_sanitize_module.

document

значение: 0 или 1

по умолчанию: 0

контекст: querystring

Указывает, следует ли добавлять <!DOCTYPE> в тело ответа.

html

значение: 0 или 1

по умолчанию: 0

контекст: querystring

Указывает, следует ли добавлять <html></html> в тело ответа.

script

значение: 0 или 1

по умолчанию: 0

контекст: querystring

Указывает, разрешено ли использование <script></script>.

style

значение: 0 или 1

по умолчанию: 0

контекст: querystring

Указывает, разрешено ли использование <style></style>.

context

значение: [0, 150)

по умолчанию: 38(GUMBO_TAG_DIV)

контекст: querystring

Указывает контекст gumbo-parser со значением из этого файла tag_enum.h.

element

значение: 0、1、2

по умолчанию: 0

контекст: querystring

Указывает режим вывода элемента со значением следующим образом:

• 0: не выводить элемент
• 1: выводить все элементы
• 2: выводить разрешенные элементы

attribute

значение: 0、1、2

по умолчанию: 0

контекст: querystring

Указывает режим вывода атрибута со значением следующим образом:

• 0: не выводить атрибуты
• 1: выводить все атрибуты
• 2: выводить разрешенные атрибуты

style_property

значение: 0、1、2

по умолчанию: 0

контекст: querystring

Указывает режим вывода CSS-свойства со значением следующим образом:

• 0: не выводить CSS-свойство
• 1: выводить все CSS-свойства
• 2: выводить разрешенные CSS-свойства

style_property_value

значение: 0、1

по умолчанию: 0

контекст: querystring

Указывает режим вывода значения CSS-свойства со значением следующим образом:

• 0: не проверять значение CSS-свойства
• 1: проверять значение CSS-свойства для функции URL и функции выражения IE, чтобы избежать XSS-инъекций.

url_protocol

значение: 0、1

по умолчанию: 0

контекст: querystring

Указывает, следует ли проверять протокол URL в linkable_attribute. Значение следующее:

• 0: не проверять протокол URL
• 1: выводить разрешенный протокол URL

url_domain

значение: 0、1

по умолчанию: 0

контекст: querystring

Указывает, следует ли проверять домен URL в linkable_attribute, когда включена проверка url_protocol. Значение следующее:

• 0: не проверять домен URL
• 1: выводить разрешенный домен URL

iframe_url_protocol

значение: 0、1

по умолчанию: 0

контекст: querystring

То же самое, что и url_protocol, но только для iframe.src.

iframe_url_domain

значение: 0、1

по умолчанию: 0

контекст: querystring

То же самое, что и url_domain, но только для iframe.src.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-html-sanitize.