Эти запросы уже достигают вашего Laravel-приложения. Ваш журнал доступа показывает URL
и код статуса — и ничего больше: ни декодированной полезной нагрузки, ни того, какой из ваших
маршрутов был атакован, ни того, пытался ли тот же IP-адрес сделать сорок других вещей за этот час.

Этот пакет отвечает на эти вопросы. Установите его в любое приложение 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).

## Начало работы менее чем за минуту```bash
composer require jayanta/laravel-threat-detection
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate

---

## Где он вписывается: IDS против WAF против edge

Этот пакет — **пассивная IDS уровня приложения** — он наблюдает и записывает, но не
блокирует. Он предназначен для работы *вместе* с WAF или edge-сервисом, а не вместо них. Каждый уровень видит
то, чего не видят другие:

| | **Этот пакет** (IDS приложения) | **WAF** (mod_security, Cloudflare WAF) | **Edge / CDN** (Cloudflare) |
|---|:---:|:---:|:---:|
| Блокирует вредоносные запросы | ❌ только логирует | ✅ | ✅ |
| Полный контекст приложения (точный маршрут, декодированный payload, аутентифицированный пользователь) | ✅ | ⚠️ частично | ❌ |
| Встроенная панель управления + журнал угроз в вашей БД | ✅ | ⚠️ зависит | ⚠️ только edge |
| Специфичные для приложения детекции (например, Aadhaar / PAN / IFSC PII) | ✅ пользовательские паттерны | ❌ | ❌ |
| Работает офлайн / без внешнего сервиса | ✅ | ⚠️ зависит | ❌ |
| Останавливает трафик до того, как он достигнет вашего приложения | ❌ | ✅ edge | ✅ |
| Установка | один `composer require` | средняя–высокая | низкая–средняя |
| Стоимость | бесплатно, MIT | зависит | бесплатный тариф + платный |

**Коротко:** edge/WAF — это ваш замок на двери; этот пакет — камера видеонаблюдения
*внутри*, с контекстом приложения, чтобы точно сказать, что пытаются сделать на каком маршруте, кем
и как часто. Используйте его для принятия реальных решений — банов fail2ban, ограничений скорости,
гео-блокировок — на основе данных, которые ваш edge-уровень никогда не видит.

### Чем он намеренно НЕ является

