Laravel 安全最佳实践

为 Laravel 应用程序提供全面的安全指导，以防范常见漏洞。

激活时机

• 添加身份验证或授权功能时
• 处理用户输入和文件上传时
• 构建新的 API 端点时
• 管理密钥和环境设置时
• 加固生产环境部署时

工作原理

• 中间件提供基础防护（通过 VerifyCsrfToken 实现 CSRF 防护，通过 SecurityHeaders 实现安全标头）
• 守卫和策略强制执行访问控制（auth:sanctum、$this->authorize、策略中间件）
• 表单请求在数据到达服务层之前进行验证和整形（如 UploadInvoiceRequest）
• 速率限制在身份验证控制之外增加了滥用防护（RateLimiter::for('login')）
• 数据安全性来自加密类型转换、批量赋值保护和签名路由（URL::temporarySignedRoute + signed 中间件）

核心安全设置

• 生产环境中 APP_DEBUG=false
• APP_KEY 必须设置，并在泄露后轮换
• 设置 SESSION_SECURE_COOKIE=true 和 SESSION_SAME_SITE=lax（敏感应用可设为 strict）
• 配置受信任的代理以正确检测 HTTPS

会话和 Cookie 加固

• 设置 SESSION_HTTP_ONLY=true 防止 JavaScript 访问
• 对于高风险流程使用 SESSION_SAME_SITE=strict
• 在登录和权限变更时重新生成会话

身份验证与令牌

• 使用 Laravel Sanctum 或 Passport 进行 API 身份验证
• 对于敏感数据，优先使用具有刷新流程的短期令牌
• 在登出或账户被入侵时撤销令牌

路由保护示例：

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->get('/me', function (Request $request) {
    return $request->user();
});

密码安全

• 使用 Hash::make() 对密码进行哈希处理，切勿存储明文密码
• 使用 Laravel 的密码代理进行重置流程

use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\Rules\Password;

$validated = $request->validate([
    'password' => ['required', 'string', Password::min(12)->letters()->mixedCase()->numbers()->symbols()],
]);

$user->update(['password' => Hash::make($validated['password'])]);

授权：策略与门卫

• 使用策略进行模型级别的授权
• 在控制器和服务中强制执行授权

$this->authorize('update', $project);

使用策略中间件进行路由级别强制执行：

use Illuminate\Support\Facades\Route;

Route::put('/projects/{project}', [ProjectController::class, 'update'])
    ->middleware(['auth:sanctum', 'can:update,project']);

验证与数据清洗

• 始终使用表单请求验证输入
• 使用严格的验证规则和类型检查
• 永远不要信任请求负载中的派生字段

批量赋值保护

• 使用 $fillable 或 $guarded，避免使用 Model::unguard()
• 优先使用 DTO 或显式属性映射

SQL 注入防护

• 使用 Eloquent 或查询构造器的参数绑定
• 除非绝对必要，否则避免使用原生 SQL

DB::select('select * from users where email = ?', [$email]);

XSS 防护

• Blade 默认转义输出（{{ }}）
• 仅在处理可信的、已清理的 HTML 时使用 {!! !!}
• 使用专用库清理富文本内容

CSRF 防护

• 保持 VerifyCsrfToken 中间件启用
• 在表单中包含 @csrf，并为 SPA 请求发送 XSRF 令牌

对于使用 Sanctum 的 SPA 身份验证，确保配置了有状态请求：

// config/sanctum.php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost')),

文件上传安全

• 验证文件大小、MIME 类型和扩展名
• 如果可能，将上传文件存储在公共路径之外
• 根据需要扫描文件是否存在恶意软件

final class UploadInvoiceRequest extends FormRequest
{
    public function authorize(): bool
    {
        return (bool) $this->user()?->can('upload-invoice');
    }

    public function rules(): array
    {
        return [
            'invoice' => ['required', 'file', 'mimes:pdf', 'max:5120'],
        ];
    }
}

$path = $request->file('invoice')->store(
    'invoices',
    config('filesystems.private_disk', 'local') // 将其设置为非公共磁盘
);

速率限制

• 在认证和写入端点上应用 throttle 中间件
• 对登录、密码重置和 OTP 使用更严格的限制

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('login', function (Request $request) {
    return [
        Limit::perMinute(5)->by($request->ip()),
        Limit::perMinute(5)->by(strtolower((string) $request->input('email'))),
    ];
});

密钥与凭证

• 切勿将密钥提交到源代码控制
• 使用环境变量和密钥管理器
• 在密钥泄露后轮换密钥并使会话失效

加密属性

使用加密类型转换来保护存储的敏感列。

protected $casts = [
    'api_token' => 'encrypted',
];

安全标头

• 在适当的地方添加 CSP、HSTS 和框架保护
• 使用受信任的代理配置来强制执行 HTTPS 重定向

设置标头的中间件示例：

use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

final class SecurityHeaders
{
    public function handle(Request $request, \Closure $next): Response
    {
        $response = $next($request);

        $response->headers->add([
            'Content-Security-Policy' => "default-src 'self'",
            'Strict-Transport-Security' => 'max-age=31536000', // 仅在所有子域名都是 HTTPS 时添加 includeSubDomains/preload
            'X-Frame-Options' => 'DENY',
            'X-Content-Type-Options' => 'nosniff',
            'Referrer-Policy' => 'no-referrer',
        ]);

        return $response;
    }
}

CORS 与 API 暴露

• 在 config/cors.php 中限制来源
• 避免对认证路由使用通配符来源

// config/cors.php
return [
    'paths' => ['api/*', 'sanctum/csrf-cookie'],
    'allowed_methods' => ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
    'allowed_origins' => ['https://app.example.com'],
    'allowed_headers' => [
        'Content-Type',
        'Authorization',
        'X-Requested-With',
        'X-XSRF-TOKEN',
        'X-CSRF-TOKEN',
    ],
    'supports_credentials' => true,
];

日志与个人身份信息 (PII)

• 切勿记录密码、令牌或完整的卡数据
• 在结构化日志中编辑敏感字段

use Illuminate\Support\Facades\Log;

Log::info('用户更新了个人资料', [
    'user_id' => $user->id,
    'email' => '[已编辑]',
    'token' => '[已编辑]',
]);

依赖安全

• 定期运行 composer audit
• 谨慎固定依赖版本，并在出现 CVE 时及时更新

签名 URL

使用签名路由来实现临时的、防篡改的链接。

use Illuminate\Support\Facades\URL;

$url = URL::temporarySignedRoute(
    'downloads.invoice',
    now()->addMinutes(15),
    ['invoice' => $invoice->id]
);

use Illuminate\Support\Facades\Route;

Route::get('/invoices/{invoice}/download', [InvoiceController::class, 'download'])
    ->name('downloads.invoice')
    ->middleware('signed');