Limited availability
Die setHTML()-Methode der ShadowRoot-Schnittstelle bietet eine XSS-sichere Methode, um einen HTML-String in einem DocumentFragment zu parsen und zu bereinigen, der dann den bestehenden Baum im Shadow DOM ersetzt.
setHTML(input)
setHTML(input, options)
input
Ein String, der HTML definiert, welches bereinigt und in den Shadow-Root eingefügt werden soll.
options Optional
Ein Optionsobjekt mit den folgenden optionalen Parametern:
sanitizer
Ein Sanitizer- oder SanitizerConfig-Objekt, das definiert, welche Elemente der Eingabe erlaubt oder entfernt werden, oder der String "default" für die Standard-Sanitizer-Konfiguration. Beachten Sie, dass im Allgemeinen ein Sanitizer effizienter ist als ein SanitizerConfig, wenn die Konfiguration wiederverwendet werden soll. Wird kein Wert angegeben, wird die Standard-Sanitizer-Konfiguration verwendet.
Keiner (undefined).
TypeError
Dies wird ausgelöst, wenn options.sanitizer eine:
SanitizerConfig (eine, die sowohl "erlaubte" als auch "entfernte" Konfigurationseinstellungen enthält)."default" hat.Sanitizer, SanitizerConfig noch ein String ist, übergeben wird.Die setHTML()-Methode bietet eine XSS-sichere Methode, um einen HTML-String zu parsen und zu bereinigen und ihn zu nutzen, 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 weiter alle XSS-unsicheren Elemente oder Attribute â unabhängig davon, ob sie von der Sanitizer-Konfiguration erlaubt sind oder nicht.
Wenn keine Sanitizer-Konfiguration im Parameter options.sanitizer angegeben wird, wird setHTML() mit der Standard-Sanitizer-Konfiguration verwendet. Diese Konfiguration erlaubt alle Elemente und Attribute, die als XSS-sicher angesehen werden, wodurch Entitäten, die als unsicher gelten, nicht erlaubt sind. Ein benutzerdefinierter Sanitizer oder eine benutzerdefinierte Sanitizer-Konfiguration kann angegeben werden, um auszuwählen, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden. Beachten Sie, dass auch wenn unsichere Optionen durch die Sanitizer-Konfiguration erlaubt sind, sie bei Verwendung dieser Methode immer noch entfernt werden (was implizit Sanitizer.removeUnsafe() aufruft).
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 spezieller Bedarf, unsichere Elemente und Attribute zuzulassen.
Da diese Methode Eingabestrings von XSS-unsicheren Entitäten immer bereinigt, wird sie nicht durch die Trusted Types API gesichert oder validiert.
Beispiele Grundlegende VerwendungDieses 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 programmgesteuert 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 wie folgt erhalten:
const shadow = document.querySelector("#host").shadowRoot;
Der unten stehende Code zeigt, wie wir setHTML() mit einem String und verschiedenen Sanitizern aufrufen können, um den HTML-Inhalt im Shadow-Root zu filtern und 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 ursprüngliche String und das bereinigte HTML werden protokolliert, damit Sie die Ergebnisse in jedem Fall prüfen können.
HTMLDas HTML definiert zwei <button>-Elemente, um verschiedene Sanitizer anzuwenden, eine weitere Schaltfläche, 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>
#log {
height: 220px;
overflow: scroll;
padding: 0.5rem;
border: 1px solid black;
margin: 5px;
}
const logElement = document.querySelector("#log");
function log(text) {
logElement.textContent += text;
}
if ("Sanitizer" in window) {
Zuerst definieren wir den Handler für die Neulade-Schaltfläche.
const reload = document.querySelector("#reload");
reload.addEventListener("click", () => document.location.reload());
Dann definieren wir den String, der bereinigt werden soll, welcher in allen Fällen 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 Verweis 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>
</div>
`;
const shadow = document.querySelector("#host").shadowRoot;
Als nächstes definieren wir den Klick-Handler für die Schaltfläche, die den Shadow-Root mit dem Standardsanitizer setzt. Dieser sollte alle unsicheren Entitäten strippen, bevor der HTML-String eingefügt wird. Beachten Sie, dass Sie genau sehen können, welche Elemente in den Sanitizer()-Konstruktorbeispielen 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 and onclick attribute\n\n";
log(`\nunsanitized: ${unsanitizedString}`);
log(`\nsanitized: ${shadow.innerHTML}`);
});
Der nächste Klick-Handler setzt das Ziel-HTML mit einem benutzerdefinierten Sanitizer, der nur <div>, <p>, und <script>-Elemente erlaubt. Beachten Sie, dass das <script> trotzdem entfernt wird, da wir die setHTML-Methode verwenden!
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(`\nsanitized: ${shadow.innerHTML}`);
});
} else {
log("The HTML Sanitizer API is NOT supported in this browser.");
// Provide fallback or alternative behavior
}
Klicken Sie auf die Schaltflächen "Default" und "allowScript", um die Effekte des Standardsanitizers bzw. des benutzerdefinierten Sanitizers zu sehen. Beachten Sie, dass, da wir eine gleiche Bereinigungsmethode verwenden, in beiden Fällen das <script>-Element und der onclick-Handler entfernt werden, selbst wenn sie explizit vom Sanitizer erlaubt sind.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4