HTMLPurifier による HTML サニタイズ

a-blog cms は、エントリー本文などユーザーが入力した HTML をテンプレート変数として出力する際、HTMLPurifier を使って XSS につながる要素・属性を取り除きます。このページでは、標準のサニタイズ処理と、設定・Hook による拡張方法を説明します。

テンプレートでの出力とサニタイズ

テンプレート変数は既定で エスケープされ、HTML タグは < などの文字列として表示されます。エントリー本文のように HTML を HTML のまま出力したいときは raw 校正オプションを付けます。サニタイズ（HTMLPurifier）は、この raw 出力に対して危険な要素・属性だけを取り除き、安全な HTML を残す処理です（エスケープのように全体を文字化するのではなく、HTML の構造を保ったまま無害化します）。

標準テンプレートでのサニタイズの効き方は、校正オプションと config で決まります。

Twig テンプレートでは {{ entry.body|safe_html }} がサニタイズ付き出力、{{ entry.body|raw }} が非サニタイズ出力にあたります。

サニタイズが適用されるタイミング

サニタイズは HTML を保存するときではなく、出力するときに適用されます。データベースに保存されている HTML 自体が書き換わるわけではありません。代表的には次の場面です。

• エントリー本文などのHTML文字列を raw でテンプレート出力するとき

• ページキャッシュを再生成するとき

• システム更新時にコンテンツを再生成するとき

出力のたびに適用されるため、dangerous_tags や iframe の許可ホストといった設定を変更すると、既存のエントリーもキャッシュの再生成タイミングで新しい方針に沿って出力し直されます。

自作のモジュールや拡張から同じサニタイズ処理を利用したい場合は、次のように呼び出せます。

$html = Acms\Services\Facades\Application::make('html-purifier')->clean($html);

サニタイズ設定

有効無効 （strip_dangerous_tag）

標準テンプレートでraw 校正オプション利用時の変数の出力時にデフォルトで HTMLPurifier を利用したサニタイズを適用するかどうかを設定します。

strip_dangerous_tag: on # on | off 変数から標準で危険なタグ（dangerous_tagsで指定）を削除するか指定

新規インストール時のデフォルトは on です。

禁止タグ（dangerous_tags）

private/config.system.default.yaml のデフォルト値は次のとおりです。

dangerous_tags: ['form']

ここに列挙したタグは丸ごと削除されます。<font> など HTML 標準で非推奨・廃止されたタグは、dangerous_tags の指定に関わらず常に削除されます。

iframe は dangerous_tags ではなく、次に説明する whitelist で制御します。

iframe のホスト whitelist （Ver. 3.2.25 ~）

html_purifier_iframe_allowed_hosts で、src を許可するホスト（パス prefix 可）を指定します。

html_purifier_iframe_allowed_hosts: [
    'www.youtube.com/embed|fullscreen; encrypted-media; picture-in-picture|',
    'www.youtube-nocookie.com/embed|fullscreen; encrypted-media; picture-in-picture|',
    'player.vimeo.com/video|fullscreen; picture-in-picture|',
    'embed.nicovideo.jp/watch/|fullscreen; encrypted-media; picture-in-picture|',
    'www.dailymotion.com/embed/video|fullscreen; picture-in-picture|',
    'player.twitch.tv|fullscreen|',
    'embed.ted.com/talks|fullscreen|',
    'streamable.com/e/|fullscreen|',
    'players.brightcove.net|fullscreen; encrypted-media|',
    'fast.wistia.net/embed/iframe|fullscreen|',
    'www.google.com/maps/embed',
    'docs.google.com/forms|',
    'calendar.google.com/calendar/embed|',
    'lookerstudio.google.com/embed/reporting|fullscreen|',
    'docs.google.com/document/d/e/|fullscreen|',
    'docs.google.com/spreadsheets/d/e/|',
    'docs.google.com/presentation/d/e/|fullscreen|',
    'docs.google.com/drawings/d/e/|',
    'open.spotify.com/embed/|encrypted-media|',
    'voicy.jp/embed/|',
    'stand.fm/embed/channels/|',
    'stand.fm/embed/episodes/|',
    'w.soundcloud.com/player|',
    'embed.podcasts.apple.com|encrypted-media|',
    'speakerdeck.com/player/|fullscreen|',
    'www.slideshare.net/slideshow/embed_code/|fullscreen|',
    'note.com/embed/notes/|',
    'hatenablog-parts.com/embed|',
    'e.issuu.com/embed.html|fullscreen|',
    'www.scribd.com/embeds|',
    'www.figma.com/embed|fullscreen|',
    'www.canva.com/design/|fullscreen|',
    'codepen.io|fullscreen|',
    'codesandbox.io/embed|fullscreen|',
    'miro.com/app/live-embed|fullscreen|',
    'sketchfab.com/models|fullscreen|',
    'map.yahoo.co.jp/embed|',
    'www.navitime.co.jp/maps/embed|',
]

