次に、`web` グループにミドルウェアを追加します（Laravel 11+ では `bootstrap/app.php`、Laravel 10 では `app/Http/Kernel.php` に1行追加）— 完全なスニペットは下記の [クイックスタート](#quick-start) にあります。これで完了です。検出が有効になりました。```bash
php artisan threat-detection:doctor   # confirms it is actually recording

### 2. マイグレーションを公開して実行する

> **この手順は必須です。** これを実行しないと、パッケージは脅威を検出してもデータベースに保存できません。この手順をスキップすると、`threat_logs` テーブルが存在せず、すべての検出結果が通知なしに失われます（`storage/logs/laravel.log` にエラーのみが表示されます）。```bash
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate

`create_threat_logs_table`、`add_confidence_to_threat_logs_table`、`create_threat_exclusion_rules_table` を探してください - すべて `Ran` と表示されるはずです。

### 3. ミドルウェアを登録する

ミドルウェアはリクエストをスキャンするものです。これを `web` ミドルウェアグループに追加する必要があります。

**Laravel 11 または 12 を使用している場合** -  `bootstrap/app.php` を開きます：```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \JayAnta\ThreatDetection\Http\Middleware\ThreatDetectionMiddleware::class,
    ]);
})

### 4. (オプション) 設定ファイルを公開```bash
php artisan vendor:publish --tag=threat-detection-config

### ステップ 2: ブラウザでテストURLを開く

アプリ内の**既存の任意のルート**（ホームページ、製品ページなど）に悪意のあるクエリパラメータを追加してください。例:

**SQLインジェクション:**```
http://localhost:8000/?q=' UNION SELECT * FROM users--

**ディレクトリトラバーサル:**```
http://localhost:8000/?file=../../etc/passwd

**Shellshock (CVE-2014-6271):**```
http://localhost:8000/?cmd=() { :;}; /bin/bash

**DROP TABLE (SQL DDL):**```
http://localhost:8000/?q=DROP TABLE users

`Total Threats`、重大度のカウント、および上位 IP を含むテーブルが表示されるはずです。

**オプション B -  Tinker:**```bash
php artisan tinker

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

What it covers: この環境で検出が有効になっているか; ライターが必要とするすべてのカラム(欠けているものは**すべての**脅威を破棄します); ダッシュボード/APIのカラム; 除外ルールのテーブル; ミドルウェアが実際にルートまたはグループに接続されているか; このバージョンより前に公開された設定; ビルトインのパターンをシャドウするカスタムパターン; DDoSカウントを実行できないキャッシュドライバ; そして認証なしで公開されたダッシュボードまたはAPI。

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

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

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

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

**"APIが401 Unauthorizedを返す"**

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

**"ダッシュボードに404が表示される"**

ダッシュボードはデフォルトで無効です。`THREAT_DETECTION_DASHBOARD=true` を `.env` に追加し、ルートキャッシュをクリアしてください:```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

空のまま（デフォルト）にすると、すべてのルートをスキャンします（`skip_paths` の対象となります）。両方が設定されている場合、最初に `only_paths` がチェックされ、次に一致したセット内で `skip_paths` が適用されます。

### キューサポート

デフォルトでは、脅威ログはリクエストサイクル内で同期的に記録されます。高トラフィックのアプリケーションでは、DB 書き込みと Slack 通知をキューにオフロードできます。```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 Event

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

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

このイベントは `$ipAddress`、`$requestCount`、`$threshold`、`$windowSeconds` を保持し、ログ行と同じスロットルで
重複排除ウィンドウごとに IP ごとに 1 回に制限されるため、フラッドが発生しても
リスナーが埋もれることはありません。アラート発報や外部のBANストアへのフィードに使用してください。しきい値を超えたクライアントを*拒否*するには、
代わりに独自のミドルウェアから `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

---

## ダッシュボード

このパッケージには、ダークモード対応のダッシュボード（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'
],

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

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

| Method | Endpoint | Description |
|--------|----------|-------------|
| 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` のクエリパラメータ

| Parameter | Description |
|-----------|-------------|
| `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 の jail と同じ判断（「ダッシュボードを見ると、この /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では、それはしばしば広すぎます。特定のキー全体を除外せずに、特定のフィールドの値だけを除外したい場合もあるでしょう。その場合は、ドット記法の**パス**で一致し、`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', /* ... */],
],

同じオプションは、`THREAT_DETECTION_API_GUARD` を伴う API ルートでも利用できます。

`guard=none`（デフォルト）の場合、パッケージは認証を設定するよう促す警告を1日1回ログに記録します。

このガードは **フェイルクローズ** です：認識されないガード値（例：タイプミス）は、黙ってアクセスを許可するのではなく、403とログに記録される警告で拒否されます。また、`guard=role` の場合、認証済みユーザーモデルに `hasRole()` メソッドがないときは（警告付きで）拒否されます。

### 検出の無効化には読み取りアクセス以上の権限が必要

脅威を誤検知としてマークすることと除外ルールを削除することは、どちらも全ユーザーに対して検出タイプを無効化する操作であり、ログの読み取りとは異なる権限です。これら2つのエンドポイントは、別のガードに対してチェックされます：```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）となるため、タイポが静かにデータを晒すことはありません。検出の無効化は別途 `THREAT_DETECTION_API_WRITE_GUARD` によって制御され、デフォルトは `role` です。[ダッシュボードと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）で、幅広い数値パターン（例: bank-account）は認証ルート外の長い数値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テンプレート、式言語 |
| **コマンドインジェクション** | 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