DOMPurify v3.4.13

セキュリティ

### 圧縮・テスト済みの本番バージョンを使用する場合（ソースマップあり）```html
<script type="text/javascript" src="dist/purify.min.js"></script>

Angularや類似のフレームワークでの作業が好きなら、こちらもどうぞ:```js
import DOMPurify from 'dompurify';

const clean = DOMPurify.sanitize('<b>hello there</b>');

### 足を撃ち抜くような落とし穴はありますか?

はい、注意してください。もし _最初に_ HTMLをサニタイズして、その _後に_ 変更を加えると、サニタイズの効果を**簡単に無効化してしまう**可能性があります。サニタイズ後のマークアップを別のライブラリに渡す場合は、そのライブラリが独自にHTMLをいじらないことを必ず確認してください。安全な使用方法や、よく考えてから使うべきタグ・属性については、[Security Goals & Threat Model](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model) を参照してください。また、後処理やマークアップのコンテキスト変更がなぜサニタイズを無効化するのかについては、[Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) を参照してください。

### わかりました、では次に進みましょう

マークアップをサニタイズした後、`DOMPurify.removed` プロパティを確認して、どの要素や属性が除去されたかを調べることもできます。ただし、このプロパティをセキュリティ上重要な判断に**使用しないでください**。これは好奇心旺盛な方のための小さなヘルパーにすぎません。

### サーバー上でDOMPurifyを実行する

DOMPurifyは技術的にはNode.jsのサーバーサイドでも動作します。私たちのサポートは[Node.jsのリリースサイクル](https://nodejs.org/en/about/previous-releases)に従うよう努めています。

サーバー上でDOMPurifyを実行するにはDOMが必要です。これはおそらく驚くことではないでしょう。通常は[jsdom](https://github.com/jsdom/jsdom)が選択肢の定番であり、_jsdom_ の最新バージョンを使用することを**強くお勧めします**。

なぜでしょうか? 古いバージョンの _jsdom_ は、DOMPurifyが100%正しく動作していてもXSSにつながるようなバグがあることが知られているためです。例えば _jsdom v19.0.0_ には**既知の攻撃ベクトル**があり、それは _jsdom v20.0.0_ で修正されています。そのため、_jsdom_ を最新に保つことを本当にお勧めします。

また、[happy-dom](https://github.com/capricorn86/happy-dom) のようなツールも存在しますが、現時点では**安全とは見なされていません**。DOMPurifyと _happy-dom_ を組み合わせることは現在推奨されておらず、XSSにつながる可能性が高いです。選択するサーバーサイドDOMがなぜ信頼できるコンピューティング基盤の一部となるのかについては、[Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) を参照してください。

それ以外については、サーバー上でDOMPurifyを使用しても問題ありません。おそらく。これは実際には _jsdom_ や、サーバーサイドで利用するDOMに依存します。それが許容できるのであれば、以下のようにして動作させることができます:```bash
npm install dompurify
npm install jsdom

あるいは、インポートを使った作業を好むなら、次のようにもできます:```js
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';

const window = new JSDOM('').window;
const purify = DOMPurify(window);
const clean = purify.sanitize('<b>hello there</b>');

I need the input content to translate. Please provide the chunk of Markdown content you'd like me to translate from English to Japanese.```js
import DOMPurify from 'isomorphic-dompurify';

const clean = DOMPurify.sanitize('<s>hello</s>');

これはほんの一部にすぎません。これらのサンプルが由来する攻撃クラスの完全な分類（mutation XSS、ネームスペース混乱、DOM clobbering、rawtextブレイクアウトなど）については、[Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) を参照してください。

## 何がサポートされていますか？

