DiesetHTMLUnsafe()-Methode derShadowRoot-Schnittstelle kann verwendet werden, um HTML-Eingaben in einDocumentFragment zu parsen, unerwünschte Elemente und Attribute optional herauszufiltern und es dann zu nutzen, um den bestehenden Baum im Shadow DOM zu ersetzen.

Syntax

setHTMLUnsafe(input)setHTMLUnsafe(input, options)

Parameter

input

Eine Instanz vonTrustedHTML oder ein String, das HTML definiert, das geparst werden soll.

optionsOptional

Ein Optionsobjekt mit den folgenden optionalen Parametern:

sanitizerOptional

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

Beachten Sie, dass einSanitizer im Allgemeinen effizienter ist als einSanitizerConfig, wenn die Konfiguration wiederverwendet werden soll.

Rückgabewert

Keiner (undefined).

Ausnahmen

TypeError

Dies wird ausgelöst, wenn:

• input ein String übergeben wird, wennVertrauenswürdige Typendurch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
• options.sanitizer wird übergeben:
  • SanitizerConfig, die nichtgültig ist.Zum Beispiel eine Konfiguration, die sowohl "erlaubt" als auch "entfernt" Konfigurationseinstellungen enthält.
  • einem String, der nicht den Wert"default" hat.
  • einem Wert, der weder einSanitizer,SanitizerConfig noch ein String ist.

Beschreibung

DiesetHTMLUnsafe()-Methode kann verwendet werden, um einen String von HTML zu parsen, unerwünschte Elemente und Attribute optional zu filtern und ihn zu verwenden, um den bestehenden Shadow DOM zu ersetzen.

Im Gegensatz zuShadowRoot.innerHTML werdendeklarative Shadow Roots in der Eingabe in den DOM geparst.Wenn der HTML-String mehr als einedeklarative Shadow Root in einem bestimmten Shadow-Host definiert, wird nur der ersteShadowRoot erstellt – nachfolgende Deklarationen werden als<template>-Elemente innerhalb dieses Shadow-Roots geparst.

setHTMLUnsafe() führt standardmäßig keine Sanitierung durch.Wenn kein Sanitizer als Parameter übergeben wird, werden alle HTML-Entitäten in der Eingabe injiziert.

Sicherheitsüberlegungen

Das Suffix „Unsafe“ im Methodennamen weist darauf hin, dass es die Entfernung aller XSS-unsicheren HTML-Entitäten nicht erzwingt (im Gegensatz zuShadowRoot.setHTML()).Während dies mit einem geeigneten Sanitizer erfolgen kann, muss es keinen effektiven Sanitizer verwenden oder überhaupt keinen Sanitizer verwenden!Die Methode ist daher ein möglicher Vektor fürCross-Site-Scripting (XSS)-Angriffe, bei denen möglicherweise unsichere Strings, die von einem Benutzer bereitgestellt werden, ohne vorherige Sanitierung in den DOM injiziert werden.

Sie sollten dieses Risiko mindern, indem Sie immerTrustedHTML-Objekte anstelle von Strings verwenden, undvertrauenswürdige Typen erzwingen mittels derrequire-trusted-types-for-CSP-Direktive.Dies gewährleistet, dass die Eingabe durch eine Transformationsfunktion weitergegeben wird, die die Möglichkeit hat, die Eingabe zusanitisieren, um potenziell gefährliches Markup (wie<script> Elemente und Event-Handler-Attribute) zu entfernen, bevor sie injiziert wird.

Die Verwendung vonTrustedHTML macht es möglich, zu prüfen und zu überprüfen, dass Sanitierungscode in nur wenigen Stellen effektiv ist, anstatt über alle Ihre Injection-Sinks verstreut zu sein.Sie sollten keinen Sanitizer an die Methode übergeben müssen, wenn SieTrustedHTML verwenden.

