> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook 検証者チューニングガイド

> webhook 検証者しきい値の非規範的チューニングレシピ — 開始値、ベースライン化方法論、攻撃シナリオのウォークスルー。

<Note>
  この文書は非規範的です。[Webhook Security](/docs/building/by-layer/L1/security#webhook-security) で **構造的形状** が仕様化されている webhook 検証者しきい値の **開始値** とチューニング方法論を提供します。規範的仕様はカテゴリー（短ウィンドウ比、中ウィンドウ比、長ウィンドウ比、比例上限）としきい値がオペレーター構成可能であるべきという要件のみを仕様化します。このガイドはどこから始めどうチューニングするかを伝えます。
</Note>

<Warning>
  **最初の 30 日のオラクルリスク。** 下の開始値は公開されており、したがって攻撃者に既知です。出荷されたデフォルトで動く検証者は、オペレーターがしきい値を自身のトラフィックにチューニングするまでオラクルに対して動いています。**オペレーターは初回デプロイから 30 日以内に各しきい値をチューニングしなければなりません（MUST）**。公開された開始値で 30 日を超えて動く検証者は、既知の攻撃者チューニングターゲットに対して動いています。実装は初回デプロイで各開始しきい値をランダム化すべきで（SHOULD）、開始値の \[0.5×, 2×] にわたる log-uniform 分布から引きます（同等に: フリート全体で最も狭いデフォルトと最も広いデフォルトの間に 4× のスプレッドを持つ比率一様ジッター）。より狭い分布（例: ±30%、わずか 1.86× のスプレッドを与える）は、規律ある攻撃者が公開値の 0.7× にチューニングしフリートのすべてのジッターされたデプロイの下に留まることを許します。\[0.5×, 2×] にわたる log-uniform は攻撃者に 4× の範囲をカバーすることを強い、それは攻撃ボリュームで意味あるコストを課し始めます。**実装は、任意のしきい値が検証者の初回受理から 30 日を超えて出荷開始値のままであるとき `threshold_tuning_overdue` イベントをログまたはアラームすべきです（SHOULD）** — これは 30 日チューニングルールにテスト可能で監査可能なフックを与えます（それなしでは、ルールはオペレーターの勤勉さのみに依存し、勤勉さが失われると黙って失敗します）。
</Warning>

**なぜこのガイドが仕様と別か。** 具体的なしきい値を規範的デフォルトとして公開することは攻撃者にオラクルを渡します — 規律ある攻撃者は仕様を読み、公開値のちょうど下に留まるよう攻撃をチューニングします。規範的仕様は意図的に *ルールがどんな形状を持つか* を述べます。このガイドは *どんな数字から始めるか* を述べます。オペレーターはこれらを開始値として扱い、自身のトラフィックを観測し、調整しなければなりません（MUST）。

## チューニングしているルール

検証者は新 keyid 受理圧力を追跡しなければならず（MUST）、レートが 4 つのしきい値の **いずれか**（最初にトリガーするもの）を超えるときアラートすべきです（SHOULD）。規範的仕様はこれら 4 つのしきい値をカテゴリーで名指します。このガイドは各カテゴリーの開始値を与えます。

## 開始値

| #     | Category | 開始式                                                        | 捕捉するもの                                                                                    |
| ----- | -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **a** | 短ウィンドウ比  | 新 keyid 受理レートの `24 時間移動平均の 3×`                             | 安定したベースラインに対する突然のスパイク — 古典的な「異常なトラフィックボリューム」シグナル。                                         |
| **b** | 中ウィンドウ比  | `30 日 P95 の 2×`                                            | 複数週のランプアップ攻撃。30 日 P95 はベースライントラフィックのテールに支配されるため、2〜3 週のランプは参照を攻撃にドリフトできない。                 |
| **c** | 長ウィンドウ比  | `90 日 P99 の 1.5×`                                          | 複数月のランプアップ攻撃。30 日 P95 をドリフトさせる 60〜90 日の段階的侵害は、P99 テールがはるかにゆっくり動くため依然として 90 日 P99 をトリップする。 |
| **d** | 比例上限     | `max(20 個の異なる新 keyid、10% × 30 日ユニーク keyid 数) per 5 分ウィンドウ` | 移動平均と P95/P99 値がゼロ近い（小規模オペレーター）疎トラフィック検証者、かつ任意のサイズのオペレーターの自動スケーリング。                       |

**これらは開始値であり、規範的デフォルトではありません。** 新規デプロイは初日にそれらを使えます。トラフィックベースラインが安定するにつれ、観測された偽陽性と偽陰性のレートに基づいて締めるか緩めてください。

## ベースライン化方法論

しきい値をチューニングする前に、検証者のトラフィックのベースライン形状を確立してください:

1. **アラームなしで 30 日の新 keyid 受理を収集する。** レートをインストルメントするがオペレーターをページしない。
2. **デプロイの P50、P95、P99** を 5 分ウィンドウあたりの新 keyid 受理で計算する。
3. **30 日スライディングウィンドウあたりのユニーク keyid 数を追跡する。** これは条項 (d) の分母です。
4. **中央値とピークの正当なオンボーディングバッチを文書化する。** 日常的に 1 日 50 の新署名者をオンボードする（週 2 回 10 分ウィンドウにバッチ化）場合、条項 (d) の 20/5 分の固定フロアは厳しすぎます。最大の正当なバッチに合わせて上げてください。

ベースラインが分かれば、各条項 (a)/(b)/(c)/(d) はデプロイ内の具体的なしきい値になります。仕様の 4 つの OR 形状は、任意の 1 つの条項のトリップでアラートに十分であることを意味します — したがってしきい値は形状で一致する必要はなく、それぞれ異なる攻撃者パターンを閉じる必要があります。

## 攻撃シナリオのウォークスルー

### シナリオ 1: 突然の大量侵害

攻撃者が週末に 100 の署名者鍵を侵害し、月曜朝から 100 すべてから同時に webhook を送り始める。

* **トリップするもの**: 条項 (a)。新 keyid 受理の 24 時間移動平均は約 0（安定した検証者上）。1 つの 5 分ウィンドウでの 100 の新 keyid はその `3×` より桁違いに上。
* **オペレーターが必要とするアラーム詳細**: どの条項 (a) か。トリアージチームが単一鍵スパイクではなく大量侵害パターンを探すべきと分かるように。

### シナリオ 2: 忍耐強い複数週ランプ

攻撃者が週 1 に 5 鍵、週 2 に 10、週 3 に 20、週 4 に 40 を侵害 — 週ごとに倍増し、今日のレートが昨日の 2× を超えないため任意の「昨日の 3×」ルールの下に留まる。

* **トリップするもの**: 条項 (b)。30 日 P95 は最初の 3 週のベースライントラフィックに支配されるため、その `2×` はほぼ通常のピーク。週 4 までに 40 keyid/日は週次ベースラインの 8× で、P95 アンカーを十分に超える。
* **条項 (a) だけならミス**: はい。2× 日次ランプは 3× 短ウィンドウ MA の下に永続的に留まる。

### シナリオ 3: 複数四半期の段階的侵害

攻撃者が 90 日間 1 日 1 鍵を侵害 — 今日のレートが昨日とほぼ等しいため任意の日次または週次比をトリガーしない。

* **トリップするもの**: 条項 (c)。90 日 P99 は攻撃よりはるかに古いベースライントラフィックにアンカーされる。ランプの最後の 2 週（76〜90 日）でさえ P99 の `1.5× ベースライン` を超えて登録される。
* **条項 (a) と (b) だけならミス**: はい。単調な遅いランプは 24 時間 MA と 30 日 P95 の両方をそれとともにドリフトさせる。

### シナリオ 4: 疎トラフィック検証者、バースト攻撃

合計 20 のアクティブ署名者とゼロ近い新 keyid トラフィックを持つ検証者が、突然 5 分ウィンドウで 15 の新 keyid を見る。

* **トリップするもの**: 何も。比率ルール (a)/(b)/(c) はゼロ近いベースライン（`3× 0.01 = 0.03`）に対して比較し、正当な単一セラーオンボーディングを含む任意の正の受理でトリップする — したがって疎トラフィック検証者でアラームするにはノイズが多すぎる。条項 (d) の `max(20, 10%×20) = max(20, 2) = 20` 固定フロアは、発火前に 5 分ウィンドウあたり 20 を超える新 keyid を要求する。15 はフロアの下。
* **オペレーターが見るもの**: 何も。疎トラフィック検証者での 15 の新 keyid は通常範囲内。疎トラフィック検証者を運用するオペレーターは、日常オンボーディングが定期的にそれを超えるなら固定フロアを上げるべきで（SHOULD）、または日常オンボーディングが下に留まるならフロアを 20 のままにする（攻撃者の上限が ≤20/ウィンドウになり、合理的なウィンドウでの集約圧力を鋭く制限する）。

### シナリオ 5: 大規模検証者の上限スケーリング

10,000 のアクティブ署名者を持つ検証者が 5 分ウィンドウで 500 の新 keyid を見る。

* **トリップするもの**: 条項 (d) からは何も。10% × 10,000 = 1,000。500 は比例フロアを超えない。検証者のベースラインに応じて、500/5 分が 24 時間移動平均または 30 日 P95 より実質的に上なら条項 (a) または (b) がトリップするかもしれない。
* **スケールで変わるもの**: 小規模検証者（100 署名者）では、500 の新 keyid は署名者ベース全体の 5× — 明らかに攻撃。条項 (d) の `max(20, 10%×100) = 20` フロアは 500 が 25× 超で即座に発火することを意味する。比例形状は自動スケールする。

### シナリオ 6: オンボーディングバースト偽陽性

計画された火曜バッチで 200 の新セラーをオンボードする検証者が、バッチ中に条項 (a) または (d) をトリップする。

* **オペレーターがすること**: 条項 (d) の固定フロアを一時的に上げる（変更管理で文書化）、または既知のオンボーディングウィンドウでアラートをサイレンスする。バッチ後、フロアはベースラインに戻る。監査でき戻せるよう引き上げを文書化する。引き上げフロアウィンドウはできるだけ短く内部スコープに保つべき（SHOULD） — 公に発表されたオンボーディングウィンドウは攻撃者の計画シグナル（シナリオ 10 を参照）。
* **なぜ自動失効がここで間違いか**: 仕様の `Alarms SHOULD route to incident response, not automatic revocation` ルールはまさにこのケースのために存在する。機械導出可能な「攻撃対オンボーディング」は信頼できない。オペレーターコンテキストが区別シグナル。

### シナリオ 7: 正当な鍵ローテーションストーム

ピアセラーのルート CA が失効し、その 500 の署名エージェントすべてが 10 分ウィンドウ内で新しい `keyid` にローテートする。検証者は 1 つの 5 分ウィンドウで 500 の新 keyid を、次で 0 を見る。

* **トリップするもの**: 条項 (a) とおそらく (d)。形状はレートのみのレベルでシナリオ 1（突然の大量侵害）と区別できない。
* **オペレーターがすること**: アラームをトリアージし、ピアセラーの通知からイベント形状を認識し（CA 侵害インシデントは通常ピアに事前発表される）、インシデントレコードで正当とマークし、自動失効しない。ピアが事前発表しなかった場合、ピア連絡が確認するまでシナリオ 1 とまったく同様に扱う。**ピアの発表だけに基づいてアラームを先制的にサイレンスしない** — 侵害されたピア事前発表チャネル自体が攻撃者の戦術。アラームが発火しトリアージされることが多層防御レイヤー。

### シナリオ 8: 薄い履歴ウィンドウ攻撃（デプロイ後 1〜90 日）

昨日デプロイされた検証者は 30 日 P95 データも 90 日 P99 データも持たない。条項 (b) と (c) はパーセンタイルウィンドウが成熟するまで条項 (d) フロアに優雅に劣化する。検証者が新しいと知る攻撃者は、最初の 90 日間条項 (d) の `max(20, 10%×count)` フロアの下に留まるランプを段階化し、その間条項 (a) のみが意味あるカバレッジを提供する。

* **トリップするもの**: 条項 (a) のみ — そして十分に大きい短ウィンドウスパイクでのみ。条項 (b)、(c)、(d) はすべてフロア支配ケースに劣化する。
* **オペレーターがすること**: 新しい検証者では、P95/P99 が成熟する間の最初の 90 日間、条項 (d) の絶対フロアを公開開始値の下に締めるべき（SHOULD）（例: 20 の代わりに 10）。これを永続的チューニングではなく文書化された初回デプロイ姿勢として扱う — パーセンタイルウィンドウが実データを持ったら成熟検証者フロアに戻す。
* **なぜウォームアップ中に条項 (b)/(c)/(d) が独立でないか**: 条項 (c) は明示的に `1.5× max(observed_P99, clause_d_floor)` に劣化するため、1〜90 日の間、条項 (c) と (d) は冗長。これはルール形状の既知の制限。締めたフロア姿勢が緩和策。

### シナリオ 9: 断続的低ボリューム攻撃（ルール形状の制限）

攻撃者が 500 鍵を侵害し、フリート全体で 30 分ごとに 1 つの新 keyid を発行 — 約 48/日。`max(20, 10% × 200 署名者数) = 20`/5 分の条項 (d) フロアに対して、各 5 分ウィンドウは 0 か多くて 1〜2 の新 keyid を見る。30 日で攻撃は 1,440 の新 keyid を受理する — それが条項 (b) が比較する 30 日ユニーク keyid 数の一部になる。攻撃はベースラインに事前に焼き込まれている。

* **トリップするもの**: 何も。
* **オペレーターが見るもの**: 30 日にわたる上昇したユニーク keyid 数だが、単一ウィンドウアラームは発火しない。
* **なぜこれが既知の制限か**: 受理圧力ルールはボリュームスパイク攻撃を閉じ、長ウィンドウにわたって平滑化された低レート長期間攻撃を閉じない。**keyid ごとの上限（ステップ 9a）と集約キャッシュ上限はこのギャップを閉じない** — それらはキャッシュサイズを制限し、鍵集団の成長ではない。1,440 の新 keyid/月は 10M 集約上限の約 0.014%。レートウィンドウレベルでは、各条項 (a/b/c/d) はゼロでトリップし集約上限アラームは決して発火しない。脅威モデルに緩やかに滴る鍵集団の成長を持つオペレーターは **アプリケーションレベル検出を重ねなければならない（MUST）**（署名者評判スコアリング、「請求期間あたり配信されるシグナル」のようなビジネス上意味あるウィンドウにわたるセラーごとのトラフィック異常検出、宣言されたフリートサイズ期待に対して追跡される新 keyid 受理）。受理圧力ルールと上限だけに依存することは、攻撃クラスが仕様で認められているが実際の検出がない検証者を出荷することになる。

### シナリオ 10: オンボーディングウィンドウタイミング攻撃

攻撃者が検証者オペレーターの公開発表（製品ローンチ、会計年度境界、プラットフォームパートナーシップ）を監視する。オペレーターはシナリオ 6 に従い予定された火曜オンボーディングウィンドウのため条項 (d) のフロアを `200` に上げる。攻撃者は大量侵害をその火曜にタイミングし、一時的に上げられたフロアに乗る。

* **トリップするもの**: 上げられたフロアウィンドウ中は何も。
* **オペレーターがすること**: 上げられたフロアウィンドウ中、条項 (d) が意図的に緩くても、条項 (a)/(b)/(c) のアラームは **自動抑制ではなく必須の人間レビュー** にエスカレートすべき（SHOULD）。上げられたフロアウィンドウをできるだけ短く内部スコープに保つ — 攻撃者がスケジュールできる形で「新セラーオンボーディングが日付 X に起こる」と公に発表するのを避ける。公開発表が避けられない場合（規制開示、顧客向けローンチ）、ウィンドウ中に帯域外検出を増やすべき（SHOULD）（トラフィックパターン分析、セラークレームのクロス検証、リクエストボディサンプリング）。

### シナリオ 11: 成熟検証者でのベースラインリセット（フェイルオーバー、キャッシュ再構築、設定変更）

90 日の安定した P95/P99 データを持つ成熟検証者が、ベースライン計算キャッシュが空のスタンバイプールにフェイルオーバーする。条項 (b)/(c) は再構築の間、条項 (d) フロア支配ケースに劣化する — シナリオ 8（薄い履歴ウィンドウ）を反映するが、成熟しているはずの検証者で。フェイルオーバーイベントが起こることを知る攻撃者（公開ステータスページインシデント、予定メンテナンスウィンドウ、観測可能な応答時間変化）は、再構築ウィンドウ中に着地するよう攻撃をタイミングできる。

* **トリップするもの**: 条項 (a) のみ（シナリオ 8 と同じ）。条項 (b)/(c) はベースラインデータを持たない。
* **オペレーターがすること**: *一時的な* 薄い履歴姿勢として扱う。空のキャッシュから再構築するのではなく、フェイルオーバー全体でベースライン統計状態を永続化する（Redis / 共有 dedup サービス） — 仕様がクロスエンドポイントスコーピング下のリプレイキャッシュに既に要求するのと同じインフラ選択がこれも修正する。永続化が不可能なら、再構築ウィンドウ中に条項 (d) の絶対フロアを締め、シナリオ 10 に従い (a)/(b)/(c) アラームを人間レビューにエスカレートする。
* **なぜこれがシナリオ 8 と仕様上異なるか**: シナリオ 8 は 90 日で安定すると期待される初回デプロイ姿勢。シナリオ 11 は、オペレーターがフェイルオーバー全体でベースラインを永続化しなければ無期限に再発しうる成熟検証者の運用イベント姿勢。仕様は永続化選択を義務化できない（デプロイ内部）。チューニングガイドは、オペレーターが緩和責任を負う既知の攻撃タイミング機会としてそれを呼び出せる。

## 考慮すべきチューニング調整

| Observation                            | Adjustment                                                                                           |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| 正当なバースト中に条項 (a) から偽陽性が多すぎる             | 条項 (a) の比率を `3×` から `4×` または `5×` に上げる。補償のため条項 (b)/(c)/(d) のしきい値を下げない — それらは異なる攻撃者形状を捕捉する。           |
| 条項 (d) が日常オンボーディングで発火する                | 条項 (d) の固定フロア成分を最大の正当なバッチサイズに合わせて上げる。`10%×30d-unique-count` 比例部分は変えないままにする。                          |
| 条項 (c) が 60 日未満実行するレッドチーム演習中に決して発火しない  | 期待通り — 条項 (c) は複数月アンカー。レッドチーム演習は、条項 (c) が 90 日 P99 に正しく配線されていることを検証するため 60 日の遅いランプシナリオを含むべき（SHOULD）。 |
| アラームが同じイベントに条項 (a) と (d) の両方が発火したことを示す | アラームペイロードで最初にトリップした条項をレポートする（仕様に従い）。両方の条項が表面化することは情報的であり、バグではない。                                     |
| 検証者が意味ある P99 データを持つには小さすぎる             | 条項 (c) は `1.5× max(observed_P99, clause_d_floor)` に優雅に劣化する — 決して比例上限より低くならない。90 日追跡し、その後 P99 が意味を持つ。 |

## してはいけないこと

* **チューニングしたしきい値を外部に公開しない。** しきい値はデプロイ内部の運用パラメーター。このルールは 3 つのオーディエンスを区別する:
  * **公開開示**（ブログ投稿、マーケティングコピー、公開設定リポジトリ、オープンソースデフォルト、カンファレンストーク）: **禁止**。これはこのガイドが閉じるために存在する攻撃者オラクル。
  * 資格ある**セキュリティ監査人、規制当局、契約レッドチームへの NDA 下での証明済み開示**: **許可**。検出姿勢評価自体が多層防御慣行で、SOC 2 / ISO 27001 監査がそれを要求するかもしれない。NDA スコープは再配布を制限しエンゲージメント終了時の削除を義務付けるべき（SHOULD）。
  * **内部オペレーターランブック、インシデントレスポンスランブック、バージョン管理されたオペレーター設定**: **必須**。検出チームは効果的にトリアージするため値を必要とし、インシデント後フォレンジックはイベント時のしきい値を知ることを要求する。
* **4 つのしきい値すべてを同じ値にチューニングしない。** 各条項は異なる攻撃者パターンを捕捉する。それらを崩すと検出カバレッジを失う。
* **アラームで自動失効しない。** アラームはインシデントレスポンスのシグナルであり、修復アクションではない。受理圧力アラームでの署名者鍵の自動失効はサービス拒否ベクターを作る: 正当な新署名者オンボーディングを駆動する任意の当事者がアラームをトリップし大量失効を引き起こせる。
* **開始値をデプロイ設定にハードコードしない。** 各しきい値をチューナブルパラメーター（例: 環境変数、設定ファイル）にし、オペレーターがコード変更なしに調整できるようにする。ハードコードされた開始値は事実上のオペレーター可視デフォルトになり、攻撃者オラクルを再導入する。

## 関連

* [Webhook Security → Webhook replay dedup sizing](/docs/building/by-layer/L1/security#webhook-replay-dedup-sizing) — このガイドがチューニングするルールの規範的仕様。15 チェック検証者フローの直下の §Webhook replay dedup sizing 見出しまでスクロール。「New-keyid admission pressure」箇条書きが、チューニングガイドが開始値で埋める 4 つのカテゴリーを持つルール。
* [Webhook 検証者チェックリスト](/docs/building/by-layer/L1/security#webhook-callbacks) — 完全な 15 チェックフロー。ステップ 14b（ロギング規律）はステップ 14（ボディの整形式性）下のサブステップ。そのサニタイズルール（非印字分類、32 バイト UTF-8 コードポイント安全トランケーション、4 でのカウント上限）は、このガイドがアラームが運ぶと仮定する診断情報に適用される。