DOMPurifyは現在、HTML5、SVG、MathMLをサポートしています。DOMPurifyはデフォルトでCSSとHTMLカスタムデータ属性を許可します。DOMPurifyはShadow DOMもサポートしており、DOMテンプレートを再帰的にサニタイズします。また、DOMPurifyを使用すると、jQueryの `$()` および `elm.html()` APIで使用するためのHTMLを、既知の問題なくサニタイズすることもできます。デフォルトで許可される要素と属性の正確なセットについては、[Default TAGs & ATTRIBUTEs allow-list & blocklist](https://github.com/cure53/DOMPurify/wiki/Default-TAGs-ATTRIBUTEs-allow-list-&-blocklist) のWikiページを参照してください。

## Internet Explorerのようなレガシーブラウザではどうですか？

DOMPurifyは何も行いません。単に、入力した文字列をそのまま返すだけです。DOMPurifyは `isSupported` というプロパティを公開しており、これによってジョブを実行できるかどうかがわかるため、独自のバックアッププランを考案できます。

## DOMPurifyとTrusted Typesについてはどうですか？

バージョン1.0.9で、[Trusted Types API](https://github.com/w3c/webappsec-trusted-types)（[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API)）のサポートがDOMPurifyに追加されました。
バージョン2.0.0では、この点に関するDOMPurifyの動作を制御するための設定フラグが追加されました。

`DOMPurify.sanitize` がTrusted Types APIが利用可能な環境で使用され、`RETURN_TRUSTED_TYPE` が `true` に設定されている場合、文字列の代わりに `TrustedHTML` 値を返そうとします（`RETURN_DOM` および `RETURN_DOM_FRAGMENT` 設定オプションの動作は変わりません）。

DOMPurifyを使用して `trustedTypes` にポリシーを作成するには、`createHTML` が通常の文字列（`TrustedHTML` ではない）を期待するため、`RETURN_TRUSTED_TYPE: false` が必要であることに注意してください。以下の例にこれを示します。```js
window.trustedTypes.createPolicy('default', {
  createHTML: (to_escape) =>
    DOMPurify.sanitize(to_escape, { RETURN_TRUSTED_TYPE: false }),
});

自身のラッピングポリシーを、その`createHTML`がすでに`DOMPurify.sanitize`を呼び出している場合に、DOMPurifyの`TRUSTED_TYPES_POLICY`として（たとえば`DOMPurify.setConfig({ TRUSTED_TYPES_POLICY: myPolicy })`経由で）渡し**ない**でください。これは定義上循環しています。サニタイズがポリシーを呼び出し、ポリシーは再びDOMPurifyを呼び出すことでサニタイズするためです。DOMPurifyは無限再帰を防ぐために、説明的な`TypeError`をスローします。自身のポリシーはDOMPurifyを呼び出すべきであり、DOMPurifyが自身のポリシーを呼び出すように設定すべきではありません。

この`default`ポリシーパターンをページ全体に自動的に適用したい場合（レガシーコード、サードパーティ製ウィジェット、簡単には見つけたり書き換えたりできない何千もの`innerHTML`代入を含む、すべてのHTMLシンクがサニタイズされるように）は、[DOMFortify](https://github.com/cure53/DOMFortify)を参照してください。これはDOMPurifyをバックエンドにした、まさにそのようなTrusted Typesの`default`ポリシーをインストールし、スクリプトシンク（`eval`、`script.src`など）を完全に拒否します。これは意図的に別個のプロジェクトです。DOMPurifyは焦点を絞ったサニタイザーであり続け、DOMFortifyが、意図的にDOMPurifyの範囲外にあるドキュメント全体の強制レイヤーを処理します。

## DOMPurifyを設定できますか？

はい。同梱されているデフォルト設定値はすでにかなり優れていますが、もちろん上書きできます。[`/demos`](https://github.com/cure53/DOMPurify/tree/main/demos)フォルダを確認して、[DOMPurifyをカスタマイズする](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this)方法の例を多数参照してください。

許可リストを広げる（`ADD_TAGS`、`ADD_ATTR`、`CUSTOM_ELEMENT_HANDLING`など）か、デフォルトを緩める前に、[よく考えてから許可すべきタグと属性](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model#dangerous-tags-and-attributes-think-twice-before-allow-listing)に目を通す価値があります。いくつかは、わかりにくい方法で危険です。

### 一般設定```js
// strip {{ ... }}, ${ ... } and <% ... %> to make output safe for template systems
// be careful please, this mode is not recommended for production usage.
// allowing template parsing in user-controlled HTML is not advised at all.
// only use this mode if there is really no alternative.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_TEMPLATES: true });

// change how e.g. comments containing risky HTML characters are treated.
// be very careful, this setting should only be set to `false` if you really only handle
// HTML and nothing else, no SVG, MathML or the like.
// Otherwise, changing from `true` to `false` will lead to XSS in this or some other way.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_XML: false });

### カスタムエレメントに関する制御動作```js
// DOMPurify allows to define rules for Custom Elements. When using the CUSTOM_ELEMENT_HANDLING
// literal, it is possible to define exactly what elements you wish to allow (by default, none are allowed).
//
// The same goes for their attributes. By default, the built-in or configured allow.list is used.
//
// You can use a RegExp literal to specify what is allowed or a predicate, examples for both can be seen below.
// When using a predicate function for attributeNameCheck, it can optionally receive the tagName as a second parameter
// for more granular control over which attributes are allowed for specific elements.
// The default values are very restrictive to prevent accidental XSS bypasses. Handle with great care!

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: null, // no custom elements are allowed
      attributeNameCheck: null, // default / standard attribute allow-list is used
      allowCustomizedBuiltInElements: false, // no customized built-ins allowed
    },
  }
); // <div is=""></div>

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: /^foo-/, // allow all tags starting with "foo-"
      attributeNameCheck: /baz/, // allow all attributes containing "baz"
      allowCustomizedBuiltInElements: true, // customized built-ins are allowed
    },
  }
); // <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: (tagName) => tagName.match(/^foo-/), // allow all tags starting with "foo-"
      attributeNameCheck: (attr) => attr.match(/baz/), // allow all containing "baz"
      allowCustomizedBuiltInElements: true, // allow customized built-ins
    },
  }
); // <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>

