Sanitizer: Sanitizer() Konstruktor

Syntax

new Sanitizer()
new Sanitizer(configuration)

Parameter

configuration Optional

Ein SanitizerConfig, das eine gültige Konfiguration definiert, oder der String "default", um die Standardkonfiguration anzuzeigen.

Rückgabewert

Eine Instanz des Sanitizer Objekts.

Ausnahmen

TypeError

Der configuration Parameter wird mit einem der folgenden Werte übergeben:

• einem SanitizerConfig, das keine gültige Konfiguration ist. Zum Beispiel eine Konfiguration, die sowohl "zugelassene" als auch "entfernte" Konfigurationseinstellungen enthält.
• einem String, der nicht den Wert "default" hat.

Beschreibung

Der Konstruktor erzeugt ein neues Sanitizer Objekt, das verwendet werden kann, um unerwünschte Elemente und Attribute aus HTML oder Dokumenten herauszufiltern, bevor sie in den DOM eingefügt oder dort geparst werden.

Der Standard-Sanitizer erlaubt standardmäßig nur XSS-sichere Eingaben, indem er Elemente wie <script>, <frame>, <iframe>, <object>, <use> und Event-Handler-Attribute aus ihren jeweiligen Erlaubnislisten auslässt und Datenattribute sowie Kommentare nicht zulässt. Er wird erstellt, wenn "default" oder kein Objekt an den Konstruktor übergeben wird.

Dem Konstruktor kann ein SanitizerConfig mit einer gültigen Konfiguration übergeben werden, um das Verhalten des Sanitizers anzupassen.

Eine gültige Konfiguration kann entweder elements- oder removeElements-Arrays (aber nicht beide) und entweder die attributes- oder removeAttributes-Arrays (aber nicht beide) angeben. In den meisten Fällen ist es egal, welches dieser Arrays Sie verwenden, da die Methode allowAttribute() dasselbe Verhalten durch Hinzufügen des Attributs zum attributes-Array oder durch Entfernen aus dem removeAttributes-Array implementieren kann. Wichtig zu beachten ist, dass wenn Sie eine Konfiguration mit removeElements haben, Sie keine pro-Element-Attribute haben können, da diese im elements-Array definiert werden müssen.

Beispiele

Erstellen des Standard-Sanitizers

Dieses Beispiel zeigt, wie Sie den Standard-Sanitizer erstellen und das resultierende Konfigurationsobjekt protokollieren können.

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

#log {
  height: 400px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

Der Code prüft zunächst, ob die Sanitizer-Schnittstelle unterstützt wird. Dann wird der Standard-Sanitizer erstellt, ohne Optionen zu übergeben, und anschließend die Konfiguration abgerufen und protokolliert.

const logElement = document.querySelector("#log");
function log(text) {
  logElement.textContent = text;
}

if ("Sanitizer" in window) {

// Create default sanitizer
const sanitizer = new Sanitizer();

// Get and log the (default) configuration
const defaultConfig = sanitizer.get();
log(JSON.stringify(defaultConfig, null, 2));

} else {
  log("The HTML Sanitizer API is NOT supported in this browser.");
}

Ergebnisse

Das Ergebnis wird unten protokolliert. Beachten Sie, dass die Standardkonfiguration eine Erlaubniskonfiguration ist, die sowohl elements- als auch attributes-Arrays enthält, welche die Elemente enthalten, die erlaubt sind, wenn der Sanitizer verwendet wird.

Erstellen eines Sanitizers und dessen Verwendung mit setHTML()

Dieses Beispiel zeigt, wie Sie einen benutzerdefinierten Sanitizer in einer sicheren HTML-DOM-Einfügemethode erstellen und verwenden können.

HTML

Hier definieren wir zwei <pre>-Elemente, in denen sowohl das bereinigte als auch das unbereinigte HTML angezeigt wird.

<pre id="unmodified"></pre>
<pre id="setHTML"></pre>

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

#log {
  height: 430px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

const logElement = document.querySelector("#log");
function log(text) {
  logElement.textContent = text;
}

Der folgende Code testet, ob die Sanitizer-Schnittstelle unterstützt wird. Dann wird ein String von "unsicherem HTML" definiert, der sowohl sichere Elemente, wie <p> und <span>, als auch XSS-unsichere Elemente wie <script> enthält.

Wir erstellen dann ein Sanitizer-Objekt mit einer SanitizerConfig, die die HTML-Elemente: <div>, <p>, <span> und <script> erlaubt. Der Sanitizer wird mit dem unsicheren String in Element.setHTML() verwendet. Sowohl der ursprüngliche als auch der bereinigte String werden als Textknoten angezeigt.

if ("Sanitizer" in window) {

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

// Set unsafe string as a text node of first element
const unmodifiedElement = document.querySelector("#unmodified");
unmodifiedElement.innerText = unsafeHTMLString;

// Create sanitizer using a SanitizerConfig that allows script (and other elements)
const sanitizer = new Sanitizer({ elements: ["div", "p", "span", "script"] });

// Use the sanitizer to set the HTML of the second element using the safe method
const setHTMLElement = document.querySelector("#setHTML");
setHTMLElement.setHTML(unsafeHTMLString, { sanitizer });

// Get that HTML and set it back to the element as a text node
// (so we can see the elements)
setHTMLElement.innerText = setHTMLElement.innerHTML;

// Log the configuration
const sanitizerConfig = sanitizer.get();
log(JSON.stringify(sanitizerConfig, null, 2));

} else {
  log("The HTML Sanitizer API is NOT supported in this browser.");
}

Ergebnisse

Der ursprüngliche String und das bereinigte HTML, das in den DOM geparst wurde, sind unten zu sehen. Beachten Sie, dass selbst wenn der Sanitizer <script>-Elemente erlaubt, diese aus dem eingefügten HTML entfernt werden, wenn Element.setHTML() verwendet wird. Beachten Sie auch, dass die Konfiguration sowohl die Namen der Elemente als auch ihre Namensräume umfasst.

Spezifikationen

Browser-Kompatibilität