Wenn Sie aus irgendeinem GrundTrustedHTML (oder noch besser,setHTML()) nicht verwenden können, dann ist die nächstsicherste Option,setHTMLUnsafe() mit dem XSS-sicheren Standard-Sanitizer zu verwenden.

Wann solltesetHTMLUnsafe() verwendet werden?

setHTMLUnsafe() sollte fast nie verwendet werden, wennShadowRoot.setHTML() verfügbar ist, da es nur sehr wenige (wenn überhaupt) Fälle gibt, in denen benutzerbereitgestellte HTML-Eingaben XSS-unsichere Elemente enthalten müssen.Nicht nur istsetHTML() sicher, sondern es vermeidet auch das Problem der vertrauenswürdigen Typen.

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

• SiesetHTML() oder vertrauenswürdige Typen aus irgendeinem Grund nicht verwenden können und Sie den sichersten möglichen Filter haben möchten.In diesem Fall könnten SiesetHTMLUnsafe() mit dem Standard-Sanitizer verwenden, um alle XSS-unsicheren Elemente herauszufiltern.

• SiesetHTML() nicht verwenden können und die Eingabe deklarative Shadow Roots enthalten könnte, sodass sieShadowRoot.innerHTML nicht verwenden können.

• Sie einen Sonderfall haben, in dem Sie HTML-Eingaben benötigen, die eine bekannte Menge unsicherer HTML-Entitäten enthalten.

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

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

Für den letzten Punkt betrachten Sie eine Situation, in der Ihr Code darauf angewiesen ist, unsichereonclick-Handler verwenden zu können.Der folgende Code zeigt die Wirkung der verschiedenen Methoden und Sanitizer in diesem Fall.

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

Beispiele

setHTMLUnsafe() mit Vertrauenswürdigen Typen

Um das Risiko von XSS zu mindern, erstellen wir zuerst einTrustedHTML-Objekt aus dem String, der das HTML enthält, und übergeben dann dieses Objekt ansetHTMLUnsafe().Da vertrauenswürdige Typen noch nicht in allen Browsern unterstützt werden, definieren wir dentrusted 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() definiert, um einen Eingabestring inTrustedHTML-Instanzen zu transformieren.Üblicherweise verwenden Implementierungen voncreateHTML() eine Bibliothek wieDOMPurify, um die Eingabe zu sanitisieren, 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 folgende Code, wie Sie es mitsetHTMLUnsafe() verwenden können.Zuerst erstellen wir denShadowRoot, den wir anvisieren möchten.Dies könnte programmgesteuert mitElement.attachShadow() erstellt werden, aber für dieses Beispiel erstellen wir die Wurzel deklarativ.

<div>  <template shadowrootmode="open">    <span>A span element in the shadow DOM</span>  </template></div>

Dann erhalten wir einen Handle auf die Shadow Root aus dem#host-Element und rufensetHTMLUnsafe() auf.Die Eingabe wurde der Transformationsfunktion unterzogen, sodass wir keinen Sanitizer an die Methode übergeben.

const shadow = document.querySelector("#host").shadowRoot;// setHTMLUnsafe() with no sanitizer (no filtering)shadow.setHTMLUnsafe(trustedHTML);

Verwendung von setHTMLUnsafe() ohne Vertrauenswürdige Typen

Dieses Beispiel zeigt den Fall, in dem wir keine vertrauenswürdigen Typen verwenden, sodass wir Sanitizer-Argumente übergeben werden.

Der Code erstellt zunächst einen nicht vertrauenswürdigen String und zeigt eine Reihe von Möglichkeiten, wie ein Sanitizer an die Methode übergeben werden kann.

