Latest Version Tests Total Downloads PHP Version License

Laravel Threat Detection

लारवेल के लिए निष्क्रिय घुसपैठ पहचान — हर SQL इंजेक्शन, XSS, स्कैनर और बॉट प्रोब देखें जो आपके ऐप पर हिट कर रहे हैं, पूरे संदर्भ के साथ लॉग किया हुआ। यह एक IDS है, WAF नहीं: यह कभी भी किसी अनुरोध को ब्लॉक, फ़िल्टर या संशोधित नहीं करता।

Threat Detection Dashboard — stats, 7-day timeline, live threat log, top offending IPs, and threats by country

इसे किसी भी Laravel 10–13 ऐप में डालें और यह हर HTTP अनुरोध को 150+ आक्रमण पैटर्न के विरुद्ध स्कैन करना शुरू कर देता है, प्रत्येक मैच को विश्वास के आधार पर स्कोर करता है और उसे आपके डेटाबेस में लिखता है — एक अंतर्निहित डैशबोर्ड, Slack अलर्ट, geo-enrichment, और fail2ban/blocklist निर्यात के साथ। किसी भी अनुरोध को कभी ब्लॉक नहीं किया जाता। इसे सुरक्षा कैमरा समझें, ताला नहीं: यह आपको ठीक-ठीक दिखाता है कि कौन आपके रूट्स की जाँच कर रहा है, कितनी बार, और किन तकनीकों से।

एक प्रोडक्शन ऐप से निकाला गया और वास्तविक ट्रैफ़िक पर आज़माया गया। 335 परीक्षण, Laravel के अलावा कोई रनटाइम निर्भरताएँ नहीं, और पहचान के लिए इंटरनेट कनेक्शन की आवश्यकता नहीं।

एक मिनट में शुरू करें```bash

composer require jayanta/laravel-threat-detection php artisan vendor:publish --tag=threat-detection-migrations php artisan migrate

फिर अपने `web` ग्रुप में मिडलवेयर जोड़ें (Laravel 11+ पर `bootstrap/app.php` में एक पंक्ति, या Laravel 10 पर `app/Http/Kernel.php` में) — पूरा स्निपेट नीचे [Quick Start](#quick-start) में है। बस इतना ही; डिटेक्शन लाइव है।```bash
php artisan threat-detection:doctor   # confirms it is actually recording

यह कहाँ फिट बैठता है: IDS बनाम WAF बनाम edge

यह पैकेज एक निष्क्रिय, एप्लिकेशन-स्तरीय IDS है — यह देखता और रिकॉर्ड करता है, अवरोधित नहीं करता। इसे किसी WAF या edge सेवा के बगल में बैठने के लिए बनाया गया है, न कि उसे बदलने के लिए। हर परत कुछ ऐसा देखती है जो दूसरी नहीं देख सकती:

संक्षेप में: edge/WAF आपके दरवाज़े का ताला है; यह अंदर लगा सुरक्षा कैमरा है, जिसमें ऐप संदर्भ आपको बताता है कि किस रूट पर, किसके द्वारा, और कितनी बार क्या प्रयास किया जा रहा है। इसका उपयोग वास्तविक निर्णय लेने के लिए करें — fail2ban प्रतिबंध, दर सीमाएँ, जियो-ब्लॉकिंग — उस डेटा के साथ जो आपकी edge परत कभी नहीं देखती।

यह जानबूझकर क्या नहीं है

WAF नहीं। यह कभी किसी अनुरोध को अवरोधित, फ़िल्टर या संशोधित नहीं करता। प्रवर्तन के लिए Cloudflare, mod_security, या असली WAF का उपयोग करें। (सौंपने के लिए कोई edge परत नहीं है? ऑपरेटर-साइड सहायक पैकेज के निर्णयों को उजागर करते हैं ताकि आप अपना खुद का पाँच-पंक्ति वाला ब्लॉकिंग मिडलवेयर लिख सकें — प्रवर्तन कोड आपका ही रहता है, पैकेज का नहीं।)
सुरक्षित कोडिंग का विकल्प नहीं। पैरामीटराइज़्ड क्वेरी, इनपुट सत्यापन, और आउटपुट एस्केपिंग आपकी वास्तविक सुरक्षा हैं। यह पैकेज मानता है कि आपका कोड पहले से सुरक्षित है और आपको दृश्यता देता है, सुरक्षा नहीं।
Edge सेवा नहीं। यदि आप Cloudflare को आगे रख सकते हैं, तो रखें — फिर उन एप्लिकेशन-स्तरीय विवरणों के लिए इसे जोड़ें जिन्हें edge सेवाएँ नहीं देख सकतीं।

तो आप वास्तव में इसके साथ क्या करते हैं?

सबसे आम सवाल एक डिटेक्टर के बारे में जो कभी ब्लॉक नहीं करता। चार उत्तर, प्रयास के बढ़ते क्रम में:

पैकेज बुद्धिमत्ता प्रदान करता है; आप अस्वीकृति प्रदान करते हैं। यह विभाजन जानबूझकर है — आपके ऐप में रहने वाला प्रवर्तन कोड वह कोड है जिसे आप पढ़ सकते हैं, परीक्षण कर सकते हैं और बंद कर सकते हैं, और इसका मतलब है कि एक डिटेक्शन बग कभी भी आपकी साइट को डाउन नहीं कर सकता।

आवश्यकताएँ

PHP 8.2+ (Laravel 13 के लिए PHP 8.3+ आवश्यक है)
Laravel 10.x, 11.x, 12.x, या 13.x
Laravel द्वारा समर्थित कोई भी डेटाबेस (MySQL, PostgreSQL, SQLite, SQL Server)
कोई भी कैश ड्राइवर - कोई Redis या queue worker आवश्यक नहीं. Redis/Memcached केवल वैकल्पिक DDoS जाँच को सक्षम करने के लिए अनुशंसित है (जो गैर-परमाणु ड्राइवरों पर स्वतः अक्षम हो जाती है)। क्यू में डाले गए राइट ऑप्ट-इन हैं और डिफ़ॉल्ट रूप से बंद हैं।

यह कैसे काम करता है

एक मिडलवेयर हर आने वाले HTTP अनुरोध को स्कैन करता है
अनुरोध को 158 regex पैटर्न के विरुद्ध जाँचा जाता है जिसमें SQL injection, XSS, RCE, file traversal, SSRF, LDAP, XPath, SSTI, और अधिक शामिल हैं
यदि कोई खतरा पैटर्न मेल खाता है, तो IP, URL, खतरा प्रकार, गंभीरता स्तर और एक कॉन्फिडेंस स्कोर के साथ आपकी threat_logs डेटाबेस तालिका में एक रिकॉर्ड लिखा जाता है
वैकल्पिक रूप से, उच्च-गंभीरता वाले खतरों के लिए एक Slack अलर्ट भेजा जाता है
अनुरोध सामान्य रूप से आगे बढ़ता है - कुछ भी अवरोधित नहीं होता

जाँच के लिए किसी इंटरनेट कनेक्शन की आवश्यकता नहीं है।

त्वरित आरंभ

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

Look for `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

The package works with sensible defaults. Publishing the config lets you customize detection patterns, sensitivity modes, Slack notifications, and more. If you skip this step, everything still works.

That's it. Your app is now detecting threats.

Verify It Works

After installation, trigger a test threat and confirm it was logged.

Step 1: Start your app```bash

php artisan serve

### चरण 2: अपने ब्राउज़र में एक परीक्षण URL खोलें

अपने ऐप में **किसी भी मौजूदा रूट** (आपका होमपेज, एक प्रोडक्ट पेज, आदि) में एक दुर्भावनापूर्ण क्वेरी पैरामीटर जोड़ें। उदाहरण के लिए:

