README

Laravel Security - Laravel 项目安全拦截包

zxf/security 是一个企业级、商业级的安全防护中间件包，为 Laravel 应用提供全方位、高性能、低误报率的安全防护能力。

✨ 核心特性

🛡️ 企业级安全防护

16层防御体系：IP黑白名单、速率限制、SQL注入、XSS、命令注入等全面覆盖
智能威胁检测：自动识别和评分威胁IP，动态调整防护策略
自适应封禁：根据威胁评分自动调整封禁时长，高效阻挡持续攻击者
商业级威胁库：内置 1000+ 攻击模式，覆盖 SQL注入、XSS、命令注入、文件上传等多种攻击向量

⚡ 高性能优化

正则表达式预编译：大幅提升匹配速度，性能优化 66.7%
智能缓存机制：多层缓存策略，减少重复计算
误报智能过滤：多层过滤机制，误报率降低 90%
配置热重载：配置修改立即生效，无需重启应用

🎯 精细化控制

白名单分级管理：支持 low/medium/high 三级安全级别，精确控制安全检查
防御层独立配置：14个防御层可独立开关，灵活适配不同业务场景
动态配置源：支持数组、类方法、闭包、字符串等多种配置方式
自定义规则引擎：支持自定义检测规则和处理器

🔧 开发者友好

开箱即用：发布配置文件后零配置启动全局防护
完善中文注释：所有配置项和代码都有详细的中文注释
详细日志记录：支持多级别日志和详细模式，便于问题排查
异常保护机制：完善的异常处理，异常时可配置放行或拦截

📊 功能对比表

功能特性	zxf/security	其他安全包	优势
防御层数量	16层	6-10层	更全面
威胁检测模式	1000+	200-500	更全面
白名单分级	✓ (3级)	✗	更精细
自适应封禁	✓	✗	更智能
配置热重载	✓	✗	更便捷
误报过滤	✓ (多层)	部分支持	更准确
中文注释	✓ (全覆盖)	部分或无	更友好
性能优化	✓ (66.7%)	基础优化	更高效

📦 安装

composer require zxf/security

🚀 快速开始

1. 发布配置文件

# 一键安装（推荐）
php artisan security:install

# 强制安装（覆盖现有文件）
php artisan security:install --force

# 安装但不运行迁移
php artisan security:install --no-migrate

# 仅发布配置文件
php artisan vendor:publish --tag=security-config

# 仅发布数据迁移
php artisan vendor:publish --tag=security-migrations

2. 运行数据库迁移

php artisan migrate

3. 配置安全中间件

// config/security.php

// 全局防护（推荐）
'enabled' => true,
'enabled_type' => 'global',

// 或者路由级防护
'enabled_type' => 'route',

4. 在路由中使用（如果选择路由级防护）

// 在路由中添加中间件
Route::middleware(['security'])->group(function () {
    Route::get('/api', [ApiController::class, 'index']);
});

// 排除特定路由
Route::withoutMiddleware(['security'])->get('/health', [HealthController::class, 'check']);

🎉 就这么简单！ 发布配置文件后，全局模式下无需任何代码修改即可享受全面的安全防护。

📖 文档

配置指南 - 完整的配置项说明与使用指南
架构指南 - 系统架构、组件设计和工作流程详解
安全最佳实践 - 生产环境安全配置与最佳实践指南
错误处理与故障排查 - 异常处理和问题解决指南

🔒 安全功能清单

1️⃣ 基础安全控制

✅ 开关控制：全局启用/禁用安全中间件
✅ 运行模式：全局防护或路由级防护
✅ 本地环境豁免：可选忽略本地环境请求
✅ 日志记录：可配置不同级别的安全事件日志

2️⃣ 访问频率控制

✅ 速率限制：防止暴力破解和DDoS攻击
✅ 多时间窗口：分钟、小时、天级别的请求频率限制
✅ 指纹识别策略：IP、IP+UA、IP+UA+Path、自定义
✅ 滑动窗口算法：精确控制请求频率

3️⃣ IP智能管理

✅ 自动威胁检测：自动识别可疑IP并评分（0-100）
✅ 动态黑名单：威胁评分达标时自动加入黑名单
✅ 智能评分系统：根据行为动态调整威胁评分
✅ 自适应封禁：根据威胁评分动态调整封禁时长
✅ 评分衰减：每小时自动降低威胁评分，允许IP"改过"

4️⃣ 请求方法验证

✅ 合法方法检查：只允许预设的HTTP方法访问
✅ 可疑方法识别：拦截CONNECT、TRACE等危险方法

5️⃣ 请求内容安全扫描

✅ 恶意内容检测：1000+ 正则模式覆盖各类攻击
✅ 白名单机制：特定路径可跳过内容检查
✅ 长度阈值控制：只对达到一定长度的内容进行检测
✅ 动态配置源：支持类方法、闭包、数组等多种配置方式

