Der häufigste Anwendungsfall für die API ist das sichere Einfügen eines von Benutzern bereitgestellten Strings in einElement. Sofern der einzufügende Stringkeine unsicheren HTML-Entitäten enthalten muss, können SieElement.setHTML() als Ersatz fürElement.innerHTML verwenden.

Zum Beispiel wird der folgende Code alle XSS-unsicheren Elemente und Attribute im Eingabestring entfernen (in diesem Fall das<script>-Element) sowie alle Elemente, die laut HTML-Spezifikation nicht als Kinder des Ziel-Elements erlaubt sind:

const untrustedString = "abc <script>alert(1)<" + "/script> def";const someTargetElement = document.getElementById("target");// someElement.innerHTML = untrustedString;someElement.setHTML(untrustedString);console.log(target.innerHTML); // abc def

Die anderen XSS-sicheren Methoden,ShadowRoot.setHTML() undDocument.parseHTML(), werden auf die gleiche Weise verwendet.

Sie können die HTML-Entitäten angeben, die Sie zulassen oder entfernen möchten, indem Sie einenSanitizer als zweiten Parameter an alle Sanitizer-Methoden übergeben.

Zum Beispiel, wenn Sie wissen, dass nur<p>- und<a>-Elemente im Kontext von „someElement“ unten erwartet werden, können Sie eine Sanitizer-Konfiguration erstellen, die nur diese Elemente zulässt:

sanitizerOne = Sanitizer({ elements: ["p", "a"] });sanitizerOne.allowAttribute("href");someElement.setHTML(untrustedString, { sanitizer: sanitizerOne });

Beachten Sie jedoch, dass unsichere HTML-Entitäten immer entfernt werden, wenn Sie die sicheren Methoden verwenden. Bei Verwendung mit den sicheren Methoden wird eine freizügige Sanitizer-Konfiguration entweder dieselben oder weniger Entitäten als die Standardkonfiguration zulassen.

Manchmal möchten Sie möglicherweise Eingaben einfügen, die potenziell unsichere Elemente oder Attribute enthalten müssen. In diesem Fall können Sie eine der API-Methoden verwenden, die für XSS-Unsicherheit nicht sicher sind:Element.setHTMLUnsafe(),ShadowRoot.setHTMLUnsafe(), undDocument.parseHTMLUnsafe().

Ein übliches Vorgehen ist, mit dem Standardsanitizer zu beginnen, der nur sichere Elemente zulässt, und dann nur die unsicheren Entitäten zu erlauben, die wir in der Eingabe erwarten.

Zum Beispiel werden im folgenden Sanitizer alle sicheren Elemente zugelassen, und wir erlauben darüber hinaus nur den unsicherenonclick-Handler aufbutton-Elementen:

const untrustedString = '<button>Button text</button>';const someTargetElement = document.getElementById("target");sanitizerOne = Sanitizer(); // Default sanitizersanitizerOne.allowElement({ name: "button", attributes: ["onclick"] });someElement.setHTMLUnsafe(untrustedString, { sanitizer: sanitizerOne });

Mit diesem Code wäre dasalert(1) erlaubt, und es besteht ein potenzielles Problem, dass das Attribut für böswillige 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 kümmern müssen und andere Maßnahmen ergreifen können.

Die unsicheren Methoden verwenden jede von Ihnen bereitgestellte Sanitizer-Konfiguration (oder keine), daher müssen Sie vorsichtiger sein als bei der Verwendung der sicheren Methoden.

Sie können eine"Allow"-Sanitizer-Konfiguration erstellen, indem Sie nur die Menge an HTML-Elementen und Attributen angeben, die Sie beim Verwenden des Sanitizers zulassen möchten. Diese Form der Konfiguration ist leicht verständlich und nützlich, wenn Sie genau wissen, welche HTML-Entitäten im Zielkontext erlaubt sein sollten.

Zum Beispiel erlaubt die folgende Konfiguration die<p>- und<div>-Elemente sowie die Attributecite undonclick. Außerdem ersetzt sie<b>-Elemente durch ihren Inhalt (dies ist eine Form des „Zulassens“, da der Inhalt des Elements nicht entfernt wird).

