DiesetHTMLUnsafe()-Methode desElement-Interfaces wird verwendet, um HTML-Eingaben in einDocumentFragment zu analysieren, wobei optionale Filter unerwünschte Elemente und Attribute sowie diejenigen, die im Kontext nicht zulässig sind, herausfiltern, und dann damit den Teilbaum des Elements im DOM zu ersetzen.

Syntax

setHTMLUnsafe(input)setHTMLUnsafe(input, options)

Parameter

input

EineTrustedHTML-Instanz oder ein String, der definiert, welches HTML analysiert werden soll.

optionsOptional

Ein Optionsobjekt mit den folgenden optionalen Parametern:

sanitizerOptional

EinSanitizer oderSanitizerConfig-Objekt, das definiert, welche Elemente der Eingabe erlaubt oder entfernt werden sollen.Dies kann auch ein String mit dem Wert"default" sein, was einenSanitizer mit der Standardkonfiguration (XSS-sicher) anwendet.Wenn nicht angegeben, wird kein Sanitizer verwendet.

Beachten Sie, dass einSanitizer im Allgemeinen effizienter ist als eineSanitizerConfig, vorausgesetzt, dass die Konfiguration wiederverwendet wird.

Rückgabewert

Keiner (undefined).

Ausnahmen

TypeError

Wird geworfen, wenn:

• input einen String erhält, wennTrusted Typesdurch eine CSP durchgesetzt werden und keine Standardrichtlinie definiert ist.
• options.sanitizer einen übergebenen:
  • SanitizerConfig, der nichtgültig ist.Zum Beispiel eine Konfiguration, die sowohl "allowed" als auch "removed" Konfigurationseinstellungen enthält.
  • String, der nicht den Wert"default" hat.
  • Wert, der weder einSanitizer,SanitizerConfig noch ein String ist.

Beschreibung

DiesetHTMLUnsafe()-Methode wird verwendet, um eine HTML-Eingabe in einDocumentFragment zu analysieren, wobei unerwünschte Elemente und Attribute optional bereinigt werden, und Elemente verworfen werden, die das HTML-Spezifikation im Ziel-Element nicht erlaubt (wie<li> innerhalb eines<div>).DasDocumentFragment wird dann verwendet, um den Teilbaum des Elements im DOM zu ersetzen.

Im Gegensatz zuElement.innerHTML werdendeklarative Schattenwurzeln in der Eingabe in das DOM analysiert.Wenn der HTML-String mehr als einedeklarative Schattenwurzel in einem bestimmten Schatten-Host definiert, wird nur die ersteShadowRoot erstellt — nachfolgende Deklarationen werden als<template> Elemente innerhalb der Schattenwurzel analysiert.

setHTMLUnsafe() führt standardmäßig keine Bereinigung durch.Wenn kein Sanitizer als Parameter übergeben wird, werden alle HTML-Entitäten in die Eingabe eingebettet.Es ist daher potenziell sogar weniger sicher alsElement.innerHTML, das bei der Analyse die Markierung<script> deaktiviert.

Sicherheitsüberlegungen

Das Suffix "Unsafe" im Methodennamen weist darauf hin, dass es nicht die Entfernung aller XSS-gefährlichen HTML-Entitäten erzwingt (im Gegensatz zuElement.setHTML()).Obwohl es so sein kann, wenn es mit einem geeigneten Sanitizer verwendet wird, muss es nicht unbedingt einen effektiven Sanitizer verwenden oder überhaupt einen verwenden!Die Methode ist daher ein möglicher Vektor fürCross-Site Scripting (XSS)-Angriffe, bei denen potenziell unsichere Strings, die von einem Benutzer bereitgestellt werden, in das DOM eingefügt werden, ohne vorher bereinigt zu werden.

Sie sollten dieses Risiko mindern, indem Sie immerTrustedHTML-Objekte anstelle von Strings verwenden undTrusted Types mit derrequire-trusted-types-for CSP-Direktive durchsetzen.Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geführt wird, die die Möglichkeit hat, die Eingabe zubereinigen, um potenziell gefährliche Markierungen (wie<script> Elemente und Ereignis-Handler-Attribute) zu entfernen, bevor sie eingebettet werden.

Die Verwendung vonTrustedHTML ermöglicht es, den Bereinigungscode auf nur wenige Stellen zu überprüfen und sicherzustellen, dass er effektiv ist, anstatt über alle Ihre Injection-Sinks verstreut zu sein.Wenn SieTrustedHTML verwenden, sollte es nicht nötig sein, einen Sanitizer an die Methode zu übergeben.

Wenn Sie aus irgendeinem Grund wederTrustedHTML (noch besser,setHTML()) verwenden können, dann ist die nächste sichere Option,setHTMLUnsafe() mit dem XSS-sicheren Standard-Sanitizer zu verwenden.

Wann solltesetHTMLUnsafe() verwendet werden?

