Document: parseHTMLUnsafe() 静的メソッド

構文

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

引数

input

構文解析する HTML を定義する TrustedHTML インスタンスまたは文字列です。

options 省略可

以下のオプション引数を持ったオプションオブジェクトです。

sanitizer 省略可

入力のどの要素を許可することができるかまたは除去されるかを定義する、Sanitizer または SanitizerConfig オブジェクトです。 これは、値が "default" の文字列でもよく、その場合は（XSS 対策済みの）デフォルトのサニタイザー設定を持つ Sanitizer が適用されます。 指定がない場合は、サニタイザーは使用されません。

なお、同じ設定を複数回使用する場合は、Sanitizer を使用し、必要に応じてそれを変更する方が効率的であると考えられます。

返値

Document です。

例外

TypeError

これは次の場合に発生します。

• html が文字列で渡された場合（信頼型がCSP によって強制されており、デフォルトポリシーが定義されていない場合）。
• options.sanitizer に次のいずれかが渡された場合。
  • SanitizerConfig が有効でないもの。 例えば、"allowed" と "removed" の両方の設定項目を含む構成などです。
  • "default" 以外の値の文字列。
  • Sanitizer、SanitizerConfig、文字列のいずれでもない値。

解説

parseHTMLUnsafe() 静的メソッドを使用すると、新しい Document インスタンスを生成し、必要に応じて不要な要素や属性をフィルタリングすることができます。 生成される Document のコンテンツタイプは "text/html"、文字セット は UTF-8、URL は "about:blank" となります。

入力 HTML には、宣言型シャドウルートが含まれている場合があります。 HTML の文字列が具体的なシャドウホスト内で複数の宣言型シャドウルートを定義している場合、最初のShadowRootのみが生成されます。それ以降の宣言は、そのシャドウルート内の<template>要素として構文解析されます。

parseHTMLUnsafe() は、デフォルトで無害化処理を行いません。 サニタイザーが引数として渡されなかった場合、入力に含まれるすべての HTML エンティティが挿入されます。

セキュリティの注意事項

メソッド名の接尾辞 "Unsafe" は、このメソッドがすべての XSS リスクのある HTML エンティティの除去を強制しないことを示しています（Document.parseHTML()とは異なります）。 適切なサニタイザーと併用すればそのように動作させることができますが、効果的なサニタイザーを保有する必要はなく、サニタイザー自体を使用しなくてもよいのです！ したがって、このメソッドは、ユーザーから指定された潜在的に安全でない文字列が、先に無害化されることなく DOM に注入される、クロスサイトスクリプティング (XSS)攻撃の攻撃経路となり得ます。

このリスクを軽減するには、文字列の代わりに常に TrustedHTML オブジェクトを渡すようにし、CSP の require-trusted-types-for ディレクティブを使用して信頼型を強制することで、このリスクを軽減する必要があります。 これにより、入力は変換関数を通過することになり、挿入される前に入力を無害化して、潜在的に危険なマークアップ（<script> 要素やイベントハンドラー属性など）を除去することが可能になります。

TrustedHTML を使用することで、無害化処理のコードが有効であるかどうかを、すべてのインジェクション・シンクに散在させるのではなく、わずかな場所だけで監査・検査することができます。 TrustedHTML を使用する場合、メソッドに無害化処理関数を渡す必要はありません。

何らかの理由で TrustedHTML （あるいは、さらに望ましいのは setHTML()）を使用できない場合は、次に安全な選択肢として、XSS 対策済みの デフォルトのサニタイザー設定 とともに setHTMLUnsafe() を使用することをお勧めします。

仕様書

ブラウザーの互換性

関連情報

• Document.parseHTML()
• Element.setHTML() および Element.setHTMLUnsafe()
• ShadowRoot.setHTML() および ShadowRoot.setHTMLUnsafe()
• DOMParser.parseFromString(): HTML または XML を DOM ツリーに入れる
• HTML 無害化 API