これらのリクエストはすでにLaravelアプリに到達しています。アクセスログにはURLとステータスコードだけが記録され、それ以外の情報——デコードされたペイロード、どのルートが標的にされたか、同じIPがこの1時間に他に40件試みたかどうか——は一切わかりません。

このパッケージはそうした疑問に答えます。Laravel 10〜13の任意のアプリに導入するだけで、すべてのHTTPリクエストを150以上の攻撃パターンに対してスキャンし、各マッチを信頼度でスコアリングしてデータベースに書き込みます。組み込みのダッシュボード、Slackアラート、ジオエンリッチメント、fail2ban/ブロックリストのエクスポートも備えています。リクエストがブロックされることは一切ありません。鍵ではなく防犯カメラと考えてください。誰がどのルートを探っているのか、どのくらいの頻度で、どのような手法を使っているのかを正確に示してくれます。

> 本番アプリから抽出し、実際のトラフィックで実戦テスト済み。335件のテスト、Laravel本体以外の実行時依存関係なし、検出にインターネット接続も不要です。
>
> アップグレードする場合? [UPGRADING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/UPGRADING.md) を参照してください。貢献する場合? [CONTRIBUTING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/CONTRIBUTING.md) を参照してください。

## 1分以内で始める```bash
composer require jayanta/laravel-threat-detection
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate

---

## 位置づけ: IDS vs WAF vs エッジ

このパッケージは**パッシブなアプリケーションレベルのIDS**です。監視・記録は行いますが、ブロックはしません。WAFやエッジサービスの*横に*置くことを想定しており、置き換えるものではありません。各レイヤーは、他では見えないものをそれぞれ捉えます:

| | **このパッケージ** (アプリIDS) | **WAF** (mod_security、Cloudflare WAF) | **エッジ / CDN** (Cloudflare) |
|---|:---:|:---:|:---:|
| 悪意のあるリクエストをブロック | ❌ ログのみ | ✅ | ✅ |
| 完全なアプリコンテキスト (正確なルート、デコード済みペイロード、認証済みユーザー) | ✅ | ⚠️ 部分的 | ❌ |
| 組み込みダッシュボード + DB内の脅威ログ | ✅ | ⚠️ 場合による | ⚠️ エッジのみ |
| アプリ固有の検出 (例: Aadhaar / PAN / IFSC PII) | ✅ カスタムパターン | ❌ | ❌ |
| オフライン動作 / 外部サービス不要 | ✅ | ⚠️ 依存する | ❌ |
| アプリに到達する前にトラフィックを停止 | ❌ | ✅ エッジ | ✅ |
| セットアップ | `composer require` 1回 | 中〜高 | 低〜中 |
| コスト | 無料、MIT | 場合による | 無料枠 + 有料 |

**要約:** エッジ/WAFはドアの鍵、これは*内部*の防犯カメラであり、どのルートに対して何が、誰によって、どのくらいの頻度で試行されているかをアプリコンテキストで正確に教えてくれます。fail2banのBAN、レート制限、ジオブロッキングといった実際の判断を、エッジレイヤーでは決して見えないデータで下すために使用します。

### 意図的にそうではないもの

