PHPackages zxf/security - 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. zxf/security ActiveLibrary[Security](/categories/security) zxf/security ============ Laravel / ThinkPHP 安全中间件 - 简洁、无缓存、低误报的请求拦截包 v1.1.7(4w ago)145MITPHPPHP >=8.2 Since Nov 12Pushed 4w agoCompare [ Source](https://github.com/zhaoxianfang/security)[ Packagist](https://packagist.org/packages/zxf/security)[ RSS](/packages/zxf-security/feed)WikiDiscussions master Synced 3w ago READMEChangelog (10)Dependencies (8)Versions (25)Used By (0) [![Security's Logo](./resources/images/security.jpg)](./resources/images/security.jpg) zxf/security - Laravel / ThinkPHP 安全中间件 ======================================= [](#zxfsecurity---laravel--thinkphp-安全中间件) [![PHP](https://camo.githubusercontent.com/93ef770c7b4975b384b845a4b61d157e329f008f72faae2f9300f624b15ecb2a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d2533453d382e322d383839326266)](https://php.net)[![Laravel](https://camo.githubusercontent.com/75fe5d1dacb6a7da9a9ca4bd6855b10b52ed24ff64070bf88dd53270ef10e52f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d2533453d31312d666632643230)](https://laravel.com)[![ThinkPHP](https://camo.githubusercontent.com/4db6c6d2462425dd4dccec09dbdfce66e337008cdb710387dfbed4977f54521e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7468696e6b7068702d2533453d382d336561663763)](https://www.thinkphp.cn)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE) **简洁、高效、智能的跨框架安全防护中间件** 同时支持 **Laravel 11+** 和 **ThinkPHP 8+**，通过统一的桥接层自动适配当前运行框架。 --- 特性 -- [](#特性) - **14层安全防护** - 全面的安全检测体系，从URL路径到文件上传层层防护 - **精准拦截** - 高危攻击（SQL注入、命令注入、路径遍历、NoSQL、SSTI、SSRF）严格拦截 - **SSRF检测** - 检测服务器端请求伪造攻击，包括内网IP、云元数据、危险协议等 - **编码绕过检测** - 检测多重URL编码、UTF-8过度编码、空字节注入等绕过技术 - **CRLF/Header注入检测** - 检测HTTP头注入和响应拆分攻击 - **智能识别** - 自动识别Markdown文档内容，代码块内的标签不会误拦截 - **零缓存依赖** - 不使用Redis/Memcached，直接使用框架原生功能 - **低内存占用** - 正则模式延迟加载，避免 `php artisan optimize` 内存溢出（v5.1+） - **高性能** - 单次请求处理耗时 < 1ms，支持预过滤快速跳过 - **CIDR支持** - IP黑白名单支持IPv4和IPv6网段格式（如 `192.168.0.0/16`、`2001:db8::/32`） - **拦截回调** - 支持自定义拦截决策，实现动态放行策略 - **自定义视图** - 支持自定义拦截页面，支持Blade视图/ThinkPHP模板/闭包/类方法 - **安全响应头** - 拦截响应自动添加安全HTTP头（X-Content-Type-Options, X-Frame-Options 等） - **跨框架兼容** - 同一套代码支持 Laravel 11+ 和 ThinkPHP 8+（v6.1+） --- 快速开始 ---- [](#快速开始) ### 安装 [](#安装) ``` composer require zxf/security ``` ### Laravel 配置 [](#laravel-配置) ``` # 发布配置文件 php artisan vendor:publish --tag=security-config ``` 编辑 `.env`： ``` SECURITY_ENABLED=true SECURITY_LOG_ENABLED=true SECURITY_RATE_LIMIT_ENABLED=true SECURITY_RATE_LIMIT_ATTEMPTS=60 ``` #### Laravel 11+ 中间件注册（推荐） [](#laravel-11-中间件注册推荐) 由于 Laravel 11+ 调整了 `Router::middleware()` 的行为，ServiceProvider 的自动全局注册在 Laravel 11+ 下会降级为组级注册（web / api）。**强烈建议在 `bootstrap/app.php` 中手动注册全局中间件**，确保所有路由（包括非 web/api 路由）都受到保护： ``` // bootstrap/app.php use Illuminate\Foundation\Configuration\Middleware; ->withMiddleware(function (Middleware $middleware) { $middleware->append(\zxf\Security\Middleware\SecurityMiddleware::class); }) ``` > ⚠️ **Laravel 11+ 注意事项**： > > - `bootstrap/app.php` 手动注册是**唯一可靠的全局中间件注册方式** > - ServiceProvider 仍会自动将中间件推入 `web` 和 `api` 组作为兜底 > - 如果存在 `global` 中间件组，也会自动推入 > ✅ 支持 Laravel 11、12、13 ### ThinkPHP 8+ 配置 [](#thinkphp-8-配置) 1. **发布配置文件** 将 `vendor/zxf/security/config/security.php` 复制到项目 `config/security.php`。 2. **注册中间件** 在 `app/middleware.php` 中添加： ``` return [ // ... 其他中间件 \zxf\Security\Middleware\SecurityMiddleware::class, ]; ``` 或者通过服务类自动注册（在 `app/AppService.php` 的 `init()` 中）： ``` \zxf\Security\Providers\ThinkPHPSecurityServiceProvider::register($this->app); ``` 3. **配置环境变量** ThinkPHP 下在 `.env` 中添加： ``` SECURITY_ENABLED=true SECURITY_LOG_ENABLED=true SECURITY_RATE_LIMIT_ENABLED=true ``` > 📖 详细 ThinkPHP 使用指南：[docs/thinkphp.md](docs/thinkphp.md) ### 内存优化（v5.1+） [](#内存优化v51) 本包默认正则模式已从配置文件迁移至独立数据文件，实现**延迟加载**： - `php artisan optimize` 时不再加载任何正则模式 → **内存占用大幅降低** - 正则仅在首次安全检测时按需加载（请求时），并由进程级缓存复用 - 配置文件体积精简至原来的 ~30%，仅保留轻量配置参数 **添加自定义检测模式**：在配置中追加即可，会自动与内置模式合并： ``` // config/security.php 'high_risk_patterns' => [ 'sql' => ['/your_custom_sql_pattern/i'], 'my_custom_type' => ['/custom_regex/i'], ], 'xss_patterns' => [ 'script' => ['/extra_xss_pattern/i'], ], 'url_path_detection' => [ 'path_patterns' => ['/custom_path_pattern/i'], ], ``` --- 核心功能 ---- [](#核心功能) 功能说明IP白名单可信IP跳过所有检查IP黑名单恶意IP直接拦截URL路径攻击检测直接检测URL中的路径遍历等攻击多重编码检测检测空字节、UTF-8过度编码、多重URL编码等绕过技术User-Agent检查封禁已知恶意扫描器HTTP头检查验证Host头、禁止的头信息、CRLF注入检测请求体大小限制防止内存溢出攻击速率限制防止暴力破解、CC攻击（IP+路由组合key）SQL注入检测UNION注入、堆叠查询、时间盲注、错误注入命令注入检测系统命令执行防护路径遍历检测`../../../etc/passwd` 等NoSQL注入检测MongoDB等NoSQL数据库注入防护SSTI检测服务器端模板注入防护SSRF检测内网IP访问、云元数据、危险协议CRLF/Header注入检测HTTP头注入和响应拆分攻击XSS防护智能识别Markdown代码块文件上传检查禁止WebShell上传安全响应头拦截响应添加 X-Content-Type-Options 等安全头--- 拦截示例 ---- [](#拦截示例) ``` # SQL注入 - 被拦截 curl "https://example.com/api?id=1' UNION ALL SELECT password FROM users--" # → HTTP 403: 请求包含高危安全威胁 # 正常Markdown内容 - 放行 curl -X POST https://example.com/docs \ -d 'content=```htmlalert(1)```' # → HTTP 200: 请求通过 ``` --- 拦截回调（高级功能） ---------- [](#拦截回调高级功能) 通过 `before_block_callback` 配置，你可以在拦截前执行自定义逻辑： ``` // config/security.php 'before_block_callback' => function(\zxf\Security\Dto\InterceptionContext $context) { // 1. 记录到数据库 SecurityLog::create($context->toArray()); // 2. 低风险请求自动放行 if ($context->getRiskLevel() === 'low') { return false; // 放行 } // 3. 特定IP段放行 if (str_starts_with($context->clientIp, '192.168.')) { return false; } // 4. 发送告警（异步队列） SecurityAlertJob::dispatch($context); return true; // 拦截 }, ``` ### 回调返回值说明 [](#回调返回值说明) 返回值行为`false`**放行** - 请求继续处理`true` / `null`**拦截** - 返回拦截响应给用户### InterceptionContext 对象 [](#interceptioncontext-对象) 回调接收的上下文对象包含以下信息： ``` $context->threatType // 威胁类型: sql, xss, command, blacklist... $context->getThreatTypeDescription() // 中文描述 $context->getRiskLevel() // 风险等级: high, medium, low $context->clientIp // 客户端IP $context->method // HTTP方法 $context->url // 请求URL $context->matchedPattern // 匹配的正则模式 $context->matchedContent // 匹配的内容片段（脱敏） $context->allThreats // 所有检测到的威胁 $context->toArray() // 转为数组格式 ``` ### 使用场景 [](#使用场景) 1. **动态放行策略** - 根据业务规则临时放行某些请求 2. **威胁日志记录** - 将拦截事件记录到数据库或外部系统 3. **实时告警通知** - 发送钉钉/企业微信/短信告警 4. **威胁情报分析** - 收集攻击数据用于后续分析 --- 自定义拦截页面 ------- [](#自定义拦截页面) 通过 `response.view` 配置自定义拦截视图： ### 方法1：使用 Blade 视图 [](#方法1使用-blade-视图) ``` // config/security.php 'response' => [ 'view' => 'errors.security', ], ``` 创建视图 `resources/views/errors/security.blade.php`： ``` 访问被拒绝 body { font-family: sans-serif; padding: 50px; text-align: center; } .alert { background: #fee; border: 1px solid #fcc; padding: 30px; border-radius: 5px; max-width: 600px; margin: 0 auto; } .threats { background: #f5f5f5; padding: 15px; margin-top: 20px; text-align: left; } 🛡️ 访问被拒绝 {{ $message }} @if(!empty($threats)) 威胁类型： {{ implode(', ', $threats) }} @endif ``` ### 方法2：使用闭包函数 [](#方法2使用闭包函数) ``` 'response' => [ 'view' => function($data) { // 根据威胁类型返回不同视图 if (in_array('sql', $data['threats'])) { return view('errors.sql-injection', $data); } return view('errors.generic', $data); }, ], ``` ### 视图可用变量 [](#视图可用变量) 变量类型说明`$message`string拦截提示消息`$blocked`bool是否被拦截`$threats`array威胁类型数组`$matched_pattern`string匹配的正则模式`$matched_content`string匹配的内容片段--- 文档 -- [](#文档) - [完整配置指南](docs/configuration.md) - [攻击防护说明](docs/security-patterns.md) - [API参考](docs/api.md) - [常见问题](docs/faq.md) - [使用示例](docs/examples.md) - [ThinkPHP 8+ 使用指南](docs/thinkphp.md) --- 许可证 --- [](#许可证) MIT License - 详见 [LICENSE](LICENSE) 文件 ### Health Score 45 — FairBetter than 91% of packages Maintenance94 Actively maintained with recent releases Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity58 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 Every ~8 days Recently: every ~1 days Total 24 Last Release 28d ago Major Versions v0.0.6 → v1.0.02025-12-06 PHP version history (3 changes)v0.0.1PHP ^8.2|^8.3|^8.4 v0.0.2PHP ^8.1 v1.0.1PHP >=8.2 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/1578312?v=4)[Felix Zhu](/maintainers/zxf)[@zxf](https://github.com/zxf) --- Top Contributors [![zhaoxianfang](https://avatars.githubusercontent.com/u/28860960?v=4)](https://github.com/zhaoxianfang "zhaoxianfang (1 commits)") --- Tags laravelmiddlewarephpsecuritythinkphpmiddlewarelaravelsecurityIPfirewallprotectionthinkphpzxf ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/zxf-security/health.svg) ``` [![Health](https://phpackages.com/badges/zxf-security/health.svg)](https://phpackages.com/packages/zxf-security) ``` ### Alternatives [akaunting/laravel-firewall Web Application Firewall (WAF) package for Laravel 1.0k494.9k2](/packages/akaunting-laravel-firewall) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)