書式は host[/pathPrefix][|allow[|sandbox]] です。

allow / sandbox は「編集者が要求できる capability の許可リスト」です。エントリー側の <iframe> に書かれた allow（セミコロン区切り）/ sandbox（スペース区切り）のうち、ここに列挙したトークンだけが残り、許可リスト外のトークンは削除されます。編集者が allow / sandbox を書いていなければ何も付与されません（強制で付与されることはありません）。ホスト部分だけを書いた場合は許可リストが空になり、編集者が何を書いても capability が付与されない最小権限になります。

• 許可ホストにマッチしない <iframe> は、src だけが取り除かれて空の <iframe> として残ります（要素ごと削除されるわけではありません）。

• html_purifier_iframe_allowed_hosts: [] にすると、すべての iframe の src が無効化されます。

• 設定は private/config.system.yaml 側で上書き（追加・削除）できます。

Hook による拡張

dangerous_tags や whitelist だけで表現できない要件（独自タグ・属性の許可、URI スキームの追加など）は、extendsHtmlPurifierConfig / extendsHtmlPurifierDefinition の 2 つのフックで拡張します。サイト拡張（extension/acms/Hook.php）やプラグインのフッククラスに実装します。

2 つのフックの違い（Ver. 3.2.25 ~）

HTML.* 系の設定は定義の取得前に確定させる必要があるため、許可タグ・属性・URI スキームの調整は必ず extendsHtmlPurifierConfig 側で行ってください。定義取得後にしか行えない要素・属性の追加（addElement / addAttribute）は extendsHtmlPurifierDefinition 側で行います。

/**
 * HTMLPurifier の設定構築時に呼ばれる拡張ポイント（カスタム HTML 定義の取得前）
 */
public function extendsHtmlPurifierConfig(\HTMLPurifier_Config $config): void
{
    // 例: data: スキームの画像を許可する
    $config->set('URI.AllowedSchemes', ['http' => true, 'https' => true, 'mailto' => true, 'data' => true]);

    // 例: 特定タグをさらに禁止する（既定値を上書き）
    $config->set('HTML.ForbiddenElements', ['script', 'iframe', 'form', 'object']);
}

/**
 * HTMLPurifier のカスタム HTML 定義の構築時に呼ばれる拡張ポイント（定義の取得後）
 */
public function extendsHtmlPurifierDefinition(\HTMLPurifier_HTMLDefinition $def, \HTMLPurifier_Config $config): void
{
    // 例: <details> / <summary> を許可し、独自 data 属性を通す
    $def->addElement('details', 'Block', 'Flow', 'Common', ['open' => 'Bool#open']);
    $def->addElement('summary', 'Inline', 'Inline', 'Common');
    $def->addAttribute('div', 'data-my-widget', 'CDATA');
}

雛形（ablogcms/extension/acms/Hook.php）にも同じ形の空実装とサンプルコメントが用意されています。

キャッシュ

カスタム HTML 定義はキャッシュされます。iframe whitelist（html_purifier_iframe_allowed_hosts）を config で変更した場合は自動でキャッシュが再生成されますが、extendsHtmlPurifierConfig / extendsHtmlPurifierDefinition フックで追加・変更した内容は自動では反映されません。

フックの実装を追加・変更したときは、必ず管理画面からキャッシュを削除してください。 削除すると html-purifier 用のキャッシュディレクトリが消え、次回アクセス時に新しい定義でキャッシュが再生成されます。挙動が反映されていないように見えたときも、まずキャッシュ削除を試してください。

注意点

• extendsHtmlPurifierConfig / extendsHtmlPurifierDefinition はフック機能が有効（HOOK_ENABLE）であることが前提です。フックを無効化している環境では呼ばれません。

• 独自属性を許可する際は、フリーフォームの CDATA を安易に増やさず、可能な限り Enum や Bool など型付きの AttrDef を使ってください。