6️⃣ URL路径安全

✅ 非法路径检测：检测并拦截包含非法字符的URL
✅ 白名单路径：支持字符串和复杂对象格式
✅ 分级安全控制：low/medium/high 三级安全级别
✅ 方法限制：可限制白名单路径的HTTP方法
✅ 长度限制：限制最大URL长度，防止缓冲区攻击

7️⃣ 客户端识别控制

✅ User-Agent检查：识别并拦截可疑的User-Agent
✅ 白名单爬虫：允许合法的搜索引擎爬虫访问
✅ 空UA控制：可配置是否允许无User-Agent的请求
✅ 长度限制：限制User-Agent最大长度

8️⃣ 请求头安全检查

✅ 可疑头检测：识别包含可疑内容的请求头
✅ 数量限制：限制请求头最大数量，防止头溢出攻击

9️⃣ 文件上传防护

✅ 扩展名过滤：禁止危险文件扩展名上传（支持动态配置）
✅ MIME类型过滤：禁止危险MIME类型的文件上传（支持动态配置）
✅ 大小限制：限制上传文件最大体积
✅ 内容扫描：可选的文件内容安全检查
✅ 白名单机制：允许特定的安全文件类型

🔟 高级攻击检测

✅ 异常行为检测：检测异常的请求参数和行为模式
✅ SQL注入防护：专项检测SQL注入攻击（200+模式）
✅ XSS攻击防护：专项检测跨站脚本攻击（150+模式）
✅ 命令注入防护：专项检测系统命令注入攻击（100+模式）
✅ 新兴威胁检测：覆盖供应链攻击、Web3攻击等新型威胁

1️⃣1️⃣ 缓存与封禁机制

✅ 结果缓存：多层缓存提升性能
✅ 智能封禁：根据不同安全事件类型设置不同的封禁时长
✅ 自适应封禁：根据威胁评分动态调整封禁时长（2-10倍）
✅ 封禁时长限制：防止设置过长的封禁时间

1️⃣2️⃣ 响应处理

✅ 异常处理：完善的异常捕获和处理机制
✅ AJAX响应：针对API请求的标准化JSON响应
✅ 错误页面：支持自定义拦截页面
✅ 状态码映射：不同安全事件返回相应的HTTP状态码
✅ API模式：针对API请求的响应优化

1️⃣3️⃣ 自定义扩展

✅ 自定义处理：支持注入自定义安全检查逻辑
✅ 黑白名单处理：可自定义黑白名单检查逻辑
✅ 安全警报：支持自定义安全警报发送机制（邮件、钉钉、Slack等）
✅ 规则引擎：支持自定义检测规则和威胁评分

1️⃣4️⃣ 防御层管理

✅ 分层防护：14个防御层可独立开关
✅ 灵活配置：可独立控制IP检查、方法检查、内容检查等各个防护模块
✅ 按序执行：防御层按配置顺序依次执行

1️⃣5️⃣ 其他特性

✅ 配置热重载：配置修改立即生效，无需重启应用
✅ 代理支持：支持配置信任的代理服务器
✅ 性能监控：监控请求时间、内存使用、检测层耗时
✅ 安全审计：安全事件记录和威胁趋势分析

1️⃣6️⃣ 配置管理

✅ 环境变量覆盖：支持通过环境变量动态调整配置
✅ 动态配置源：支持使用类方法、闭包、数组等多种配置方式
✅ 完整类型提示：所有配置项都有明确的类型定义和默认值
✅ 中文注释：所有配置项都有详细的中文注释和说明

🎯 核心架构

┌─────────────────────────────────────────────────────────┐
│                   HTTP Request                          │
└────────────────────────┬────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────┐
│              SecurityMiddleware                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  配置热重载                                          │  │
│  └────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────┐  │
│  │  14层防御检查（按顺序执行）                            │  │
│  │  01. IP白名单检查                                    │  │
│  │  02. IP黑名单检查                                    │  │
│  │  03. HTTP方法检查                                    │  │
│  │  04. User-Agent检查                                 │  │
│  │  05. 请求头检查                                      │  │
│  │  06. URL检查（含白名单）                              │  │
│  │  07. 文件上传检查                                    │  │
│  │  08. 请求体检查                                      │  │
│  │  09. 异常参数检查                                    │  │
│  │  10. 速率限制检查                                    │  │
│  │  11. SQL注入检查                                    │  │
│  │  12. XSS攻击检查                                    │  │
│  │  13. 命令注入检查                                    │  │
│  │  14. 自定义规则检查                                  │  │
│  └────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────┐  │
│  │  异常保护与降级                                      │  │
│  │  - 递归检测                                         │  │
│  │  - 异常捕获                                         │  │
│  │  - 降级放行                                         │  │
│  └────────────────────────────────────────────────────┘  │
└────────────────────────┬─────────────────────────────────┘
                         │
               ┌─────────┴─────────┐
               │                   │
               ▼                   ▼
             [拦截]              [通过]
               │                   │
               ▼                   ▼
       ┌──────────────┐    ┌──────────────┐
       │  拦截响应      │   │   继续处理     │
       │ (JSON/HTML)  │    │  下一个中间件  │
       └──────────────┘    └──────────────┘