**SQL इंजेक्शन:**```
http://localhost:8000/?q=' UNION SELECT * FROM users--

XSS (क्रॉस-साइट स्क्रिप्टिंग):``` http://localhost:8000/?q=

**डायरेक्टरी ट्रैवर्सल:**```
http://localhost:8000/?file=../../etc/passwd

RCE (रिमोट कोड निष्पादन):``` http://localhost:8000/?cmd=system('ls -la')

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

विंडोज़ कमांड इंजेक्शन:``` http://localhost:8000/?cmd=powershell -c whoami

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

अपने ऐप में वास्तव में मौजूद रूट का उपयोग करें (जैसे /)। यदि URL 404 लौटाता है, तो मिडलवेयर शायद नहीं चला होगा।

चरण 3: जांचें कि खतरे लॉग किए गए थे

विकल्प A - Artisan कमांड (सबसे तेज़):```bash php artisan threat-detection:stats

आपको `Total Threats`, गंभीरता गणना और शीर्ष IPs वाली एक तालिका दिखनी चाहिए।

**विकल्प B -  Tinker:**```bash
php artisan tinker

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%]

### Things to know when testing

| Behavior | Explanation |
|----------|-------------|
| समान खतरा प्रति 5 मिनट में केवल एक बार लॉग होता है | डीडुप्लीकेशन: समान IP + समान खतरा प्रकार 5 मिनट के लिए कैश किया जाता है। प्रत्येक परीक्षण के लिए **विभिन्न हमले प्रकार** उपयोग करें, या परीक्षणों के बीच प्रतीक्षा करें। |
| `curl` अनुरोध अतिरिक्त पहचान को ट्रिगर करते हैं | `curl` का उपयोग करने से "cURL Command" उपयोगकर्ता-एजेंट का पता (कम गंभीरता) भी लॉग होता है। यह अपेक्षित है - पैकेज स्वचालित उपकरणों का पता लगाता है। |
| पैकेज कभी भी अनुरोधों को ब्लॉक नहीं करता | आपका ऐप सामान्य रूप से कार्य करता रहता है। पहचान निष्क्रिय है। |
| कोई Slack सेटअप आवश्यक नहीं | सूचनाएँ डिफ़ॉल्ट रूप से बंद हैं। |
| कोई इंटरनेट कनेक्शन आवश्यक नहीं | कोर पहचान 100% स्थानीय है। केवल वैकल्पिक `threat-detection:enrich` कमांड भू-डेटा के लिए बाहरी API को कॉल करता है। |

### समस्या निवारण

**यहाँ से शुरू करें — एक कमांड इसका अधिकांश उत्तर देता है:**```bash
php artisan threat-detection:doctor

यह उन चीज़ों की जाँच करता है जो डिटेक्शन को चुपचाप विफल कराती हैं — जहाँ डैशबोर्ड खाली रहता है, जो "कोई हमला नहीं" जैसा दिखता है — और प्रत्येक के लिए सटीक समाधान प्रिंट करता है। यह वास्तविक विफलता पर non-zero exit code देता है, इसलिए इसे 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 कॉलम; बहिष्करण-नियम तालिका; क्या मिडलवेयर वास्तव में किसी रूट या समूह से जुड़ा है; इस संस्करण से पहले प्रकाशित कॉन्फ़िगरेशन; बिल्ट-इन पैटर्न को छायांकित करने वाले कस्टम पैटर्न; एक कैश ड्राइवर जो DDoS गिनती नहीं कर सकता; और बिना प्रमाणीकरण के खुला छोड़ा गया डैशबोर्ड या API।

**"मैंने परीक्षण किया लेकिन `threat-detection:stats` शून्य खतरे दिखाता है" / "खतरे डेटाबेस में संग्रहीत नहीं होते"**

यदि डॉक्टर पास हो गया, तो इंस्टॉल सही है और समस्या स्वयं परीक्षण अनुरोध में है। यह आपके लिए तीन चीज़ें जाँच नहीं सकता:

| जाँच | सत्यापन कैसे करें |
|-------|---------------|
| IP व्हाइटलिस्टेड नहीं है | यदि आपने `.env` में `THREAT_DETECTION_WHITELISTED_IPS` जोड़ा है, तो परीक्षण के दौरान इसे हटा दें |
| मौजूदा रूट का उपयोग किया | परीक्षण URL एक वास्तविक रूट से मेल खाना चाहिए (जैसे, `/`). 404 का मतलब है कि मिडलवेयर कभी चला ही नहीं |
| डेडुप कैश | समान IP + समान अटैक प्रकार 5 मिनट के लिए कैश होता है -  कोई अलग अटैक प्रकार आज़माएँ |

> केवल `php artisan migrate` चलाना कभी पर्याप्त नहीं होता: माइग्रेशन फ़ाइलें पैकेज के अंदर होती हैं और पहले आपके ऐप की `database/migrations/` में प्रकाशित की जानी चाहिए। जब यह समस्या हो, तो डॉक्टर सटीक कमांड प्रिंट करता है।

**"API 401 Unauthorized लौटाता है"**

