ホワイトリスト（ブロック免除）

概要 — 何をする画面か

ホワイトリスト 画面は、InfraGuard の自動ブロックパイプラインから除外する IP と範囲を管理します。ここに登録したものは、検知コレクターがブロックする直前に参照する「免除リスト」になります。これにより、信頼できる送信元（CDN、提携先 API、オフィス回線）が誤検知でブロックされることを防ぎます。

中心となる概念は有効期限です。

• expires_at が NULL → 恒久免除（失効しません）。CDN やオフィス回線のように、常に信頼する送信元向けです。
• expires_at が日時 → 一時免除（その時刻を過ぎると自動的に失効します）。短期間の調査や、自動の無実判定向けです。

免除は 3 つの登録元から入ります。

infr_whitelist テーブルはアプリの DB ではなく、legacy_glory 接続（blacklist_info や suricata_* テーブルと同じ DB）に置かれます。そのため Node コレクターの srct_tx が、ブロックの直前にこのテーブルを直接読み、無実の IP を直接書き込むことができます。

いつ使うか

• 誤検知を防ぐ: スキャン／レートのヒューリスティックに引っかかりかねない通常のトラフィック（監視ボット、提携先のクローラー、決済のコールバック）を、あらかじめ登録しておきます。
• 調査中の一時的な例外: 範囲に有効期限を設定して、数日間だけ免除します。
• CDN／オフィスを常に信頼する: Cloudflare／Google／AWS／Akamai のフロントエンド IP や、固定のオフィス IP を恒久的に免除します。
• 自動判定を確認する: srct_tx が作成した auto の項目を確認し、延長または削除します。
• ブロックリストで誤ってブロックされた IP を解除し、再びブロックされないようにします（免除を登録します）。

画面構成

上部の KPI（5 個）

WhitelistService::summary() が 30 秒キャッシュで計算します。有効 = is_active = 1 かつ（expires_at IS NULL または expires_at > now）。

免除リスト

フィルター可能なテーブルです（1 ページあたり 25 行）。並び順は恒久が先（expires_at IS NULL DESC）→ 有効期限の昇順 → id の降順です。

フィルター: 状態（有効・失効・すべて）、登録元（手動・自動・既定・すべて）、検索（IP・CIDR・名称）。リストは 30 秒ごとに更新を取得します。

手動追加モーダル

[Add manually]（手動で追加）ボタンでモーダルが開きます。入力項目は、IP または CIDR、名称（任意）、有効期限の日時（任意。空欄なら恒久）です。

使い方

1. 手動で免除を追加する

1. [Add manually]（手動で追加）をクリックします。
2. IP または CIDR を入力します。単一 IP は /32 に、範囲はそのネットワークアドレスに正規化されます（下の正規化ルールを参照）。
3. 必要に応じて名称と有効期限の日時を入力します。恒久免除にする場合は、有効期限を空欄のままにします。
4. [Add]（追加）をクリックします。同じ cidr がすでに存在する場合は再有効化され（is_active=1）、有効期限と名称が更新されます。

2. 正規化（normalizeCidr）のルール

WhitelistService::normalizeCidr() が入力を正規形に書き換えます（ロケール非依存で、srct_tx の照合規約と同一です）。

203.0.113.10        → 203.0.113.10/32     (単一 IP は /32 になります)
203.0.113.0/24      → 203.0.113.0/24      (変更なし)
203.0.113.55/24     → 203.0.113.0/24      (ホストビットをマスク → ネットワークアドレス)
10.0.0.5/8          → 10.0.0.0/8
999.1.1.1           → (不正 → null、422 invalid_ip)

• IPv4 のみです。プレフィックス長は 0〜32 です。
• 保存前に、コントローラーが正規表現 ^\d{1,3}\.\d{1,3}\.\d{1,3}(\.\d{1,3})?(/\d{1,2})?$ で事前検証し、サービスが filter_var(... FILTER_FLAG_IPV4) ＋ ip2long で最終確定します。

/24 の範囲を追加するとき、ホストビットは残したままで構いません — 203.0.113.55/24 は自動的に 203.0.113.0/24（そのネットワークアドレス）として保存されます。

3. 有効期限の入力

• 空欄 → 恒久（expires_at = NULL）。
• YYYY-MM-DD または YYYY-MM-DD HH:MM → Carbon::parse で解釈されます。
• 解釈に失敗した場合も恒久になります（parseExpiry → null）。

4. 削除

リスト行の削除操作は、確認のうえ remove を呼び出します。行は物理削除されます（論理削除ではありません）。seed の CDN 項目も削除できますが、次回のシーダー実行で再作成される場合があります。

5. srct_tx による自動の無実判定（auto 登録元） — どのように登録されるか

srct_tx コレクターは、スキャン／レート異常の IP をブロックする直前に、非常に厳格な手順で無実を検証し、判定が確実な場合にのみここに auto の項目を残します。