// Example with attributeNameCheck receiving tagName as a second parameter
const clean = DOMPurify.sanitize(
  '<element-one attribute-one="1" attribute-two="2"></element-one><element-two attribute-one="1" attribute-two="2"></element-two>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: (tagName) => tagName.match(/^element-(one|two)$/),
      attributeNameCheck: (attr, tagName) => {
        if (tagName === 'element-one') {
          return ['attribute-one'].includes(attr);
        } else if (tagName === 'element-two') {
          return ['attribute-two'].includes(attr);
        } else {
          return false;
        }
      },
      allowCustomizedBuiltInElements: false,
    },
  }
); // <element-one attribute-one="1"></element-one><element-two attribute-two="2"></element-two>

### 許可された属性値の制御```js
// allow external protocol handlers in URL attributes (default is false, be careful, XSS risk)
// by default only http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
const clean = DOMPurify.sanitize(dirty, { ALLOW_UNKNOWN_PROTOCOLS: true });

// allow specific protocol handlers in URL attributes via regex (default is false, be careful, XSS risk)
// by default only (protocol-)relative URLs, http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
// Default RegExp: /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;
const clean = DOMPurify.sanitize(dirty, {
  ALLOWED_URI_REGEXP:
    /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp|matrix):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i,
});

### サニタイズ方法への影響```js
// return entire document including <html> tags (default is false)
const clean = DOMPurify.sanitize(dirty, { WHOLE_DOCUMENT: true });

// disable DOM Clobbering protection on output (default is true, handle with care, minor XSS risks here)
const clean = DOMPurify.sanitize(dirty, { SANITIZE_DOM: false });