नीचे [API प्रमाणीकरण](#api-authentication) देखें।

**"Dashboard 404 दिखाता है"**

डैशबोर्ड डिफ़ॉल्ट रूप से अक्षम है। `.env` में `THREAT_DETECTION_DASHBOARD=true` जोड़ें और रूट कैश साफ़ करें:```bash
php artisan route:clear

Features

150+ डिटेक्शन पैटर्न - SQL injection (UNION, DDL, DML, file ops), XSS (script, SVG, CSS expression), RCE, directory traversal, SSRF, XXE, Log4Shell, NoSQL injection, command injection (Linux + Windows), LDAP injection, XPath injection, SSTI, CRLF injection, Java deserialization, और भी
83 बॉट/स्कैनर सिग्नेचर - SQLMap, Nikto, Nmap, Burp Suite, FeroxBuster, FFUF, XSStrike, Dalfox, Netsparker, और 70+ अन्य स्कैनर और बॉट सिग्नेचर
AI स्क्रैपर डिटेक्शन - GPTBot, ClaudeBot, ByteSpider, Common Crawl, और अन्य AI ट्रेनिंग बॉट्स
हेडलेस ब्राउज़र डिटेक्शन - HeadlessChrome, PhantomJS, Selenium, Puppeteer, Playwright
404 प्रोब ट्रैकिंग - ज्ञात कमजोर पथों (/wp-admin, /.env, /phpmyadmin, /actuator, आदि) को निशाना बनाने वाले रिकॉनिसांस प्रोब का पता लगाता है, 50+ डिफ़ॉल्ट प्रोब पथों के साथ
DDoS मॉनिटरिंग - कॉन्फ़िगर करने योग्य विंडो के साथ दर-आधारित थ्रेशोल्ड डिटेक्शन
कॉन्फिडेंस स्कोरिंग - पैटर्न गिनती, संदर्भ और सिग्नल के आधार पर प्रत्येक खतरे को 0-100 कॉन्फिडेंस स्कोर मिलता है
एवेज़न प्रतिरोध - पैटर्न मिलान से पहले SQL टिप्पणी सम्मिलन, डबल URL एन्कोडिंग, HTML एंटिटी एन्कोडिंग, यूनिकोड एस्केप और हेक्स एस्केप को नॉर्मलाइज़ेशन पाइपलाइन विफल करती है
CVE डिटेक्शन - Shellshock (CVE-2014-6271), Spring4Shell (CVE-2022-22965), PHPUnit RCE (CVE-2017-9841), Drupalgeddon, Log4Shell
कॉन्टेक्स्ट-अवेयर डिटेक्शन - क्वेरी स्ट्रिंग में मिले पैटर्न रिक्वेस्ट बॉडी में मिले पैटर्न से अधिक स्कोर करते हैं
रिक्वेस्ट बॉडी स्कैनिंग - फ़ॉर्म-एन्कोडेड और JSON (application/json) दोनों रिक्वेस्ट बॉडी की जाँच की जाती है
सुरक्षित फ़ील्ड - स्कैनिंग से विशिष्ट फ़ॉर्म फ़ील्ड को बाहर करें (CMS एडिटर, कोड इनपुट, सर्च फ़ील्ड के लिए)

कॉन्फ़िगरेशन

पैकेज बिना किसी .env बदलाव के काम करता है। नीचे दिए गए सभी मान वैकल्पिक हैं - उन्हें केवल तब जोड़ें जब आप डिफ़ॉल्ट ओवरराइड करना चाहें।```env

Enable/disable detection globally (default: true)

THREAT_DETECTION_ENABLED=true

Detection sensitivity (default: balanced)

Options: strict, balanced, relaxed

THREAT_DETECTION_MODE=balanced

Custom table name (default: threat_logs)

THREAT_DETECTION_TABLE=threat_logs

Whitelist IPs to skip detection entirely (default: empty)

Supports CIDR notation. Comma-separated.

THREAT_DETECTION_WHITELISTED_IPS=10.0.0.0/8,192.168.1.0/24

Static operator denylist read by ThreatDetection::isBlocklisted() (default: empty)

The package itself never blocks — see "Acting on the Data" for the

enforcement recipe. Supports CIDR. Whitelist wins on overlap.

THREAT_DETECTION_BLOCKLISTED_IPS=203.0.113.0/24,198.51.100.7

DDoS detection thresholds (defaults shown)

THREAT_DETECTION_DDOS_THRESHOLD=300

THREAT_DETECTION_DDOS_WINDOW=60

Minimum confidence score to log a threat (default: 0)

Threats below this score are silently ignored.

THREAT_DETECTION_MIN_CONFIDENCE=0

Slack notifications (disabled by default)

THREAT_DETECTION_NOTIFICATIONS=true

THREAT_DETECTION_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

THREAT_DETECTION_SLACK_CHANNEL=#threat-alerts

Dashboard (disabled by default)

THREAT_DETECTION_DASHBOARD=true

API endpoints (enabled by default)

THREAT_DETECTION_API=true

API rate limiting (default: 60 requests per minute)

THREAT_DETECTION_API_THROTTLE=60,1

Queue support - offload DB writes to a queue (disabled by default).

OPTIONAL: only enable if your app already runs a queue worker. When false

(default), threats are written synchronously with a plain DB insert - no

Redis, no worker, nothing extra to run.

THREAT_DETECTION_QUEUE=false

THREAT_DETECTION_QUEUE_CONNECTION=redis

THREAT_DETECTION_QUEUE_NAME=default

Auto-purge old logs (disabled by default)

Requires Laravel scheduler to be running.

THREAT_DETECTION_RETENTION=false

THREAT_DETECTION_RETENTION_DAYS=90

404 probe tracking (enabled by default)

Detects bots hitting /wp-admin, /.env, /phpmyadmin, etc.

THREAT_DETECTION_PROBE_TRACKING=true

Max detections per request (default: 0 = unlimited)

Stop scanning after N pattern matches per request.

THREAT_DETECTION_MAX_DETECTIONS=0

Dashboard auth guard (default: none)

Options: none, auth, role, ip

THREAT_DETECTION_DASHBOARD_GUARD=none

THREAT_DETECTION_DASHBOARD_ROLE=admin

THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1

API auth guard (default: none - uses existing middleware config)

THREAT_DETECTION_API_GUARD=none

### पहचान मोड

| मोड | विश्वास सीमा | व्यवहार |
|------|---------------------|----------|
| `strict` | 0 (सब कुछ लॉग करता है) | सभी पैटर्न सक्रिय, न्यूनतम सीमाएँ। सब कुछ पकड़ता है लेकिन वैध ट्रैफ़िक को भी फ़्लैग कर सकता है। |
| `balanced` | 10 | डिफ़ॉल्ट। विश्वास स्कोरिंग सक्रिय, मानक सीमाएँ। अधिकांश ऐप्स के लिए अच्छा। |
| `relaxed` | 40 | केवल उच्च-गंभीरता वाले पैटर्न ट्रिगर होते हैं। बार-बार गलत सकारात्मक परिणाम वाली सामग्री-भारी साइटों के लिए सर्वोत्तम। |

### सक्षम वातावरण

डिफ़ॉल्ट रूप से, पहचान `production`, `staging`, और `local` में चलती है। बदलने के लिए, कॉन्फ़िग प्रकाशित करें और संपादित करें:```php
'enabled_environments' => ['production', 'staging', 'local'],

अपने टेस्ट सूट में डिटेक्शन अक्षम करने के लिए, APP_ENV=testing सेट करें (ऊपर दी गई सूची में नहीं) या अपने phpunit.xml में जोड़ें:```xml

### कॉन्फ़िग संदर्भ

सभी उपलब्ध विकल्प देखने के लिए कॉन्फ़िग फ़ाइल प्रकाशित करें:```bash
php artisan vendor:publish --tag=threat-detection-config

मुख्य कॉन्फ़िग अनुभाग: skip_paths (स्किप करने के पथ), only_paths (व्हाइटलिस्ट मोड), auth_paths (लॉगिन रूट्स के लिए स्मार्ट डिटेक्शन), content_paths (गैर-हाई अलर्ट दबाएँ), safe_fields (स्कैनिंग से विशिष्ट फ़ील्ड बाहर करें), safe_paths (नेस्टेड JSON के लिए पाथ-अवेयर फ़ील्ड बहिष्करण), probe_tracking (404 प्रोब डिटेक्शन), context_weights (स्कोरिंग गुणक), threat_levels (गंभीरता कीवर्ड मैपिंग), api_route_filtering (API रूट्स पर लो/मीडियम दबाएँ), queue (एसिंक प्रोसेसिंग), retention (ऑटो-पर्ज), max_detections_per_request (प्रदर्शन कैप), dashboard.guard / (ऑथ मोड).

रूट व्हाइटलिस्टिंग (`only_paths`)

अगर आपके ऐप में कई रूट हैं लेकिन आपको केवल कुछ ही चाहिए, तो only_paths का उपयोग करके केवल उन्हीं रूट्स को स्कैन करें। बाकी सभी रूट्स स्वचालित रूप से स्किप हो जाते हैं - कोई मिडलवेयर ओवरहेड नहीं।```php // config/threat-detection.php 'only_paths' => [ 'admin/', 'api/', 'login', 'register', ],

### कतार समर्थन

डिफ़ॉल्ट रूप से, खतरे की लॉगिंग अनुरोध चक्र में सिंक्रोनस रूप से होती है। उच्च-ट्रैफ़िक ऐप्स के लिए, आप DB लेखन और Slack सूचनाओं को कतार में स्थानांतरित कर सकते हैं:

खाली छोड़ें (डिफ़ॉल्ट) सभी रूट्स स्कैन करने के लिए (`skip_paths` के अधीन)। जब दोनों कॉन्फ़िगर किए जाते हैं, तो पहले `only_paths` की जाँच की जाती है, फिर मिलान किए गए सेट के भीतर `skip_paths` लागू होता है।```env
THREAT_DETECTION_QUEUE=true
THREAT_DETECTION_QUEUE_CONNECTION=redis
THREAT_DETECTION_QUEUE_NAME=threat-logs

यह एक StoreThreatLog जॉब भेजता है (3 रिट्राइज़, बैकऑफ़ 10s/30s)। डिटेक्शन अभी भी रीयल-टाइम में होता है - केवल राइट को विलंबित किया जाता है।

ऑटो-पर्ज (धारण नीति)

पुराने थ्रेट लॉग्स को दैनिक शेड्यूल पर स्वचालित रूप से हटाएँ:```env THREAT_DETECTION_RETENTION=true THREAT_DETECTION_RETENTION_DAYS=90

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,
    ],
];