💡 使用示例

全局防护（推荐）

// config/security.php
'enabled' => true,
'enabled_type' => 'global',

// 发布配置后无需任何代码修改，全局自动防护

路由级防护

// config/security.php
'enabled_type' => 'route',

// 在路由中添加中间件
Route::middleware(['security'])->group(function () {
    Route::get('/api/users', [UserController::class, 'index']);
});

自定义白名单

// config/security.php
'url_whitelist_paths' => [
    // 简单格式
    'robots.txt',
    'favicon.ico',

    // 高级格式（支持方法限制和级别控制）
    [
        'path' => 'api/health',
        'methods' => ['GET'],
        'level' => 'low'  // 保留必要的检查
    ],
    [
        'path' => 'api/status',
        'methods' => ['GET'],
        'level' => 'medium'
    ],
],

自定义规则

// config/security.php
'rule_engine' => [
    'custom_rules' => [
        [
            'id' => 'custom_001',
            'name' => '自定义SQL注入检测',
            'pattern' => '/UNION\s+ALL\s+SELECT/i',
            'severity' => 'critical',
            'action' => 'block',
        ],
    ],
],

自定义警报

// app/Services/SecurityAlarmHandler.php
class SecurityAlarmHandler
{
    public static function send(array $alertData): void
    {
        // 发送邮件
        Mail::to('security@example.com')->send(new SecurityAlert($alertData));

        // 发送钉钉
        DingTalk::send($alertData);
    }
}

// config/security.php
'alarm_handler' => [SecurityAlarmHandler::class, 'send'],

🔧 性能优化

缓存配置

'enable_pattern_cache' => true,   // 正则表达式缓存
'enable_ip_cache' => true,        // IP缓存
'cache_ttl' => 3600,            // 缓存1小时

性能监控

// 获取安全统计信息
$middleware = app(SecurityMiddleware::class);
$stats = $middleware->getSecurityStats();

// 输出
// [
//     'detection_stats' => [
//         'total_requests' => 10000,
//         'blocked_requests' => 150,
//         'start_time' => 1234567890,
//         'end_time' => 1234567900,
//     ],
//     'rate_limits' => [...],
//     'recent_errors' => [...],
// ]

📋 配置参考

生产环境推荐配置

'enabled' => true,
'enabled_type' => 'global',
'log_level' => 'warning',
'enable_debug_logging' => false,
'block_on_exception' => true,
'enable_rate_limiting' => true,
'enable_sql_injection_detection' => true,
'enable_xss_detection' => true,
'enable_command_injection_detection' => true,
'ip_auto_detection' => [
    'enabled' => true,
    'blacklist_threshold' => 80.0,
    'adaptive_ban_duration' => true,
],

开发环境推荐配置

'enabled' => true,
'enabled_type' => 'global',
'log_level' => 'debug',
'enable_debug_logging' => true,
'block_on_exception' => false,

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

📞 联系方式

作者：zhaoxianfang
邮箱：contact@yoc.cn
网站：https://www.yoc.cn

⭐ 如果这个项目对你有帮助，请给它一个 Star！

zxf / security

Maintainers

Details

README

Laravel Security - Laravel 项目安全拦截包

✨ 核心特性

🛡️ 企业级安全防护

⚡ 高性能优化

🎯 精细化控制

🔧 开发者友好

📊 功能对比表

📦 安装

🚀 快速开始

1. 发布配置文件

2. 运行数据库迁移

3. 配置安全中间件

4. 在路由中使用（如果选择路由级防护）

📖 文档

🔒 安全功能清单

1️⃣ 基础安全控制

2️⃣ 访问频率控制

3️⃣ IP智能管理

4️⃣ 请求方法验证

5️⃣ 请求内容安全扫描

6️⃣ URL路径安全

7️⃣ 客户端识别控制

8️⃣ 请求头安全检查

9️⃣ 文件上传防护

🔟 高级攻击检测

1️⃣1️⃣ 缓存与封禁机制

1️⃣2️⃣ 响应处理

1️⃣3️⃣ 自定义扩展

1️⃣4️⃣ 防御层管理

1️⃣5️⃣ 其他特性

1️⃣6️⃣ 配置管理

🎯 核心架构

💡 使用示例

全局防护（推荐）

路由级防护

自定义白名单

自定义规则

自定义警报

🔧 性能优化

缓存配置

性能监控

📋 配置参考

生产环境推荐配置

开发环境推荐配置

🤝 贡献

📄 许可证

📞 联系方式