ShadowRoot: setHTMLUnsafe() Methode

Syntax

setHTMLUnsafe(input)
setHTMLUnsafe(input, options)

Parameter

input

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

options Optional

Ein Optionsobjekt mit den folgenden optionalen Parametern:

sanitizer Optional

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

Beachten Sie, dass ein Sanitizer im Allgemeinen effizienter ist als ein SanitizerConfig, wenn die Konfiguration wiederverwendet werden soll.

Rückgabewert

Keiner (undefined).

Ausnahmen

TypeError

Dies wird ausgelöst, wenn:

• input ein String übergeben wird, wenn Vertrauenswürdige Typen durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
• options.sanitizer wird übergeben:
  • SanitizerConfig, die nicht gü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 ein Sanitizer, SanitizerConfig noch ein String ist.

Beschreibung

Die setHTMLUnsafe()-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 zu ShadowRoot.innerHTML werden deklarative Shadow Roots in der Eingabe in den DOM geparst. Wenn der HTML-String mehr als eine deklarative Shadow Root in einem bestimmten Shadow-Host definiert, wird nur der erste ShadowRoot 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 zu ShadowRoot.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ür Cross-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 immer TrustedHTML-Objekte anstelle von Strings verwenden, und vertrauenswürdige Typen erzwingen mittels der require-trusted-types-for-CSP-Direktive. Dies gewährleistet, dass die Eingabe durch eine Transformationsfunktion weitergegeben wird, die die Möglichkeit hat, die Eingabe zu sanitisieren, um potenziell gefährliches Markup (wie <script> Elemente und Event-Handler-Attribute) zu entfernen, bevor sie injiziert wird.

Die Verwendung von TrustedHTML 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 Sie TrustedHTML verwenden.

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

Wann sollte setHTMLUnsafe() verwendet werden?

setHTMLUnsafe() sollte fast nie verwendet werden, wenn ShadowRoot.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 ist setHTML() sicher, sondern es vermeidet auch das Problem der vertrauenswürdigen Typen.

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

• Sie setHTML() 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 Sie setHTMLUnsafe() mit dem Standard- Sanitizer verwenden, um alle XSS-unsicheren Elemente herauszufiltern.

• Sie setHTML() nicht verwenden können und die Eingabe deklarative Shadow Roots enthalten könnte, sodass sie ShadowRoot.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 Sie setHTML() nicht verwenden, da es alle unsicheren Entitäten entfernt. Sie könnten setHTMLUnsafe() ohne Sanitizer oder innerHTML 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, unsichere onclick-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 attributes
shadow.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 ein TrustedHTML-Objekt aus dem String, der das HTML enthält, und übergeben dann dieses Objekt an setHTMLUnsafe(). Da vertrauenswürdige Typen noch nicht in allen Browsern unterstützt werden, definieren wir den trusted 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 eine TrustedTypePolicy, die eine createHTML() definiert, um einen Eingabestring in TrustedHTML-Instanzen zu transformieren. Üblicherweise verwenden Implementierungen von createHTML() eine Bibliothek wie DOMPurify, um die Eingabe zu sanitisieren, wie unten gezeigt:

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

Dann verwenden wir dieses policy-Objekt, um ein TrustedHTML-Objekt aus dem potenziell unsicheren Eingabestring zu erstellen:

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

Jetzt, da wir trustedHTML haben, zeigt der folgende Code, wie Sie es mit setHTMLUnsafe() verwenden können. Zuerst erstellen wir den ShadowRoot, den wir anvisieren möchten. Dies könnte programmgesteuert mit Element.attachShadow() erstellt werden, aber für dieses Beispiel erstellen wir die Wurzel deklarativ.

<div id="host">
  <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 rufen setHTMLUnsafe() 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 string
const untrustedString = "abc <script>alert(1)<" + "/script> def";

// Get the shadow root element
const shadow = document.querySelector("#host").shadowRoot;

// Define custom Sanitizer and use in setHTMLUnsafe()
// This allows only elements: div, p, button, script
const 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 id="buttonNoSanitizer" type="button">None</button>
<button id="buttonAllowScript" type="button">allowScript</button>
<button id="reload" type="button">Reload</button>

<div id="host">
  <template shadowrootmode="open">
    <span>I am in the shadow DOM </span>
  </template>
</div>

<pre id="log"></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 den onclick-Handler, die beide als XSS-unsicher gelten. Wir erhalten auch die Variable shadow, die unser Handle zur Shadow Root ist.

// Define unsafe string of HTML
const unsanitizedString = `
  <div>
    <p>Paragraph to inject into shadow DOM.
      <button onclick="alert('You clicked the 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 mit setHTMLUnsafe() 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() und Element.setHTMLUnsafe()
• Document.parseHTML() und Document.parseHTMLUnsafe()
• HTML Sanitizer API