The event carries $threatLog (पूर्ण DB पंक्ति सरणी), $ipAddress, और $threatLevel. इसका उपयोग कस्टम क्रियाएँ ट्रिगर करने के लिए करें - Telegram अलर्ट भेजें, ब्लॉकलिस्ट अपडेट करें, SIEM को फ़ीड करें, आदि।

DdosThresholdExceeded ईवेंट

जब कोई क्लाइंट कॉन्फ़िगर किए गए DDoS थ्रेशोल्ड (ddos.threshold अनुरोध ddos.window सेकंड के भीतर) को पार करता है, तो एक DdosThresholdExceeded ईवेंट थ्रेट लॉग प्रविष्टि के साथ भेजा जाता है:```php use JayAnta\ThreatDetection\Events\DdosThresholdExceeded;

protected $listen = [ DdosThresholdExceeded::class => [ YourFloodListener::class, ], ];

यह इवेंट `$ipAddress`, `$requestCount`, `$threshold`, और `$windowSeconds` लेकर आता है। इसे प्रति IP प्रति डीडुप विंडो में एक बार थ्रॉटल किया जाता है (लॉग रो की तरह ही थ्रॉटल), ताकि फ्लड आपके लिसनर्स को न डुबो दे। इसका उपयोग अलर्टिंग के लिए या किसी बाहरी बैन स्टोर को फीड करने के लिए करें; *अस्वीकार* करने के लिए
ओवर-थ्रेशोल्ड क्लाइंट्स को, अपने स्वयं के मिडलवेयर से `ThreatDetection::isDdosThresholdExceeded($ip)` का उपयोग करें — देखें [Acting on the Data](#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

डिफ़ॉल्ट रूप से केवल उच्च-गंभीरता वाले खतरे सूचनाएँ ट्रिगर करते हैं (config में notify_levels के माध्यम से कॉन्फ़िगर किया जा सकता है)।

Laravel 10: अंतर्निहित SlackMessage सूचना क्लास का उपयोग करता है। किसी अतिरिक्त पैकेज की आवश्यकता नहीं है।

Laravel 11+: अंतर्निहित Slack चैनल हटा दिया गया था। पैकेज इसे स्वचालित रूप से पहचानता है और आपके Slack URL पर raw HTTP POST webhooks भेजता है। किसी अतिरिक्त पैकेज की आवश्यकता नहीं है। यदि आप पूर्ण सूचना चैनल पसंद करते हैं, तो इंस्टॉल करें:```bash composer require laravel/slack-notification-channel

---

## डैशबोर्ड

पैकेज में एक अंतर्निहित डार्क-मोड डैशबोर्ड शामिल है (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                                         |
+-------------------------------------------------------------------------+

डैशबोर्ड सक्षम करें

.env में जोड़ें:```env THREAT_DETECTION_DASHBOARD=true

विज़िट करें: `http://your-app.test/threat-detection`

### स्थानीय विकास के दौरान प्रवेश करना

डैशबोर्ड डिफ़ॉल्ट रूप से `['web', 'auth']` मिडलवेयर का उपयोग करता है, इसलिए उपयोगकर्ताओं को लॉग इन होना चाहिए। यदि आपके ऐप में अभी तक कोई प्रमाणीकरण नहीं है, तो इसे केवल अपनी मशीन तक सीमित रखें:```env
THREAT_DETECTION_DASHBOARD_GUARD=ip
THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1

सभी गार्ड विकल्प, और एंडपॉइंट्स पर अलग गार्ड जो डिटेक्शन को अक्षम करता है, डैशबोर्ड और API प्रमाणीकरण में शामिल हैं।

यदि डैशबोर्ड खाली डेटा दिखाता है, तो पेज लोड हो गया लेकिन उसके API कॉल नहीं हुए। API प्रमाणीकरण देखें।

API एंडपॉइंट्स

पैकेज कस्टम डैशबोर्ड या एकीकरण बनाने के लिए 15 REST एंडपॉइंट्स प्रदान करता है।

API प्रमाणीकरण

API रूट्स डिफ़ॉल्ट रूप से auth:sanctum मिडलवेयर का उपयोग करते हैं। पैकेज इसे सुचारू रूप से संभालता है:

Sanctum स्थापित: API को Sanctum टोकन या SPA सत्र प्रमाणीकरण के माध्यम से प्रमाणीकरण की आवश्यकता होती है।
Sanctum स्थापित नहीं: पैकेज स्वचालित रूप से पता लगाता है कि Sanctum अनुपस्थित है और केवल ['api'] पर वापस आ जाता है। API बिना प्रमाणीकरण के काम करता है।

यदि आप Sanctum का उपयोग नहीं करते हैं लेकिन अपने API को सुरक्षित रखना चाहते हैं, तो आपके पास दो विकल्प हैं:

विकल्प 1 - अंतर्निहित auth गार्ड का उपयोग करें:```env THREAT_DETECTION_API_GUARD=auth

**विकल्प 2 -  middleware को सीधे बदलें:**```php
// config/threat-detection.php
'api' => [
    'enabled' => true,
    'prefix' => 'api/threat-detection',
    'middleware' => ['api', 'auth'],  // or 'auth:your-guard'
],

स्थानीय परीक्षण के लिए (यदि Sanctum पहुँच को अवरुद्ध करता है), अस्थायी रूप से बदलें:```php 'middleware' => ['api'], // remove 'auth:sanctum'

> उत्पादन में तैनाती से पहले प्रमाणीकरण पुनर्स्थापित करें।

### एंडपॉइंट संदर्भ

| 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` | प्रकार, स्तर, आईपी द्वारा विस्तृत विश्लेषण |
| 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` | शीर्ष अपराधी आईपी |
| GET | `/api/threat-detection/timeline` | खतरे की समयरेखा (चार्ट के लिए) |
| GET | `/api/threat-detection/ip-stats?ip=x.x.x.x` | विशिष्ट आईपी के लिए आँकड़े |
| 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` | आईपी पते से फ़िल्टर करें |
| `level` | खतरे के स्तर से फ़िल्टर करें (`high`, `medium`, `low`) |
| `type` | खतरे के प्रकार से फ़िल्टर करें |
| `country` | देश कोड से फ़िल्टर करें |
| `is_foreign` | विदेशी आईपी फ़िल्टर करें (`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
  }
}

कस्टम फ्रंटएंड बनाना

Vue.js:```javascript async mounted() { const response = await fetch('/api/threat-detection/stats'); this.stats = await response.json();

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));
}, []);

यदि आपका API auth:sanctum का उपयोग करता है, तो प्रमाणीकरण हेडर शामिल करें या कुकी-आधारित अनुरोधों के लिए Sanctum SPA प्रमाणीकरण कॉन्फ़िगर करें।

Artisan कमांड्स```bash

Check that detection is installed, wired up and actually recording.

Exits non-zero on a real failure, so it works in CI or a deploy step.

php artisan threat-detection:doctor

View threat stats summary in the terminal

php artisan threat-detection:stats

Enrich existing logs with geo-data (country, city, ISP, cloud provider)