- **WAFではない。** リクエストをブロック、フィルタリング、変更することは一切ありません。強制にはCloudflare、mod_security、または本物のWAFを使用してください。(引き渡すエッジレイヤーがない場合? [オペレーター側ヘルパー](#acting-on-the-data-operator-side-blocking)がパッケージの判断を公開するので、独自の5行のブロッキングミドルウェアを書けます — 強制コードはパッケージではなく、あなたのもののままです。)
- **安全なコーディングの代替ではない。** パラメータ化クエリ、入力検証、出力エスケープが実際の防御です。このパッケージはコードがすでに安全であることを前提とし、*可視性*を提供します。保護ではありません。
- **エッジサービスではない。** Cloudflareを前面に置けるなら置いてください — その後、エッジサービスでは見えないアプリケーションレベルの詳細のためにこれを追加します。

### では、実際に何に使うのか?

ブロックしない検出器に関する最も一般的な質問。労力の少ない順に4つの答え:

| やりたいこと | 使用 | 労力 |
|---|---|---|
| 何が自分にヒットしているか確認 | [ダッシュボード](#dashboard) または `threat-detection:stats` | なし、すでに実行中 |
| ファイアウォールで常習犯をBAN | [`threat-detection:export-fail2ban`](#artisan-commands) — cronにパイプ | 1行 |
| Webサーバーで拒否 | [`threat-detection:export-blocklist`](#artisan-commands) → nginx/apacheディレクティブ | 1行 |
| アプリ内でリクエストを拒否 | [オペレーター側ヘルパー](#acting-on-the-data-operator-side-blocking) — `isBlocklisted()`、`isDdosThresholdExceeded()` | 独自ミドルウェア約10行 |
| リアルタイムで反応 | [`ThreatDetected` イベント](#threatdetected-event) — Telegram、SIEM、PagerDuty | リスナー |

パッケージはインテリジェンスを提供し、拒否はあなたが提供します。この分割は意図的です — アプリ内に存在する強制コードは、読み取り、テスト、無効化が可能なコードであり、検出バグがサイトをダウンさせることは決してないことを意味します。

### 他のLaravelセキュリティパッケージとの比較

これらは異なる問題を解決し、うまく組み合わせられます — この表は優劣ではなく、適切なツールを選ぶためのものです。

| パッケージ | 機能 | ブロック? | 使用する場面 |
|---|---|:---:|---|
| **このパッケージ** | 150以上のパターンに対してすべてのリクエストをスキャンし、完全なアプリコンテキストでログ記録 | ❌ | アプリに対して何が試行されているかを*確認*したい場合 |
| `spatie/laravel-honeypot` | スパムボットを捕捉する隠しフォームフィールド | ✅ フォームのみ | スパムされる公開フォームがある場合 |
| `graham-campbell/security` | 入力からXSS的なマークアップを除去 | ✅ 変更する | 単純な入力サニタイズが必要な場合 |
| `spatie/laravel-csp` | Content-Security-Policyヘッダーを送信 | ✅ ブラウザ | ブラウザが読み込むものを制限したい場合 |
| `laravel/fortify` + レート制限 | 認証スロットリングとロックアウト | ✅ | ログインにブルートフォース保護が必要な場合 |
| Cloudflare / mod_security | エッジWAF、アプリの前にブロック | ✅ | トラフィックが到着する前に停止させたい場合 |

正直なまとめ: ハニーポットはフォームスパムを捕捉し、WAFはエッジで既知の悪意トラフィックをブロックし、CSPはブラウザを制約します。**それらのどれも、攻撃者が特定のルートに対して何を試みたか、ペイロードがデコードされ認証済みユーザーが添付された状態で教えてくれるものはありません。** そのギャップを埋めるのがこれです — そして、パッケージが意図的にブロックしない理由でもあります: 上記のすべてと並行して、互いに競合することなく実行できます。

---

## 要件

- PHP 8.2+ (Laravel 13ではPHP 8.3+が必要)
- Laravel 10.x、11.x、12.x、または13.x
- Laravelがサポートする任意のデータベース (MySQL、PostgreSQL、SQLite、SQL Server)
- 任意のキャッシュドライバー — **Redisやキューワーカーは不要**。Redis/Memcachedは、オプションのDDoSチェックを有効にするために*推奨*されるだけです (非アトミックドライバーでは自動無効化)。キュー書き込みはオプトインで、デフォルトではオフです。

---

## 仕組み

1. ミドルウェアがすべての受信HTTPリクエストをスキャン
2. リクエストはSQLインジェクション、XSS、RCE、ファイルトラバーサル、SSRF、LDAP、XPath、SSTIなどをカバーする158の正規表現パターンに対してチェック
3. 脅威パターンが一致した場合、IP、URL、脅威タイプ、重大度レベル、信頼スコアを含むレコードが`threat_logs`データベーステーブルに書き込まれる
4. オプションで、高重大度の脅威に対してSlackアラートが送信される
5. リクエストは通常どおり続行 — **何もブロックされない**

検出にインターネット接続は不要です。

---

## クイックスタート

### 1. パッケージをインストール```bash
composer require jayanta/laravel-threat-detection

これにより、`threat_logs`（検出された脅威を保存）と`threat_exclusion_rules`（誤検知ルールを保存）の2つのテーブルが作成されます。

**テーブルが作成されたことを確認する:**```bash
php artisan migrate:status

> **Laravel のバージョンを確認する方法:** ターミナルで `php artisan --version` を実行します。

**Laravel 10 を使用している場合** - `app/Http/Kernel.php` を開きます:```php
protected $middlewareGroups = [
    'web' => [
        // ... existing middleware
        \JayAnta\ThreatDetection\Http\Middleware\ThreatDetectionMiddleware::class,
    ],
];

このパッケージは適切なデフォルト設定で動作します。設定を公開すると、検出パターン、感度モード、Slack通知などをカスタマイズできます。この手順をスキップしても、すべて正常に動作します。

**これで完了です。** アプリは脅威を検出できるようになりました。

---

## 動作確認

インストール後、テスト用の脅威をトリガーして、ログに記録されたことを確認します。

### ステップ1: アプリを起動する```bash
php artisan serve

**XSS（クロスサイトスクリプティング）：**```
http://localhost:8000/?q=<script>alert(1)</script>

**RCE（リモートコード実行）：**```
http://localhost:8000/?cmd=system('ls -la')

**Windows コマンドインジェクション:**```
http://localhost:8000/?cmd=powershell -c whoami

> アプリ内に実際に存在するルート（`/` など）を使用してください。URL が 404 を返す場合、ミドルウェアが実行されていない可能性があります。

### ステップ 3: 脅威がログに記録されたことを確認する

**オプション A - Artisan コマンド（最速）:**```bash
php artisan threat-detection:stats

```php
DB::table('threat_logs')->latest()->take(5)->get(['ip_address', 'type', 'threat_level', 'confidence_score']);

### テスト時の注意点

| 動作 | 説明 |
|----------|-------------|
| 同じ脅威は5分間に1回のみログ記録 | 重複排除: 同じIP + 同じ脅威タイプは5分間キャッシュされます。各テストでは**異なる攻撃タイプ**を使用するか、テスト間で待機してください。 |
| `curl` リクエストは追加の検出をトリガー | `curl` を使用すると、「cURL Command」ユーザーエージェント検出（低重要度）もログに記録されます。これは想定内です。パッケージは自動化ツールを検出します。 |
| パッケージはリクエストをブロックしない | アプリは正常に機能し続けます。検出は受動的です。 |
| Slackの設定は不要 | 通知はデフォルトでオフです。 |
| インターネット接続は不要 | コア検出は100%ローカルです。オプションの `threat-detection:enrich` コマンドのみが、地理位置情報データのために外部APIを呼び出します。 |

### トラブルシューティング

**ここから始めてください — 1つのコマンドでほとんどの問題が解決します:**```bash
php artisan threat-detection:doctor

対象範囲: この環境で有効化されている検出機能。ライターが必要とするすべてのカラム（1つ欠けると**すべての**脅威が破棄される）。ダッシュボード/APIカラム。除外ルールのテーブル。ミドルウェアが実際にルートまたはグループに配線されているかどうか。このバージョンより前に公開された設定。組み込みパターンを覆い隠すカスタムパターン。DDoSカウントを実行できないキャッシュドライバ。認証なしで開かれたままのダッシュボードまたはAPI。

**「テストしたのに `threat-detection:stats` がゼロ件の脅威を表示する」/「脅威がデータベースに保存されない」**

ドクターが合格した場合、インストールは正常で、問題はテストリクエスト自体にあります。ドクターが確認できない3つの項目:

| チェック | 確認方法 |
|-------|---------------|
| IPがホワイトリストに登録されていない | `.env` に `THREAT_DETECTION_WHITELISTED_IPS` を追加した場合は、テスト中に削除する |
| 既存のルートを使用した | テストURLは実際のルート（例: `/`）と一致する必要がある。404が返る場合、ミドルウェアは実行されていない |
| 重複排除キャッシュ | 同じIP + 同じ攻撃タイプは5分間キャッシュされる - 別の攻撃タイプで試す |

> `php artisan migrate` を単独で実行するだけでは不十分です。マイグレーションファイルはパッケージ内にあり、最初にアプリの `database/migrations/` に公開する必要があります。この問題が原因の場合、ドクターが正確なコマンドを表示します。

**「APIが401 Unauthorizedを返す」**

以下の [API認証](#api-authentication) を参照してください。

**「ダッシュボードが404を表示する」**

ダッシュボードはデフォルトで無効です。`.env` に `THREAT_DETECTION_DASHBOARD=true` を追加し、ルートキャッシュをクリアしてください:```bash
php artisan route:clear

### 検出モード

| モード | 信頼度しきい値 | 動作 |
|------|---------------------|----------|
| `strict` | 0（すべてをログ記録） | すべてのパターンが有効、最低しきい値。すべてを検出するが、正当なトラフィックをフラグ付けする可能性がある。 |
| `balanced` | 10 | デフォルト。信頼度スコアリングが有効、標準しきい値。ほとんどのアプリに適している。 |
| `relaxed` | 40 | 高重大度パターンのみがトリガーされる。誤検知が頻発するコンテンツ重視のサイトに最適。 |

### 有効な環境

デフォルトでは、検出は `production`、`staging`、`local` で実行されます。変更するには、設定を公開して編集します：```php
'enabled_environments' => ['production', 'staging', 'local'],

### 設定リファレンス

設定ファイルを公開して、利用可能なすべてのオプションを確認します:```bash
php artisan vendor:publish --tag=threat-detection-config

Leave empty (default) to scan all routes (subject to `skip_paths`). When both are configured, `only_paths` is checked first, then `skip_paths` applies within the matched set.

### Queue Support

By default, threat logging happens synchronously in the request cycle. For high-traffic apps, you can offload DB writes and Slack notifications to a queue:```env
THREAT_DETECTION_QUEUE=true
THREAT_DETECTION_QUEUE_CONNECTION=redis
THREAT_DETECTION_QUEUE_NAME=threat-logs

Laravelのスケジューラーが実行されている必要があります（`php artisan schedule:run`）。`threat-detection:purge` により毎日02:00に実行されます。

### ThreatDetected イベント

確認された脅威はそれぞれ `ThreatDetected` イベントをディスパッチします。これをリッスンできます：```php
// app/Providers/EventServiceProvider.php
use JayAnta\ThreatDetection\Events\ThreatDetected;

protected $listen = [
    ThreatDetected::class => [
        YourCustomListener::class,
    ],
];

イベントは `$ipAddress`、`$requestCount`、`$threshold`、`$windowSeconds` を保持します。これはIPごとに重複排除ウィンドウごとに1回に制限されるため（ログ行と同じスロットル）、フラッド攻撃でリスナーが埋もれることはありません。アラート通知や外部の禁止ストアへの供給に使用してください。閾値を超えたクライアントを*拒否*するには、代わりに独自のミドルウェアから `ThreatDetection::isDdosThresholdExceeded($ip)` を使用してください — [データへの対応](#acting-on-the-data-operator-side-blocking) を参照してください。

---

## Slack通知

Slackアラートはデフォルトで無効です。有効にするには：```env
THREAT_DETECTION_NOTIFICATIONS=true
THREAT_DETECTION_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
THREAT_DETECTION_SLACK_CHANNEL=#threat-alerts

---

## ダッシュボード

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12500/fc7950bd0cc6323bcc2d62b03e31c99edc7450b0ef76f9cbfa5133b527b25269.png" alt="脅威検出ダッシュボード — 統計、7日間のタイムライン、ライブ脅威ログ、上位の攻撃元IP、国別の脅威" width="100%">
</p>

このパッケージには、ダークモード対応のダッシュボード（Alpine.js + Tailwind CDN — ビルド手順不要）が組み込まれています。```
+-------------------------------------------------------------------------+
|  Threat Detection Dashboard                                              |
+-------------------------------------------------------------------------+
|  Total: 847  |  High: 23  |  Med: 156  |  Low: 668  |  IPs: 94         |
+-------------------------------------------------------------------------+
|  [Timeline Chart - 7 Day Stacked Bar]                                   |
+-------------------------------------------------------------------------+
|  Search: [___________]  Level: [All]                                    |
|  Time         IP             Type            Level  Confidence  Actions  |
|  Mar 2 14:02  185.220.101.4  SQL Injection   HIGH   80%         [FP]    |
|  Mar 2 13:58  45.33.32.156   XSS Script Tag  HIGH   65%         [FP]    |
|  Mar 2 13:45  192.168.1.10   Scanner: Nikto  MED    35%         [FP]    |
+-------------------------------------------------------------------------+
|  Top IPs              |  Threats by Country                              |
|  185.220.101.4  [23]  |  US  234                                        |
|  45.33.32.156   [18]  |  CN  156                                        |
|  103.152.220.1  [12]  |  RU  98                                         |
+-------------------------------------------------------------------------+

訪問先: `http://your-app.test/threat-detection`

### ローカル開発中にアクセスする

ダッシュボードはデフォルトで `['web', 'auth']` ミドルウェアを使用するため、ユーザーはログインしている必要があります。アプリにまだ認証がない場合は、代わりに自分のマシンに限定してください:```env
THREAT_DETECTION_DASHBOARD_GUARD=ip
THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1

**オプション 2 - ミドルウェアを直接変更する:**```php
// config/threat-detection.php
'api' => [
    'enabled' => true,
    'prefix' => 'api/threat-detection',
    'middleware' => ['api', 'auth'],  // or 'auth:your-guard'
],

> 本番環境にデプロイする前に認証を復元してください。

### エンドポイントリファレンス

| メソッド | エンドポイント | 説明 |
|--------|----------|-------------|
| GET | `/api/threat-detection/threats` | 脅威の一覧（ページング、フィルタリング対応） |
| GET | `/api/threat-detection/threats/{id}` | 単一の脅威の詳細 |
| POST | `/api/threat-detection/threats/{id}/false-positive` | 脅威を誤検知としてマーク |
| GET | `/api/threat-detection/stats` | 全体の統計 |
| GET | `/api/threat-detection/summary` | タイプ、レベル、IP別の詳細な内訳 |
| GET | `/api/threat-detection/live-count` | 直近1時間の脅威 |
| GET | `/api/threat-detection/by-country` | 国別にグループ化 |
| GET | `/api/threat-detection/by-cloud-provider` | クラウドプロバイダー別にグループ化 |
| GET | `/api/threat-detection/top-ips` | 攻撃が多い上位IP |
| GET | `/api/threat-detection/timeline` | 脅威のタイムライン（チャート用） |
| GET | `/api/threat-detection/ip-stats?ip=x.x.x.x` | 特定のIPの統計 |
| GET | `/api/threat-detection/correlation` | 相関分析 |
| GET | `/api/threat-detection/export` | CSVにエクスポート |
| GET | `/api/threat-detection/exclusion-rules` | 除外ルールの一覧 |
| DELETE | `/api/threat-detection/exclusion-rules/{id}` | 除外ルールの削除 |

### `/threats` のクエリパラメータ

| パラメータ | 説明 |
|-----------|-------------|
| `keyword` | IP、URL、タイプ内を検索 |
| `ip` | IPアドレスでフィルタリング |
| `level` | 脅威レベルでフィルタリング（`high`、`medium`、`low`） |
| `type` | 脅威タイプでフィルタリング |
| `country` | 国コードでフィルタリング |
| `is_foreign` | 海外IPでフィルタリング（`true`/`false`） |
| `cloud_provider` | クラウドプロバイダーでフィルタリング |
| `is_false_positive` | 誤検知ステータスでフィルタリング（`true`/`false`） |
| `date_from` / `date_to` | 日付範囲フィルタ |
| `per_page` | 1ページあたりの件数（デフォルト: 20、最大: 100） |

### APIレスポンスの例

**GET `/api/threat-detection/stats`:**```json
{
  "success": true,
  "data": {
    "total_threats": 847,
    "high_severity": 23,
    "medium_severity": 156,
    "low_severity": 668,
    "unique_ips": 94,
    "foreign_ips": 67,
    "cloud_attacks": 12,
    "today": 34,
    "last_hour": 5
  }
}

const threats = await fetch('/api/threat-detection/threats?per_page=20');
this.threats = await threats.json();

**React:**```jsx
useEffect(() => {
    fetch('/api/threat-detection/stats')
        .then(res => res.json())
        .then(data => setStats(data));
}, []);

## データへの対応（オペレーター側でのブロック）

このパッケージはリクエストをブロックすることはありません。それがこのパッケージのアイデンティティであり、デフォルト動作ではありません。上記のエクスポートは、すでに運用している防御レイヤー（fail2ban、nginx、エッジWAF）にデータを供給します。しかし、一部のデプロイ環境にはそのような供給先となるレイヤーが存在しません。共有ホスティング、PaaS、制御できないロードバランサーの背後にあるコンテナなどです。そのような環境向けに、このパッケージは*判定結果*をヘルパーとして公開しており、強制（ブロック）のミドルウェアはご自身で記述します。エクスポートと同じアーキテクチャです。**インテリジェンスは当方が提供し、拒否の実行はお客様が提供します。**```php
// app/Http/Middleware/EnforceThreatDecisions.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use JayAnta\ThreatDetection\Facades\ThreatDetection;

class EnforceThreatDecisions
{
    public function handle(Request $request, Closure $next)
    {
        $ip = (string) $request->ip();

        // Static operator denylist (config: blocklisted_ips).
        // CIDR supported; whitelisted_ips wins on overlap.
        if (ThreatDetection::isBlocklisted($ip)) {
            abort(403);
        }

        // Volumetric flood: refuse over-threshold clients until the window resets.
        if (ThreatDetection::isDdosThresholdExceeded($ip)) {
            return response('Too Many Requests', 429, [
                'Retry-After' => (string) config('threat-detection.ddos.window', 60),
            ]);
        }

        return $next($request);
    }
}

ヘルパー:

| ヘルパー | 戻り値 | バックエンド |
|---|---|---|
| `ThreatDetection::isBlocklisted($ip)` | `bool` | `blocklisted_ips` 設定（`IpUtils` によるCIDR対応。ホワイトリストが優先） |
| `ThreatDetection::isWhitelisted($ip)` | `bool` | `whitelisted_ips` 設定 |
| `ThreatDetection::ddosRequestCount($ip)` | `int` | 検出ミドルウェアが維持するフラッドカウンター |
| `ThreatDetection::isDdosThresholdExceeded($ip)` | `bool` | そのカウンターと `ddos.threshold` の比較 |

注意点:

- **拒否リストは静的で、運用者が管理します。** パッケージ内でこれに追加することは一切ありません。これは fail2ban のジョイルが下すのと同じ判断（「ダッシュボードを確認した。この /24 は敵対的だ」）を、アプリ内で実行するだけです。
- DDoS カウンターは検出に到達したリクエストのみをカウントし（`skip_paths`、ホワイトリスト登録済みIP、無効化された環境は決してカウントされません）、DDoS 検出が無効なキャッシュドライバー（`file`、`database`、`null`）では 0 のままです。
- クライアントがしきい値を超えると、[`DdosThresholdExceeded` イベント](#ddosthresholdexceeded-event)もディスパッチされます。これはアラートや外部の禁止リストへの供給に役立ちます。ただし、リスナー内で `abort()` を呼び出さないでください。リスナーは検出ミドルウェアのフェイルオープンな `try/catch` 内で実行されるため、拒否は上記のように独自のミドルウェアで行うべきです。

---

## 404 プローブ追跡

このパッケージは偵察プローブを検出します。これは、WordPress や phpMyAdmin を使用していないサイトに対して `/wp-admin`、`/.env`、`/phpmyadmin` などの既知の脆弱なパスにアクセスするボットです。これらには悪意のあるペイロードはなく、パス自体がシグナルとなります。

ペイロードベースの検出とは別に、`[probe]` タイプタグで記録されます。プローブリクエストに悪意のあるペイロードも含まれている場合、両方が独立して記録されます。

デフォルトで有効で、50以上のプローブパスが含まれています。`config/threat-detection.php` でカスタマイズできます:```php
'probe_tracking' => [
    'enabled' => true,
    'default_level' => 'medium',
    'paths' => [
        '/wp-admin' => 'WordPress Admin',
        '/wp-admin/*' => 'WordPress Admin',
        '/.env' => 'Environment File',
        '/phpmyadmin' => 'phpMyAdmin',
        '/actuator/*' => 'Spring Actuator',
        // Add your own probe paths...
    ],
],

ここにリストされているフィールドは、検出が実行される前にクエリパラメータとリクエストボディ（フォームエンコードおよびJSON（`application/json`）の両方）から取り除かれます。同じリクエスト上の他のフィールドは引き続き完全にスキャンされます。

### セーフパス（ネストされたJSON API向けのパス認識型）

`safe_fields` は、キー名が**どこに**現れてもマッチします。ネストされたJSON APIでは、これはしばしば広すぎます。特定のキーをどこでも除外せずに、1つの特定のフィールドの値を除外したい場合があるでしょう。その場合は、ドット記法の**パス**でマッチし、`fnmatch` ワイルドカードをサポートする `safe_paths` を使用してください。```php
// config/threat-detection.php
'safe_paths' => ['search.query', 'filters.*.value'],

利用可能なバリデータ:

| バリデータ | チェックサム | 一般的な用途 |
|------------|----------|-------------|
| `verhoeff` | Verhoeff | Aadhaar番号 |
| `luhn`     | Luhn     | クレジット/デビットカード番号 |

同梱のマッピングを使用すると、たまたま12桁の長さであるタイムスタンプ、注文ID、バーコードはPIIとしてログに記録されなくなります。一方、本物のAadhaar番号は引き続き記録されます。複数の値が一致し、そのうち1つだけがチェックサムを通過する場合でも、検出は発動します。ノイズの中の本物の番号は依然として漏洩です。

チェックサムで制御されたカード検出のために、独自のパターンとバリデータを組み合わせてください:```php
'custom_patterns'    => ['/\b(?:\d[ -]?){13,19}\b/' => 'Card Number Detected'],
'pattern_validators' => ['Card Number Detected' => 'luhn'],

アラート、エンドポイント、フィールド名、攻撃元IPはすべて保持されます。削除されるのは値のみです。編集は*検出の後*に実行されるため、見逃しは発生しません。```php
// config/threat-detection.php
'redact' => [
    'enabled' => env('THREAT_DETECTION_REDACT', true),
    'mask'    => '[REDACTED]',
    'labels'  => ['Aadhaar Number Detected', 'PAN Number Detected', /* ... */],
],

The same options are available for API routes with `THREAT_DETECTION_API_GUARD`.

When `guard=none` (default), the package logs a warning once per day to remind you to configure authentication.

The guard **fails closed**: an unrecognised guard value (e.g. a typo) is denied with a 403 and a logged warning rather than silently granting access, and `guard=role` denies (with a warning) when the authenticated user model has no `hasRole()` method.

### Disabling a detection needs more than read access

Marking a threat as a false positive and deleting an exclusion rule both silence a detection type for everyone, which is a different privilege from reading the log. Those two endpoints are checked against a separate guard:```env
# Options: none, auth, role, ip. Default: role
THREAT_DETECTION_API_WRITE_GUARD=role

**例 - カスタム管理者エンドポイントのプローブを検出する:**```php
'/\/my-admin-panel/i' => 'Custom Admin Panel Probe',

- **`level`** は、ラベルの `threat_levels` キーワードから導出する代わりに、脅威レベルを直接設定します。
- **`contexts`** は、スキャンを特定のリクエストセグメントに制限します。例えば、ボディ内でのみ意味を持つカードパターンが、ヘッダー内の数字の連なりに誤って一致するのを防ぎます。
- **`validator`** は、インラインのポストマッチチェックに名前を付けます（[ポストマッチバリデータ](#post-match-validators-checksum-aware-false-positive-reduction) を参照）。これは `pattern_validators` ラベルマップよりも優先されます。

文字列と配列のエントリは、同じ設定内で自由に混在できます。不正なオプションは **フェイルオープン** します。つまり、パターンは制限なしでスキャンされ続け、警告がログに記録されるため、設定ミスによって検出が黙って無効化されたり狭められたりすることは決してありません。

> **注:** `/wp-login.php`、`/.env`、`/phpmyadmin` などの一般的なプローブパスは、[404プローブ追跡](#404-probe-tracking) 機能によって自動的に処理されるようになりました。これらに対してカスタムパターンを作成する必要はありません。

各パターンの脅威レベルは、ラベル内のキーワードを `threat_levels` 設定と照合することで自動的に決定されます。```php
'threat_levels' => [
    'high' => ['XSS', 'SQL Injection', 'SQL DDL', 'SQL DML', 'SQL File', 'SQL Hex', 'RCE', ..., 'Shellshock', 'Spring4Shell', 'PowerShell', 'CRLF', 'Null Byte', 'SSTI', 'Java', 'LDAP', 'XPath', 'PHP assert', ...],
    'medium' => ['Directory Traversal', 'LFI', 'SSRF', 'Sensitive', 'Config', ..., 'Open Redirect', 'LF Injection', 'GraphQL', 'Spring Boot Actuator', ...],
    'low' => ['User-Agent', 'JS Redirect', 'SEO Bot', 'Empty', 'Rate', 'Command-line Downloader', 'DNS Rebinding'],
],

---

## 本番環境への移行

このパッケージは設計上パッシブです。リクエストをブロック、拒否、変更することは一切なく、検出ミドルウェアは本体全体を`try/catch`でラップしているため、検出の失敗がアプリを壊すことは決してありません。適切なデフォルト設定が同梱されており、実行に外部サービスは不要です。本番公開前に、この短いチェックリストを確認する価値があります。

1. **ダッシュボードとAPIを保護する。** どちらも初期設定ではゼロコンフィグで初回実行できるよう`guard = none`にデフォルト設定され、保護されていない間は毎日警告をログに記録します。本番環境の前にガードを設定してください - `THREAT_DETECTION_DASHBOARD_GUARD`と`THREAT_DETECTION_API_GUARD`（`auth`、`role`、または`ip`）。認識されない値や、`hasRole()`を持たないユーザーモデルに対する`role`ガードは、現在**フェイルクローズ（403）**となるため、タイプミスでデータが黙って露出することはありません。検出の無効化は、デフォルトで`role`に設定されている`THREAT_DETECTION_API_WRITE_GUARD`によって別途制御されます。[ダッシュボードとAPIの認証](#dashboard-and-api-authentication)を参照してください。
2. **マイグレーションを実行する**（`vendor:publish --tag=threat-detection-migrations && migrate`）。再公開は安全です - すでに公開されたマイグレーションはスキップされます。
3. **検出モードを選択する。** `balanced`（デフォルト）はほとんどのアプリに適しています。コンテンツ中心のサイトでは`relaxed`を、高セキュリティの領域では`strict`を使用します。`content_paths`、`safe_fields`、`min_confidence`で調整します - [誤検知の削減](#reducing-false-positives)を参照してください。
4. **地域別のPII / カスタムパターンを確認する。** デフォルトはインド中心（Aadhaar、PAN、IFSC）であり、広範な数値パターン（例：銀行口座）は、認証ルート外の長い数値IDに一致する可能性があります。お住まいの地域とアプリに合わせて`custom_patterns`を置換または削減し、コンテンツ量の多いルートを`auth_paths` / `content_paths`に追加してください。
5. **ボリュームが見込まれる場合は保持を有効にする：** `THREAT_DETECTION_RETENTION=true`（スケジューラー経由で自動パージ）。Laravelのスケジューラー（`schedule:run`）がcronで駆動されている必要があります。
6. **オプションの追加機能（すべてデフォルトでオフ）：** Slackアラート（`THREAT_DETECTION_NOTIFICATIONS`）、ジオエンリッチメント（`php artisan threat-detection:enrich` - 無料のip-api.comへのアウトバウンドコールを行う唯一の機能）、およびキュー書き込み（`THREAT_DETECTION_QUEUE` - すでにキューワーカーを実行している場合のみ有効にしてください。それ以外の場合、書き込みは同期でありRedisは不要です）。

コアの検出とロギングには、Redis、キューワーカー、アウトバウンドのネットワークコールは一切必要ありません。

---

## 誤検知の削減

このパッケージは、誤検知を減らすための複数のツールを提供します。状況に合ったものを使用してください：

### セーフフィールドとセーフパス

フィールドをスキャンから完全に除外します。すべての場所で名前を指定するか（`safe_fields`）、ネストされたJSONのドット記法パスで指定します（`safe_paths`）。最もシンプルで最も大雑把なアプローチです - フィールドはスキップされるため、そのフィールドでは検出は一切実行されません。

詳細と例：[セーフフィールド](#safe-fields-false-positive-reduction)。

### コンテンツパスの抑制

CMSエディター、ブログ投稿フォーム、ユーザーがリッチコンテンツを送信するコメントセクションがある場合、それらのパスは誤検知を引き起こすことがよくあります（例：`<script>`コードサンプルを含むブログ投稿）。それらのパスを追加して、低/中レベルのアラートを抑制します：```php
// config/threat-detection.php
'content_paths' => [
    'admin/posts/*',
    'admin/pages/*',
    'blog/*/edit',
    'comments',
],

### 信頼度スコアリング

すべての脅威には、以下に基づく信頼度スコア（0〜100）が付与されます：
- 同じリクエスト内でのパターンマッチ数
- マッチしたパターンの重大度
- パターンが見つかった場所（クエリ文字列 > ヘッダー > ボディ）
- ユーザーエージェントが既知の攻撃ツールと一致するかどうか
- 現在の検出モード

検出モードの信頼度しきい値を下回る脅威はログに記録されません（[検出モード](#detection-modes)を参照）。

---

## 検出される攻撃タイプ

| カテゴリ | 例 |
|----------|---------|
| **SQLインジェクション** | UNION、ブール型、時間ベース、CHARエンコーディング、DDL（DROP/ALTER/CREATE）、DML（INSERT/UPDATE/DELETE）、ファイル操作（INTO OUTFILE、LOAD_FILE）、ORDER BY列挙、16進文字列、UNHEX |
| **NoSQLインジェクション** | MongoDBの$ne、$gt、$regex、$where演算子 |
| **XSS** | スクリプトタグ、SVGイベントハンドラ（`<svg onload=`）、HTMLイベントハンドラ（`<body onload=`、`<img onerror=`）、CSS式、JavaScript URI、DOM操作 |
| **コード実行** | RCEシェル関数、PHPデシリアライゼーション、Javaデシリアライゼーション（base64 + 16進マジックバイト）、テンプレートインジェクション（Blade、JSP、ASP、Jinja2、Velocity）、eval()、base64デコード、PHP assert()、create_function()、preg_replace /e |
| **SSTI** | 数学的プローブ（`{{7*7}}`）、Jinja2 import/config、Velocityテンプレート、Expression Language |
| **コマンドインジェクション** | Linux（シェル関数、コマンドチェーン、curl、wget、nc）、Windows（cmd.exe、PowerShell、wscript、cscript、net user） |
| **ファイルアクセス** | ディレクトリトラバーサル、LFI/RFIプロトコル、機密ファイルのプローブ（.env、.git、composer.json） |
| **SSRF** | ローカルホスト（127.0.0.1、0.0.0.0、::1）、AWS/GCPメタデータ、プライベートIP、16進/10進エンコードされたローカルホスト、DNSリバインディング（xip.io、nip.io、sslip.io） |
| **LDAPインジェクション** | LDAPフィルタ操作、ORインジェクション |
| **XPathインジェクション** | 属性セレクタ、XPath関数（contains、substring） |
| **CRLF / ヘッダーインジェクション** | URLエンコードされたCRLF（`%0d%0a`）、LFインジェクション、ヌルバイトインジェクション |
| **プロトコル攻撃** | HTTPリクエストスマグリング（CL+TE）、SSIインジェクション |
| **CVEエクスプロイト** | Shellshock（CVE-2014-6271）、Spring4Shell（CVE-2022-22965）、PHPUnit RCE（CVE-2017-9841）、Drupalgeddon、Log4Shell |
| **プローブ追跡** | WordPress（`/wp-admin`、`/wp-login.php`）、設定ファイル（`/.env`、`/.git`）、データベースツール（`/phpmyadmin`）、テクノロジープローブ（`.asp`、`.jsp`）、Spring actuator、Swagger/APIドキュメント - 50以上のパス |
| **スキャナー** | SQLMap、Nikto、Nmap、Burp Suite、FeroxBuster、FFUF、XSStrike、Dalfox、Netsparker、Qualys、Nuclei、およびその他20以上（合計53） |
| **AIスクレイパー** | GPTBot、ClaudeBot、ChatGPT、ByteSpider、Cohere、Common Crawl |
| **ヘッドレスブラウザ** | HeadlessChrome、PhantomJS、Selenium、Puppeteer、Playwright |
| **ボット** | Pythonスクリプト、Go HTTPクライアント、cURL、wget、AhrefsBot、SEMRushBot、空のユーザーエージェント |
| **認証** | ブルートフォース検出、トークン漏洩、パスワード露出、セッションID露出 |
| **DDoS** | レートベースの過剰リクエスト検出 |
| **回避技術** | SQLコメント挿入、二重URLエンコーディング、HTMLエンティティエンコーディング、Unicodeエスケープ、IIS Unicode、16進エスケープ |
| **その他** | GraphQLイントロスペクション、プロトタイプ汚染、オープンリダイレクト、XXE、Webシェル、暗号通貨マイニング、PII検出 |

---

## テストスイートの実行```bash
composer test