Get to know MDN better
Dieser Inhalt wurde automatisch aus dem Englischen übersetzt, und kann Fehler enthalten. Erfahre mehr über dieses Experiment.
Die HTML Sanitizer API bietet Methoden, mit denen Entwickler nicht vertrauenswürdiges HTML sicher in ein Element, einen ShadowRoot oder ein Document einfügen können. Die API gibt Entwicklern auch die Flexibilität, falls erforderlich, weiter einzuschränken oder zu erweitern, welche HTML-Entitäten erlaubt sind.
Der häufigste Anwendungsfall für die API ist das sichere Einfügen einer vom Benutzer bereitgestellten Zeichenkette in ein Element. Sofern die einzufügende Zeichenkette keine unsicheren HTML-Entitäten enthalten muss, können Sie Element.setHTML() als Ersatz für Element.innerHTML verwenden.
Zum Beispiel entfernt der folgende Code alle XSS-unsicheren Elemente und Attribute in der Eingabezeichenkette (in diesem Fall das <script>-Element) zusammen mit allen Elementen, die von der HTML-Spezifikation nicht als Kinder des Zielelements zulässig sind:
Die anderen XSS-sicheren Methoden, ShadowRoot.setHTML() und Document.parseHTML(), werden auf dieselbe Weise verwendet.
Allen Bereinigungsmethoden kann ein Sanitizer oder SanitizerConfig übergeben werden, der definiert, welche Elemente, Attribute und Kommentare entweder erlaubt oder entfernt werden sollen, wenn HTML-Zeichenketten eingefügt werden.
Der Sanitizer ist im Wesentlichen ein Wrapper um eine SanitizerConfig, der einige Optimierungen und Normalisierungen vornimmt, die die Verwendung, das Teilen und das Modifizieren erleichtern und sicherer machen.
Die XSS-sicheren Methoden entfernen immer alle unsicheren HTML-Elemente oder Attribute (wie oben in Sichere Bereinigung standardmäßig besprochen).
Sie können einen Sanitizer als zweites Argument an die sicheren Methoden übergeben, um die gleichen oder weniger Entitäten als in der Standardkonfiguration zuzulassen. Zum Beispiel, wenn Sie wissen, dass im Kontext von someElement unten nur <p>- und <a>-Elemente erwartet werden, könnten Sie eine Sanitizer-Konfiguration erstellen, die nur diese Elemente zulässt:
Manchmal möchten Sie möglicherweise Eingaben injizieren, die möglicherweise unsichere Elemente oder Attribute enthalten müssen. In diesem Fall könnten Sie eine der API XSS-unsicheren Methoden verwenden: Element.setHTMLUnsafe(), ShadowRoot.setHTMLUnsafe() und Document.parseHTMLUnsafe().
Um das Risiko etwas zu reduzieren, könnten Sie zuerst den Standard-Sanitizer erstellen, der nur XSS-sichere Elemente erlaubt, und dann nur die unsicheren Entitäten erlauben, die in der Eingabe erwartet werden.
Zum Beispiel sind im folgenden Sanitizer alle sicheren Elemente erlaubt, und wir erlauben zusätzlich nur den unsicheren onclick-Handler auf button-Elementen.
Mit diesem Code wäre das alert(1) erlaubt, und es besteht ein potenzielles Problem, dass das Attribut für bösartige Zwecke verwendet werden könnte. Wir wissen jedoch, dass alle anderen XSS-unsicheren HTML-Entitäten entfernt wurden, sodass wir uns nur um diesen einen Fall sorgen müssen und können andere Maßnahmen ergreifen.
Die unsicheren Methoden verwenden jede Sanitizer-Konfiguration, die Sie bereitstellen (oder keine), daher müssen Sie vorsichtig sein, wenn Sie sie verwenden. Mindestens sollten Sie Trusted Types durchsetzen und TrustedHTML anstelle von Zeichenketten in die Methoden übergeben.
Sie können eine „Erlaubte“ Sanitizer-Konfiguration erstellen, indem Sie nur die Menge an HTML-Elementen und -Attributen spezifizieren, die beim Einsatz des Sanitizers eingefügt werden dürfen. Diese Form der Konfiguration ist leicht verständlich und nützlich, wenn Sie genau wissen, welche HTML-Entitäten im Zielkontext zulässig sein sollen.
Zum Beispiel erlaubt die folgende Konfiguration die <p>- und <div>-Elemente sowie die Attribute cite und onclick. Ebenso werden <b>-Elemente durch ihren Inhalt ersetzt (dies ist eine Form des „Erlaubens“, da die Elementinhalte nicht entfernt werden).
Die erlaubten Elemente können über die elements-Eigenschaft der an den Sanitizer()-Konstruktor (oder direkt an die Bereinigungsmethoden) übergebenen SanitizerConfig-Instanz spezifiziert werden.
Der einfachste Weg, die Eigenschaft zu verwenden, besteht darin, ein Array von Elementnamen anzugeben:
Sie können jedoch auch jedes der erlaubten Elemente mit einem Objekt spezifizieren, das seinen name und namespace definiert, wie unten gezeigt (der Sanitizer wird automatisch einen Namespace ableiten, wenn er dazu in der Lage ist).
Sie können die Elemente auch einem Sanitizer mit Sanitizer.allowElement() hinzufügen. Hier fügen wir dieselben Elemente einem leeren Sanitizer hinzu:
Um Attribute global auf allen Elementen zu erlauben, wo es die HTML-Spezifikation erlaubt, können Sie die attributes-Eigenschaft der SanitizerConfig verwenden.
Der einfachste Weg, die attributes-Eigenschaft zu verwenden, besteht darin, ein Array von Attributnamen zu spezifizieren:
Sie können auch jedes Attribut mit den name- und namespace-Eigenschaften spezifizieren, genau wie Elemente:
Sie können auch jedes der erlaubten Attribute einem Sanitizer mit der Methode Sanitizer.allowAttribute() hinzufügen:
Sie können auch Attribute auf einem bestimmten Element erlauben oder entfernen. Beachten Sie, dass dies Teil einer „Erlauben-Konfiguration“ ist, da Sie in diesem Fall dennoch erlauben, dass das Element eingefügt wird.
Um ein Attribut auf einem Element zu erlauben, können Sie das Element als Objekt mit den Eigenschaften name und attributes spezifizieren. Die attributes-Eigenschaft enthält ein Array der auf dem Element erlaubten Attribute.
Unten zeigen wir einen Sanitizer, bei dem die <div>, <a> und <span>-Elemente erlaubt sind und das <a>-Element zusätzlich die Attribute href, rel, hreflang und type erlaubt.
Ähnlich können wir die Attribute, die auf einem Element nicht erlaubt sind, mit einem Elementobjekt mit der removeAttributes-Eigenschaft spezifizieren. Zum Beispiel würde der folgende Sanitizer das type-Attribut von allen <a>-Elementen entfernen.
In beiden Fällen können Sie auch jedes Attribut als Objekt mit den Eigenschaften name und namespace spezifizieren. Sie können auch die Attribut-Eigenschaften mit demselben Elementobjekt setzen, das an Sanitizer.allowElement() übergeben wird.
Beachten Sie, dass es unmöglich ist, ein Verhalten pro Element-Attribut auf einem Sanitizer mit einer Entfernungs-Konfiguration zu definieren, da das (nötige) elements-Array nicht vorhanden ist. Andere Einschränkungen zu pro Element-Attributen werden in Gültige Konfigurationen behandelt.
Sie können ein Array von Elementen angeben, die durch ihren inneren Inhalt ersetzt werden sollen. Dies wird am häufigsten verwendet, um Stile von Elementen zu entfernen.
Zum Beispiel verwendet der folgende Code die replaceWithChildrenElements-Eigenschaft der SanitizerConfig, um anzugeben, dass das <b>-Element ersetzt werden soll:
Wie bei Elementen und Attributen können Sie auch die Ersetzungselemente mit einem Namespace spezifizieren oder die Methode Sanitizer.replaceElementWithChildren() verwenden:
Sie können eine „Entfernungs“ Sanitizer-Konfiguration erstellen, indem Sie die Menge an HTML-Elementen und -Attributen spezifizieren, die aus der Eingabe entfernt werden sollen, wenn Sie den Sanitizer verwenden. Alle anderen Elemente und Attribute sind durch die Konfiguration erlaubt, obwohl sie entfernt werden können, wenn Sie die Konfiguration in einer sicheren Bereinigung verwenden.
Hinweis: Eine Sanitizer-Konfiguration kann Erlauben-Listen oder Entfernen-Listen enthalten, aber nicht beides.
Zum Beispiel entfernt die folgende Konfiguration die <script>, <div> und <span>-Elemente und auch das onclick-Attribut.
Die Spezifizierung von Elementen zur Entfernung ist nützlicher, wenn Sie eine bestehende Konfiguration anpassen möchten. Zum Beispiel betrachten Sie den Fall, in dem wir den (sicheren) Standard-Sanitizer verwenden, aber auch sicherstellen wollen, dass einige andere Elemente entfernt werden.
Die removeElements-Eigenschaft einer SanitizerConfig-Instanz kann verwendet werden, um die zu entfernenden Elemente zu spezifizieren.
Der einfachste Weg, die Eigenschaft zu verwenden, besteht darin, ein Array von Elementnamen zu spezifizieren:
Wie beim Erlauben von Elementen können Sie auch jedes der zu entfernenden Elemente mit einem Objekt spezifizieren, das seinen name und namespace definiert. Sie können auch die entfernten Elemente mit Hilfe der Sanitizer-API wie gezeigt konfigurieren:
Die removeElements-Eigenschaft der SanitizerConfig kann verwendet werden, um Attribute anzugeben, die global entfernt werden sollen.
Der einfachste Weg, die Eigenschaft zu verwenden, besteht darin, ein Array von Elementnamen zu spezifizieren:
Sie können auch jedes der Elemente mit einem Objekt spezifizieren, das seinen name und namespace definiert, und auch Sanitizer.removeAttribute() verwenden, um ein Attribut hinzuzufügen, das von allen Elementen entfernt werden soll.
Die SanitizerConfig kann auch verwendet werden, um zu spezifizieren, ob Kommentare aus injizieren Inhalten gefiltert werden sollen, unter Verwendung der comments-Eigenschaft, und ob data--Attribute erlaubt sind, ohne dass sie der attributes-Liste hinzugefügt werden müssen, mit der booleschen Eigenschaft dataAttributes.
Um Kommentare und alle data-*-Attribute zu erlauben, könnten Sie eine Konfiguration wie diese verwenden:
Sie können die Kommentare und Daten-Attribut-Eigenschaften auch auf einem bestehenden Sanitizer mit Sanitizer.setComments() und Sanitizer.setDataAttributes() setzen:
Allen Bereinigungsmethoden kann eine Sanitizer-Konfiguration übergeben werden, die entweder eine Sanitizer oder SanitizerConfig-Instanz ist.
Die SanitizerConfig bietet eine kompakte Methode zur Spezifizierung mehrerer Elemente oder Attribute, die gleichzeitig erlaubt oder entfernt werden sollen. Es kann einige Vorsicht erforderlich sein, wenn Sie dieses Objekt ändern, um sicherzustellen, dass es eine gültige Konfiguration bleibt.
Das Sanitizer-Objekt ist ein Wrapper um SanitizerConfig, der zusätzliche nützliche Funktionalität bietet:
Beachten Sie, dass wenn Sie die sicheren Bereinigungsmethoden verwenden können, dann müssen Sie möglicherweise keine Sanitizer-Konfiguration definieren.
Weitere Beispiele finden Sie in der HTML Sanitizer API und den einzelnen Methoden der Sanitizer-Schnittstelle.
Dieses Beispiel zeigt, wie Sie die Sanitizer-Methoden verwenden können, um einen Sanitizer zu aktualisieren. Das Ergebnis ist eine Demonstrationsschnittstelle, in der Sie Elemente und Attribute zu den Erlaubens- und Entfernungslisten hinzufügen können und ihre Auswirkungen sehen, wenn der Sanitizer mit Element.setHTML() und Element.setHTMLUnsafe() verwendet wird.
Zuerst definieren wir Schaltflächen, um den Standard-Sanitizer oder einen leeren Sanitizer zurückzusetzen.
Es folgen <select>-Elemente, die es Benutzern ermöglichen, Elemente auszuwählen, die zu den Erlaubens- und Entfernungslisten für Elemente und Attribute hinzugefügt werden sollen.
Dann fügen wir Schaltflächen hinzu, um zu toggeln, ob Kommentare und Datenattribute erlaubt oder entfernt werden.
Die übrigen Elemente zeigen die zu parsende Zeichenkette (editierbar) und das Ergebnis dieser beiden Zeichenketten, wenn sie in ein Element mit setHTML() und setHMLUnsafe() injiziert werden:
Der Code testet zunächst, ob die Sanitizer-Schnittstelle unterstützt wird. Anschließend definiert er eine Zeichenkette aus „unsicherem HTML“, die eine Mischung aus XSS-sicheren und XSS-unsicheren Elementen (wie <script>) enthält. Diese wird als Text in das erste Textfeld eingefügt. Der Textbereich ist editierbar, sodass Benutzer den Text später nach Bedarf ändern können.
Wir holen uns dann die Elemente für die setHTML und setHTMLUnsafe Textbereịche, in die wir das geparste HTML schreiben werden, und erstellen eine leere Sanitizer-Konfiguration. Die Methode applySanitizer() wird mit dem neuen Sanitizer aufgerufen, um das Ergebnis der Bereinigung der initialen Zeichenkette mit einem sicheren und unsicheren Sanitizer zu protokollieren.
Die applySanitizer()-Protokollierungsmethode wird unten gezeigt. Diese holt den initialen Inhalt der „untrusted string“ aus dem ersten Textbereich und parst ihn mit den Methoden Element.setHTML() und Element.setHTMLUnsafe() mit dem übergebenen sanitizer-Argument in die jeweiligen Textbereiche. In beiden Fällen wird das injizierte HTML dann vom Element mit innerHTML gelesen und als innerText (sodass es menschlich lesbar ist) zurück in das Element geschrieben.
Der Code protokolliert dann die aktuelle Sanitizer-Konfiguration, die er mit Sanitizer.get() erhält.
Anschließend holen wir uns die Elemente für jede der Schaltflächen und Auswahllisten.
Die Handler für die ersten beiden Schaltflächen erstellen jeweils den Standارد- und leeren Sanitizer. Die Methode applySanitizer(), die wir vorher gezeigt haben, wird verwendet, um den Sanitizer auszuführen und die Protokolle zu aktualisieren.
Die Handler für die Auswahllisten werden als nächstes gezeigt. Diese rufen die zugehörige Sanitizer-Methode auf dem aktuellen Sanitizer auf, wenn ein neues Element oder Attribut ausgewählt wird. Zum Beispiel ruft der Listener für die allowElementSelect Sanitizer.allowElement() auf, um das ausgewählte Element den erlaubten Elementen hinzuzufügen. In jedem Fall protokolliert applySanitizer() die Ergebnisse mit dem aktuellen Sanitizer.
Die Handler für die letzten beiden Schaltflächen sind unten gezeigt. Diese toggeln den Wert der dataAttributesActive und commentsActive Variablen und verwenden diese Werte in Sanitizer.setComments() und Sanitizer.setDataAttributes(). Beachten Sie, dass wenn die Kommentare initial deaktiviert sind, der erste Druck auf die Schaltfläche möglicherweise keine Wirkung zeigt!
Das Ergebnis wird unten gezeigt. Wählen Sie die oberen Schaltflächen aus, um einen neuen Standard- oder leeren Sanitizer zu setzen. Sie können dann die Auswahllisten verwenden, um einige Elemente und Attribute zu den jeweiligen Erlauben- und Entfernen-Listen des Sanitizers hinzuzufügen, und die anderen Schaltflächen, um Kommentare ein- und auszuschalten. Die aktuelle Sanitizer-Konfiguration wird protokolliert. Der Text im oberen Textbereich wird mit der aktuellen Sanitizer-Konfiguration bereinigt und mit setHTML() und setHTMLUnsafe() geparst.
Beachten Sie, dass das Hinzufügen von Elementen und Attributen zu den Erlauben-Listen sie aus den Entfernen-Listen entfernt, und umgekehrt. Beachten Sie auch, dass Sie Elemente in einem Sanitizer zulassen können, die mit den unsicheren Methoden injiziert werden, aber nicht mit den sicheren Methoden.
Der Bauplan für ein besseres Internet.
Besuche die gemeinnützige Muttergesellschaft der Mozilla Corporation, die Mozilla Foundation.
Teile dieses Inhalts sind ©1998–2026 von einzelnen mozilla.org-Mitwirkenden. Inhalte sind verfügbar unter einer Creative-Commons-Lizenz.