setHTMLUnsafe() sollte fast nie verwendet werden, wennElement.setHTML() verfügbar ist, da es nur sehr wenige (wenn überhaupt) Fälle gibt, in denen benutzerdefinierte HTML-Eingaben unsichere XSS-Elemente enthalten müssen.Nicht nur istsetHTML() sicher, sondern es vermeidet auch die Berücksichtigung vertrauenswürdiger Typen.

Die Verwendung vonsetHTMLUnsafe() könnte angemessen sein, wenn:

• SiesetHTML() oder vertrauenswürdige Typen aus irgendeinem Grund nicht verwenden können und Sie das sicherste mögliche Filtern haben möchten.In diesem Fall könnten SiesetHTMLUnsafe() mit dem Standard-Sanitizer verwenden, um alle XSS-unsicheren Elemente zu filtern.

• SiesetHTML() nicht verwenden können und die Eingabe deklarative Schattenwurzeln enthalten kann, sodass SieElement.innerHTML nicht verwenden können.

• Sie einen Sonderfall haben, bei dem Sie HTML-Eingaben zulassen müssen, die eine bekannte Menge unsicherer HTML-Entitäten enthalten.

  Sie könnensetHTML() in diesem Fall nicht verwenden, da es alle unsicheren Entitäten entfernt.Sie könntensetHTMLUnsafe() ohne Sanitizer oderinnerHTML verwenden, aber das würde alle unsicheren Entitäten zulassen.

  Eine bessere Option hier ist,setHTMLUnsafe() mit einem Sanitizer aufzurufen, der nur diejenigen gefährlichen Elemente und Attribute erlaubt, die wir tatsächlich benötigen.Obwohl dies immer noch unsicher ist, ist es sicherer, als alle von ihnen zuzulassen.

Für den letzten Punkt sollten Sie eine Situation in Betracht ziehen, in der Ihr Code darauf angewiesen ist, unsichereonclick-Handler verwenden zu können.Der folgende Code zeigt die Auswirkungen der verschiedenen Methoden und Sanitizer für diesen Fall.

const target = document.querySelector("#target");const input = "<img src=x onclick=alert('onclick') onerror=alert('onerror')>";// Safe - removes all XSS-unsafe entities.target.setHTML(input);// Removes no event handler attributestarget.setHTMLUnsafe(input);target.innerHTML = input;// Safe - removes all XSS-unsafe entities.const configSafe = new Sanitizer();target.setHTMLUnsafe(input, { sanitizer: configSafe });// Removes all XSS-unsafe entities except `onclick`const configLessSafe = new Sanitizer();config.allowAttribute("onclick");target.setHTMLUnsafe(input, { sanitizer: configLessSafe });

Beispiele

setHTMLUnsafe() mit Trusted Types

Um das Risiko von XSS zu mindern, erstellen wir zunächst einTrustedHTML-Objekt aus dem String, der das HTML enthält, und übergeben dann dieses Objekt ansetHTMLUnsafe().Da Trusted Types noch nicht in allen Browsern unterstützt werden, definieren wir dietrusted types tinyfill.Dies fungiert als transparenter Ersatz für die Trusted Types JavaScript API:

if (typeof trustedTypes === "undefined")  trustedTypes = { createPolicy: (n, rules) => rules };

Als Nächstes erstellen wir eineTrustedTypePolicy, die einecreateHTML() für die Transformation eines Eingabestrings inTrustedHTML-Instanzen definiert.Üblicherweise verwenden Implementierungen voncreateHTML() eine Bibliothek wieDOMPurify, um die Eingaben zu bereinigen, wie unten gezeigt:

const policy = trustedTypes.createPolicy("my-policy", {  createHTML: (input) => DOMPurify.sanitize(input),});

Dann verwenden wir diesespolicy-Objekt, um einTrustedHTML-Objekt aus dem potenziell unsicheren Eingabestring zu erstellen:

// The potentially malicious stringconst untrustedString = "abc <script>alert(1)<" + "/script> def";// Create a TrustedHTML instance using the policyconst trustedHTML = policy.createHTML(untrustedString);

Jetzt, da wirtrustedHTML haben, zeigt der untenstehende Code, wie Sie es mitsetHTMLUnsafe() verwenden können.Die Eingabe wurde durch die Transformationsfunktion geleitet, daher übergeben wir keinen Sanitizer an die Methode.

// Get the target Element with id "target"const target = document.getElementById("target");// setHTMLUnsafe() with no sanitizertarget.setHTMLUnsafe(trustedHTML);

Verwendung von setHTMLUnsafe() ohne Trusted Types

Dieses Beispiel demonstriert den Fall, in dem wir keine Trusted Types verwenden, sodass wir Sanitizer-Argumente übergeben.

Der Code erstellt einen unzuverlässigen String und zeigt verschiedene Wege, auf denen ein Sanitizer an die Methode übergeben werden kann.

