Reporting APIでCSP違反などのレポートをサーバーに集める
Reporting APIは、CSP違反のようにブラウザが検知した問題を、Reporting-Endpointsで指定したサーバーへ送らせます。ReportingObserverで受け取る方法と、届くJSONも説明します。
- 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'に違反します。
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はレスポンスヘッダーで、レポートの送り先のエンドポイントに名前を付けて定義します。カンマで区切れば、複数の名前を定義できます。
Reporting-Endpoints: default="https://example.com/reports"エンドポイントのURLはHTTPSにします。HTTPのエンドポイントは無視されますが、手元で試すときのhttp://localhostには届きます。
エンドポイントの指定方法
CSPのreport-toディレクティブに、Reporting-Endpointsで付けた名前を書きます。
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はレポートの配列です。
[
{
"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ヘッダーを使うと、ポリシーを強制せずにレポートだけを集められます。
Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports"
Content-Security-Policy-Report-Only: default-src 'self'; report-to csp-endpointReport-Onlyで送られるレポートのdispositionは"report"になり、強制しているときの"enforce"と見分けられます。新しいポリシーを入れるときは、まずReport-Onlyで違反を洗い出してから強制に切り替えます。
ReportingObserver
ReportingObserverは、ページのJavaScriptでレポートを受け取るAPIです。サーバーに送らなくてよいときや、レポートに応じてページで何かしたいときに使います。
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自身が渡されます。
const observer = new ReportingObserver(
(reports, observer) => {
// レポートの処理
},
{
// 受け取るレポートの種類を絞り込む
types: ['csp-violation'],
// observe()を呼ぶ前にできたレポートも受け取る
buffered: true,
},
);typesを指定しないと、すべての種類のレポートを受け取ります。bufferedをtrueにすると、observe()を呼ぶ前にたまっていたレポートも受け取れるので、ページを読み込んだときに起きた違反も後から確かめられます。
メソッド
ReportingObserverには3つのメソッドがあります。
observer.observe(); // 受け取りを始める
const records = observer.takeRecords(); // たまっているレポートを配列で取り出し、キューを空にする
observer.disconnect(); // 受け取りをやめるReportオブジェクト
コールバックに渡されるレポートは、次のプロパティを持ちます。
type:レポートの種類("csp-violation"など)url:レポートが作られたドキュメントのURLbody:レポートの種類ごとの詳細(ReportBody | null)
CSPの違反のレポート(type: "csp-violation")のbodyは、次のプロパティを持ちます。
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を書いておきます。