1. ホワイトリストによる除外 — infr_whitelist（およびコード内の CDN リスト）にすでに存在すれば、その場で免除してスキップします。
2. E 単独の候補のみ評判を照会 — 誤検知が多い「短時間スキャン単独」のシグナル（ヒューリスティック E）だけを持ち、強いシグナル（A／A2／B／C／D）を一つも持たない IP のみを AbuseIPDB に照会します（キーのラウンドロビン・6 時間キャッシュ・スイープごとの上限）。
3. 完全に無実という判定 — abuse_score=0 かつ reports=0 かつ Tor でない場合（またはホワイトリスト登録済みでスコア 0 の場合）、30 日間の免除（ip/32）を infr_whitelist(source=auto) に自動登録し、ブロックをスキップします。

自動の無実判定は srct_tx 専用です。kts_tx（Kitsune ML）はホワイトリストを読み取ってフィルタリングするだけで、評判の照会も自動登録も行いません。

6. cidrList() — コード生成での再利用

WhitelistService::cidrList() は、重複を除いた有効で未失効の CIDR を返します（30 秒キャッシュ）。このリストは、ルール・しきい値の画面が srct_tx／kts_tx のスクリプトを生成する際に、CDN_WHITELIST_CIDRS 定数の元データとして注入されます。つまり、UI で管理した免除が実際のコレクターのコードに流れ込みます。

データソース

テーブル infr_whitelist（接続: legacy_glory、マイグレーション 000734）

インデックス: (is_active, expires_at)、source。

infr_whitelist は legacy_glory（GLORY）の DB 上に作成されます。legacy_glory が mysql／mariadb として設定されていない場合、マイグレーションとシーダーは何もしないようガードされています — 画面は表示されますが KPI は 0 のままです。実運用では GLORY 接続を必ず設定してください。

シーダー InfrWhitelistSeeder（source=seed、恒久）

以前はハードコードされていた CDN／OFFICE の範囲を移行します（firstOrCreate により冪等です）。Cloudflare、Google、Meta、AWS、Akamai のフロントエンド範囲と、OFFICE の固定 IP を含みます。

php artisan db:seed --class=InfrWhitelistSeeder

モデル・サービス

• モデル: App\Models\Infr\InfrWhitelist（protected $connection = 'legacy_glory'）。
• サービス: App\Services\Security\WhitelistService — summary()（KPI、30 秒キャッシュ）、page()（フィルター／ページング）、add()／remove()（書き込み）、cidrList()（コード生成の元データ）、normalizeCidr()（静的な SOT）。
• コントローラー: App\Http\Controllers\Security\WhitelistController — index ・ live ・ add ・ remove。

アクセス権限

レベル体系は demo=1 ・ staff=5 ・ admin=10 です。したがって staff と admin はどちらも読み取りと書き込みができます。書き込みに失敗すると 403 forbidden が返ります（トーストは「許可されていません(レベル 2 以上)」）。

すべての書き込みは InfrAuditLog に記録されます。

• 追加 → sec.whitelist_add（target=ip、meta に id ・ reactivated）。
• 削除 → sec.whitelist_remove（target=ip、meta に id）。

レベルとロールのポリシー全体はアクセスレベルを、書き込みの確認方法は監査ログを参照してください。

トラブルシューティング・FAQ

KPI がすべて 0 でリストが空です

legacy_glory 接続が設定されていないか、infr_whitelist テーブルがまだ存在しません。GLORY の DB 設定を確認し、マイグレーションとシーダーを実行してください。DB エラー時、サービスは安全に空の値を返します。

「有効な IP ／ CIDR ではありません」（422）

入力が IPv4 でないか、プレフィックス長が 0〜32 の範囲外です。IPv6 には対応していません。例: 203.0.113.10、203.0.113.0/24。

/24 を入力したのに保存された範囲が違います

それが正しい動作です。ホストビットはネットワークアドレスにマスクされます（203.0.113.55/24 → 203.0.113.0/24）。

同じ IP を再度追加すると重複しますか

いいえ。cidr は一意なので、既存の項目が再有効化され、有効期限と名称が更新されます（レスポンスは reactivated: true）。既存の項目が seed だった場合、登録元は seed のままです。

auto の項目はなぜ現れるのですか／削除できますか

srct_tx が明らかに無実と判断した IP を、30 日間の免除として自動登録したものです。削除できますが、その IP が再び誤って検知された場合は再登録されることがあります。

失効した項目は自動的に消えますか

行は残りますが、有効期限を過ぎると「有効」の集計から外れます。状態フィルターを失効／すべてに切り替えると表示されます。完全になくすには削除してください。

IP を免除したのにまだブロックされます

次を確認してください。(1) 正規化された範囲が実際にそのトラフィックの IP を含んでいるか（例: /32 と /24 の違い）、(2) cidrList() のキャッシュ（30 秒）と、コレクターのスクリプトが再生成されたかどうか、(3) blacklist_info にすでにブロックのレコードがないか。既存のブロックはブロックリストから解除する必要があります。

関連項目

• ブロックリスト・評判 — ブロックリストの管理（免除の反対）
• 自動ブロック — スケジューラによる自動ブロック（ホワイトリスト／無実判定による拒否）
• 脅威 — IDS 脅威のトリアージ、IP のドリルダウン
• ルール・しきい値 — srct_tx／kts_tx の定数 ＋ cidrList の注入
• IP 評判 — アプリ内の AbuseIPDB 照会
• 監査ログ — 書き込み操作の監査