セキュリティ違反や非推奨の API 呼び出しなどをモニタリングするには、Reporting API を使用してください。
一部のエラーは本番環境でのみ発生します。実際のユーザー、実際のネットワーク、実際のデバイスによってゲームが変わるため、ローカルや開発中はこれらは表示されません。Reporting API は、セキュリティ違反や、サイト全体で非推奨またはまもなく非推奨の API 呼び出しなどのエラーを検出し、指定したエンドポイントに送信します。
HTTP ヘッダーを介してモニタリングする対象を宣言でき、ブラウザによって操作されます。
Reporting API を設定することで、ユーザーがこの種のエラーに遭遇したときに気づき、修正できるため、安心感が得られます。
この投稿では、この API の機能と使用方法について説明します。それでは詳しく見ていきましょう。
デモとコード
Chrome 96 以降(2021 年 10 月現在、Chrome ベータ版または Canary 版)の Reporting API の動作をご確認ください。
概要
サイト site.example
に Content-Security-Policy と Document-Policy が設定されているとします。どんな機能かわからない場合は、それでも この例は理解できます
それらのポリシーに違反したタイミングを知るためにサイトをモニタリングするだけでなく、コードベースで使用されている、非推奨の API や非推奨が近い API を監視するためにも、サイトをモニタリングすることにしました。
これを行うには、Reporting-Endpoints
ヘッダーを構成し、必要に応じてポリシーの report-to
ディレクティブを使用してこれらのエンドポイント名をマッピングします。
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint
予期せぬ事態が発生し、一部のユーザーがこれらのポリシーに違反します。
違反の例
index.html
<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>
script.js
、index.html
が読み込みました
// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
document.write('<h1>hi</h1>');
} catch (e) {
console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;
ブラウザは、これらの問題をキャプチャする CSP 違反レポート、ドキュメント ポリシー違反レポート、非推奨レポートを生成します。
ブラウザは短い遅延(最大 1 分)で、この違反タイプ用に構成されたエンドポイントにレポートを送信します。レポートは、サーバーやサイトではなく、ブラウザ自体からスパンタップで送信されます。
エンドポイントはこれらのレポートを受け取ります。
これで、これらのエンドポイントのレポートにアクセスして、何が問題かをモニタリングできるようになりました。これで、ユーザーに影響を及ぼしている問題のトラブルシューティングを開始できます。
サンプル レポート
{
"age": 2,
"body": {
"blockedURL": "https://site2.example/script.js",
"disposition": "enforce",
"documentURL": "https://site.example",
"effectiveDirective": "script-src-elem",
"originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
"referrer": "https://site.example",
"sample": "",
"statusCode": 200
},
"type": "csp-violation",
"url": "https://site.example",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}
ユースケースとレポートタイプ
サイト全体で発生するさまざまな警告や問題をモニタリングできるように、Reporting API を設定できます。
レポートタイプ | レポートが生成される状況の例 |
---|---|
CSP 違反(レベル 3 のみ) | いずれかのページに Content-Security-Policy (CSP)を設定していますが、そのページで CSP で許可されていないスクリプトを読み込もうとしています。 |
COOP 違反 | ページに Cross-Origin-Opener-Policy を設定しましたが、クロスオリジン ウィンドウがドキュメントを直接操作しようとしています。 |
COEP 違反 | ページに Cross-Origin-Embedder-Policy を設定していますが、クロスオリジン ドキュメントによる読み込みが有効にされていないクロスオリジン iframe がドキュメントに含まれています。 |
ドキュメントのポリシー違反 | document.write の使用を禁止するドキュメント ポリシーがそのページに含まれていますが、スクリプトが document.write を呼び出そうとしています。 |
権限ポリシーへの違反 | このページには、マイクの使用を禁止する権限ポリシーと、音声入力をリクエストするスクリプトが設定されています。 |
非推奨に関する警告 | サポートが終了した API またはサポート終了予定の API がページで使用されています。API を直接、または最上位のサードパーティ スクリプトを介して呼び出しています。 |
介入 | セキュリティ、パフォーマンス、またはユーザー エクスペリエンスの理由でブラウザが無視できない動作をページで行おうとしています。Chrome の例: ページが低速ネットワークで document.write を使用しているか、ユーザーがまだ操作していないクロスオリジン フレームで navigator.vibrate を呼び出しています。 |
衝突事故 | サイトを開いている間にブラウザがクラッシュします。 |
レポート
レポートの外観
設定したエンドポイントに、ブラウザがレポートを送信します。次のようなリクエストを送信します。
POST
Content-Type: application/reports+json
これらのリクエストのペイロードはレポートのリストです。
レポートリストの例
[
{
"age": 420,
"body": {
"columnNumber": 12,
"disposition": "enforce",
"lineNumber": 11,
"message": "Document policy violation: document-write is not allowed in this document.",
"policyId": "document-write",
"sourceFile": "https://site.example/script.js"
},
"type": "document-policy-violation",
"url": "https://site.example/",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
},
{
"age": 510,
"body": {
"blockedURL": "https://site.example/img.jpg",
"destination": "image",
"disposition": "enforce",
"type": "corp"
},
"type": "coep",
"url": "https://dummy.example/",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}
]
各レポートでは、次のデータを確認できます。
項目 | 説明 |
---|---|
age |
レポートのタイムスタンプから現在の時刻までのミリ秒数。 |
body |
JSON 文字列にシリアル化された実際のレポートデータ。レポートの body に含まれるフィールドは、レポートの type によって決まります。⚠️ レポートの種類によって本文が異なります。
各レポートタイプの正確な本文については、デモレポート エンドポイント を確認し、手順に沿ってサンプル レポートを生成してください。 |
type |
レポートタイプ(例: csp-violation 、coep )。 |
url |
レポート生成元のドキュメントまたはワーカーのアドレス。ユーザー名、パスワード、フラグメントなどの機密データはこの URL から削除されます。 |
user_agent |
レポートが生成されたリクエストの User-Agent ヘッダー。 |
認証情報レポート
レポートを生成するページと同じオリジンのレポート エンドポイントは、レポートを含むリクエストで認証情報(Cookie)を受け取ります。
認証情報は、レポートに関する有用な追加コンテキストを提供できます。たとえば、特定のユーザー アカウントが一貫してエラーをトリガーしているかどうかや、他のページで実行された特定の一連の操作によってこのページのレポートがトリガーされているかどうかなどを確認できます。
ブラウザがレポートを送信するタイミングと方法
レポートはサイトから帯域外に配信される: 構成済みのエンドポイントに送信されるタイミングはブラウザによって制御されます。また、ブラウザがレポートを送信するタイミングを制御する方法もありません。適切なタイミングでレポートをキャプチャし、キューに入れて、自動的に送信します。
つまり、Reporting API を使用する際にパフォーマンスに関する懸念はほとんど、あるいはまったくありません。
レポートの送信には最大 1 分の遅延があるため、レポートを一括で送信できる可能性が高くなります。これにより、ユーザーのネットワーク接続に応じた帯域幅を節約できます。これはモバイルで特に重要です。また、ブラウザが優先度の高い作業の処理でビジー状態である場合や、ユーザーが使用しているときにネットワークが低速または混雑している場合にも、配信が遅延することがあります。
サードパーティと自社に関する問題
ページで発生した違反またはサポート終了により生成されたレポートは、構成したエンドポイントに送信されます。これには、ページで実行されているサードパーティ スクリプトによる違反も含まれます。
ページに埋め込まれたクロスオリジンの iframe で発生した違反またはサポート終了は、エンドポイントに報告されません(デフォルトでは報告されません)。iframe で独自のレポートを設定して、サイト(ファーストパーティのレポート サービス)にレポートすることもできますが、それはフレーム対象のサイト次第です。また、ほとんどのレポートはページのポリシーに違反した場合にのみ生成されます。また、ページのポリシーと iframe のポリシーが異なる場合にのみ生成されます。
非推奨の例
ブラウザ サポート
次の表は、ブラウザによる Reporting API v1(Reporting-Endpoints
ヘッダー付き)のサポートをまとめたものです。ブラウザでの Reporting API v0(Report-To
ヘッダー)のサポートは、レポートタイプ 1(ネットワーク エラー ロギングが新しい Reporting API でサポートされていない)を除き、同じです。詳しくは、移行ガイドをご覧ください。
レポートタイプ | Chrome | Chrome iOS | Safari | Firefox | エッジ |
---|---|---|---|---|---|
CSP 違反(レベル 3 のみ)* | ✔ はい | ✔ はい | ✔ はい | Ж × | ✔ はい |
ネットワーク エラーのロギング | Ж × | Ж × | Ж × | Ж × | Ж × |
Co-op/COEP 違反 | ✔ はい | Ж × | ✔ はい | Ж × | ✔ はい |
その他すべてのタイプ: ドキュメント ポリシー違反、非推奨、介入、クラッシュ | ✔ はい | Ж × | Ж × | Ж × | ✔ はい |
次の表は、新しい Reporting-Endpoints
ヘッダーを使用した report-to
のサポートをまとめたものです。Reporting-Endpoints
に移行する場合は、CSP レポートの移行のヒントをご覧ください。
Reporting API を使用する
レポートの送信先を決定する
この場合は、次のどちらかを行ってください。
- 既存のレポート コレクタ サービスにレポートを送信します。
- 自分で作成および運用するレポート コレクタにレポートを送信します。
オプション 1: 既存のレポート コレクタ サービスを使用する
レポート コレクタ サービスの例を次に示します。
他の解決策をご存じでしたら、問題を作成してお知らせください。この投稿を更新いたします。
レポート コレクタを選択する際は、料金のほかにも次の点を考慮してください。 🧐?
- このコレクタはすべてのレポートタイプをサポートしていますか?たとえば、すべてのレポート エンドポイント ソリューションが COOP/COEP レポートをサポートしているわけではありません。
- アプリケーションの URL をサードパーティのレポート コレクタと共有しても問題ないですか。 ブラウザによって URL から機密情報が削除されても、機密情報がこのように漏えいする可能性はあります。アプリケーションにとってリスクが高すぎるように思われる場合は、独自のレポート エンドポイントを運用してください。
オプション 2: 独自のレポート コレクタを作成して運用する
レポートを受信する独自のサーバーを構築することは簡単ではありません。手始めに 軽量のボイラープレートを フォークしますExpress で構築されており、レポートを受信して表示できます。
ボイラープレート レポート コレクタに移動します。
[Remix to Edit] をクリックしてプロジェクトを編集可能にします。
これでクローンができました。目的に合わせてカスタマイズできます。
ボイラープレートを使用せず、独自のサーバーをゼロから作成する場合:
- ブラウザからエンドポイントに送信されたレポート リクエストを認識するため、
Content-Type
がapplication/reports+json
のPOST
リクエストを確認します。 - エンドポイントがサイトとは異なるオリジンに存在する場合は、CORS プリフライト リクエストをサポートしていることを確認します。
オプション 3: オプション 1 と 2 を組み合わせる
レポートの種類によっては特定のプロバイダに処理を任せて、他のプロバイダには社内ソリューションを用意することもできます。
この場合、次のように複数のエンドポイントを設定します。
Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"
Reporting-Endpoints
ヘッダーを構成する
Reporting-Endpoints
レスポンス ヘッダーを設定します。値は、1 つまたは一連のカンマ区切りの Key-Value ペアにする必要があります。
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
以前の Reporting API から新しい Reporting API に移行する場合は、Reporting-Endpoints
と Report-To
の両方を設定することをおすすめします。詳しくは、移行ガイドをご覧ください。特に、report-uri
ディレクティブを介してのみ Content-Security-Policy
違反のレポートを使用している場合は、CSP レポートの移行手順を確認してください。
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: ...
キー(エンドポイント名)
各キーには、main-endpoint
や endpoint-1
など、任意の名前を付けることができます。レポートタイプごとに異なる名前付きエンドポイントを設定できます(例: my-coop-endpoint
、my-csp-endpoint
)。これにより、タイプに応じてレポートを異なるエンドポイントにルーティングできます。
介入、非推奨、クラッシュ レポートを受け取るには、default
という名前のエンドポイントを設定します。
Reporting-Endpoints
ヘッダーで default
エンドポイントが定義されていない場合、このタイプのレポートは送信されません(ただし生成されます)。
値(URL)
各値は、レポートの送信先として指定する URL です。ここで設定する URL は、ステップ 1 で決めた URL によって異なります。
エンドポイント URL:
- 先頭はスラッシュ(
/
)にする必要があります。相対パスはサポートされていません。 - クロスオリジンの場合もありますが、その場合、認証情報はレポートとともに送信されません。
例
Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"
その後、各名前付きエンドポイントを適切なポリシーで使用することも、すべてのポリシーで 1 つのエンドポイントを使用することもできます。
ヘッダーをどこに設定するか
この投稿で説明する新しい Reporting API では、レポートのスコープがドキュメントになります。つまり、1 つのオリジンに対して、異なるドキュメント(site.example/page1
や site.example/page2
など)から異なるエンドポイントにレポートを送信できます。
サイトの任意のページで違反または非推奨の発生に関するレポートを受け取るには、すべてのレスポンスでヘッダーをミドルウェアとして設定します。
Express での例を次に示します。
const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;
app.use(function (request, response, next) {
// Set up the Reporting API
response.set(
'Reporting-Endpoints',
`main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
);
next();
});
ポリシーを編集する
Reporting-Endpoints
ヘッダーを構成したので、違反レポートを受け取る各ポリシー ヘッダーに report-to
ディレクティブを追加します。report-to
の値は、構成した名前付きエンドポイントのいずれかにする必要があります。
複数のポリシーに複数のエンドポイントを使用することも、ポリシー間で異なるエンドポイントを使用することもできます。
非推奨、介入、クラッシュ レポートに report-to
は必要ありません。これらのレポートは、どのポリシーにもバインドされていません。default
エンドポイントが設定され、この default
エンドポイントに送信されている限り、生成されます。
例
# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint
コード例
これらすべてをコンテキストとして確認するために、Express を使用してこの記事で説明したすべての要素を 1 つにまとめたノードサーバーの例を示します。さまざまなレポートタイプのレポートを設定する方法と、結果を表示します。
レポート設定をデバッグする
意図的にレポートを生成する
Reporting API の設定時には、意図したとおりにレポートが生成されて送信されるかどうかを確認するため、意図的にポリシー違反をする必要が生じる場合があります。あらゆるタイプのレポートを生成する、ポリシー違反などの悪質なコードの例を確認するには、デモをご覧ください。
時間を節約
レポートの送信に 1 分ほどかかる場合があります。デバッグには長い時間がかかります。❌ Chrome でデバッグする際には、--short-reporting-delay
フラグを使用すると、レポートが生成されたらすぐに受信できます。
このフラグを有効にするには、ターミナルで次のコマンドを実行します。
YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay
DevTools を使用する
Chrome で DevTools を使用して、送信済みのレポートと今後送信されるレポートを確認します。
2021 年 10 月現在、この機能は試験運用版です。使用する手順は次のとおりです。
- Chrome バージョン 96 以降を使用している(ブラウザで「
chrome://version
」と入力して確認) - Chrome の URL バーに「
chrome://flags/#enable-experimental-web-platform-features
」と入力するか貼り付けます。 - [有効] をクリックします。
- ブラウザを再起動する。
- Chrome DevTools を開きます。
- Chrome DevTools で [設定] を開きます。[テスト] の [アプリケーション] パネルの [Reporting API を有効にする] をクリックします。
- DevTools を再読み込みします。
- ページを再読み込みします。DevTools が開いているページで生成されたレポートは、Chrome DevTools の [Application] パネルの [Reporting API] に表示されます。
レポートのステータス
[ステータス] 列には、レポートが正常に送信されたかどうかが表示されます。
ステータス | 説明 |
---|---|
Success |
ブラウザがレポートを送信し、エンドポイントから成功コード(200 または別の成功レスポンス コード 2xx )が返されます。 |
Pending |
ブラウザは現在、レポートの送信を試行しています。 |
Queued |
レポートが生成されましたが、ブラウザは現在その送信を試みていません。レポートは、次の 2 つのケースのいずれかで Queued として表示されます。
|
MarkedForRemoval |
しばらく(Queued )再試行した後で、ブラウザはレポートの送信を停止しました。レポートはまもなく送信対象のレポートのリストから削除されます。 |
レポートは、送信したかどうかに関係なくしばらくすると削除されます。
トラブルシューティング
レポートが生成されなかったり、想定どおりにエンドポイントに送信されなかったりしていませんか?この問題のトラブルシューティングのヒントをいくつか紹介します。
レポートが生成されない
DevTools に表示されるレポートが正しく生成されています。目的のレポートがこのリストに表示されない場合:
- ポリシーで
report-to
を確認してください。正しく構成されていない場合、レポートは生成されません。この問題を解決するには、ポリシーを編集するをご覧ください。この問題をトラブルシューティングするもう 1 つの方法は、Chrome の DevTools コンソールを確認することです。予想される違反のエラーがコンソールに表示された場合は、ポリシーが正しく構成されている可能性があります。 - このリストには、DevTools が開いているドキュメントに対して生成されたレポートのみが表示されます。一例として、サイト
site1.example
に、ポリシーに違反する iframesite2.example
が埋め込まれているためにレポートが生成された場合、このレポートは、個別のウィンドウで iframe を開き、そのウィンドウで DevTools を開いた場合にのみ、DevTools に表示されます。
レポートは生成されるが、送信または受信されない
DevTools にレポートが表示されるのに、エンドポイントがレポートを受信できない場合は、どうすればよいでしょうか。
- 必ず短い遅延を設定する。レポートが表示されない理由は レポートがまだ送信されていないことです
Reporting-Endpoints
ヘッダーの構成を確認します。問題がある場合、正しく生成されたレポートは送信されません。この場合、DevTools ではレポートのステータスはQueued
のままです(Pending
にジャンプし、配信が試行されるとすぐにQueued
に戻ることがあります)。原因としては次のようなものが考えられます。エンドポイントが使用されていますが、構成されていません。例:
Document-Policy: document-write=?0;report-to=endpoint-1; Reporting-Endpoints: default="https://reports.example/default"
default
エンドポイントがありません。非推奨レポートや介入レポートなど、一部のレポートタイプは、default
という名前のエンドポイントにのみ送信されます。詳しくは、Reporting-Endpoints ヘッダーを構成するをご覧ください。ポリシー ヘッダーの構文の問題(引用符の欠落など)を探します。詳細を表示
エンドポイントが受信リクエストを処理できることを確認します。
エンドポイントが CORS プリフライト リクエストをサポートしていることを確認します。有効になっていない場合はレポートを受け取れません。
エンドポイントの動作をテストします。そのためには、レポートを手動で生成する代わりに、ブラウザが送信する内容のようなリクエストをエンドポイントに送信することで、ブラウザをエミュレートできます。以下のコマンドを実行します。
curl --header "Content-Type: application/reports+json" \ --request POST \ --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \ YOUR_ENDPOINT
エンドポイントから成功コード(
200
または別の成功レスポンス コード2xx
)が返されます。返されない場合は、構成に問題があります。
関連する報告メカニズム
レポート専用
-Report-Only
ポリシー ヘッダーと Reporting-Endpoints
は連携します。
Reporting-Endpoints
で構成され、Content-Security-Policy
、Cross-Origin-Embedder-Policy
、Cross-Origin-Opener-Policy
の report-to
フィールドで指定されたエンドポイントは、これらのポリシーに違反した場合にレポートを受け取ります。
Reporting-Endpoints
で構成されたエンドポイントは、Content-Security-Policy-Report-Only
、Cross-Origin-Embedder-Policy-Report-Only
、Cross-Origin-Opener-Policy-Report-Only
の report-to
フィールドで指定することもできます。また、これらのポリシーに違反した場合にも報告が送信されます。
どちらの場合もレポートが送信されますが、-Report-Only
ヘッダーはポリシーを適用しません。破損したり、実際にブロックされたりすることはありませんが、破損したりブロックされたものが報告されます。
ReportingObserver
ReportingObserver
JavaScript API を使用すると、クライアント側の警告を確認できます。
ReportingObserver
ヘッダーと Reporting-Endpoints
ヘッダーは、生成されるレポートの内容は同じですが、ユースケースが若干異なります。
次の場合は ReportingObserver
を使用します。
- 非推奨化やブラウザ介入のみをモニタリングする場合。
ReportingObserver
は、非推奨やブラウザの介入などのクライアントサイドの警告を表示しますが、Reporting-Endpoints
とは異なり、CSP 違反や COOP/COEP 違反など、他の種類のレポートはキャプチャされません。 - こうした違反にはリアルタイムで対応する必要があります。
ReportingObserver
を使用すると、違反イベントにコールバックをアタッチできます。 - カスタム コールバックを使用して、デバッグに役立つ追加情報をレポートに添付する場合。
もう 1 つの違いは、ReportingObserver
はクライアント側でのみ構成されることです。サーバー側のヘッダーを制御できず、Reporting-Endpoints
を設定できない場合でも、この修飾子を使用できます。
関連情報
- Reporting API v0 から v1 への移行ガイド
- ReportingObserver
- 仕様: 以前の Reporting API(v0)
- 仕様: 新しい Reporting API(v1)
ヒーロー画像(作成者: Nine Koepfer / @enka80、Unsplash より編集)。この記事に対するレビューと提案に協力してくれた Ian Clelland、Eiji Kitamura、Milica Mihajlija に感謝します。