// enforce strict DOM Clobbering protection via namespace isolation (default is false)
// when enabled, isolates the namespace of named properties (i.e., `id` and `name` attributes)
// from JS variables by prefixing them with the string `user-content-`
const clean = DOMPurify.sanitize(dirty, { SANITIZE_NAMED_PROPS: true });

// keep an element's content when the element is removed (default is true)
const clean = DOMPurify.sanitize(dirty, { KEEP_CONTENT: false });

// glue elements like style, script or others to document.body and prevent unintuitive browser behavior in several edge-cases (default is false)
const clean = DOMPurify.sanitize(dirty, { FORCE_BODY: true });

// remove all <a> elements under <p> elements that are removed
const clean = DOMPurify.sanitize(dirty, {
  FORBID_CONTENTS: ['a'],
  FORBID_TAGS: ['p'],
});

// extend the default FORBID_CONTENTS list to also remove <a> elements under <p> elements
const clean = DOMPurify.sanitize(dirty, {
  ADD_FORBID_CONTENTS: ['a'],
  FORBID_TAGS: ['p'],
});

// change the parser type so sanitized data is treated as XML and not as HTML, which is the default
const clean = DOMPurify.sanitize(dirty, {
  PARSER_MEDIA_TYPE: 'application/xhtml+xml',
});

以下に、チャンク43/45の翻訳を示します。

[さらに多くの例はこちら](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this)にあり、DOMPurifyを実行、カスタマイズ、設定する方法を確認できます。

## 永続的な設定

毎回同じ設定を`DOMPurify.sanitize`に渡す代わりに、`DOMPurify.setConfig`メソッドを使用できます。設定は、次に`DOMPurify.setConfig`を呼び出すまで、または`DOMPurify.clearConfig`を呼び出してリセットするまで保持されます。アクティブな設定は1つだけであることに注意してください。つまり、設定が設定されると、`DOMPurify.sanitize`に渡される追加の設定パラメータはすべて無視されます。

## フック

DOMPurifyでは、`DOMPurify.addHook`メソッドを使用して1つ以上の関数を次のフックのいずれかにアタッチすることで、機能を拡張できます。

- `beforeSanitizeElements`
- `uponSanitizeElement`（'s'なし - すべての要素に対して呼び出されます）
- `afterSanitizeElements`
- `beforeSanitizeAttributes`
- `uponSanitizeAttribute`
- `afterSanitizeAttributes`
- `beforeSanitizeShadowDOM`
- `uponSanitizeShadowNode`
- `afterSanitizeShadowDOM`

コールバックには、現在処理中のDOMノード、必要に応じて検証済みのノードと属性データを含むリテラル、およびDOMPurify設定が渡されます。APIの使用方法の良い例については、[MentalJSフックデモ](https://github.com/cure53/DOMPurify/blob/main/demos/hooks-mentaljs-demo.html)を確認してください。

_例_:```js
DOMPurify.addHook(
  'uponSanitizeAttribute',
  function (currentNode, hookEvent, config) {
    // Do something with the current node
    // You can also mutate hookEvent for current node (i.e. set hookEvent.forceKeepAttr = true)
    // For other than 'uponSanitizeAttribute' hook types hookEvent equals to null
  }
);

DOMPurify v3.4.13

DOMPurify

目次

何をするものですか？

どうやって使うのですか？

圧縮されていないバージョンを使用する場合（ソースマップ付き）```html

デモはありますか？

セキュリティバグを見つけたらどうすればいいですか？

浄化のサンプルをいくつか見せてくれませんか？

許可リストとブロックリストを制御する```js

URI値に関する制御動作```js

戻り値の型に影響を与える```js

サニタイズする場所への影響```js

フックからsanitize()を呼び出す際の注意点

削除された設定

継続的インテグレーション

開発と貢献

インストール（npm i）

スクリプト

セキュリティメーリングリスト

貢献者

カテゴリ

フックから`sanitize()`を呼び出す際の注意点

インストール（`npm i`）