Uses the free ip-api.com service (rate-limited to 45 req/min, auto-throttled)

php artisan threat-detection:enrich --days=7

Purge old logs to keep the database clean

php artisan threat-detection:purge --days=30

Export threat IPs for fail2ban (pipe to file or run directly)

php artisan threat-detection:export-fail2ban --level=high --since=24h --min-hits=5 php artisan threat-detection:export-fail2ban --format=plain > /tmp/banlist.txt

Export blocklist in various formats

php artisan threat-detection:export-blocklist --format=nginx > /etc/nginx/blocklist.conf php artisan threat-detection:export-blocklist --format=apache > .htaccess-deny php artisan threat-detection:export-blocklist --format=csv --since=7d

## डेटा पर कार्रवाई (ऑपरेटर-पक्ष ब्लॉकिंग)

पैकेज कभी भी किसी अनुरोध को ब्लॉक नहीं करता — यही उसकी पहचान है, कोई डिफ़ॉल्ट नहीं। उपरोक्त एक्सपोर्ट्स उन प्रवर्तन परतों को फ़ीड करते हैं जिन्हें आप पहले से चलाते हैं (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);
    }
}

IP पर प्रवर्तन लागू करने से पहले, TrustProxies कॉन्फ़िगर करें।

ऊपर की सभी चीज़ें $request->ip() पर निर्भर करती हैं। लोड बैलेंसर, CDN या रिवर्स प्रॉक्सी के पीछे, यह केवल तभी क्लाइंट IP लौटाता है जब Laravel को बताया जाता है कि किन प्रॉक्सी पर भरोसा करना है। यदि ऐसा नहीं है, तो एक साथ दो चीज़ें टूट जाती हैं: हर अनुरोध प्रॉक्सी से आता हुआ प्रतीत होता है, इसलिए एक डेनीलिस्ट प्रविष्टि आपके सभी ट्रैफ़िक को ब्लॉक कर देती है या किसी को नहीं — और बुरी बात यह है कि यदि ऐप किसी ऐसे फॉरवर्डेड हेडर पर भरोसा करता है जिसे उसे नहीं करना चाहिए, तो एक हमलावर X-Forwarded-For सेट करता है और सीधे ब्लॉकलिस्ट को पार कर जाता है।

यहाँ यह whitelisted_ips की तुलना में अधिक महत्वपूर्ण है। एक गलत व्हाइटलिस्ट मैच केवल यह दर्शाता है कि पैकेज किसी ऐसे अनुरोध को स्कैन करता है जिसे उसने शायद छोड़ दिया होता: यह फेल-सेफ़ होता है। ट्रैफ़िक को अस्वीकार करने वाली डेनीलिस्ट ओपन फेल होती है — आप मानते हैं कि एक पता ब्लॉक है जबकि वह नहीं है। प्रवर्तन के लिए किसी भी हेल्पर पर भरोसा करने से पहले app/Http/Middleware/TrustProxies.php (या Laravel 11+ पर bootstrap/app.php में trustProxies कॉल) जाँचें।

इसे वैश्विक रूप से पंजीकृत करें (डिटेक्शन मिडलवेयर से पहले होना ठीक है — हेल्पर कॉन्फ़िग और कैश पढ़ते हैं, वे मिडलवेयर क्रम पर निर्भर नहीं होते):```php // bootstrap/app.php (Laravel 11+) ->withMiddleware(function ($middleware) { $middleware->prepend(\App\Http\Middleware\EnforceThreatDecisions::class); })

The helpers:

| Helper | Returns | Backed by |
|---|---|---|
| `ThreatDetection::isBlocklisted($ip)` | `bool` | `blocklisted_ips` कॉन्फ़िग (`IpUtils` के माध्यम से CIDR; व्हाइटलिस्ट जीतता है) |
| `ThreatDetection::isWhitelisted($ip)` | `bool` | `whitelisted_ips` कॉन्फ़िग |
| `ThreatDetection::ddosRequestCount($ip)` | `int` | फ्लड काउंटर जिसे डिटेक्शन मिडलवेयर बनाए रखता है |
| `ThreatDetection::isDdosThresholdExceeded($ip)` | `bool` | वह काउंटर बनाम `ddos.threshold` |

Notes:

- **डेनीलिस्ट स्थिर है और ऑपरेटर द्वारा अनुरक्षित है।** पैकेज में कुछ भी इसमें कभी नहीं जोड़ता — यह वही निर्णय निष्पादित करता है जो fail2ban जेल करता ("मैंने डैशबोर्ड पढ़ा; यह /24 शत्रुतापूर्ण है"), बस इन-ऐप।
- DDoS काउंटर केवल उन अनुरोधों को गिनता है जो डिटेक्शन तक पहुँचे (`skip_paths`, व्हाइटलिस्टेड IP, और अक्षम वातावरण कभी नहीं गिने जाते), और उन कैश ड्राइवरों पर 0 रहता है जहाँ DDoS डिटेक्शन अक्षम है (`file`, `database`, `null`)।
- जब कोई क्लाइंट सीमा पार करता है, तो एक [`DdosThresholdExceeded` event](#ddosthresholdexceeded-event) भी डिस्पैच किया जाता है — अलर्टिंग या बाहरी बैन सूची फीड करने के लिए उपयोगी। लिसनर से `abort()` न करें, हालाँकि: लिसनर डिटेक्शन मिडलवेयर के fail-open `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...
    ],
],

THREAT_DETECTION_PROBE_TRACKING=false से निष्क्रिय करें।

सुरक्षित फ़ील्ड्स (गलत सकारात्मकता में कमी)

यदि कुछ फ़ॉर्म फ़ील्ड्स में वैध रूप से HTML, SQL कीवर्ड या कोड होता है (जैसे CMS एडिटर, कोड स्निपेट इनपुट), तो आप उन्हें स्कैनिंग से बाहर कर सकते हैं:```php // config/threat-detection.php 'safe_fields' => ['content', 'body', 'html', 'description', 'code'],

Fields listed here are stripped from query params and the request body -  both form-encoded and JSON (`application/json`) -  before detection runs. Other fields on the same request are still fully scanned.

### Safe Paths (path-aware, for nested JSON APIs)

`safe_fields` नाम से किसी भी **स्थान** पर मौजूद कुंजी से मेल खाता है। नेस्टेड JSON APIs के लिए यह अक्सर बहुत व्यापक होता है — आप किसी एक विशेष फ़ील्ड के मान को छूट दे सकते हैं, बिना उस कुंजी को हर जगह छूट दिए। `safe_paths` का उपयोग करें, जो डॉट-नोटेशन **पथ** द्वारा मेल खाता है और `fnmatch` वाइल्डकार्ड का समर्थन करता है:```php
// config/threat-detection.php
'safe_paths' => ['search.query', 'filters.*.value'],

उदाहरण के लिए, search.query {"search": {"query": "..."}} के मान को छूट देता है (एक खोज बॉक्स जिसका टेक्स्ट वैध रूप से SELECT जैसे शब्द रखता है), जबकि अनुरोध में कहीं और एक query फ़ील्ड अभी भी स्कैन की जाती है। जो कुछ भी सूचीबद्ध नहीं है, उसे पहले की तरह ही स्कैन किया जाता है।