- **Не WAF.** Он никогда не блокирует, не фильтрует и не изменяет запрос. Используйте Cloudflare,
  mod_security или настоящий WAF для принудительного применения. (Нет edge-уровня для передачи? 
  [Вспомогательные функции на стороне оператора](#acting-on-the-data-operator-side-blocking) раскрывают
  решения пакета, чтобы вы могли написать собственное пятистрочное блокирующее middleware —
  код принудительного применения остаётся вашим, а не пакета.)
- **Не замена безопасному кодированию.** Параметризованные запросы, валидация ввода и
  экранирование вывода — ваша настоящая защита. Этот пакет предполагает, что ваш код уже
  безопасен, и даёт вам *видимость*, а не защиту.
- **Не edge-сервис.** Если вы можете поставить Cloudflare впереди — сделайте это — затем добавьте этот пакет для
  деталей уровня приложения, которые edge-сервисы не видят.

### Так что же с ним на самом деле делать?

Самый частый вопрос о детекторе, который никогда не блокирует. Четыре ответа, в
порядке возрастания усилий:

| Вы хотите | Используйте | Усилия |
|---|---|---|
| Видеть, что на вас направлено | [Панель управления](#dashboard) или `threat-detection:stats` | нет, уже работает |
| Забанить повторных нарушителей на файрволе | [`threat-detection:export-fail2ban`](#artisan-commands) — передать в cron | одна строка |
| Отклонить на веб-сервере | [`threat-detection:export-blocklist`](#artisan-commands) → директивы nginx/apache | одна строка |
| Отказать в запросах внутри приложения | [Вспомогательные функции на стороне оператора](#acting-on-the-data-operator-side-blocking) — `isBlocklisted()`, `isDdosThresholdExceeded()` | ~10 строк вашего собственного middleware |
| Реагировать в реальном времени | [Событие `ThreatDetected`](#threatdetected-event) — Telegram, SIEM, PagerDuty | слушатель |

Пакет предоставляет интеллект; вы предоставляете отказ. Такое разделение
намеренно — код принудительного применения, живущий в вашем приложении, — это код, который вы можете читать,
тестировать и отключать, а значит, ошибка детекции никогда не сможет положить ваш сайт.

### Как он сравнивается с другими пакетами безопасности Laravel

Они решают разные задачи и хорошо сочетаются — таблица о выборе
правильного инструмента, а не о победе.

| Пакет | Что делает | Блокирует? | Используйте, когда |
|---|---|:---:|---|
| **этот пакет** | Сканирует каждый запрос по 150+ паттернам, логирует с полным контекстом приложения | ❌ | Вы хотите *видеть*, что пытаются сделать с вашим приложением |
| `spatie/laravel-honeypot` | Скрытое поле формы, которое ловит спам-ботов | ✅ только форма | У вас публичные формы, заваленные спамом |
| `graham-campbell/security` | Удаляет XSS-подобную разметку из ввода | ✅ изменяет | Вы хотите наивную санитизацию ввода |
| `spatie/laravel-csp` | Отправляет заголовки Content-Security-Policy | ✅ браузер | Вы хотите ограничить, что загружает браузер |
| `laravel/fortify` + ограничения скорости | Троттлинг и блокировка аутентификации | ✅ | Вам нужна защита от brute-force на входе |
| Cloudflare / mod_security | Edge WAF, блокирует до вашего приложения | ✅ | Вы хотите останавливать трафик до его прибытия |

Честное резюме: honeypot ловит спам в формах, WAF блокирует известный вредоносный трафик
на edge, а CSP ограничивает браузер. **Ни один из них не сообщает вам, что
злоумышленник пытался сделать с вашими конкретными маршрутами, с декодированным payload и
прикреплённым аутентифицированным пользователем.** Именно этот пробел заполняет пакет — и именно поэтому он
намеренно не блокирует: вы можете запускать его вместе со всеми вышеперечисленными
без конфликтов между ними.

---

## Требования

- PHP 8.2+ (Laravel 13 требует PHP 8.3+)
- Laravel 10.x, 11.x, 12.x или 13.x
- Любая база данных, поддерживаемая Laravel (MySQL, PostgreSQL, SQLite, SQL Server)
- Любой драйвер кэша — **Redis или очередь worker не требуются**. Redis/Memcached
  только *рекомендуется* для включения опциональной проверки DDoS (которая автоматически отключается на
  неатомарных драйверах). Запись в очередь — опциональна и по умолчанию выключена.

---

## Как это работает

1. Middleware сканирует каждый входящий HTTP-запрос
2. Запрос проверяется по 158 regex-паттернам, покрывающим SQL-инъекции, XSS, RCE, обход файлов, SSRF, LDAP, XPath, SSTI и другое
3. Если паттерн угрозы совпадает, в вашу таблицу базы данных `threat_logs` записывается запись с IP, URL, типом угрозы, уровнем серьёзности и оценкой уверенности
4. Опционально отправляется Slack-оповещение для угроз высокой серьёзности
5. Запрос продолжается нормально — **ничего не блокируется**

Для детекции не требуется подключение к интернету.

---

## Быстрый старт

### 1. Установите пакет```bash
composer require jayanta/laravel-threat-detection

Это создаёт две таблицы: `threat_logs` (хранит обнаруженные угрозы) и `threat_exclusion_rules` (хранит правила ложных срабатываний).

**Проверьте, что таблицы были созданы:**```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 минут | Дедупликация: один и тот же IP + один и тот же тип угрозы кэшируется на 5 минут. Используйте **разные типы атак** для каждого теста или подождите между тестами. |
| Запросы `curl` вызывают дополнительное обнаружение | Использование `curl` также логирует обнаружение user-agent «cURL Command» (низкая степень серьёзности). Это ожидаемо — пакет обнаруживает автоматизированные инструменты. |
| Пакет никогда не блокирует запросы | Ваше приложение продолжает работать в обычном режиме. Обнаружение пассивно. |
| Настройка Slack не требуется | Уведомления по умолчанию отключены. |
| Подключение к интернету не требуется | Базовое обнаружение работает на 100% локально. Только опциональная команда `threat-detection:enrich` обращается к внешнему API для получения гео-данных. |

### Устранение неполадок

**Начните здесь — одна команда отвечает на большинство вопросов:**```bash
php artisan threat-detection:doctor

Что охватывает: включённое обнаружение для этого окружения; каждая колонка, которая нужна
писателю (отсутствующая отбрасывает **каждую** угрозу); колонки дашборда/API;
таблица правил исключений; подключено ли промежуточное ПО к маршруту или
группе; опубликованная конфигурация, которая предшествует этой версии; пользовательские шаблоны, перекрывающие
встроенные; драйвер кэша, который не может выполнять подсчёт DDoS; и дашборд или
API, оставленные открытыми без аутентификации.

**«Я тестировал, но `threat-detection:stats` показывает ноль угроз» / «Угрозы не сохраняются в базе данных»**

Если проверка пройдена, установка в порядке, и проблема в самом тестовом запросе.
Три вещи, которые она не может проверить за вас:

| Проверка | Как проверить |
|-------|---------------|
| IP не в белом списке | Если вы добавили `THREAT_DETECTION_WHITELISTED_IPS` в `.env`, удалите его во время тестирования |
| Использован существующий маршрут | Тестовый URL должен соответствовать реальному маршруту (например, `/`). Код 404 означает, что промежуточное ПО никогда не запускалось |
| Кэш дедупликации | Один и тот же IP + один и тот же тип атаки кэшируется на 5 минут — попробуйте другой тип атаки |

> Выполнения `php artisan migrate` в одиночку никогда не достаточно: файлы миграций
> находятся внутри пакета и должны быть опубликованы в `database/migrations/` вашего приложения
> сначала. Проверка выводит точную команду, когда проблема в этом.

**«API возвращает 401 Unauthorized»**

См. [API Authentication](#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'],

### Config Reference

Опубликуйте файл конфигурации, чтобы увидеть все доступные параметры:```bash
php artisan vendor:publish --tag=threat-detection-config

Оставьте пустым (по умолчанию) для сканирования всех маршрутов (с учётом `skip_paths`). Когда настроены оба параметра, сначала проверяется `only_paths`, затем `skip_paths` применяется в пределах совпавшего набора.

### Поддержка очередей

По умолчанию запись угроз выполняется синхронно в цикле обработки запроса. Для приложений с высокой нагрузкой вы можете выгрузить записи в БД и уведомления Slack в очередь:```env
THREAT_DETECTION_QUEUE=true
THREAT_DETECTION_QUEUE_CONNECTION=redis
THREAT_DETECTION_QUEUE_NAME=threat-logs

Требует запущенного планировщика Laravel (`php artisan schedule:run`). Выполняется ежедневно в 02:00 через `threat-detection:purge`.

### Событие ThreatDetected

Каждая подтверждённая угроза отправляет событие `ThreatDetected`, на которое вы можете подписаться:```php
// app/Providers/EventServiceProvider.php
use JayAnta\ThreatDetection\Events\ThreatDetected;

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

Событие содержит `$ipAddress`, `$requestCount`, `$threshold` и `$windowSeconds`. Оно
ограничивается одним событием на IP за окно дедупликации (то же ограничение, что и для строки журнала), поэтому поток запросов не может
перегрузить ваши слушатели. Используйте его для оповещений или для передачи во внешнее хранилище банов; чтобы *отказать*
клиентам, превысившим порог, используйте `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`

### Доступ во время локальной разработки

Панель управления по умолчанию использует middleware `['web', 'auth']`, поэтому пользователи должны быть авторизованы. Если в вашем приложении ещё нет аутентификации, ограничьте доступ только вашей машиной:```env
THREAT_DETECTION_DASHBOARD_GUARD=ip
THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1

**Вариант 2 — Изменить middleware напрямую:**```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` | Угрозы за последний час |
| 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` | Элементов на странице (по умолчанию: 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` (CIDR через `IpUtils`; белый список имеет приоритет) |
| `ThreatDetection::isWhitelisted($ip)` | `bool` | конфиг `whitelisted_ips` |
| `ThreatDetection::ddosRequestCount($ip)` | `int` | счётчик флуда, который ведёт промежуточное ПО обнаружения |
| `ThreatDetection::isDdosThresholdExceeded($ip)` | `bool` | этот счётчик по сравнению с `ddos.threshold` |

Примечания:

- **Чёрный список статичен и поддерживается оператором.** Ничто в пакете никогда не добавляет в него записи —
  он выполняет то же решение, которое приняла бы тюрьма fail2ban («я прочитал панель управления; эта /24
  враждебна»), просто внутри приложения.
- Счётчик DDoS учитывает только запросы, которые достигли этапа обнаружения (`skip_paths`, IP из белого
  списка и отключённые окружения никогда не учитываются) и остаётся на 0 в драйверах кэша, где
  обнаружение DDoS отключено (`file`, `database`, `null`).
- Когда клиент превышает порог, также отправляется событие [`DdosThresholdExceeded`](#ddosthresholdexceeded-event)
  — полезно для оповещения или передачи во внешний список блокировок. Однако не вызывайте `abort()`
  из слушателя: слушатели выполняются внутри `try/catch` промежуточного ПО обнаружения с отказоустойчивым
  поведением, поэтому отказ должен обрабатываться в вашем собственном промежуточном ПО, как описано выше.

---

## Отслеживание 404-зондирования

Пакет обнаруживает разведывательные зонды — ботов, которые обращаются к известным уязвимым путям, таким как `/wp-admin`, `/.env` или `/phpmyadmin`, на вашем сайте, не являющемся WordPress или 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...
    ],
],

Поля, перечисленные здесь, удаляются из параметров запроса и тела запроса — как в форме (`application/x-www-form-urlencoded`), так и в JSON (`application/json`) — до запуска детектирования. Остальные поля того же запроса по-прежнему полностью сканируются.

### Безопасные пути (с учётом пути, для вложенных JSON API)

`safe_fields` сопоставляет имя ключа **где угодно**, где оно встречается. Для вложенных JSON API это часто слишком широко — вам может понадобиться исключить значение одного конкретного поля, не исключая этот ключ повсюду. Используйте `safe_paths`, который сопоставляет по **пути** в точечной нотации и поддерживает подстановочные знаки `fnmatch`:```php
// config/threat-detection.php
'safe_paths' => ['search.query', 'filters.*.value'],

Доступные валидаторы:

| Валидатор  | Контрольная сумма | Типичное использование |
|------------|-------------------|------------------------|
| `verhoeff` | Verhoeff          | Номера Aadhaar         |
| `luhn`     | Luhn              | Номера кредитных/дебетовых карт |

С поставляемой конфигурацией метки времени, идентификаторы заказов и штрих-коды, которые случайно состоят из 12 цифр, больше не логируются как PII — в то время как настоящие номера Aadhaar по-прежнему распознаются. Если несколько значений совпадают и только одно проходит проверку контрольной суммы, детектирование всё равно срабатывает: реальный номер среди шума — это всё ещё утечка.

Скомбинируйте валидатор с собственным шаблоном для обнаружения карт с проверкой контрольной суммы:```php
'custom_patterns'    => ['/\b(?:\d[ -]?){13,19}\b/' => 'Card Number Detected'],
'pattern_validators' => ['Card Number Detected' => 'luhn'],

The alert, the endpoint, the field names and the attacking IP all survive -  only the value goes. Redaction runs *after* detection, so nothing is missed.```php
// config/threat-detection.php
'redact' => [
    'enabled' => env('THREAT_DETECTION_REDACT', true),
    'mask'    => '[REDACTED]',
    'labels'  => ['Aadhaar Number Detected', 'PAN Number Detected', /* ... */],
],

Те же параметры доступны для маршрутов API с `THREAT_DETECTION_API_GUARD`.

Когда `guard=none` (по умолчанию), пакет один раз в день записывает предупреждение в журнал, напоминая о необходимости настроить аутентификацию.

Защита **отказывает закрыто**: нераспознанное значение guard (например, опечатка) отклоняется с кодом 403 и записью предупреждения в журнал, а не молча предоставляет доступ, а `guard=role` отклоняет запрос (с предупреждением), когда у аутентифицированной модели пользователя нет метода `hasRole()`.

### Отключение обнаружения требует больше, чем доступ на чтение

Пометка угрозы как ложного срабатывания и удаление правила исключения — оба действия отключают тип обнаружения для всех, что является привилегией, отличной от чтения журнала. Эти две конечные точки проверяются отдельной защитой:```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'],
],

---

## Переход в продакшн

Пакет пассивен по своей конструкции — он никогда не блокирует, не отклоняет и не изменяет запрос, а middleware обнаружения оборачивает всё своё тело в `try/catch`, поэтому сбой обнаружения никогда не сломает ваше приложение. Он поставляется с разумными настройками по умолчанию и не требует внешних сервисов для работы. Перед запуском стоит просмотреть этот краткий чек-лист:

1. **Защитите панель управления и API.** Оба по умолчанию используют `guard = none` для первого запуска без конфигурации и ежедневно записывают предупреждение, пока не защищены. Перед продакшном задайте guard — `THREAT_DETECTION_DASHBOARD_GUARD` и `THREAT_DETECTION_API_GUARD` (`auth`, `role` или `ip`). Неизвестное значение или guard `role` на модели пользователя без `hasRole()` теперь **закрывается с ошибкой** (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), а широкие числовые шаблоны (например, банковский счёт) могут совпадать с длинными числовыми идентификаторами вне маршрутов аутентификации. Замените или сократите `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) на основе:
- Количества совпадений с паттернами в одном запросе
- Критичности совпавшего паттерна
- Места обнаружения паттерна (строка запроса > заголовки > тело)
- Совпадения user-agent с известным инструментом атаки
- Текущего режима обнаружения

Угрозы ниже порога уверенности для вашего режима обнаружения не регистрируются (см. [Режимы обнаружения](#detection-modes)).

---

## Обнаруживаемые типы атак

| Категория | Примеры |
|----------|---------|
| **SQL-инъекции** | UNION, boolean, time-based, кодирование CHAR, DDL (DROP/ALTER/CREATE), DML (INSERT/UPDATE/DELETE), файловые операции (INTO OUTFILE, LOAD_FILE), перечисление ORDER BY, hex-строки, UNHEX |
| **NoSQL-инъекции** | Операторы MongoDB $ne, $gt, $regex, $where |
| **XSS** | Теги script, обработчики событий SVG (`<svg onload=`), HTML-обработчики событий (`<body onload=`, `<img onerror=`), CSS-выражения, JavaScript URI, манипуляции с DOM |
| **Выполнение кода** | RCE-шелл-функции, десериализация PHP, десериализация Java (base64 + hex magic bytes), инъекции шаблонов (Blade, JSP, ASP, Jinja2, Velocity), eval(), декодирование base64, PHP assert(), create_function(), preg_replace /e |
| **SSTI** | Математические проверки (`{{7*7}}`), import/config Jinja2, шаблоны Velocity, язык выражений |
| **Инъекции команд** | Linux (шелл-функции, цепочки команд, curl, wget, nc), Windows (cmd.exe, PowerShell, wscript, cscript, net user) |
| **Доступ к файлам** | Обход каталогов, протоколы LFI/RFI, проверки чувствительных файлов (.env, .git, composer.json) |
| **SSRF** | Localhost (127.0.0.1, 0.0.0.0, ::1), метаданные AWS/GCP, частные IP-адреса, hex/десятично закодированный localhost, DNS rebinding (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, пустые user-agent |
| **Аутентификация** | Обнаружение перебора, утечки токенов, раскрытие паролей, раскрытие идентификаторов сессий |
| **DDoS** | Обнаружение чрезмерных запросов на основе частоты |
| **Обход защиты** | Вставка SQL-комментариев, двойное URL-кодирование, кодирование HTML-сущностей, Unicode-экранирование, IIS Unicode, hex-экранирование |
| **Прочее** | GraphQL-интроспекция, загрязнение прототипов, открытые редиректы, XXE, веб-шеллы, криптомайнинг, обнаружение PII |

---

## Запуск набора тестов```bash
composer test