const sanitizer = Sanitizer({  elements: ["p", "div"],  attributes: ["cite", "onclick"],  replaceWithChildrenElements: ["b"],});

Die erlaubten Elemente können mit derelements-Eigenschaft derSanitizerConfig-Instanz angegeben werden, die demSanitizer()-Konstruktor übergeben wird (oder direkt den Bereinigungsmethoden).

Der einfachste Weg, die Eigenschaft zu verwenden, besteht darin, ein Array von Elementnamen anzugeben:

const sanitizer = Sanitizer({  elements: ["div", "span"],});

Sie können jedoch auch jedes der erlaubten Elemente mithilfe eines Objekts angeben, das seinenname undnamespace definiert, wie unten gezeigt (derSanitizer wird automatisch ein Namespace ableiten, wenn dies möglich ist).

const sanitizer = Sanitizer({  elements: [    {      name: "div",      namespace: "http://www.w3.org/1999/xhtml",    },    {      name: "span",      namespace: "http://www.w3.org/1999/xhtml",    },  ],});

Sie können die Elemente über die API demSanitizer hinzufügen. Hier fügen wir die gleichen Elemente zu einem leeren Sanitizer hinzu:

const sanitizer = Sanitizer({});sanitizer.allowElement("div");sanitizer.allowElement({  name: "span",  namespace: "http://www.w3.org/1999/xhtml",});

Um Attribute global, auf jedem Element, das durch die HTML-Spezifikation erlaubt ist, zuzulassen, können Sie dieattributes-Eigenschaft derSanitizerConfig verwenden.

Der einfachste Weg, dieattributes-Eigenschaft zu verwenden, besteht darin, ein Array von Attributnamen anzugeben:

const sanitizer = Sanitizer({  attributes: ["cite", "onclick"],});

Ebenso können Sie jedes Attribut mit denname- undnamespace-Eigenschaften genauso wie Elemente spezifizieren:

const sanitizer = Sanitizer({  attributes: [    {      name: "cite",      namespace: null,    },    {      name: "onclick",      namespace: null,    },  ],});

Sie können auch jedes der erlaubten Attribute mithilfe derallowAttribute()-Methode desSanitizer hinzufügen:

const sanitizer = Sanitizer({});sanitizer.allowAttribute("cite");sanitizer.allowAttribute("onclick");

Sie können auch Attribute an einem bestimmten Element erlauben oder entfernen. Beachten Sie, dass dies Teil einer „Allow-Konfiguration“ ist, da Sie in diesem Fall das Element weiterhin zur Injektion zulassen.

Um ein Attribut an einem Element zu erlauben, können Sie das Element als Objekt mit den Eigenschaftenname undattributes angeben. Dieattributes-Eigenschaft enthält ein Array der an 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 Attributehref,rel,hreflang undtype zulässt.

const sanitizer = Sanitizer({  elements: [    "div",    { name: "a", attributes: ["href", "rel", "hreflang", "type"] },    "span",  ],});

Genauso können wir Attribute, die an einem Element nicht erlaubt sind, mithilfe eines Elementobjekts mit derremoveAttributes-Eigenschaft angeben. Zum Beispiel würde der folgende Sanitizer dastype-Attribut von allen<a>-Elementen entfernen.

const sanitizer = Sanitizer({  elements: ["div", { name: "a", removeAttributes: ["type"] }],});

In beiden Fällen können Sie auch jedes Attribut als Objekt mitname- undnamespace-Eigenschaften angeben. Sie können auch die Attribut-Eigenschaften mithilfe des gleichen Elementobjekts festlegen, das anSanitizer.allowElement() übergeben wird.

Beachten Sie jedoch, dass Sie nicht sowohl Element-Attribute als auchremoveAttributes in einem Aufruf angeben können. Der Versuch, dies zu tun, führt zu einer Ausnahme.

Sie können ein Array von Elementen angeben, die durch ihren inneren Inhalt ersetzt werden sollen. Dies wird am häufigsten verwendet, um Styles von Elementen zu entfernen.

