Dokumentation: parseHTMLUnsafe() statische Methode

Syntax

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

Parameter

input

Eine TrustedHTML-Instanz oder ein String, der das zu analysierende 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 standardmäßigen (XSS-sicheren) Konfiguration anwendet. Wird nichts angegeben, wird kein Sanitizer verwendet.

Beachten Sie, dass im Allgemeinen ein Sanitizer effizienter erwartet wird als eine SanitizerConfig, wenn die Konfiguration wiederverwendet werden soll.

Rückgabewert

Ein Document.

Ausnahmen

TypeError

Diese Ausnahme wird ausgelöst, wenn:

• html ein String übergeben wird, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
• options.sanitizer einen übergebenen Wert erhält:
  • SanitizerConfig, die nicht gültig ist. Ein Beispiel hierfür ist eine Konfiguration, die sowohl "erlaubte" als auch "entfernte" Einstellungen enthält.
  • String, der nicht den Wert "default" hat.
  • Wert, der weder ein Sanitizer, SanitizerConfig noch ein String ist.

Beschreibung

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

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

parseHTMLUnsafe() führt standardmäßig keine Sanitization durch. Wird kein Sanitizer als Parameter übergeben, werden alle HTML-Entitäten der Eingabe injiziert.

Sicherheitsüberlegungen

Das Suffix "Unsafe" im Methodennamen zeigt an, dass es nicht die Entfernung aller XSS-unsicheren HTML-Entitäten erzwingt (im Gegensatz zu Document.parseHTML()). Obwohl es möglich ist, wenn ein geeigneter Sanitizer verwendet wird, muss es keinen effektiven Sanitizer verwenden oder überhaupt einen Sanitizer! Die Methode stellt daher einen möglichen Vektor für Cross-Site Scripting (XSS) Angriffe dar, bei denen potenziell unsichere Strings, die von einem Benutzer bereitgestellt werden, in das DOM injiziert werden, ohne vorher saniert worden zu sein.

Sie sollten dieses Risiko mindern, indem Sie immer TrustedHTML-Objekte anstelle von Strings verwenden und vertrauenswürdige Typen durch die Verwendung der require-trusted-types-for CSP-Direktive erzwingen. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Eingabe möglicherweise sanitisieren kann, um potenziell gefährliches Markup (wie <script>-Elemente und Event-Handler-Attribute) zu entfernen, bevor es injiziert wird.

Die Verwendung von TrustedHTML ermöglicht es, zu überprüfen und zu kontrollieren, dass der Sanitisierungscode an nur wenigen Stellen effektiv ist, anstatt über alle Ihre Injection Sinks verstreut zu sein. Sie sollten keinen Sanitizer an die Methode übergeben müssen, wenn Sie TrustedHTML verwenden.

Sollten Sie aus irgendeinem Grund TrustedHTML (oder noch besser, setHTML()) nicht verwenden können, dann ist die nächst sicherere Option die Verwendung von setHTMLUnsafe() mit dem XSS-sicheren Standard Sanitizer.

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