jay123anta/laravel-threat-detectionوسيط Laravel سلبي يكتشف ويسجّل حقن SQL وXSS وRCE وماسحات البوتات وأكثر من 175 نمط هجوم. يتضمن لوحة تحكم مدمجة، وتنبيهات Slack، وواجهة REST API، وإثراءً جغرافيًا. نظام IDS، وليس WAF.
<p align="center">
<a href="https://packagist.org/packages/jayanta/laravel-threat-detection"><img src="https://img.shields.io/packagist/v/jayanta/laravel-threat-detection.svg?style=flat-square" alt="أحدث إصدار"></a>
<a href="https://github.com/jay123anta/laravel-threat-detection/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/jay123anta/laravel-threat-detection/tests.yml?branch=main&style=flat-square&label=tests" alt="الاختبارات"></a>
<a href="https://github.com/jay123anta/laravel-threat-detection/actions/workflows/tests.yml"><img src="https://img.shields.io/badge/PHPStan-level%205-brightgreen?style=flat-square" alt="PHPStan المستوى 5"></a>
<a href="https://github.com/jay123anta/laravel-threat-detection/actions/workflows/tests.yml"><img src="https://img.shields.io/badge/code%20style-Pint-orange?style=flat-square" alt="نمط الكود Pint"></a>
<a href="https://packagist.org/packages/jayanta/laravel-threat-detection"><img src="https://img.shields.io/packagist/dt/jayanta/laravel-threat-detection.svg?style=flat-square" alt="إجمالي التنزيلات"></a>
<a href="https://packagist.org/packages/jayanta/laravel-threat-detection"><img src="https://img.shields.io/packagist/php-v/jayanta/laravel-threat-detection?style=flat-square" alt="إصدار PHP"></a>
<a href="https://github.com/jay123anta/laravel-threat-detection/blob/main/LICENSE"><img src="https://img.shields.io/packagist/l/jayanta/laravel-threat-detection.svg?style=flat-square" alt="الترخيص"></a>
</p>
# Laravel Threat Detection
**مراقبة أمنية وتسجيل الهجمات لـ Laravel. اكتشف وسجّل حقن SQL،
XSS، RCE، اجتياز المسارات، ماسحات الروبوتات وفحوصات الاستطلاع من نوع `/wp-admin` —
كل طلب عدائي يُسجَّل في قاعدة بياناتك مع سياق التطبيق الكامل.
إنه نظام كشف تسلل (IDS)، وليس جدار حماية تطبيقات (WAF): لا يحجب أو يفلتر أو يعدّل أي طلب أبدًا.**
<p align="center">
<img src="https://raw.githubusercontent.com/jay123anta/laravel-threat-detection/main/art/demo.gif" alt="ثبّت الحزمة، أرسل ثلاث هجمات — حقن SQL، اجتياز المسارات، XSS — كل واحدة تُرجع HTTP 200 لأن لا شيء محجوب، وجميعها محسوبة بالفعل في threat-detection:stats" width="100%">
</p>
### هل أنت هنا لأنك رأيت شيئًا كهذا؟
```
GET /wp-admin/setup-config.php 404 — on a site that isn't WordPress
GET /.env 404 — someone wants your database password
GET /?id=1' UNION SELECT password FROM 200 — SQL injection against a real route
GET /phpmyadmin/index.php 404 — scanning for an admin panel
```
تلك الطلبات تصل بالفعل إلى تطبيق Laravel الخاص بك. يُظهر سجل الوصول لديك عنوان URL
ورمز الحالة، ولا شيء آخر — ليس الحمولة المفكوكة، ولا أي من مساراتك
تم استهدافه، ولا ما إذا كان نفس عنوان IP قد جرّب أربعين شيئًا آخر في هذه الساعة.
تجيب هذه الحزمة عن تلك الأسئلة. أضفها إلى أي تطبيق Laravel 10–13 وتبدأ
بفحص كل طلب HTTP مقابل أكثر من 150 نمط هجوم، مع تقييم كل تطابق حسب
درجة الثقة وكتابته إلى قاعدة بياناتك — مع لوحة تحكم مدمجة، وتنبيهات Slack،
وإثراء جغرافي، وتصديرات fail2ban/blocklist. لا يتم حظر أي طلب أبدًا. فكّر في
كاميرا مراقبة، وليس قفلًا: فهي تُظهر لك بالضبط من يتحسّس مساراتك، وكم مرة،
وبأي تقنيات.
> مستخرجة من تطبيق إنتاجي ومُجرّبة على حركة مرور حقيقية. أكثر من 2,400 اختبار، بلا
> تبعيات وقت تشغيل تتجاوز 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
```
ثم أضف الوسيط إلى مجموعة `web` الخاصة بك (سطر واحد في `bootstrap/app.php` على Laravel 11+،
أو `app/Http/Kernel.php` على Laravel 10) — المقتطف الكامل في [البدء السريع](#quick-start) أدناه.
هذا كل شيء؛ الكشف أصبح نشطًا.
```bash
php artisan threat-detection:doctor # confirms it is actually recording
```
---
## أين يندرج: IDS مقابل WAF مقابل الحافة
هذه الحزمة هي **نظام كشف تسلل سلبي على مستوى التطبيق** — يراقب ويسجل، ولا يحجب.
الغرض منها أن تكون *بجانب* WAF أو خدمة الحافة، لا أن تحل محلها. كل طبقة ترى
شيئًا لا تستطيع الطبقات الأخرى رؤيته:
| | **هذه الحزمة** (app IDS) | **WAF** (ModSecurity + OWASP CRS، Cloudflare WAF) | **الحافة / CDN** (Cloudflare) |
|---|:---:|:---:|:---:|
| حجب الطلبات الخبيثة | ❌ تسجيل فقط | ✅ | ✅ |
| سياق التطبيق الكامل (الرابط الدقيق، الحمولة المفكوكة، المستخدم الموثق) | ✅ | ⚠️ جزئي | ❌ |
| لوحة تحكم مدمجة + سجل تهديدات في قاعدة بياناتك | ✅ | ⚠️ يختلف | ⚠️ الحافة فقط |
| كشوفات خاصة بالتطبيق (مثل Aadhaar / PAN / IFSC PII) | ✅ مدمج + مخصص | ⚠️ اكتب قواعدك بنفسك | ⚠️ قواعد مخصصة، تعتمد على الخطة |
| يعمل دون اتصال / بدون خدمة خارجية | ✅ | ⚠️ يعتمد | ❌ |
| يوقف حركة المرور قبل وصولها إلى خادمك | ❌ | ⚠️ WAF السحابي فقط | ✅ |
| الإعداد | `composer require`، ترحيل، سطر middleware واحد | متوسط–عالٍ | منخفض–متوسط |
| التكلفة | مجاني، MIT | يختلف | طبقة مجانية + مدفوع |
**الخلاصة:** الحافة/WAF هو القفل على الباب؛ هذه هي كاميرا المراقبة
*بالداخل*، مع سياق التطبيق لتخبرك بالضبط ما يُحاول على أي مسار، ومن قِبَل من،
وبأي تكرار. استخدمها لتغذية قرارات حقيقية — حظر fail2ban، حدود المعدل،
الحظر الجغرافي — ببيانات لا تراها طبقة الحافة أبدًا.
### ما هي ليست كذلك عمدًا
- **ليست WAF.** لا تحجب أو تصفّي أو تعدّل أي طلب أبدًا. استخدم Cloudflare،
mod_security، أو WAF حقيقي للتنفيذ. (لا توجد طبقة حافة لتسليمها المهمة؟ إن
[مساعدات جانب المشغّل](#acting-on-the-data-operator-side-blocking) تكشف
قرارات الحزمة حتى تكتب middleware الحجب الخاص بك في خمسة أسطر —
كود التنفيذ يبقى لك، لا للحزمة.)
- **ليست بديلاً عن البرمجة الآمنة.** الاستعلامات المُعاملة (parameterized queries)، والتحقق من المدخلات، و
تهريب المخرجات هي دفاعاتك الفعلية. تفترض هذه الحزمة أن كودك آمن بالفعل وتمنحك *رؤية*،
لا حماية.
- **ليست خدمة حافة.** إذا كان بإمكانك وضع Cloudflare في المقدمة، افعل — ثم أضف هذه للتفاصيل
على مستوى التطبيق التي لا تستطيع خدمات الحافة رؤيتها.
- **ليست كاشفًا كاملاً، ولا يمكن أن تكون كذلك.** مطابقة الأنماط تلتقط الهجمات التي
*تبدو مثل* هجمات معروفة. تقنية جديدة، أو تقنية مألوفة أُعيدت صياغتها بما يكفي، ستمر
دون تسجيل — ولن يُخبرك أحد أنها فعلت. الصمت هنا يعني
"لم يتطابق شيء"، وليس أبدًا "لم يحدث شيء". ما يجعلها تستحق مكانها هو
حركة المرور عالية الحجم منخفضة الجهد التي تشكل معظم ما يضرب تطبيق Laravel
عامًا فعلاً: الماسحات، مجسّات الاستطلاع، سلاسل الحقن الجاهزة، رشّ بيانات الاعتماد.
تعامل مع سجل هادئ كغياب دليل، لا كدليل على الغياب.
### توقّع أن تُعلّم على محتواك الخاص من اليوم الأول
تثبيت غير مضبوط يُطلق على محتوى مشروع، ويجب أن تعرف ذلك قبل
التثبيت لا بعده. هذه قياسات فعلية، لا افتراضات. الصفوف
أدناه عيّنة من الحد الأدنى الذي يثبّته
[`LegitimateTrafficCorpusTest`](https://github.com/jay123anta/laravel-threat-detection/blob/main/tests/Feature/LegitimateTrafficCorpusTest.php);
كل صف يسرد *كل* ما يسجله ذلك الطلب، و
[`ReadmeNoiseFloorTest`](https://github.com/jay123anta/laravel-threat-detection/blob/main/tests/Feature/ReadmeNoiseFloorTest.php) يُفشل
البناء إذا توقف أي صف عن مطابقة ما تقيسه المجموعة له.
<!-- noise-floor:start -->
| طلب مشروع تمامًا | ما يسجله تثبيت غير مضبوط |
|---|---|
| `how to write a UNION SELECT in postgres` مكتوب في مربع بحث <!-- case: sql tutorial in a search box --> | `SQL Injection UNION` / عالٍ |
| مقالة مدونة تحتوي على `<script>window.dataLayer=[];</script>` <!-- case: javascript snippet in a blog post --> | `XSS Script Tag` / عالٍ · `Command Chain Injection` / متوسط |
| تذكرة دعم فيها خطأ `SELECT * FROM users WHERE id = 1` ملصوق <!-- case: a pasted sql error in a support ticket --> | `SQLi Variant` / عالٍ · `SQL SELECT Query` / منخفض |
| توثيق يشرح أن `../../etc/passwd` هي حمولة الاجتياز الكلاسيكية <!-- case: a traversal explainer in documentation --> | `Directory Traversal` / متوسط · `Sensitive File Access` / متوسط |
| نموذج ملف شخصي يجمع رقم جوال هندي حقيقي و PAN <!-- case: a profile form collecting genuine indian pii --> | `PAN Number Detected` / عالٍ · `Bank Account Number Detected` / عالٍ · `Mobile Number Detected` / منخفض |
<!-- noise-floor:end -->
**لا شيء من هذه أخطاء.** مقالة مدونة تحتوي على `<script>` هي، بايت ببايت،
حمولة XSS مخزّنة؛ والبحث عن `UNION SELECT` لا يمكن تمييزه عن محاولة
حقن؛ ورقم جوال من عشرة أرقام هو أيضًا رقم حساب بنكي محتمل. لا شيء
سوى سياق التطبيق يفصل بينها، ولا يمكن لأي محرك أنماط أن يوفّر لك ذلك
السياق.
توفيره تغيير إعداد من سطر واحد: سمِّ الحقل الذي يحمل شرعًا
محتوى كهذا في `safe_fields` (أو `safe_paths`، لمسار واحد داخل JSON متداخل) و
لن يُفحص بعد ذلك. هذا هو المفتاح الذي يُسكِت الصفوف أعلاه — وهو
مقايضة حقيقية، لأن هجومًا يُسلَّم عبر ذلك الحقل سيظل غير مرئي أيضًا.
`content_paths` ووضع `relaxed` أدوات مختلفة. تُسقط الضوضاء منخفضة
ومتوسطة الخطورة، و**تُبقي عمدًا على تسجيل التطابقات عالية الخطورة** —
لذا لن تُسكِت الصفوف العالية في هذا الجدول، بحكم التصميم. راجع
[تقليل الإيجابيات الكاذبة](#reducing-false-positives) لمعرفة أيّهما تستخدم ومتى.
**إذا كان تطبيقك يقبل نصًا منسقًا، أو عينات كود، أو استعلامات بحث، فافعل ذلك قبل أن
تحكم على المخرجات.** الإعداد الافتراضي صاخب-لكن-صادق عمدًا بدلاً من
هادئ-وناقص: من الأسهل إسكات تطابق معروف من اكتشاف تطابق لم
يُطلق أبدًا.
### إذن ماذا تفعل بها فعلاً؟
السؤال الأكثر شيوعًا عن كاشف لا يحجب أبدًا. أربع إجابات، بترتيب
تصاعدي من الجهد:
| تريد أن | استخدم | الجهد |
|---|---|---|
| ترى ما يضربك | [لوحة التحكم](#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` + حدود المعدل | خنق المصادقة والقفل | ✅ | تحتاج حماية من القوة الغاشمة على تسجيل الدخول |
| Cloudflare / mod_security | WAF الحافة، يحجب قبل تطبيقك | ✅ | تريد إيقاف حركة المرور قبل وصولها |
الخلاصة الصادقة: honeypot يلتقط سبام النماذج، و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. يفحص middleware كل طلب HTTP وارد
2. يُفحص الطلب مقابل 158 نمط regex تغطي حقن SQL، وXSS، وRCE، واجتياز الملفات، وSSRF، وLDAP، وXPath، وSSTI، والمزيد
3. إذا تطابق نمط تهديد، يُكتب سجل في جدول قاعدة بيانات `threat_logs` مع IP، والرابط، ونوع التهديد، ومستوى الخطورة، ودرجة الثقة
4. اختياريًا، يُرسل تنبيه Slack للتهديدات عالية الخطورة
5. يستمر الطلب بشكل طبيعي - **لا شيء يُحجب**
لا حاجة لاتصال بالإنترنت للكشف.
---
## البدء السريع
### 1. ثبّت الحزمة
```bash
composer require jayanta/laravel-threat-detection
```
### 2. نشر الترحيلات وتشغيلها
> **هذه الخطوة مطلوبة.** بدونها، ستكتشف الحزمة التهديدات ولكنها لن تستطيع تخزينها في قاعدة البيانات. إذا تخطيت هذه الخطوة، فلن يكون جدول `threat_logs` موجودًا وستُفقد جميع عمليات الكشف بصمت (سترى الأخطاء فقط في `storage/logs/laravel.log`).
```bash
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate
```
يُنشئ هذا جدولين: `threat_logs` (يخزّن التهديدات المكتشفة) و`threat_exclusion_rules` (يخزّن قواعد الإيجابيات الكاذبة).
**تحقّق من إنشاء الجداول:**
```bash
php artisan migrate:status
```
ابحث عن `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,
]);
})
```
> **كيفية التحقق من إصدار Laravel الخاص بك:** نفّذ `php artisan --version` في الطرفية.
**إذا كنت تستخدم Laravel 10** - افتح `app/Http/Kernel.php`:
```php
protected $middlewareGroups = [
'web' => [
// ... existing middleware
\JayAnta\ThreatDetection\Http\Middleware\ThreatDetectionMiddleware::class,
],
];
```
### 4. (اختياري) نشر ملف الإعدادات
```bash
php artisan vendor:publish --tag=threat-detection-config
```
يعمل الحزمة بإعدادات افتراضية معقولة. يتيح لك نشر الإعدادات تخصيص أنماط الكشف، وأوضاع الحساسية، وإشعارات Slack، والمزيد. إذا تخطيت هذه الخطوة، فسيظل كل شيء يعمل.
**هذا كل شيء.** تطبيقك الآن يكتشف التهديدات.
---
## تحقق من أنه يعمل
بعد التثبيت، قم بتشغيل تهديد تجريبي وتأكد من تسجيله.
### الخطوة 1: ابدأ تطبيقك
```bash
php artisan serve
```
### الخطوة 2: افتح عنوان URL للاختبار في متصفحك
أضف معامل استعلام ضار إلى **أي مسار موجود** في تطبيقك (صفحتك الرئيسية، صفحة منتج، إلخ). على سبيل المثال:
**حقن SQL:**
```
http://localhost:8000/?q=' UNION SELECT * FROM users--
```
**XSS (البرمجة النصية عبر المواقع):**
```
http://localhost:8000/?q=<script>alert(1)</script>
```
**اجتياز الدليل:**
```
http://localhost:8000/?file=../../etc/passwd
```
**RCE (تنفيذ التعليمات البرمجية عن بُعد):**
```
http://localhost:8000/?cmd=system('ls -la')
```
**Shellshock (CVE-2014-6271):**
```
http://localhost:8000/?cmd=() { :;}; /bin/bash
```
**حقن أوامر Windows:**
```
http://localhost:8000/?cmd=powershell -c whoami
```
**DROP TABLE (SQL DDL):**
```
http://localhost:8000/?q=DROP TABLE users
```
> استخدم مسارًا موجودًا فعليًا في تطبيقك (مثل `/`). إذا أعاد الرابط خطأ 404، فقد لا يكون الوسيط قد تم تشغيله.
### الخطوة 3: تحقق من تسجيل التهديدات
**الخيار أ - أمر Artisan (الأسرع):**
```bash
php artisan threat-detection:stats
```
يجب أن ترى جدولاً يحتوي على `Recorded Detections`، وعدد مرات الخطورة، وأعلى
عناوين IP. هذا الرقم يعدّ *الصفوف*، وليس المحاولات: تُكتب الكشف مرة واحدة لكل
عنوان IP لكل نوع تهديد كل خمس دقائق، ويتم إزالة تكرار التكرارات داخل تلك النافذة بدلاً من عدّها مرة أخرى.
**الخيار ب - Tinker:**
```bash
php artisan tinker
```
```php
DB::table('threat_logs')->latest()->take(5)->get(['ip_address', 'type', 'threat_level', 'confidence_score']);
```
**الخيار C - ملف سجل Laravel:**
يُكتب كل تهديد مكتشف كتحذير إلى `storage/logs/laravel.log`:
```
[high] Threat Detected: [middleware] SQL Injection UNION from 127.0.0.1 (http://localhost:8000/?q=...) [confidence: 50%]
```
### أشياء يجب معرفتها عند الاختبار
| السلوك | الشرح |
|----------|-------------|
| نفس التهديد يُسجَّل مرة واحدة فقط كل 5 دقائق | إزالة التكرار: نفس IP + نفس نوع التهديد يُخزَّن مؤقتًا لمدة 5 دقائق. استخدم **أنواع هجمات مختلفة** لكل اختبار، أو انتظر بين الاختبارات. |
| طلبات `curl` تُفعِّل كشفًا إضافيًا | استخدام `curl` يسجِّل أيضًا كشفًا لوكيل المستخدم "cURL Command" (خطورة منخفضة). هذا متوقع - الحزمة تكتشف الأدوات الآلية. |
| الحزمة لا تحجب الطلبات أبدًا | يستمر تطبيقك في العمل بشكل طبيعي. الكشف سلبي. |
| لا حاجة لإعداد Slack | الإشعارات معطَّلة افتراضيًا. |
| لا حاجة لاتصال بالإنترنت | الكشف الأساسي محلي 100%. فقط أمر `threat-detection:enrich` الاختياري يستدعي واجهة برمجة تطبيقات خارجية لبيانات الموقع الجغرافي. |
### استكشاف الأخطاء وإصلاحها
**ابدأ من هنا — أمر واحد يجيب على معظم هذه الأمور:**
```bash
php artisan threat-detection:doctor
```
يتحقق من الأشياء التي تجعل الكشف يفشل *بصمت* — حيث تبقى لوحة المعلومات
فارغة، وهو ما يبدو مطابقًا لـ "لا هجمات" — ويطبع الإصلاح الدقيق
لكل منها. يخرج بقيمة غير صفرية عند حدوث فشل حقيقي، لذا من الآمن تشغيله في CI أو
خطوة النشر.
```
Threat Detection — health check
PASS Detection is enabled for this environment
FAIL 'threat_logs' is missing confidence_label — EVERY threat is being discarded
Run: php artisan vendor:publish --tag=threat-detection-migrations && php artisan migrate
WARN 1 custom pattern(s) shadow a built-in: Localhost SSRF
Your copy runs instead of the maintained one, so later fixes to it never reach you.
```
ما يغطيه: الكشف مُفعَّل لهذه البيئة؛ كل عمود يحتاجه الكاتب (عمود مفقود واحد يُلغي **كل** تهديد)؛ أعمدة لوحة المعلومات/API؛ جدول قواعد الاستبعاد؛ ما إذا كانت الوسيطة (middleware) موصولة فعليًا بمسار أو مجموعة؛ الإعدادات المنشورة التي تسبق هذا الإصدار؛ الأنماط المخصصة التي تحجب الأنماط المدمجة؛ برنامج تشغيل ذاكرة تخزين مؤقت لا يمكنه إجراء عدّ DDoS؛ ولوحة معلومات أو API متروكة مفتوحة دون مصادقة.
**"اختبرت لكن `threat-detection:stats` يُظهر صفر تهديدات" / "التهديدات لا تُخزَّن في قاعدة البيانات"**
إذا نجح الفحص، فالتثبيت سليم والمشكلة في طلب الاختبار نفسه. ثلاثة أمور لا يمكنه التحقق منها نيابةً عنك:
| الفحص | كيفية التحقق |
|-------|---------------|
| عنوان IP ليس في القائمة البيضاء | إذا أضفت `THREAT_DETECTION_WHITELISTED_IPS` إلى `.env`، فأزله أثناء الاختبار |
| استُخدم مسار موجود | يجب أن يطابق عنوان URL للاختبار مسارًا حقيقيًا (مثل `/`). رمز 404 يعني أن الوسيطة لم تُنفَّذ أبدًا |
| ذاكرة التخزين المؤقت لإزالة التكرار | نفس عنوان IP + نفس نوع الهجوم يُخزَّن مؤقتًا لمدة 5 دقائق - جرّب نوع هجوم مختلف |
> تشغيل `php artisan migrate` وحده لا يكفي أبدًا: ملفات الترحيل (migration) موجودة
> داخل الحزمة ويجب نشرها إلى `database/migrations/` في تطبيقك
> أولًا. يطبع الفحص الأمر الدقيق عندما تكون هذه هي المشكلة.
**"API يُرجع 401 Unauthorized"**
راجع [مصادقة API](#api-authentication) أدناه.
**"لوحة المعلومات تُظهر 404"**
لوحة المعلومات معطَّلة افتراضيًا. أضف `THREAT_DETECTION_DASHBOARD=true` إلى `.env` وامسح ذاكرة التخزين المؤقت للمسارات:
```bash
php artisan route:clear
```
---
## الميزات
- **أكثر من 150 نمط كشف** - حقن SQL (UNION، DDL، DML، عمليات الملفات)، XSS (script، SVG، تعبير CSS)، RCE، اجتياز المسار، SSRF، XXE، Log4Shell، حقن NoSQL، حقن الأوامر (Linux + Windows)، حقن LDAP، حقن XPath، SSTI، حقن CRLF، إلغاء تسلسل Java، والمزيد
- **83 توقيع بوت/ماسح ضوئي** - SQLMap، Nikto، Nmap، Burp Suite، FeroxBuster، FFUF، XSStrike، Dalfox، Netsparker، وأكثر من 70 توقيع ماسح ضوئي وبوت آخر
- **كشف أدوات كشط الذكاء الاصطناعي** - GPTBot، ClaudeBot، ByteSpider، Common Crawl، وبوتات تدريب الذكاء الاصطناعي الأخرى
- **كشف المتصفحات بدون واجهة** - HeadlessChrome، PhantomJS، Selenium، Puppeteer، Playwright
- **تتبع فحوصات 404** - يكتشف فحوصات الاستطلاع التي تستهدف مسارات ضعيفة معروفة (`/wp-admin`، `/.env`، `/phpmyadmin`، `/actuator`، إلخ) مع أكثر من 50 مسار فحص افتراضي، بالإضافة إلى [حزمة البنية التحتية للذكاء الاصطناعي](#ai-infrastructure-probes-opt-in) الاختيارية لبوابات LLM المكشوفة
- **مراقبة DDoS** - كشف قائم على العتبة المعدلية مع نوافذ زمنية قابلة للتكوين
- **تقييم الثقة** - كل تهديد يحصل على درجة ثقة من 0 إلى 100 بناءً على عدد الأنماط والسياق والإشارات
- **مقاومة التهرب** - خط أنابيب التطبيع يتغلب على إدراج تعليقات SQL، والترميز المزدوج لـ URL، وترميز كيانات HTML، وتهريبات Unicode، وتهريبات hex، وترميز IIS `%uXXXX` قبل مطابقة الأنماط — يتكرر حتى يتوقف الحمولة عن التغير، لذا فإن تكديس تقنيتين لا يتجاوزه
- **كشف CVE** - Shellshock (CVE-2014-6271)، Spring4Shell (CVE-2022-22965)، PHPUnit RCE (CVE-2017-9841)، Drupalgeddon، Log4Shell
- **كشف واعٍ بالسياق** - الأنماط الموجودة في سلاسل الاستعلام تحصل على درجات أعلى من تلك الموجودة في جسم الطلب
- **فحص جسم الطلب** - يتم فحص أجسام الطلبات المشفرة بالنماذج و JSON (`application/json`) على حد سواء
- **الحقول الآمنة** - استبعاد حقول نموذج محددة من الفحص (لمحرري CMS، ومدخلات الكود، وحقول البحث)
- **الإبلاغ عن الإيجابيات الكاذبة** - وضع علامة على التهديدات كإيجابيات كاذبة من لوحة التحكم؛ ينشئ قواعد استبعاد تلقائيًا
- **ثلاثة أوضاع كشف** - `strict`، `balanced` (افتراضي)، و `relaxed` - حساسية قابلة للضبط
- **كبت مسارات المحتوى** - إدراج مسارات CMS/المدونة في القائمة البيضاء لكبت التنبيهات المنخفضة/المتوسطة من المحتوى الغني
- **كشف PII** - أنماط كشف البيانات الحساسة (قابلة للتكوين حسب المنطقة)
- **إثراء جغرافي** - تحديد الدولة والمدينة ومزود الخدمة ومزود السحابة عبر API مجاني
- **تنبيهات Slack** - إشعارات فورية للتهديدات عالية الخطورة (تعمل على Laravel 10 و 11+)
- **لوحة تحكم مدمجة** - لوحة تحكم Blade بالوضع الداكن (Alpine.js و Tailwind، الأنماط مُجمّعة مسبقًا، بدون خطوة بناء)
- **حارس مصادقة لوحة التحكم** - مصادقة قابلة للتكوين للوحة التحكم و API (none، auth، role، أو قائمة على IP)
- **15 نقطة نهاية API** - واجهة REST API كاملة لبناء لوحات تحكم مخصصة بـ Vue/React/الجوال
- **تصدير Fail2ban** - تصدير عناوين IP المكتشفة بتنسيق متوافق مع fail2ban أو قائمة حظر عادية
- **تصدير قائمة الحظر** - تصدير عناوين IP بتنسيق nginx deny، أو Apache deny، أو CSV، أو نص عادي
- **تصدير CSV** - تصدير سجل التهديدات بنقرة واحدة (حتى 10,000 صف)
- **تحليل الارتباط** - كشف الهجمات المنسقة وحملات الهجوم عبر عناوين IP
- **محسّن للأداء** - تحميل الأنماط البطيء القائم على الفئات (يشغّل regex فقط لفئات الهجوم ذات الصلة)، والخروج المبكر للطلبات النظيفة، والاختصار السريع لـ UA المتصفح (يتخطى أكثر من 70 فحصًا للمتصفحات العادية)، والبحث بتجزئة مسار الفحص، وإدراجات DB الدفعية، والحد الأقصى القابل للتكوين للكشف لكل طلب
- **مستقل عن قاعدة البيانات** - MySQL، PostgreSQL، SQLite، SQL Server
- **بدون تكوين** - يعمل خارج الصندوق بإعدادات افتراضية معقولة
---
[Read more](https://github.com/jay123anta/laravel-threat-detection)