Zum Beispiel verwendet der folgende Code diereplaceWithChildrenElements-Eigenschaft derSanitizerConfig um zu spezifizieren, dass das<b>-Element ersetzt werden sollte:

const replaceBoldSanitizer = Sanitizer({  replaceWithChildrenElements: ["b"],});targetElement.setHTML("This <b>highlighting</b> isn't needed", {  sanitizer: replaceBoldSanitizer,});// Log the resulttargetElement.log(targetElement.innerHTML); // This highlighting isn't needed

Wie bei Elementen und Attributen können Sie die Ersatzelemente auch mit einem Namespace spezifizieren oder dieSanitizer.replaceElementWithChildren()-Methode verwenden:

const sanitizer = Sanitizer({});sanitizer.replaceElementWithChildren("b");sanitizer.replaceElementWithChildren({  name: "i",  namespace: "http://www.w3.org/1999/xhtml",});

Sie können eine"Remove"-Sanitizer-Konfiguration erstellen, indem Sie die Menge an HTML-Elementen und Attributen angeben, die Sie aus der Eingabe entfernen möchten, 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 Bereinigungsmethode verwenden.

Zum Beispiel entfernt die folgende Konfiguration die<script>,<div>, und<span>-Elemente und auch dasonclick-Attribut.

const sanitizer = Sanitizer({  removeElements: ["script", "div", "span"],  removeAttributes: ["onclick"],});

Elemente zu entfernen ist nützlicher, wenn Sie eine bestehende Konfiguration anpassen möchten. Betrachten Sie zum Beispiel den Fall, dass wir den (sicheren) Standardsanitizer verwenden, aber auch sicherstellen möchten, dass

const sanitizer = Sanitizer();sanitizer.removeElement("div");const sanitizer = Sanitizer({  removeElements: ["script", "div", "span"],  removeAttributes: ["onclick"],});

DieremoveElements-Eigenschaft einerSanitizerConfig-Instanz kann verwendet werden, um die zu entfernenden Elemente anzugeben.

Der einfachste Weg, die Eigenschaft zu verwenden, besteht darin, ein Array von Elementnamen anzugeben:

const sanitizer = Sanitizer({  removeElements: ["div", "span"],});

Wie beimErlauben von Elementen können Sie jedes der zu entfernenden Elemente auch mit einem Objekt spezifizieren, das seinenname undnamespace definiert. Sie können die entfernten Elemente auch mithilfe derSanitizer-API konfigurieren, wie gezeigt:

const sanitizer = Sanitizer({});sanitizer.removeElement("div");sanitizer.removeElement({  name: "span",  namespace: "http://www.w3.org/1999/xhtml",});

DieremoveElements-Eigenschaft derSanitizerConfig kann verwendet werden, um Attribute anzugeben, die global entfernt werden sollen.

Der einfachste Weg, die Eigenschaft zu verwenden, besteht darin, ein Array von Elementnamen anzugeben:

const sanitizer = Sanitizer({  removeAttributes: ["onclick", "lang"],});

Sie können jedes der Elemente auch mithilfe eines Objekts angeben, das seinenname undnamespace definiert, und auchSanitizer.removeAttribute() verwenden, um ein Attribut hinzuzufügen, das aus allen Elementen entfernt werden soll.

const sanitizer = Sanitizer({});sanitizer.removeAttribute("onclick");sanitizer.removeAttribute("lang");

DieSanitizerConfig kann auch verwendet werden, um anzugeben, ob Kommentare unddata--Attribute aus eingefügtem Inhalt gefiltert werden sollen, mithilfe der Eigenschaftencomments unddataAttributes.

Um sowohl Kommentare als auch Datenattribute zu erlauben, könnten Sie eine Konfiguration wie diese verwenden:

const sanitizer = Sanitizer({  comments: true,  dataAttributes: true,});

Sie können auch Kommentare oder Datenattribute auf einem bestehenden Sanitizer mit den MethodenSanitizer.setComments() undSanitizer.setDataAttributes() aktivieren oder deaktivieren:

