Element: setHTMLUnsafe() Methode

input

Ein String oder TrustedHTML Instanz, die das zu parsende HTML definiert.

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. Beachten Sie, dass im Allgemeinen ein Sanitizer effizienter erwartet wird als ein SanitizerConfig, wenn die Konfiguration wiederverwendet werden soll. Falls nicht angegeben, wird kein Sanitizer verwendet.

Keiner (undefined).

TypeError

Diese Ausnahme wird geworfen, wenn:

• input ein String übergeben wird, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie festgelegt ist.
• options.sanitizer einen Wert übergeben bekommt, der kein Sanitizer, SanitizerConfig oder String ist.
  • eine nicht normalisierte SanitizerConfig (eine, die sowohl "allowed" als auch "removed" Konfigurationseinstellungen enthält).
  • ein String, der nicht den Wert "default" hat.

Die setHTMLUnsafe() Methode wird verwendet, um einen HTML-String in ein DocumentFragment zu parsen, wobei unerwünschte Elemente und Attribute herausgefiltert werden können, die im Kontext nicht benötigt werden. Anschließend wird es verwendet, um den Subtree des Elements im DOM zu ersetzen.

Die "Unsafe"-Endung im Methodennamen zeigt an, dass die Methode zwar erlaubt, den Eingabestring von unerwünschten HTML-Entities zu filtern, jedoch nicht die Sanierung oder Entfernung potenziell unsicherer, XSS-relevanter Eingaben, wie z. B. <script>-Elemente und Skript- oder Ereignis-Handler-Content-Attribute, erzwingt. Wenn keine Konfiguration in options.sanitizer angegeben ist, wird setHTMLUnsafe() ohne jede Sanitization verwendet.

Der HTML-Input kann declarative shadow roots umfassen. Wenn der HTML-String mehr als eine declarative shadow root in einem bestimmten Schatten-Host definiert, wird nur die erste ShadowRoot erstellt — nachfolgende Deklarationen werden als <template> Elemente innerhalb dieses Schatten-Roots geparst.

Wie setHTML(), kann setHTMLUnsafe() anstelle von Element.innerHTML verwendet werden, um HTML-Strings zu parsen, die deklarative Schatten-Roots enthalten können. setHTMLUnsafe() sollte anstelle von Element.setHTML() verwendet werden, wenn potenziell unsichere HTML-Strings analysiert werden sollen, die aus irgendeinem Grund XSS-unsichere Elemente oder Attribute enthalten müssen. Wenn die zu injectierenden Strings keine unsicheren HTML-Entities enthalten müssen, sollten Sie immer Element.setHTML() nutzen.

Da diese Methode nicht zwangsläufig Eingabe-Strings mit XSS-unsafe Entities saniert, sollten Eingabe-Strings auch unter Verwendung der Trusted Types API validiert werden. Wenn die Methode sowohl mit trusted types als auch einem Sanitizer verwendet wird, wird der Eingabestring durch die vertrauenswürdige Transformationsfunktion geführt, bevor er saniert wird.

Dieses Beispiel zeigt einige der Möglichkeiten, wie Sie setHTMLUnsafe() verwenden können, um einen HTML-String zu injecten.

// Define unsanitized string of HTML
const unsanitizedString = "abc <script>alert(1)<" + "/script> def";
// Get the target Element with id "target"
const target = document.getElementById("target");

// setHTML() with no sanitizer
target.setHTMLUnsafe(unsanitizedString);

// Define custom Sanitizer and use in setHTMLUnsafe()
// This allows only elements: div, p, button, script
const sanitizer1 = new Sanitizer({
  elements: ["div", "p", "button", "script"],
});
target.setHTML(unsanitizedString, { sanitizer: sanitizer1 });

// Define custom SanitizerConfig within setHTMLUnsafe()
// Removes the <script> element but allows other potentially unsafe entities.
target.setHTMLUnsafe(unsanitizedString, {
  sanitizer: { removeElements: ["script"] },
});

Dieses Beispiel bietet eine "Live"-Demonstration der Methode, die mit verschiedenen Sanitisatoren aufgerufen wird. Der Code definiert Schaltflächen, die Sie klicken können, um einen HTML-String zu injecten, der nicht sanitisiert wird, und der einen benutzerdefinierten Sanitizer verwendet. Der ursprüngliche String und das injectierte 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 Sanitisatoren aufzurufen, eine weitere Schaltfläche, um das Beispiel zurückzusetzen, und ein <div>-Element, in das der String injiziert wird.

<button id="buttonNoSanitizer" type="button">None</button>
<button id="buttonAllowScript" type="button">allowScript</button>

<button id="reload" type="button">Reload</button>
<div id="target">Original content of target element</div>

<pre id="log"></pre>

#log {
  height: 240px;
  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 zu sanierenden String, der in allen Fällen der gleiche sein wird. Dieser enthält das <script>-Element und den onclick Handler, die beide als XSS-unsicher gelten. Wir definieren auch den Handler für die Neu laden-Schaltfläche.

// Define unsafe string of HTML
const unsanitizedString = `
  <div>
    <p>This is a paragraph. <button onclick="alert('You clicked the button!')">Click me</button></p>
    <script src="path/to/a/module.js" type="module"><script>
  </div>
`;

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

Als nächstes definieren wir den Click-Handler für die Schaltfläche, die das HTML ohne Sanitizer setzt. Generell würden wir erwarten, dass die Methode Elemente im String verwirft, die im Kontext nicht erlaubt sind (wie tabellenspezifische Elemente in einem <div>-Element), ansonsten 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(`\nsanitized: ${target.innerHTML}`);
});

Der nächste Click-Handler setzt das Ziel-HTML mit einem benutzerdefinierten Sanitizer, der nur <div>, <p> und <script>-Elemente erlaubt. Beachten Sie, dass wenn wir die setHTMLUnsafe() 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(`\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 "None" und "allowScript" Schaltflächen, um die Effekte von keinem Sanitizer und einem benutzerdefinierten Sanitizer zu sehen.

Wenn Sie die "None" Schaltfläche klicken, sollten Sie feststellen, dass Eingabe und Ausgabe übereinstimmen, da kein Sanitizer angewendet wird. Wenn Sie die "allowScript" Schaltfläche klicken, ist das <script> Element noch vorhanden, aber das <button> Element wird entfernt. Mit diesem Ansatz können Sie sicheres HTML erstellen, müssen es aber nicht erzwingen.

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