ShadowRoot: setHTML() Methode

Syntax

setHTML(input)
setHTML(input, options)

Parameter

input

Ein String, der das zu bereinigende und in den Shadow Root einzufügende HTML definiert.

options Optional

Ein Optionsobjekt mit den folgenden optionalen Parametern:

sanitizer

Ein Sanitizer oder SanitizerConfig Objekt, das definiert, welche Elemente des Eingabewerts erlaubt oder entfernt werden, oder der String "default" für die Standard-Sanitizer-Konfiguration. Die Methode entfernt alle XSS-gefährlichen Elemente und Attribute, auch wenn sie durch den Sanitizer erlaubt sind. Wenn nicht angegeben, wird die Standardkonfiguration von Sanitizer verwendet.

Beachten Sie, dass es effizienter ist, einen Sanitizer zu verwenden und diesen bei Bedarf zu modifizieren, wenn Sie die gleiche Konfiguration mehrfach verwenden.

Rückgabewert

Keiner (undefined).

Ausnahmen

TypeError

Wird ausgelöst, wenn options.sanitizer übergeben wird mit:

• einer SanitizerConfig, die nicht gültig ist. Zum Beispiel eine Konfiguration, die sowohl "erlaubte" als auch "entfernte" Konfigurationseinstellungen enthält.
• einem String, der nicht den Wert "default" hat.
• einem Wert, der kein Sanitizer, SanitizerConfig oder String ist.

Beschreibung

Die setHTML() Methode bietet eine XSS-sichere Methode, um einen HTML-String zu parsen und zu bereinigen und diesen zu verwenden, um den bestehenden Baum im Shadow DOM zu ersetzen.

setHTML() entfernt alle HTML-Entitäten, die nicht durch die Sanitizer-Konfiguration erlaubt sind, und entfernt weiterhin alle XSS-gefährlichen Elemente oder Attribute – unabhängig davon, ob sie durch die Sanitizer-Konfiguration erlaubt sind oder nicht.

Wenn kein Sanitizer im Parameter options.sanitizer angegeben ist, wird setHTML() mit der Standard-Sanitizer-Konfiguration verwendet. Diese Konfiguration ist für die meisten Anwendungsfälle geeignet, da sie XSS-Angriffe sowie andere Angriffe wie Clickjacking oder Spoofing verhindert.

Ein benutzerdefinierter Sanitizer oder SanitizerConfig kann angegeben werden, um auszuwählen, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden. Beachten Sie, dass selbst wenn unsichere Optionen durch den Sanitizer erlaubt werden, sie bei Verwendung dieser Methode dennoch entfernt werden (sie entfernt dieselben Elemente wie ein Sanitizer, bei dem Sanitizer.removeUnsafe() aufgerufen wurde).

setHTML() sollte anstelle von ShadowRoot.innerHTML verwendet werden, um nicht vertrauenswürdige HTML-Strings in das Shadow DOM einzufügen. Es sollte auch anstelle von ShadowRoot.setHTMLUnsafe() verwendet werden, es sei denn, es besteht ein spezifisches Bedürfnis, unsichere Elemente und Attribute zuzulassen.

Beachten Sie, dass diese Methode Eingabestrings von XSS-gefährlichen Entitäten immer bereinigt, sie ist nicht gesichert oder validiert durch die Trusted Types API.

Beispiele

Grundlegende Verwendung

Dieses Beispiel zeigt einige der Möglichkeiten, wie Sie setHTML() verwenden können, um einen HTML-String zu bereinigen und einzufügen.

Zuerst erstellen wir den ShadowRoot, den wir anvisieren wollen. Dieser könnte programmatisch mit Element.attachShadow() erstellt werden, aber für dieses Beispiel erstellen wir den Root deklarativ.

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

Wir können einen Zugriff auf den Shadow Root vom #host Element so erhalten:

const shadow = document.querySelector("#host").shadowRoot;

Der untenstehende Code zeigt, wie wir setHTML() mit einem String und verschiedenen Sanitizern aufrufen können, um das HTML zu filtern und in den Shadow Root einzufügen.

// Define unsanitized string of HTML
const unsanitizedString = "abc <script>alert(1)<" + "/script> def";

// setHTML() with default sanitizer
shadow.setHTML(unsanitizedString);

// Define custom Sanitizer and use in setHTML()
// This allows only elements: <div>, <p>, <span> (<script> is unsafe and will be removed)
const sanitizer1 = new Sanitizer({ elements: ["div", "p", "span", "script"] });
shadow.setHTML(unsanitizedString, { sanitizer: sanitizer1 });

// Define custom SanitizerConfig within setHTML()
// This removes elements <div>, <p>, <span>, <script>, and any other unsafe elements/attributes
shadow.setHTML(unsanitizedString, {
  sanitizer: { removeElements: ["div", "p", "span", "script"] },
});

setHTML() 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 mit einem Standard- und einem benutzerdefinierten Sanitizer zu bereinigen und einzufügen. Der Originalstring und das bereinigte HTML werden protokolliert, sodass Sie die Ergebnisse in jedem Fall inspizieren können.

HTML

Das HTML definiert zwei <button> Elemente für die Anwendung verschiedener Sanitizer, einen weiteren Button, um das Beispiel zurückzusetzen, und ein <div>, das den deklarativen Shadow Root enthält.

<button id="buttonDefault" type="button">Default</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 den Reload-Button.

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

Dann definieren wir den zu bereinigenden String, der für alle Fälle derselbe ist. Dieser enthält das <script> Element und den onclick Handler, die beide als XSS-gefährlich gelten. Wir erhalten auch die Variable shadow, die unser Zugriff auf den 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 den Button, der den Shadow Root mit dem Standard-Sanitizer setzt. Dies sollte alle unsicheren Entitäten entfernen, bevor der HTML-String eingefügt wird. Beachten Sie, dass Sie genau sehen können, welche Elemente in den Sanitizer() Konstruktor-Beispielen entfernt werden.

const defaultSanitizerButton = document.querySelector("#buttonDefault");
defaultSanitizerButton.addEventListener("click", () => {
  // Set the content of the element using the default sanitizer
  shadow.setHTML(unsanitizedString);

  // Log HTML before sanitization and after being injected
  logElement.textContent =
    "Default sanitizer: remove script element, onclick attribute, data- attribute\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. Beachten Sie, dass weil wir die setHTML Methode verwenden, <script> trotzdem entfernt wird!

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.setHTML(unsanitizedString, { sanitizer: sanitizer1 });

  // Log HTML before sanitization and after being injected
  logElement.textContent =
    "Sanitizer: {elements: ['div', 'p', 'script']}\n Script removed even though allowed\n";
  log(`\nunsanitized: ${unsanitizedString}`);
  log(`\n\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 „Default“ und „allowScript“ Buttons, um die Effekte des Standard- und des benutzerdefinierten Sanitizers zu sehen.

Beachten Sie, dass weil wir eine sichere Bereinigungsmethode verwenden, in beiden Fällen das <script> Element und der onclick Handler entfernt werden, selbst wenn sie explizit durch den Sanitizer erlaubt sind. Während das data- Attribut mit dem Standard-Sanitizer entfernt wird, ist es erlaubt, wenn wir einen Sanitizer übergeben.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• ShadowRoot.setHTMLUnsafe()
• Element.setHTML() und Element.setHTMLUnsafe()
• Document.parseHTML() und Document.parseHTMLUnsafe()
• HTML Sanitizer API