// The potentially malicious stringconst untrustedString = "abc <script>alert(1)<" + "/script> def";// Get the target Element with id "target"const target = document.getElementById("target");// Define custom Sanitizer and use in setHTMLUnsafe()// This allows only elements: div, p, button, scriptconst sanitizer1 = new Sanitizer({  elements: ["div", "p", "button", "script"],});target.setHTMLUnsafe(untrustedString, { sanitizer: sanitizer1 });// Define custom SanitizerConfig within setHTMLUnsafe()// Removes the <script> element but allows other potentially unsafe entities.target.setHTMLUnsafe(untrustedString, {  sanitizer: { removeElements: ["script"] },});

setHTMLUnsafe() Live-Beispiel

Dieses Beispiel bietet eine "Live"-Demonstration der Methode, wenn sie mit verschiedenen Sanitizern aufgerufen wird.Der Code definiert Schaltflächen, die Sie klicken können, um einen HTML-String einzufügen.Ein Button fügt das HTML ohne jegliche Bereinigung ein, und der zweite verwendet einen benutzerdefinierten Sanitizer, der<script>-Elemente erlaubt, jedoch keine anderen unsicheren Elemente.Der Original-String und das eingebettete HTML werden protokolliert, sodass Sie die Ergebnisse in jedem Fall inspizieren können.

HTML

Das HTML definiert zwei<button>-Elemente, um die Methode mit verschiedenen Sanitizern aufzurufen, eine andere Schaltfläche, um das Beispiel zurückzusetzen, und ein<div>-Element, um den String einzufügen.

<button type="button">None</button><button type="button">allowScript</button><button type="button">Reload</button><div>Original content of target element</div>

<pre></pre>

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

JavaScript

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

if ("Sanitizer" in window) {

Zunächst definieren wir den String, der bereinigt werden soll, der in allen Fällen gleich sein wird.Dies enthält das<script>-Element und denonclick-Handler, die beide als XSS-unsicher gelten.Wir definieren auch den Handler für die Neuladeschaltfläche.

// Define unsafe string of HTMLconst unsanitizedString = `  <div>    <p>Paragraph to inject into shadow DOM.      <button>Click me</button>    </p>    <script src="path/to/a/module.js" type="module"><\/script>    <p data-id="123">Para with <code>data-</code> attribute</p>  </div>`;const reload = document.querySelector("#reload");reload.addEventListener("click", () => document.location.reload());

Als Nächstes definieren wir den Klick-Handler für die Schaltfläche, die das HTML ohne Sanitizer setzt.Im Allgemeinen würden wir erwarten, dass die Methode Elemente im String fallen lässt, die im Kontext nicht erlaubt sind (wie tabellenspezifische Elemente in einem<div>), ansonsten jedoch den Eingabestring abgleicht.In diesem Fall sollten die Strings übereinstimmen.

const buttonNoSanitizer = document.querySelector("#buttonNoSanitizer");buttonNoSanitizer.addEventListener("click", () => {  // Set unsafe HTML without specifying a sanitizer  target.setHTMLUnsafe(unsanitizedString);  // Log HTML before sanitization and after being injected  logElement.textContent =    "No sanitizer: string should be injected without filtering\n\n";  log(`\nunsanitized: ${unsanitizedString}`);  log(`\n\nsanitized: ${target.innerHTML}`);});

Der nächste Klick-Handler setzt das Ziel-HTML unter Verwendung eines benutzerdefinierten Sanitizers, der nur<div>,<p> und<script>-Elemente erlaubt.Beachten Sie, dass da wir diesetHTMLUnsafe()-Methode verwenden,<script> nicht entfernt werden!

const allowScriptButton = document.querySelector("#buttonAllowScript");allowScriptButton.addEventListener("click", () => {  // Set the content of the element using a custom sanitizer  const sanitizer1 = new Sanitizer({    elements: ["div", "p", "script"],  });  target.setHTMLUnsafe(unsanitizedString, { sanitizer: sanitizer1 });  // Log HTML before sanitization and after being injected  logElement.textContent = "Sanitizer: {elements: ['div', 'p', 'script']}\n";  log(`\nunsanitized: ${unsanitizedString}`);  log(`\n\nsanitized: ${target.innerHTML}`);});

} else {  log("The HTML Sanitizer API is NOT supported in this browser.");  // Provide fallback or alternative behavior}

Ergebnisse

Klicken Sie auf die Schaltflächen "None" und "allowScript", um die Auswirkungen ohne einen Sanitizer beziehungsweise mit einem benutzerdefinierten Sanitizer zu sehen.

Wenn Sie auf die "None"-Schaltfläche klicken, sollten Sie sehen, dass die Eingabe und Ausgabe übereinstimmen, da kein Sanitizer angewandt wird.Wenn Sie auf die "allowScript"-Schaltfläche klicken, ist das<script>-Element immer noch vorhanden, das<button>-Element wird jedoch entfernt.Mit diesem Ansatz können Sie sicheres HTML erstellen, ohne dazu gezwungen zu sein.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• ShadowRoot.setHTMLUnsafe()
• Element.innerHTML
• Document.parseHTML() undDocument.parseHTMLUnsafe()