PHPackages rafalmasiarek/threat-detector - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Security](/categories/security) 4. / 5. rafalmasiarek/threat-detector ActiveLibrary[Security](/categories/security) rafalmasiarek/threat-detector ============================= Heuristic, modular threat detection (signal-only) with weighted float scoring, predefined thresholds, and PSR-15 middleware for PSR-7 apps. v1.0.0(8mo ago)04MITPHPPHP >=8.1 Since Sep 7Pushed 8mo agoCompare [ Source](https://github.com/rafalmasiarek/php-threat-detector)[ Packagist](https://packagist.org/packages/rafalmasiarek/threat-detector)[ RSS](/packages/rafalmasiarek-threat-detector/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (4)Versions (2)Used By (0) rafalmasiarek/threat-detector ============================= [](#rafalmasiarekthreat-detector) [![Latest Version](https://camo.githubusercontent.com/40311ee613e12e60dbe3f4cace9fe62e0c1a765df39caa37bbfb27d670e20103/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f726166616c6d6173696172656b2f7468726561742d6465746563746f722e737667)](https://packagist.org/packages/rafalmasiarek/threat-detector)[![License](https://camo.githubusercontent.com/84bbf088a624d2963fa25af42cdef763891df37a7e4e5081fd0bde9e47c435c8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f726166616c6d6173696172656b2f7468726561742d6465746563746f72)](LICENSE)[![PHP](https://camo.githubusercontent.com/d6aac44f81cb2e6f4e71f098a1cb4a71992f24f7bfb424f6670db8313c9a855c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253545382e312d626c7565)](https://camo.githubusercontent.com/d6aac44f81cb2e6f4e71f098a1cb4a71992f24f7bfb424f6670db8313c9a855c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253545382e312d626c7565) Heuristic, **modular** threat detection (signal-only) with **weighted float scoring**, **predefined thresholds**, and **PSR-15 middleware** for PSR-7 applications. > โš ๏ธ This library is a *signal generator*. It **does not replace** proper validation/sanitization/escaping, CSP, prepared statements, etc. --- Features -------- [](#features) - ๐Ÿงฉ **Modular scanners** โ€” each category (XSS, SQLi, SSRF, โ€ฆ) in a separate class. - โš–๏ธ **Weighted float scoring** โ€” per-category weights; combine multiple signals. - ๐ŸŽš๏ธ **Predefined thresholds** โ€” `LOW`, `MEDIUM`, `HIGH` (or custom floats). - ๐Ÿงต **PSR-15 middleware** โ€” scan query, body, headers, cookies; annotate request; optional header `X-Threat-Suspect`. - ๐Ÿ“ **phpDocs & comments** โ€” production-friendly code with clear docs. - โœ… **Unit tests** โ€” a couple of quick checks to get you started. - ๐Ÿ“‚ **Examples** โ€” basic HTML form + PSR-15 middleware demo. --- Requirements ------------ [](#requirements) - PHP **8.1+** - ext-mbstring --- Installation ------------ [](#installation) Using Composer: ``` composer require rafalmasiarek/threat-detector ``` If you are using this repository locally (path repo): ``` composer config repositories.threat-detector path ./threat-detector composer require rafalmasiarek/threat-detector:dev-main ``` --- Quick Start (Core) ------------------ [](#quick-start-core) ``` use rafalmasiarek\Threat\Core\ThreatDetector; use rafalmasiarek\Threat\Core\ScoringPolicy; use rafalmasiarek\Threat\Core\Thresholds; // Create a policy with default weights and MEDIUM threshold $policy = ScoringPolicy::withDefaults() ->withThreshold(Thresholds::MEDIUM) // or 'LOW' | 'HIGH' | 3.5 (float) ->withWeight('SQLI', 2.25); // optional: override category weights $detector = ThreatDetector::default($policy); // Scan a string $input = "alert(1)"; $result = $detector->scanString($input); var_dump($result->suspect); // bool var_dump($result->score); // float var_dump($result->hits); // array{category => list} var_dump($result->norm); // normalized input ``` Example output: ``` bool(true) float(3) array(1) { ["XSS"]=> array(2) { [0]=> string(10) "TAG_SCRIPT" [1]=> string(9) "HTML_TAGS" } } string(23) "alert(1)" ``` --- Quick Start (PSR-15 Middleware) ------------------------------- [](#quick-start-psr-15-middleware) ``` use rafalmasiarek\Threat\Middleware\ThreatDetectMiddleware; $middleware = new ThreatDetectMiddleware([ 'threshold' => 'MEDIUM', // 'LOW' | 'MEDIUM' | 'HIGH' | float 'weights' => ['SQLI' => 2.1], // optional overrides 'scan_query' => true, 'scan_body' => true, 'scan_headers' => false, // true or array of headers to scan 'scan_cookies' => false, 'attribute' => 'threat.result', // request attribute name 'set_header' => true, // add X-Threat-Suspect: 1 when suspect ]); // Add to your PSR-15 stack (Slim/Mezzio/etc.) $result = $request->getAttribute('threat.result'); ``` Example result: ``` [ 'suspect' => true, 'score' => 3.5, 'hits' => ['XSS' => ['TAG_SCRIPT','HTML_TAGS']], ] ``` --- Scoring ------- [](#scoring) - **Weights**: per category (e.g., `SQLI=2.0`, `CMD_INJECTION=2.5`, `CRLF=1.0`). - **Score formula**: ``` score = ฮฃ ( weight(category) ร— unique_hits(category) ) ``` - **Threshold**: request is **suspect** when `score โ‰ฅ threshold`. ### Predefined thresholds [](#predefined-thresholds) NameValueSensitivityLOW1.0Very sensitiveMEDIUM2.5Balanced (default)HIGH5.0Strict### Examples [](#examples) - `alert(1)` Hits: `XSS=[TAG_SCRIPT, HTML_TAGS]` Score: `1.5 ร— 2 = 3.0` โ†’ suspect at `MEDIUM` - `UNION SELECT password FROM users` Hits: `SQLI=[UNION_SELECT]` Score: `2.0 ร— 1 = 2.0` โ†’ not suspect at `MEDIUM`, suspect at `LOW` --- Categories & Scanners ------------------------- [](#categories--scanners) - **XSS** โ€” inline event handlers, ``, `javascript:` URIs. - **SQLI** โ€” `UNION SELECT`, `SLEEP()`, `INFORMATION_SCHEMA`, etc. - **CMD\_INJECTION** โ€” subshells, `;`, `&&`, `wget/curl`, redirects. - **PATH\_TRAVERSAL** โ€” `../`, URL-encoded traversal, `file://`, wrappers. - **CRLF** โ€” header injection sequences. - **SSRF** โ€” URLs to `localhost`, `127.0.0.1`, `RFC1918` ranges. - **XXE** โ€” ``, ``, external SYSTEM. - **NOSQL** โ€” Mongo-like operators `$where`, `$regex`. - **LDAP** โ€” wildcards, null bytes. - **SERIALIZATION** โ€” PHP serialized payload patterns. --- Integration Ideas ----------------- [](#integration-ideas) - Add to Slim/Mezzio pipeline as PSR-15 middleware. - Run against form input before sending mail (contact forms). - Log suspect inputs into a security audit trail. - Flag suspicious requests in rate-limiting / WAF logic. --- Tests & Examples -------------------- [](#tests--examples) - PHPUnit tests included (`tests/`): - `TruePositiveDetectionsTest.php` - `FalsePositiveHeuristicsTest.php` - Example apps in `examples/`: - `basic/` (HTML form demo) - `psr15/` (middleware demo) Run tests: ``` ./vendor/bin/phpunit --colors=always ``` --- Security Notice --------------- [](#security-notice) This library generates **signals only**. Always combine with: - Prepared statements for SQL queries - Proper HTML escaping and CSP - Strong input validation --- Folder Structure ---------------- [](#folder-structure) ``` src/ Contracts/ScannerInterface.php Core/{ThreatDetector.php, ThreatResult.php, ScoringPolicy.php, Thresholds.php} Scanner/{XssScanner.php, SqliScanner.php, CmdInjectionScanner.php, PathTraversalScanner.php, CrlfScanner.php, SsrfScanner.php, XxeScanner.php, NoSqlScanner.php, LdapScanner.php, SerializationScanner.php} Middleware/ThreatDetectMiddleware.php tests/ ModularThreatDetectorTest.php examples/ basic/ psr15/ ``` --- License ------- [](#license) MIT ### Health Score 30 โ€” LowBetter than 64% of packages Maintenance61 Regular maintenance activity Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 248d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/17765d36dfdee9f4179c94861184464cb4282d224e9db7fa86b4dff6005c166c?d=identicon)[rafalmasiarek](/maintainers/rafalmasiarek) --- Top Contributors [![rafalmasiarek](https://avatars.githubusercontent.com/u/36776423?v=4)](https://github.com/rafalmasiarek "rafalmasiarek (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/rafalmasiarek-threat-detector/health.svg) ``` [![Health](https://phpackages.com/badges/rafalmasiarek-threat-detector/health.svg)](https://phpackages.com/packages/rafalmasiarek-threat-detector) ``` ### Alternatives [cakephp/cakephp The CakePHP framework 8.8k18.5M1.6k](/packages/cakephp-cakephp)[neos/flow Flow Application Framework 862.0M451](/packages/neos-flow)[selective/samesite-cookie Secure your site with SameSite cookies 10144.0k](/packages/selective-samesite-cookie)[neos/flow-development-collection Flow packages in a joined repository for pull requests. 144179.3k3](/packages/neos-flow-development-collection)[windwalker/framework The next generation PHP framework. 25639.1k1](/packages/windwalker-framework) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)