本文へ移動

k8o

お問い合わせ

255文字以内で入力してください

GitHub Issueからのお問い合わせもお待ちしております。

Blog

公開: 2026年4月5日(日)更新: 2026年11月9日(月)約13分で読めます

Reporting APIでCSP違反などのレポートをサーバーに集める

Reporting APIは、CSP違反のようにブラウザが検知した問題を、Reporting-Endpointsで指定したサーバーへ送らせます。ReportingObserverで受け取る方法と、届くJSONも説明します。

Newly availableReporting API2026年〜
  • Chrome96
  • Edge96
  • Firefox149
  • Safari16.4

はじめに

Reporting APIは、CSP違反のようにブラウザが検知した問題を、レポートとしてサーバーに送らせたり、JavaScriptで受け取ったりする仕組みです。Firefox 149が対応して、Baseline 2026に入りました。レポートの種類は仕様ごとに決まっていて、Baselineに入っているのはCSPの違反(csp-violation)のレポートです。

JavaScriptの例外は、window.onerrorで拾ってfetchで送れます。CSPの違反は、ブラウザが検知してもページの例外にならないので、Reporting APIで受け取ります。ユーザーのブラウザで起きた、開発環境では気づきにくい問題を集められます。

レポートを受け取る方法は2つあります。

  • Reporting-Endpointsヘッダー:サーバーのエンドポイントに、ブラウザが自動で送る
  • ReportingObserver:ページのJavaScriptで受け取る

次のコードは、両方を使う例です。ページは別のオリジンの画像を読もうとし、CSPのimg-src 'self'に違反します。

server.mjs
import { createServer } from 'node:http';

const page = `<script>
  new ReportingObserver((reports) => {
    for (const report of reports) console.log(report.type, report.body.blockedURL);
  }).observe();
</script>
<img src="https://example.com/a.png">`;

createServer((req, res) => {
  if (req.method === 'POST') {
    let body = '';
    req.on('data', (chunk) => (body += chunk));
    req.on('end', () => {
      console.log(req.headers['content-type'], body);
      res.writeHead(204).end();
    });
    return;
  }
  res.writeHead(200, {
    'Content-Type': 'text/html; charset=utf-8',
    'Reporting-Endpoints': 'default="http://localhost:3000/reports"',
    'Content-Security-Policy': "img-src 'self'; report-to default",
  });
  res.end(page);
}).listen(3000);

http://localhost:3000を開くと、DevToolsのコンソールにReportingObserverが受け取ったcsp-violation https://example.com/a.pngが出ます(SafariのURLはhttps://example.com:443/a.png)。FirefoxとSafariでは、数秒のうちにターミナルにも同じ違反のレポートが出ます。

Reporting-Endpointsヘッダー

Reporting-Endpointsはレスポンスヘッダーで、レポートの送り先のエンドポイントに名前を付けて定義します。カンマで区切れば、複数の名前を定義できます。

http
Reporting-Endpoints: default="https://example.com/reports"

エンドポイントのURLはHTTPSにします。HTTPのエンドポイントは無視されますが、手元で試すときのhttp://localhostには届きます。

エンドポイントの指定方法

CSPのreport-toディレクティブに、Reporting-Endpointsで付けた名前を書きます。

http
Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports"
Content-Security-Policy: default-src 'self'; report-to csp-endpoint

この設定では、CSPの違反のレポートがcsp-endpointのURLに届きます。

レポートの送信形式

ブラウザはレポートをJSONでエンドポイントにPOSTします。Content-Typeはapplication/reports+jsonで、bodyはレポートの配列です。

json
[
  {
    "type": "csp-violation",
    "age": 53531,
    "url": "https://example.com/page",
    "user_agent": "Mozilla/5.0 ...",
    "body": {
      "blockedURL": "https://evil.com/script.js",
      "columnNumber": 39,
      "disposition": "enforce",
      "documentURL": "https://example.com/page",
      "effectiveDirective": "script-src-elem",
      "lineNumber": 121,
      "originalPolicy": "default-src 'self'; report-to csp-endpoint",
      "referrer": "https://www.google.com/",
      "sample": "",
      "sourceFile": "https://example.com/app.js",
      "statusCode": 200
    }
  }
]