पोस्ट-मैच सत्यापक (चेकसम-जागरूक गलत-सकारात्मक न्यूनीकरण)```php

// config/threat-detection.php 'pattern_validators' => [ 'Aadhaar Number Detected' => 'verhoeff', // shipped default ],

उपलब्ध वैलिडेटर:

| Validator  | Checksum | Typical use |
|------------|----------|-------------|
| `verhoeff` | Verhoeff | आधार नंबर |
| `luhn`     | Luhn     | क्रेडिट/डेबिट कार्ड नंबर |

शामिल मैपिंग के साथ, टाइमस्टैम्प, ऑर्डर आईडी और बारकोड जो संयोग से 12 अंकों के होते हैं, अब PII के रूप में लॉग नहीं होते — जबकि असली आधार नंबर अभी भी होते हैं। यदि कई मान मेल खाते हैं और केवल एक ही चेकसम पास करता है, तो पहचान फिर भी सक्रिय होती है: शोर के बीच एक वास्तविक संख्या अभी भी लीक है।

चेकसम-गेटेड कार्ड पहचान के लिए अपने स्वयं के पैटर्न के साथ एक वैलिडेटर जोड़ें:```php
'custom_patterns'    => ['/\b(?:\d[ -]?){13,19}\b/' => 'Card Number Detected'],
'pattern_validators' => ['Card Number Detected' => 'luhn'],

एक अज्ञात वैलिडेटर नाम fails open होता है — मैच को बिना सत्यापित किए गिन लिया जाता है और एक चेतावनी एक बार लॉग होती है — इसलिए एक टाइपो कभी भी किसी डिटेक्शन पैटर्न को चुपचाप अक्षम नहीं कर सकता। इस फीचर से पहले प्रकाशित कॉन्फ़िग में यह कुंजी होती ही नहीं और वे अपना ठीक वैसा ही वर्तमान व्यवहार बनाए रखते हैं।

रिडक्शन (पता लगाना संग्रहीत करना नहीं है)

संवेदनशील डेटा का पता लगाने का मतलब पहले उसे संग्रहीत करना होता था। मोबाइल नंबर, PAN और बैंक खाता रखने वाला एक प्रोफ़ाइल फ़ॉर्म तीन PII पैटर्न को ट्रिगर कर देता, और लिखी गई तीनों पंक्तियों में से प्रत्येक पूरे रिक्वेस्ट बॉडी को शब्दशः रखती - पूरी अवधारण अवधि के लिए बनाए रखी जाती, और डैशबोर्ड या डेटाबेस एक्सेस रखने वाला कोई भी व्यक्ति उसे पढ़ सकता था। क्वेरी स्ट्रिंग में एक मान भी url कॉलम में चला जाता था। डिटेक्टर उसी चीज़ की दूसरी, संकेंद्रित प्रति बन जाता था, जिसके बारे में वह आपको चेतावनी देता है।

v1.7.0 से डिफ़ॉल्ट रूप से सक्रिय। जब किसी ऐसे पैटर्न के फायर होने पर जिसका लेबल सूचीबद्ध है, उसके द्वारा मेल किया गया मान संग्रहीत पेलोड और URL में मास्क कर दिया जाता है:``` BODY: {"name":"Jane Doe","mobile":"[REDACTED]","pan":"[REDACTED]","bank_account":"[REDACTED]"}

अलर्ट, एंडपॉइंट, फ़ील्ड नाम और हमला करने वाला IP सभी बचे रहते हैं - केवल मान हटाया जाता है। रिडक्शन *पता लगाने के बाद* चलता है, इसलिए कुछ भी नहीं छूटता।```php
// config/threat-detection.php
'redact' => [
    'enabled' => env('THREAT_DETECTION_REDACT', true),
    'mask'    => '[REDACTED]',
    'labels'  => ['Aadhaar Number Detected', 'PAN Number Detected', /* ... */],
],

Attack payloads को जानबूझकर अछूता छोड़ा जाता है - एक injection string साक्ष्य है, कोई रहस्य नहीं, और उसे mask करने से जांच नष्ट हो जाएगी। केवल आपके द्वारा सूचीबद्ध labels ही छुए जाते हैं।

यह Safe Fields का विकल्प नहीं है। वे किसी field को scanned होने से रोकते हैं; redaction आपको scanning जारी रखने और storing बंद करने देता है। अगर आपको forensics के लिए पूरे payloads की आवश्यकता है तो THREAT_DETECTION_REDACT=false सेट करें।

डैशबोर्ड और API प्रमाणीकरण

डैशबोर्ड और API .env के माध्यम से कॉन्फ़िगर करने योग्य auth guards का समर्थन करते हैं:```env

Options: none (default), auth, role, ip

THREAT_DETECTION_DASHBOARD_GUARD=auth

For role-based guard (Spatie compatible):

THREAT_DETECTION_DASHBOARD_GUARD=role THREAT_DETECTION_DASHBOARD_ROLE=admin

For IP-based guard:

THREAT_DETECTION_DASHBOARD_GUARD=ip THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1,10.0.0.0/8

API रूट्स के लिए भी वही विकल्प उपलब्ध हैं `THREAT_DETECTION_API_GUARD` के साथ।

जब `guard=none` (डिफ़ॉल्ट) होता है, तो पैकेज दिन में एक बार चेतावनी लॉग करता है ताकि आपको प्रमाणीकरण कॉन्फ़िगर करने की याद दिला सके।

गार्ड **fails closed** है: एक अपरिचित गार्ड मान (जैसे टाइपो) को मौन रूप से पहुँच देने के बजाय 403 और लॉग की गई चेतावनी के साथ अस्वीकार कर दिया जाता है, और `guard=role` तब अस्वीकार करता है (चेतावनी के साथ) जब प्रमाणित उपयोगकर्ता मॉडल में `hasRole()` विधि नहीं होती है।

### किसी डिटेक्शन को अक्षम करने के लिए केवल पढ़ने की पहुँच से अधिक की आवश्यकता होती है

किसी खतरे को false positive के रूप में चिह्नित करना और किसी बहिष्करण नियम को हटाना, दोनों ही सभी के लिए एक डिटेक्शन प्रकार को मौन कर देते हैं, जो लॉग पढ़ने से भिन्न विशेषाधिकार है। उन दो endpoints की जाँच एक अलग guard के विरुद्ध की जाती है:```env
# Options: none, auth, role, ip. Default: role
THREAT_DETECTION_API_WRITE_GUARD=role

यह केवल उन रूट्स पर लागू होता है, इसलिए रीडिंग और डैशबोर्ड बिल्कुल वैसा ही व्यवहार करते हैं जैसा THREAT_DETECTION_API_GUARD कहता है। इसके बिना, आपके एप्लिकेशन का कोई भी प्रमाणित उपयोगकर्ता किसी डिटेक्शन को बंद कर सकता है।

यदि आपके उपयोगकर्ता मॉडल में hasRole() नहीं है, तो =auth उपयोग करें। 1.7.0 से पहले के व्यवहार को बहाल करने के लिए, जहाँ कोई भी प्रमाणित उपयोगकर्ता डिटेक्शन अक्षम कर सकता था, =none उपयोग करें - threat-detection:doctor चेतावनी देगा जब तक कि वह सेट है।

डैशबोर्ड ↔ API नोट: बिल्ट-इन डैशबोर्ड अपना डेटा ब्राउज़र सेशन कुकी का उपयोग करके API रूट्स से प्राप्त करता है। यदि आपके API रूट्स auth:sanctum से सुरक्षित हैं, तो Sanctum stateful/SPA प्रमाणीकरण कॉन्फ़िगर करें (या डैशबोर्ड को कुकी-प्रमाणित गार्ड की ओर इंगित करें) ताकि वे AJAX कॉल अधिकृत हों - अन्यथा डैशबोर्ड खाली दिखता है।

कस्टम पैटर्न्स

अपने स्वयं के डिटेक्शन regex पैटर्न config/threat-detection.php में जोड़ें:```php 'custom_patterns' => [ '/your-regex-here/i' => 'Your Threat Label', ],

**उदाहरण -  कस्टम एडमिन एंडपॉइंट प्रोब का पता लगाएं:**```php
'/\/my-admin-panel/i' => 'Custom Admin Panel Probe',

