html-sanitize: NGINX-Modul zur Bereinigung von HTML 5 mit genehmigten Elementen, Attributen und CSS
Installation
Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:
- RedHat Enterprise Linux 7, 8, 9 und 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 und Amazon Linux 2023
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
Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:
load_module modules/ngx_http_html_sanitize_module.so;
Dieses Dokument beschreibt nginx-module-html-sanitize v0.2.6 veröffentlicht am 07. März 2026.
Beispiel
Es gibt ein Beispiel für die nginx-Konfiguration gemäß https://dev.w3.org/html5/html-author/#the-elements wie folgt:
server {
listen 8888;
location = /sanitize {
# Explizit utf-8 Kodierung festlegen
add_header Content-Type "text/html; charset=UTF-8";
client_body_buffer_size 10M;
client_max_body_size 10M;
html_sanitize on;
# Überprüfen Sie https://dev.w3.org/html5/html-author/#the-elements
# Wurzel-Element
html_sanitize_element html;
# Dokument-Metadaten
html_sanitize_element head title base link meta style;
# Skripting
html_sanitize_element script noscript;
# Abschnitte
html_sanitize_element body section nav article aside h1 h2 h3 h4 h5 h6 header footer address;
# Gruppierung von Inhalten
html_sanitize_element p hr br pre dialog blockquote ol ul li dl dt dd;
# Text-Level Semantik
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;
# Änderungen
html_sanitize_element ins del;
# Eingebettete Inhalte
htlm_sanitize_element figure img iframe embed object param video audio source canvas map area;
# Tabellarische Daten
html_sanitize_element table caption colgroup col tbody thead tfoot tr td th;
# Formulare
html_sanitize_element form fieldset label input button select datalist optgroup option textare output;
# Interaktive Elemente
html_sanitize_element details command bb menu;
# Verschiedene Elemente
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;
}
}
Und es wird empfohlen, den folgenden Befehl zu verwenden, um HTML5 zu bereinigen:
$ 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>
Dieser Abfrage-String 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 ist wie folgt:
- element=2: genehmigtes Element durch html_sanitize_element ausgeben
- attribute=1: jedes Attribut durch html_sanitize_attribute ausgeben
- style_property=1: jede Stil-Eigenschaft durch html_sanitize_style_property ausgeben
- style_property_value=1: den Stilwert für die url-Funktion und die expression-Funktion überprüfen, um XSS-Injektionen durch style_property_value zu vermeiden
- url_protocol=1: genehmigtes url_protocol für absolute URLs durch html_sanitize_url_protocol überprüfen
- url_domain=0: keine Überprüfung der URL-Domain für absolute URLs
- iframe_url_protocol=1: ist dasselbe wie url_protocol, aber nur für
iframe.srcdurch html_sanitize_iframe_url_protocol - iframe_url_domain=0: ist dasselbe wie url_domain, aber nur für
iframe.srcdurch html_sanitize_iframe_url_domain
Mit ngx_http_html_sanitize_module haben wir die Möglichkeit, anzugeben, ob die Ausgabeelemente von HTML5, Attribute und Inline-CSS-Eigenschaften durch directive und querystring wie folgt spezifiziert werden:
genehmigtes Element
- Element deaktivieren:
Wenn wir kein Element ausgeben möchten, können wir dies wie folgt tun:
curl -X POST -d "<h1>h1</h1>" http://127.0.0.1:8888/sanitize?element=0
- Element aktivieren:
Wenn wir ein Element ausgeben möchten, können wir dies wie folgt tun:
$ 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>
- Genehmigtes Element aktivieren:
Wenn wir genehmigte Elemente ausgeben möchten, können wir dies wie folgt tun:
$ curl -X POST -d "<h1>h1</h1><h7>h7</h7>" http://127.0.0.1:8888/sanitize?element=1
<h1>h1</h1>
Genehmigtes Attribut
- Attribut deaktivieren:
Wenn wir kein Attribut ausgeben möchten, können wir dies wie folgt tun:
curl -X POST -d "<h1 ha=\"ha\">h1</h1>" "http://127.0.0.1:8888/sanitize?element=1&attribute=0"
<h1>h1</h1>
- Attribut aktivieren:
Wenn wir ein Attribut ausgeben möchten, können wir dies wie folgt tun:
$ 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>
- Genehmigtes Attribut aktivieren:
Wenn wir genehmigte Elemente ausgeben möchten, können wir dies wie folgt tun:
$ curl -X POST -d "<img src=\"/\" ha=\"ha\" />" "http://127.0.0.1:8888/sanitize?element=1&attribute=2"
<img src="/" />
Genehmigte Stil-Eigenschaft
- Stil-Eigenschaft deaktivieren:
Wenn wir keine Stil-Eigenschaft ausgeben möchten, können wir dies wie folgt tun:
# Es wird keine Stil-Eigenschaft ausgegeben
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>
- Stil-Eigenschaft aktivieren:
Wenn wir eine Stil-Eigenschaft ausgeben möchten, können wir dies wie folgt tun:
$ 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>
- Genehmigte Stil-Eigenschaft aktivieren:
Wenn wir genehmigte Stil-Eigenschaften ausgeben möchten, können wir dies wie folgt tun:
$ 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>
Beschreibung
Die Implementierung des ngx_http_html_sanitize_module basiert jetzt auf gumbo-parser und katana-parser. Wir haben die Kombination darauf aufgebaut und führen sie auf nginx als zentrales Webdienst durch, das von professionellen Sicherheitsexperten gepflegt wird, um sprachliche Unterschiede zu beseitigen. Wenn wir eine höhere Leistung erzielen möchten (hier ist der Benchmark), wird empfohlen, eine sprachspezifische Bibliothek über der reinen C-Bibliothek zu schreiben, um die Übertragungskosten im Netzwerk zu überwinden.
Benchmark
Testen mit wrk -s benchmarks/shot.lua -d 60s "http://127.0.0.1:8888" auf Intel(R) Xeon(R) CPU E5-2630 v3 @ 2.40GHz und 64GB RAM
| Name | Größe | Durchschnittliche Latenz | 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 |
Directive
html_sanitize
syntax: html_sanitize on | off
default: html_sanitize on
context: location
Gibt an, ob der HTML-Bereinigungs-Handler im Kontext des Standorts aktiviert werden soll.
html_sanitize_hash_max_size
syntax: html_sanitize_hash_max_size size
default: html_sanitize_hash_max_size 2048
context: location
Legt die maximale Größe der Hash-Tabellen für Elemente, Attribute, Stil-Eigenschaften, URL-Protokolle, URL-Domains, iframe_url_protokolle und iframe_url_domains fest.
html_sanitize_hash_bucket_size
syntax: html_sanitize_hash_bucket_size size
default: html_sanitize_hash_bucket_size 32|64|128
context: location
Legt die Bucket-Größe für Elemente, Attribute, Stil-Eigenschaften, URL-Protokolle, URL-Domains, iframe_url_protokolle und iframe_url_domains fest. Der Standardwert hängt von der Größe der Cache-Zeile des Prozessors ab.
html_sanitize_element
syntax: html_sanitize_element element ...
default: -
context: location
Setzt die genehmigten HTML5-Elemente, wenn genehmigte Elemente aktiviert werden, indem der Querystring element im Whitelist-Modus wie folgt festgelegt wird:
html_sanitize_element html head body;
html_sanitize_attribute
syntax: html_sanitize_attribute attribute ...
default: -
context: location
Setzt die genehmigten HTML5-Attribute, wenn genehmigte Elemente aktiviert werden, indem der Querystring attribute im Whitelist-Modus wie folgt festgelegt wird:
html_sanitize_attribute a.href h1.class;
PS: Das Attributformat muss dasselbe wie element.attribute sein und unterstützt *.attribute (Präfix-Sternchen) und element.* (Suffix-Sternchen).
html_sanitize_style_property
syntax: html_sanitize_style_property property ...
default: -
context: location
Setzt die genehmigten CSS-Eigenschaften, wenn genehmigte Elemente aktiviert werden, indem der Querystring style_property im Whitelist-Modus wie folgt festgelegt wird:
html_sanitize_style_property color background-color;
html_sanitize_url_protocol
syntax: html_sanitize_url_protocol [protocol] ...
default: -
context: location
Setzt das erlaubte URL-Protokoll bei linkable attribute, wenn die URL nur absolut und nicht relativ ist, und aktiviert die Überprüfung des URL-Protokolls, indem der Querystring url_protocol im Prüfmodus wie folgt festgelegt wird:
html_sanitize_url_protocol http https tel;
html_sanitize_url_domain
syntax: html_sanitize_url_domain domain ...
default: -
context: location
Setzt die erlaubte URL-Domain bei linkable attribute, wenn die URL nur absolut und nicht relativ ist, und aktiviert die Überprüfung des URL-Protokolls und der URL-Domain, indem der Querystring url_protocol im Prüfmodus und der Querystring url_domain[#url_domain] im Prüfmodus wie folgt festgelegt wird:
html_sanitize_url_domain *.google.com google.com;
html_sanitize_iframe_url_protocol
syntax: html_sanitize_iframe_url_protocol [protocol] ...
default: -
context: location
Ist dasselbe wie html_sanitize_url_protocol, aber nur für das Attribut iframe.src.
html_sanitize_iframe_url_protocol http https tel;
html_sanitize_iframe_url_domain
syntax: html_sanitize_iframe_url_domain [protocol] ...
default: -
context: location
Ist dasselbe wie html_sanitize_url_domain, aber nur für das Attribut iframe.src.
html_sanitize_iframe_url_domain *.facebook.com facebook.com;
linkable_attribute
Die verlinkbaren Attribute sind die folgenden:
- a.href
- blockquote.cite
- q.cite
- del.cite
- img.src
- ins.cite
- iframe.src
- CSS URL-Funktion
Querystring
Der Querystring aus der Anforderungs-URL wird verwendet, um die internen Aktionen des ngx_http_html_sanitize_module zu steuern.
document
value: 0 oder 1
default: 0
context: querystring
Gibt an, ob <!DOCTYPE> zum Antwortkörper hinzugefügt werden soll.
html
value: 0 oder 1
default: 0
context: querystring
Gibt an, ob <html></html> zum Antwortkörper hinzugefügt werden soll.
script
value: 0 oder 1
default: 0
context: querystring
Gibt an, ob <script></script> erlaubt ist.
style
value: 0 oder 1
default: 0
context: querystring
Gibt an, ob <style></style> erlaubt ist.
context
value: [0, 150)
default: 38(GUMBO_TAG_DIV)
context: querystring
Gibt den Kontext des gumbo-parsers mit dem Wert in dieser Datei tag_enum.h an.
element
value: 0, 1, 2
default: 0
context: querystring
Gibt den Modus der Ausgabe von Elementen mit den folgenden Werten an:
- 0: kein Element ausgeben
- 1: alle Elemente ausgeben
- 2: genehmigte Elemente ausgeben
attribute
value: 0, 1, 2
default: 0
context: querystring
Gibt den Modus der Ausgabe von Attributen mit den folgenden Werten an:
- 0: keine Attribute ausgeben
- 1: alle Attribute ausgeben
- 2: genehmigte Attribute ausgeben
style_property
value: 0, 1, 2
default: 0
context: querystring
Gibt den Modus der Ausgabe von CSS-Eigenschaften mit den folgenden Werten an:
- 0: keine CSS-Eigenschaften ausgeben
- 1: alle CSS-Eigenschaften ausgeben
- 2: genehmigte CSS-Eigenschaften ausgeben
style_property_value
value: 0, 1
default: 0
context: querystring
Gibt den Modus der Ausgabe von CSS-Eigenschaftswerten mit den folgenden Werten an:
- 0: den Wert der CSS-Eigenschaft nicht überprüfen
- 1: den Wert der CSS-Eigenschaft für die URL-Funktion und die IE-Expression-Funktion überprüfen, um XSS-Injektionen zu vermeiden.
url_protocol
value: 0, 1
default: 0
context: querystring
Gibt an, ob das URL-Protokoll bei linkable_attribute überprüft werden soll. Der Wert ist wie folgt:
- 0: das URL-Protokoll nicht überprüfen
- 1: genehmigtes URL-Protokoll ausgeben
url_domain
value: 0, 1
default: 0
context: querystring
Gibt an, ob die URL-Domain bei linkable_attribute überprüft werden soll, wenn die url_protocol-Überprüfung aktiviert ist. Der Wert ist wie folgt:
- 0: die URL-Domain nicht überprüfen
- 1: genehmigte URL-Domain ausgeben
iframe_url_protocol
value: 0, 1
default: 0
context: querystring
Ist dasselbe wie url_protocol, aber nur für iframe.src.
iframe_url_domain
value: 0, 1
default: 0
context: querystring
Ist dasselbe wie url_domain, aber nur für iframe.src.
GitHub
Sie finden zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-html-sanitize.