const sanitizer = Sanitizer({});sanitizer.setComments(true);sanitizer.setDataAttributes(true);

Alle Bereinigungsmethoden können mit einer Sanitizer-Konfiguration, die entweder eineSanitizer oder eineSanitizerConfig-Instanz ist, verwendet werden.

DasSanitizer-Objekt ist eine Hülle umSanitizerConfig, die zusätzliche nützliche Funktionalität bietet:

• Der Standardkonstruktor erzeugt eine Konfiguration, die alle XSS-sicheren Elemente und Attribute zulässt und daher einen guten Ausgangspunkt für die Erstellung von entweder etwas mehr oder etwas weniger restriktiven Sanitisern darstellt.
• Wenn Sie die Methoden verwenden, um HTML-Entitäten zu erlauben oder zu entfernen, werden die Entitäten aus den „entgegengesetzten“ Listen entfernt. Diese Normalisierungen machen die Konfiguration effizienter.
• Die MethodeSanitizer.removeUnsafe() kann verwendet werden, um alle XSS-unsicheren Entitäten aus einer bestehenden Konfiguration zu entfernen.
• Sie können die Konfiguration exportieren, um genau zu sehen, welche Entitäten erlaubt und entfernt werden.

Beachten Sie jedoch, dass Sie möglicherweise keine Sanitizer-Konfiguration definieren müssen, wenn Sie die sicheren Bereinigungsmethoden verwenden können.

Für weitere Beispiele siehe dieHTML Sanitizer API und die einzelnen Methoden derSanitizer-Schnittstelle.

Dieses Beispiel zeigt, wie Sie dieSanitizer-Methoden verwenden können, um einen Sanitizer zu aktualisieren. Das Ergebnis ist eine Demonstrationsschnittstelle, bei der Sie Elemente und Attribute zu den Allow- und Remove-Listen hinzufügen können und deren Auswirkungen sehen, wenn der Sanitizer mitElement.setHTML() undElement.setHTMLUnsafe() verwendet wird.

HTML

Zuerst definieren wir Schaltflächen, um den Standardsanitizer oder einen leeren Sanitizer zurückzusetzen.

<div>  <button>Default Sanitizer</button>  <button>Empty Sanitizer</button></div>

Dies wird gefolgt von<select>-Elementen, um Benutzern die Möglichkeit zu geben, Elemente auszuwählen, die zu den Allow- und Remove-Listen für Elemente und Attribute hinzugefügt werden sollen.

<div>  <label for="allowElementSelect">allowElement:</label>  <select>    <option value="">--Choose element--</option>    <option value="h1">h1</option>    <option value="div">div</option>    <option value="span">span</option>    <option value="script">script</option>    <option value="p">p</option>    <option value="button">button</option>    <option value="img">img</option>  </select>  <label for="removeElementSelect">removeElement:</label>  <select>    <option value="">--Choose element--</option>    <option value="h1">h1</option>    <option value="div">div</option>    <option value="span">span</option>    <option value="script">script</option>    <option value="p">p</option>    <option value="button">button</option>    <option value="img">img</option>  </select></div><div>  <label for="allowAttributeSelect">allowAttribute:</label>  <select>    <option value="">--Choose attribute--</option>    <option value="class">class</option>    <option value="autocapitalize">autocapitalize</option>    <option value="hidden">hidden</option>    <option value="lang">lang</option>    <option value="title">title</option>    <option value="onclick">onclick</option>  </select>  <label for="removeAttributeSelect">removeAttribute:</label>  <select>    <option value="">--Choose attribute--</option>    <option value="class">class</option>    <option value="autocapitalize">autocapitalize</option>    <option value="hidden">hidden</option>    <option value="lang">lang</option>    <option value="title">title</option>    <option value="onclick">onclick</option>  </select></div>

Dann fügen wir Schaltflächen hinzu, um Kommentare und Datenattribute zum Erlauben/Entfernen zu wechseln.

<div>  <button>Toggle comments</button>  <button>Toggle data-attributes</button></div>