ऐरे रूप (प्रति-पैटर्न विकल्प)

क्लासिक स्ट्रिंग रूप के साथ-साथ, पूर्ण नियंत्रण के लिए किसी पैटर्न का मान एक ऐरे हो सकता है:```php 'custom_patterns' => [ '/\b(?:\d[ -]?){13,19}\b/' => [ 'label' => 'Card Number Detected', // required 'level' => 'high', // low|medium|high — overrides keyword derivation 'contexts' => ['query', 'body'], // query|body|headers — default: all segments 'validator' => 'luhn', // post-match checksum, wins over pattern_validators ], ],

- **`level`** थ्रेट स्तर को सीधे सेट करता है, न कि लेबल में `threat_levels` कीवर्ड से व्युत्पन्न करता है।
- **`contexts`** स्कैनिंग को विशिष्ट अनुरोध खंडों तक सीमित करता है — जैसे एक कार्ड पैटर्न जो केवल बॉडी में मायने रखता है, हेडर में अंकों की श्रृंखलाओं से मेल खाना बंद कर देता है।
- **`validator`** एक इनलाइन पोस्ट-मैच जाँच का नाम देता है (देखें [पोस्ट-मैच वैलिडेटर](#post-match-validators-checksum-aware-false-positive-reduction)); इसकी प्राथमिकता `pattern_validators` लेबल मैप से अधिक होती है।

स्ट्रिंग और ऐरे प्रविष्टियाँ एक ही कॉन्फ़िग में स्वतंत्र रूप से मिश्रित होती हैं। गलत विकल्प **fail open** होते हैं — पैटर्न फिर भी बिना किसी प्रतिबंध के स्कैन करता है, और एक चेतावनी लॉग की जाती है — इसलिए एक कॉन्फ़िग गलती कभी भी किसी डिटेक्शन को चुपचाप अक्षम या संकुचित नहीं कर सकती।

> **नोट:** `/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'],
],

यदि लेबल किसी कीवर्ड से मेल नहीं खाता है, तो खतरा डिफ़ॉल्ट रूप से low गंभीरता का होता है।

अमान्य regex पैटर्न स्वचालित रूप से छोड़ दिए जाते हैं और चेतावनी के रूप में लॉग किए जाते हैं - वे आपके एप्लिकेशन को क्रैश नहीं करेंगे।

Facade का उपयोग करना

मिडलवेयर के बाहर थ्रेट डेटा तक प्रोग्रामेटिक पहुंच के लिए:```php use JayAnta\ThreatDetection\Facades\ThreatDetection;

// Get attack statistics for a specific IP $stats = ThreatDetection::getIpStatistics('192.168.1.1');

// Detect coordinated attacks (multiple IPs targeting same URL within 15 minutes) $attacks = ThreatDetection::detectCoordinatedAttacks(15, 3);

// Detect attack campaigns (same threat type from 5+ IPs in last 24 hours) $campaigns = ThreatDetection::detectAttackCampaigns(24);

// Get a summary of all correlation data $summary = ThreatDetection::getCorrelationSummary();

// Operator-side decision helpers (see "Acting on the Data") $blocked = ThreatDetection::isBlocklisted('203.0.113.7'); // static denylist, CIDR, whitelist wins $trusted = ThreatDetection::isWhitelisted('10.0.0.5'); $count = ThreatDetection::ddosRequestCount('203.0.113.7'); // requests in the current DDoS window $flooded = ThreatDetection::isDdosThresholdExceeded('203.0.113.7');

---

## प्रोडक्शन में जाना

यह पैकेज डिज़ाइन से निष्क्रिय (passive) है - यह किसी अनुरोध को कभी ब्लॉक, अस्वीकार या बदलता नहीं है, और डिटेक्शन मिडलवेयर अपने पूरे बॉडी को `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` होता है। देखें [Dashboard and API Authentication](#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](#reducing-false-positives)।
4. **क्षेत्रीय PII / कस्टम पैटर्न की समीक्षा करें।** डिफ़ॉल्ट भारत-केंद्रित हैं (आधार, PAN, IFSC) और व्यापक संख्यात्मक पैटर्न (जैसे बैंक-खाता) प्रमाणीकरण रूट्स के बाहर लंबे संख्यात्मक आईडी से मेल खा सकते हैं। अपने क्षेत्र और ऐप के लिए `custom_patterns` को बदलें या ट्रिम करें, और भारी-सामग्री रूट्स को `auth_paths` / `content_paths` में जोड़ें।
5. **रीटेंशन चालू करें** यदि आप वॉल्यूम की उम्मीद करते हैं: `THREAT_DETECTION_RETENTION=true` (शेड्यूलर के माध्यम से ऑटो-पर्ज)। इसके लिए Laravel के शेड्यूलर (`schedule:run`) को क्रॉन-संचालित होना आवश्यक है।
6. **वैकल्पिक एक्स्ट्रा, सभी डिफ़ॉल्ट रूप से बंद:** Slack अलर्ट (`THREAT_DETECTION_NOTIFICATIONS`), जियो-एनरिचमेंट (`php artisan threat-detection:enrich` - एकमात्र फीचर जो बाहरी कॉल करता है, मुफ्त ip-api.com पर), और क्यूड राइट्स (`THREAT_DETECTION_QUEUE` - केवल तभी सक्षम करें यदि आप पहले से क्यू वर्कर चलाते हैं; अन्यथा राइट्स सिंक्रोनस होते हैं और उन्हें Redis की आवश्यकता नहीं होती)।

कोर डिटेक्शन और लॉगिंग के लिए न तो Redis, न क्यू वर्कर, और न ही बाहरी नेटवर्क कॉल की आवश्यकता होती है।

---

## फ़ॉल्स पॉज़िटिव कम करना

पैकेज फ़ॉल्स पॉज़िटिव कम करने के लिए कई उपकरण प्रदान करता है। जो आपकी स्थिति के अनुकूल हो, उसका उपयोग करें:

### Safe Fields और Safe Paths

किसी फ़ील्ड को स्कैनिंग से पूरी तरह बाहर करें, या तो हर जगह नाम से (`safe_fields`) या नेस्टेड JSON के लिए डॉट-नोटेशन पथ द्वारा (`safe_paths`)। सबसे सरल तरीका, और सबसे कठोर - फ़ील्ड को छोड़ दिया जाता है, इसलिए उस पर कोई डिटेक्शन नहीं चलता।

पूर्ण विवरण और उदाहरण: [Safe Fields](#safe-fields-false-positive-reduction)।

### Content Path Suppression

यदि आपके पास CMS संपादक, ब्लॉग पोस्ट फ़ॉर्म, या टिप्पणी अनुभाग हैं जहाँ उपयोगकर्ता समृद्ध सामग्री सबमिट करते हैं, तो वे पथ अक्सर फ़ॉल्स पॉज़िटिव ट्रिगर करते हैं (जैसे, `<script>` कोड नमूने वाली ब्लॉग पोस्ट)। लो/मीडियम अलर्ट दबाने के लिए उन पथों को जोड़ें:```php
// config/threat-detection.php
'content_paths' => [
    'admin/posts/*',
    'admin/pages/*',
    'blog/*/edit',
    'comments',
],

इन पथों पर, केवल उच्च-गंभीरता वाले खतरे लॉग किए जाते हैं।

गलत सकारात्मक रिपोर्टिंग

डैशबोर्ड में किसी भी खतरे पर FP बटन पर क्लिक करके इसे गलत सकारात्मक के रूप में चिह्नित करें। यह:

खतरे को is_false_positive = true के रूप में फ्लैग करता है
स्वचालित रूप से एक बहिष्करण नियम बनाता है ताकि समान URL/प्रकार से आने वाले समान खतरे आगे दबा दिए जाएँ

API के माध्यम से बहिष्करण नियम प्रबंधित करें:```bash GET /api/threat-detection/exclusion-rules DELETE /api/threat-detection/exclusion-rules/{id}

### विश्वास स्कोरिंग

प्रत्येक खतरे को उसके आधार पर एक विश्वास स्कोर (0-100) मिलता है:
- एक ही अनुरोध में पैटर्न मिलान की संख्या
- मिलान किए गए पैटर्न की गंभीरता
- पैटर्न कहाँ पाया गया (क्वेरी स्ट्रिंग > हेडर > बॉडी)
- क्या यूज़र-एजेंट किसी ज्ञात आक्रमण उपकरण से मेल खाता है
- वर्तमान डिटेक्शन मोड

आपके डिटेक्शन मोड के लिए विश्वास सीमा से नीचे के खतरे लॉग नहीं किए जाते हैं (देखें [डिटेक्शन मोड](#detection-modes))।

---

## पहचाने गए आक्रमण प्रकार

| श्रेणी | उदाहरण |
|----------|---------|
| **SQL Injection** | UNION, boolean, time-based, CHAR encoding, DDL (DROP/ALTER/CREATE), DML (INSERT/UPDATE/DELETE), file ops (INTO OUTFILE, LOAD_FILE), ORDER BY enumeration, hex strings, UNHEX |
| **NoSQL Injection** | MongoDB $ne, $gt, $regex, $where operators |
| **XSS** | Script tags, SVG event handlers (`<svg onload=`), HTML event handlers (`<body onload=`, `<img onerror=`), CSS expressions, JavaScript URIs, DOM manipulation |
| **Code Execution** | RCE shell functions, PHP deserialization, Java deserialization (base64 + hex magic bytes), template injection (Blade, JSP, ASP, Jinja2, Velocity), eval(), base64 decode, PHP assert(), create_function(), preg_replace /e |
| **SSTI** | Mathematical probes (`{{7*7}}`), Jinja2 import/config, Velocity templates, Expression Language |
| **Command Injection** | Linux (shell functions, command chains, curl, wget, nc), Windows (cmd.exe, PowerShell, wscript, cscript, net user) |
| **File Access** | Directory traversal, LFI/RFI protocols, sensitive file probes (.env, .git, composer.json) |
| **SSRF** | Localhost (127.0.0.1, 0.0.0.0, ::1), AWS/GCP metadata, private IPs, hex/decimal encoded localhost, DNS rebinding (xip.io, nip.io, sslip.io) |
| **LDAP Injection** | LDAP filter manipulation, OR injection |
| **XPath Injection** | Attribute selectors, XPath functions (contains, substring) |
| **CRLF / Header Injection** | URL-encoded CRLF (`%0d%0a`), LF injection, null byte injection |
| **Protocol Attacks** | HTTP request smuggling (CL+TE), SSI injection |
| **CVE Exploits** | Shellshock (CVE-2014-6271), Spring4Shell (CVE-2022-22965), PHPUnit RCE (CVE-2017-9841), Drupalgeddon, Log4Shell |
| **Probe Tracking** | WordPress (`/wp-admin`, `/wp-login.php`), config files (`/.env`, `/.git`), database tools (`/phpmyadmin`), technology probes (`.asp`, `.jsp`), Spring actuator, Swagger/API docs -  50+ paths |
| **Scanners** | SQLMap, Nikto, Nmap, Burp Suite, FeroxBuster, FFUF, XSStrike, Dalfox, Netsparker, Qualys, Nuclei, and 20+ others (53 total) |
| **AI Scrapers** | GPTBot, ClaudeBot, ChatGPT, ByteSpider, Cohere, Common Crawl |
| **Headless Browsers** | HeadlessChrome, PhantomJS, Selenium, Puppeteer, Playwright |
| **Bots** | Python scripts, Go HTTP clients, cURL, wget, AhrefsBot, SEMRushBot, empty user agents |
| **Authentication** | Brute force detection, token leaks, password exposure, session ID exposure |
| **DDoS** | Rate-based excessive request detection |
| **Evasion** | SQL comment insertion, double URL encoding, HTML entity encoding, Unicode escapes, IIS Unicode, hex escapes |
| **Other** | GraphQL introspection, prototype pollution, open redirect, XXE, web shells, crypto mining, PII detection |

---

## टेस्ट सूट चलाना```bash
composer test

पैकेज में 335 परीक्षण (856 assertions) शामिल हैं जो डिटेक्शन पैटर्न, मिडलवेयर व्यवहार, API endpoints, कॉन्फिडेंस स्कोरिंग, बहिष्करण नियम, DDoS डिटेक्शन, एवेज़न प्रतिरोध, CVE पैटर्न, LDAP/XPath/SSTI इंजेक्शन, बॉट/स्कैनर डिटेक्शन, प्रोब ट्रैकिंग, एक्सपोर्ट कमांड, डैशबोर्ड प्रमाणीकरण, सुरक्षित फ़ील्ड, प्रदर्शन अनुकूलन, और फुल-साइकिल HTTP-to-DB सत्यापन को कवर करते हैं।

लाइसेंस

MIT लाइसेंस। विवरण के लिए LICENSE देखें।

योगदान

योगदान का स्वागत है! कृपया एक Pull Request सबमिट करें।

श्रेय

Jay Anta - लेखक और मेंटेनर
David van der Tuijn - Laravel 13 समर्थन
सभी योगदानकर्ता

दुर्भावनापूर्ण अनुरोधों को अवरोधित करता है	❌ केवल लॉग करता है	✅	✅
पूर्ण ऐप संदर्भ (सटीक रूट, डिकोड किया गया पेलोड, प्रमाणित उपयोगकर्ता)	✅	⚠️ आंशिक	❌
आपके DB में बिल्ट-इन डैशबोर्ड + खतरा लॉग	✅	⚠️ अलग-अलग	⚠️ केवल edge
ऐप-विशिष्ट जाँचें (जैसे Aadhaar / PAN / IFSC PII)	✅ कस्टम पैटर्न	❌	❌
ऑफ़लाइन काम करता है / कोई बाहरी सेवा नहीं	✅	⚠️ निर्भर करता है	❌
आपके ऐप तक पहुँचने से पहले ट्रैफ़िक रोकता है	❌	✅ edge	✅
सेटअप	एक `composer require`	मध्यम–उच्च	निम्न–मध्यम
लागत	मुफ्त, MIT	अलग-अलग	मुफ्त टियर + भुगतान

देखें कि आप पर क्या हमला हो रहा है	द dashboard या `threat-detection:stats`	कुछ नहीं, यह पहले से चल रहा है
फ़ायरवॉल पर बार-बार हमला करने वालों पर प्रतिबंध लगाएँ	`threat-detection:export-fail2ban` — cron में पाइप करें	एक पंक्ति
वेब सर्वर पर अस्वीकार करें	`threat-detection:export-blocklist` → nginx/apache निर्देश	एक पंक्ति
इन-ऐप अनुरोधों को अस्वीकार करें	ऑपरेटर-साइड सहायक — `isBlocklisted()`, `isDdosThresholdExceeded()`	आपके अपने मिडलवेयर की ~10 पंक्तियाँ
वास्तविक समय में प्रतिक्रिया करें	`ThreatDetected` event — Telegram, SIEM, PagerDuty	एक listener

सबसे लोकप्रिय

laravel-threat-detection