ageは、レポートを作ってからの経過ミリ秒です。絶対時刻を入れると、ブラウザの時計のずれからユーザーを見分けるフィンガープリントに使われる恐れがあるので、相対的な時間になっています。

上のserver.mjsで試すと、Firefoxはこの形の配列を送ります。SafariはContent-Typeがapplication/csp-reportで、typeとurl、bodyだけを持つオブジェクトを1件ずつ送り、ageとuser_agentはありません。受け取るサーバーは、両方の形を扱えるようにしておきます。

いつ送るかはブラウザに任されていて、届くことも保証されません。Firefoxは数秒のうちに複数のレポートを1つの配列にまとめて送り、Safariは違反のたびにすぐ送ります。

Report-Onlyモード

Content-Security-Policy-Report-Onlyヘッダーを使うと、ポリシーを強制せずにレポートだけを集められます。

http
Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports"
Content-Security-Policy-Report-Only: default-src 'self'; report-to csp-endpoint

Report-Onlyで送られるレポートのdispositionは"report"になり、強制しているときの"enforce"と見分けられます。新しいポリシーを入れるときは、まずReport-Onlyで違反を洗い出してから強制に切り替えます。

ReportingObserver

ReportingObserverは、ページのJavaScriptでレポートを受け取るAPIです。サーバーに送らなくてよいときや、レポートに応じてページで何かしたいときに使います。

js
const observer = new ReportingObserver((reports) => {
  for (const report of reports) {
    console.log(report.type); // "csp-violation"
    console.log(report.url); // "https://example.com/page"
    console.log(report.body); // レポートの詳細
  }
});

observer.observe();

ReportingObserverがCSPの違反を受け取るかは、ブラウザで違います。report-toを書いたCSPの違反は、どのブラウザでも届きます。report-toの無いCSP(<meta>で書いたものを含む)の違反は、Chromeにだけ届きます。ページの中で受け取るだけのときも、ヘッダーのCSPにreport-toを書いておきます。

コンストラクタ

ReportingObserverのコンストラクタは、第1引数にコールバック関数、第2引数にオプションを受け取ります。コールバック関数には、レポートの配列とReportingObserver自身が渡されます。

js
const observer = new ReportingObserver(
  (reports, observer) => {
    // レポートの処理
  },
  {
    // 受け取るレポートの種類を絞り込む
    types: ['csp-violation'],
    // observe()を呼ぶ前にできたレポートも受け取る
    buffered: true,
  },
);

typesを指定しないと、すべての種類のレポートを受け取ります。bufferedをtrueにすると、observe()を呼ぶ前にたまっていたレポートも受け取れるので、ページを読み込んだときに起きた違反も後から確かめられます。

メソッド

ReportingObserverには3つのメソッドがあります。

js
observer.observe(); // 受け取りを始める
const records = observer.takeRecords(); // たまっているレポートを配列で取り出し、キューを空にする
observer.disconnect(); // 受け取りをやめる

Reportオブジェクト

コールバックに渡されるレポートは、次のプロパティを持ちます。

  • type:レポートの種類("csp-violation"など)
  • url:レポートが作られたドキュメントのURL
  • body:レポートの種類ごとの詳細(ReportBody | null)

CSPの違反のレポート(type: "csp-violation")のbodyは、次のプロパティを持ちます。

js
report.body.blockedURL; // ブロックされたリソースのURL
report.body.disposition; // "enforce" または "report"
report.body.documentURL; // ドキュメントのURL
report.body.effectiveDirective; // 違反を検出したディレクティブ
report.body.originalPolicy; // 元のCSPポリシー文字列
report.body.referrer; // リファラー(不明な場合はnull)
report.body.sample; // 違反コードの先頭40文字
report.body.sourceFile; // スクリプトファイルのURL(不明な場合はnull)
report.body.lineNumber; // 行番号
report.body.columnNumber; // 列番号
report.body.statusCode; // HTTPステータスコード

おわりに

Reporting-EndpointsヘッダーとCSPのreport-toを書けば、ユーザーのブラウザで起きたCSPの違反をサーバーに集められます。ページの中で受け取るときはReportingObserverを使い、ヘッダーのCSPにもreport-toを書いておきます。

読了率 0%
もくじ