Die verbleibenden Elemente zeigen den zu parsenen String (editierbar) und das Ergebnis dieser beiden Strings, wenn sie jeweils in ein Element mittelssetHTML() undsetHTMLUnsafe() eingefügt werden:

<div>  <p>Original string (Editable)</p>  <pre contenteditable></pre>  <p>setHTML() (HTML as string)</p>  <pre></pre>  <p>setHTMLUnsafe() (HTML as string)</p>  <pre></pre></div>

<pre></pre>

#log {  height: 430px;  overflow: scroll;  padding: 0.5rem;  border: 1px solid black;}

JavaScript

const logElement = document.querySelector("#log");function log(text) {  logElement.textContent = text;}

Der Code testet zuerst, ob dieSanitizer-Schnittstelle unterstützt wird. Danach wird ein String von „unsicherem HTML“ definiert, der eine Mischung aus XSS-sicheren und XSS-unsicheren Elementen (wie<script>) enthält. Dieses wird als Text in das erste Textfeld eingefügt. Das Textfeld ist editierbar, sodass Nutzer den Text später bei Bedarf ändern können.

Wir erhalten dann die Elemente für diesetHTML- undsetHTMLUnsafe-Textfelder, wo wir das geparste HTML schreiben, und erstellen eine leereSanitizer-Konfiguration. DieapplySanitizer()-Methode wird mit dem neuen Sanitizer aufgerufen, um das Ergebnis der Bereinigung des Startstrings durch einen sicheren und unsicheren Sanitizer zu protokollieren.