// The potentially malicious stringconst untrustedString = "abc <script>alert(1)<" + "/script> def";// Get the shadow root elementconst shadow = document.querySelector("#host").shadowRoot;// Define custom Sanitizer and use in setHTMLUnsafe()// This allows only elements: div, p, button, scriptconst sanitizer1 = new Sanitizer({  elements: ["div", "p", "button", "script"],});shadow.setHTMLUnsafe(untrustedString, { sanitizer: sanitizer1 });// Define custom SanitizerConfig within setHTMLUnsafe()// Removes the <script> element but allows other potentially unsafe entities.shadow.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 anklicken können, um einen HTML-String zu injizieren.Eine Schaltfläche injiziert das HTML, ohne es überhaupt zu sanitisieren, und die zweite verwendet einen benutzerdefinierten Sanitizer, der<script>-Elemente erlaubt, aber keine anderen unsicheren Elemente.Der originale String und das injizierte HTML werden geloggt, so dass Sie die Ergebnisse in jedem Fall inspizieren können.

HTML

Das HTML definiert zwei<button>-Elemente zum Injizieren des HTML ohne Sanitizer und mit einem benutzerdefinierten Sanitizer (jeweils), eine weitere Schaltfläche, um das Beispiel zurückzusetzen, und ein<div>, das die deklarative Shadow Root enthält.

<button type="button">None</button><button type="button">allowScript</button><button type="button">Reload</button><div>  <template shadowrootmode="open">    <span>I am in the shadow DOM </span>  </template></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) {

Zuerst definieren wir den Handler für die Neuladen-Schaltfläche.

const reload = document.querySelector("#reload");reload.addEventListener("click", () => document.location.reload());

Dann definieren wir den Eingabestring, der in die Shadow Root injiziert werden soll, der für alle Fälle gleich sein wird.Dieser enthält das<script>-Element und denonclick-Handler, die beide als XSS-unsicher gelten.Wir erhalten auch die Variableshadow, die unser Handle zur Shadow Root ist.

// 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 shadow = document.querySelector("#host").shadowRoot;

Als nächstes definieren wir den Click-Handler für die Schaltfläche, die die Shadow Root mitsetHTMLUnsafe() setzt, ohne einen Sanitizer zu übergeben.Da es keinen Sanitizer gibt, erwarten wir, dass das injizierte HTML dem Eingabestring entspricht.

const buttonNoSanitizer = document.querySelector("#buttonNoSanitizer");buttonNoSanitizer.addEventListener("click", () => {  // Set the content of the element with no sanitizer  shadow.setHTMLUnsafe(unsanitizedString);  // Log HTML before sanitization and after being injected  logElement.textContent = "No sanitizer\n\n";  log(`\nunsanitized: ${unsanitizedString}`);  log(`\n\nsanitized: ${shadow.innerHTML}`);});

Der nächste Click-Handler setzt das Ziel-HTML unter Verwendung eines benutzerdefinierten Sanitizers, der nur<div>,<p> und<script>-Elemente erlaubt.

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"],  });  shadow.setHTMLUnsafe(unsanitizedString, { sanitizer: sanitizer1 });  // Log HTML before sanitization and after being injected  logElement.textContent = "Sanitizer: {elements: ['div', 'p', 'script']}\n";  log(`\n\nunsanitized: ${unsanitizedString}`);  log(`\nsanitized: ${shadow.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 Sanitizer bzw. mit einem benutzerdefinierten Sanitizer zu sehen.

Wenn Sie auf die Schaltfläche „None“ klicken, sollten Sie sehen, dass Eingabe und Ausgabe übereinstimmen, da kein Sanitizer angewendet wird.Wenn Sie auf die Schaltfläche „allowScript“ klicken, ist das<script>-Element noch vorhanden, aber das<button>-Element wird entfernt.Mit diesem Ansatz können Sie sicheres HTML erstellen, aber Sie sind nicht dazu gezwungen.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• ShadowRoot.setHTML()
• ShadowRoot.innerHTML
• Element.setHTML() undElement.setHTMLUnsafe()
• Document.parseHTML() undDocument.parseHTMLUnsafe()
• HTML Sanitizer API