Dokumentation: parseHTMLUnsafe() statische Methode

Syntax

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

Parameter

input

Eine Instanz von TrustedHTML 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 Standardkonfiguration (XSS-sicher) anwendet. Wenn nicht 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, wenn Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
• options.sanitizer übergeben wird:
  • ein Wert, der kein Sanitizer, SanitizerConfig oder String ist.
  • eine nicht-normalisierte SanitizerConfig (eine, die sowohl "erlaubte" als auch "entfernte" Konfigurationseinstellungen umfasst).
  • ein String, der nicht den Wert "default" hat.

Beschreibung

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

Die Eingabe-HTML kann deklarative Shadow Roots enthalten. Wenn die HTML-Zeichenkette mehr als eine deklarative Shadow Root in einem bestimmten Shadow Host definiert, wird nur die erste ShadowRoot erstellt — nachfolgende Deklarationen werden als <template>-Elemente innerhalb dieser Shadow Root geparst.

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

Sicherheitsüberlegungen

Der Suffix "Unsafe" im Methodennamen zeigt an, dass es nicht die Entfernung aller XSS-unsafe HTML-Entitäten erzwingt (im Gegensatz zu Document.parseHTML()). Während es das tun kann, wenn es mit einem geeigneten Sanitizer verwendet wird, muss es keinen effektiven Sanitizer verwenden oder überhaupt keinen! Die Methode stellt somit einen möglichen Vektor für Cross-Site-Scripting (XSS) Angriffe dar, bei denen potenziell unsichere Strings, die von einem Benutzer bereitgestellt werden, in den DOM injiziert werden, ohne vorher sanitisiert zu werden.

Sie sollten dieses Risiko mindern, indem Sie stets TrustedHTML-Objekte statt Strings übergeben und vertrauenswürdige Typen durch die require-trusted-types-for CSP-Direktive durchsetzen. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Gelegenheit hat, die Eingabe zu sanitieren, um potenziell gefährliche Markups (wie <script>-Elemente und Event-Handler-Attribute) zu entfernen, bevor sie injiziert wird.

Die Verwendung von TrustedHTML macht es möglich, zu prüfen und sicherzustellen, dass der Sanitization-Code an nur wenigen Stellen effektiv ist, anstatt über alle Ihre Injection-Senken verstreut zu sein. Sie sollten keinen Sanitizer an die Methode übergeben müssen, wenn Sie TrustedHTML verwenden.

Falls Sie aus irgendeinem Grund TrustedHTML (oder noch besser, setHTML()) nicht verwenden können, dann ist die nächst sicherste Option, setHTMLUnsafe() mit dem XSS-sicheren Standard-Sanitizer 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