Dokumentation: `parseHTMLUnsafe()` statische Methode

Syntax

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

Parameter

input

Eine TrustedHTML- oder String-Instanz, die 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. Falls nicht angegeben, wird kein Sanitisierer verwendet.

Beachten Sie, dass in der Regel erwartet wird, dass ein Sanitizer effizienter ist als ein SanitizerConfig, falls die Konfiguration wiederverwendet werden soll.

Rückgabewert

Ein Document.

Ausnahmen

TypeError

Dieser wird ausgelöst, wenn:

• html wird ein String übergeben, wenn Trusted Types durch eine CSP durchgesetzt werden und keine Standardrichtlinie definiert ist.
• options.sanitizer einen Wert übergeben wird, der kein Sanitizer, SanitizerConfig oder String ist.
• nicht normalisierte SanitizerConfig (eine, die sowohl "erlaubte" als auch "entfernte" Konfigurationseinstellungen enthält) übergeben wird.
• ein String, der nicht den Wert "default" hat.

Beschreibung

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

Das Eingabe-HTML kann deklarative Shadow-Roots enthalten. Wenn der HTML-String mehr als eine deklarative 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 Sanitisierer als Parameter übergeben, werden alle HTML-Entitäten der Eingabe injiziert.

Sicherheitsüberlegungen

Der Suffix "Unsafe" im Methodennamen deutet darauf hin, dass es keine Entfernung aller XSS-unsicheren HTML-Entitäten erzwingt (im Gegensatz zu Document.parseHTML()). Während es dies tun kann, wenn es mit einem geeigneten Sanitisierer verwendet wird, muss es keinen effektiven Sanitisierer verwenden oder überhaupt keinen Sanitisierer! 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, in das DOM injiziert werden, ohne vorher sanitisiert zu werden.

Sie sollten dieses Risiko mindern, indem Sie immer TrustedHTML-Objekte anstelle von Strings übergeben und trusted type durchsetzen mit der require-trusted-types-for CSP-Direktive. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion übergeben wird, die die Möglichkeit hat, die Eingabe zu sanitieren, um potenziell gefährliche Markups (wie z. B. <script>-Elemente und Ereignis-Handler-Attribute) zu entfernen, bevor sie injiziert werden.

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

Wenn Sie aus irgendeinem Grund kein TrustedHTML (oder noch besser setHTML()) verwenden können, dann ist die nächst sicherere 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