Dokument: parseHTMLUnsafe() statische Methode

Syntax

Document.parseHTMLUnsafe(input)
Document.parseHTMLUnsafe(input, options)

Parameter

input

Eine TrustedHTML-Instanz oder ein String, der 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. Dies kann auch ein String mit dem Wert "default" sein, der einen Sanitizer mit der (XSS-sicheren) Standard-Sanitizer-Konfiguration anwendet. Wenn nicht angegeben, wird kein sanitizer verwendet.

Beachten Sie, dass es effizienter sein kann, einen Sanitizer zu verwenden und ihn bei Bedarf zu ändern, wenn Sie dieselbe Konfiguration mehrfach verwenden.

Rückgabewert

Ein Document.

Ausnahmen

TypeError

Dies wird ausgelöst, wenn:

• html ein String übergeben wird, wenn Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
• options.sanitizer übergeben wird:
  • Eine SanitizerConfig, die nicht gültig ist. Zum Beispiel eine Konfiguration, die sowohl "erlaubte" als auch "entfernte" Konfigurationseinstellungen enthält.
  • Ein String, der nicht den Wert "default" hat.
  • Ein Wert, der weder ein Sanitizer, noch ein SanitizerConfig oder ein String ist.

Beschreibung

Die parseHTMLUnsafe() statische Methode kann verwendet werden, um eine neue Document-Instanz zu erstellen und optional unerwünschte Elemente und Attribute herauszufiltern. Das resultierende Document wird einen Inhaltstyp von "text/html", einen Zeichensatz von UTF-8 und eine URL von "about:blank" haben.

Die Eingabe-HTML kann deklarative Shadow Roots enthalten. Wenn der HTML-String mehr als einen deklarativen Shadow Root in einem bestimmten Shadow-Host definiert, dann wird nur der erste ShadowRoot erstellt — nachfolgende Deklarationen werden als <template>-Elemente innerhalb dieses Shadow Roots geparst.

parseHTMLUnsafe() führt standardmäßig keine Bereinigung durch. Wenn kein sanitizer als Parameter übergeben wird, werden alle HTML-Entitäten in der Eingabe eingefügt.

Sicherheitsüberlegungen

Das Suffix "Unsafe" im Methodennamen zeigt an, dass es nicht erzwingt, dass alle XSS-unsicheren HTML-Entitäten entfernt werden (im Gegensatz zu Document.parseHTML()). Während dies möglich ist, wenn mit einem geeigneten sanitizer verwendet, muss es keinen effektiven sanitizer verwenden oder überhaupt keinen! Die Methode ist daher ein möglicher Vektor für Cross-Site Scripting (XSS)-Angriffe, bei denen potenziell unsichere Strings, die von einem Benutzer bereitgestellt werden, ohne vorherige Bereinigung in das DOM eingefügt werden.

Sie sollten dieses Risiko mindern, indem Sie immer TrustedHTML-Objekte anstelle von Strings übergeben und vertrauenswürdige Typen durchsetzen mithilfe der require-trusted-types-for CSP-Direktive. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zu bereinigen, um potenziell gefährliches Markup (wie <script>-Elemente und Event-Handler-Attribute) zu entfernen, bevor es eingefügt wird.

Die Verwendung von TrustedHTML ermöglicht es, die Wirksamkeit der Bereinigungscode-Nutzung an nur wenigen Stellen zu überprüfen und zu kontrollieren, anstatt über alle Ihre Injection Sinks verstreut zu sein. Sie sollten keinen Filter an die Methode übergeben müssen, wenn Sie TrustedHTML verwenden.

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Document.parseHTML()
• Element.setHTML() und Element.setHTMLUnsafe()
• ShadowRoot.setHTML() und ShadowRoot.setHTMLUnsafe()
• DOMParser.parseFromString() zum Parsen von HTML oder XML in einen DOM-Baum
• HTML Sanitizer API