if ("Sanitizer" in window) {  // Define unsafe string of HTML  const initialHTMLString =    `<div><!-- HTML comment -->    <p data-test="true">This is a paragraph. <button>Click me</button></p>    <p>Be <b>bold</b> and brave!</p>    <script>alert(1)<` + "/script></div>";  // Set unsafe string as a text node of first element  const unmodifiedElement = document.querySelector("#unmodified");  unmodifiedElement.innerText = initialHTMLString;  unsafeHTMLString = unmodifiedElement.innerText;  const setHTMLElement = document.querySelector("#setHTML");  const setHTMLUnsafeElement = document.querySelector("#setHTMLUnsafe");  // Create and apply default sanitizer when we start  let sanitizer = new Sanitizer({});  applySanitizer(sanitizer);

Die protokollierendeapplySanitizer()-Methode wird unten gezeigt. Diese erhält den ursprünglichen Inhalt des „untrusted string“ aus dem ersten Textfeld und parst ihn unter Verwendung der MethodenElement.setHTML() undElement.setHTMLUnsafe() mit dem übergebenensanitizer-Argument in die jeweiligen Textfelder. In jedem Fall wird das eingefügte HTML dann überinnerHTML aus dem Element gelesen und wieder alsinnerText in das Element geschrieben (sodass es menschlich lesbar ist).

Der Code protokolliert dann die aktuelle Sanitizer-Konfiguration, die er mitSanitizer.get() erhält.

function applySanitizer(sanitizer) {  // Get string to parse into element  unsafeHTMLString = unmodifiedElement.innerText;  // Sanitize string using safe method and then display as text  setHTMLElement.setHTML(unsafeHTMLString, { sanitizer });  setHTMLElement.innerText = setHTMLElement.innerHTML;  // Sanitize string using unsafe method and then display as text  setHTMLUnsafeElement.setHTMLUnsafe(unsafeHTMLString, { sanitizer });  setHTMLUnsafeElement.innerText = setHTMLUnsafeElement.innerHTML;  // Display sanitizer configuration  const sanitizerConfig = sanitizer.get();  log(JSON.stringify(sanitizerConfig, null, 2));}

Als nächstes erhalten wir Elemente für jede der Schaltflächen und Auswahllisten.

const defaultSanitizerBtn = document.querySelector("#defaultSanitizerBtn");const emptySanitizerBtn = document.querySelector("#emptySanitizerBtn");const allowElementSelect = document.querySelector("#allowElementSelect");const removeElementSelect = document.querySelector("#removeElementSelect");const allowAttributeSelect = document.querySelector("#allowAttributeSelect");const removeAttributeSelect = document.querySelector("#removeAttributeSelect");const toggleCommentsBtn = document.querySelector("#toggleCommentsBtn");const toggleDataAttributesBtn = document.querySelector(  "#toggleDataAttributesBtn",);

Die Handler für die ersten beiden Schaltflächen erstellen jeweils den Standard- und leeren Sanitizer. Die vorher gezeigteapplySanitizer()-Methode wird verwendet, um den Sanitizer auszuführen und die Protokolle zu aktualisieren.

defaultSanitizerBtn.addEventListener("click", () => {  sanitizer = new Sanitizer();  applySanitizer(sanitizer);});emptySanitizerBtn.addEventListener("click", () => {  sanitizer = new Sanitizer({});  applySanitizer(sanitizer);});

Die Handler für die Auswahllisten werden als nächstes gezeigt. Diese rufen die zugehörige Sanitizer-Methode am aktuellen Sanitizer auf, sobald ein neues Element oder Attribut ausgewählt wird. Beispielsweise ruft der Listener fürallowElementSelectSanitizer.allowElement() auf, um das ausgewählte Element zu den erlaubten Elementen hinzuzufügen. In jedem Fall protokolliertapplySanitizer() die Ergebnisse mit dem aktuellen Sanitizer.

allowElementSelect.addEventListener("change", (event) => {  if (event.target.value !== "") {    sanitizer.allowElement(event.target.value);    applySanitizer(sanitizer);  }});removeElementSelect.addEventListener("change", (event) => {  if (event.target.value !== "") {    sanitizer.removeElement(event.target.value);    applySanitizer(sanitizer);  }});allowAttributeSelect.addEventListener("change", (event) => {  if (event.target.value !== "") {    sanitizer.allowAttribute(event.target.value);    applySanitizer(sanitizer);  }});removeAttributeSelect.addEventListener("change", (event) => {  if (event.target.value !== "") {    sanitizer.removeAttribute(event.target.value);    applySanitizer(sanitizer);  }});

Die Handler für die letzten beiden Schaltflächen sind unten gezeigt. Diese wechseln den Wert der VariablendataAttributesActive undcommentsActive und verwenden dann diese Werte inSanitizer.setComments() undSanitizer.setDataAttributes(). Beachten Sie, dass, wenn die Kommentare anfänglich deaktiviert sind, das erste Drücken der Schaltfläche keine Wirkung haben könnte!

let dataAttributesActive = true;let commentsActive = true;toggleCommentsBtn.addEventListener("click", () => {  commentsActive = !commentsActive;  sanitizer.setComments(commentsActive);  applySanitizer(sanitizer);});toggleDataAttributesBtn.addEventListener("click", () => {  dataAttributesActive = !dataAttributesActive;  sanitizer.setDataAttributes(dataAttributesActive);  applySanitizer(sanitizer);});} else {  log("The HTML Sanitizer API is NOT supported in this browser.");  // Provide fallback or alternative behavior}

Ergebnisse

Das Ergebnis ist unten dargestellt. Wählen Sie die oberen Schaltflächen, um jeweils einen neuen Standard- oder leeren Sanitizer festzulegen. Sie können dann die Auswahllisten verwenden, um einige Elemente und Attribute zu den jeweiligen Allow- und Remove-Listen des Sanitizers hinzuzufügen und mit den anderen Schaltflächen Kommentare ein- und auszuschalten. Die aktuelle Sanitizer-Konfiguration wird protokolliert. Der Text im oberen Textbereich wird mit der aktuellen Sanitizer-Konfiguration bereinigt und mitsetHTML() undsetHTMLUnsafe() geparst.

Beachten Sie, dass das Hinzufügen von Elementen und Attributen zu den Allow-Listen sie aus den Remove-Listen entfernt und umgekehrt. Beachten Sie auch, dass Sie Elemente in einem Sanitizer erlauben können, die mit den unsicheren Methoden, aber nicht mit den sicheren Methoden injiziert werden.