rust-user-api/docs/security-features.md

安全中间件功能文档

概述

本项目实现了全面的API安全中间件系统，包括限流、安全检查、安全头设置和认证失败处理等功能。

主要功能

1. 限流中间件 (Rate Limiting)

• 功能: 基于IP地址的请求频率限制
• 默认配置: 每分钟60个请求
• 实现: 使用 governor crate 实现令牌桶算法
• 特性:
  • 基于IP地址的独立限流
  • 可配置的请求频率
  • 自动清理过期记录

2. 安全检查中间件 (Security Check)

• 功能: 检测和阻止可疑请求模式
• 检测模式:
  • SQL注入尝试 (union, select, insert, update, delete, drop, create, alter)
  • XSS攻击 (<script>, javascript:, vbscript:, onload=, onerror=)
  • 路径遍历 (../, ../\, /etc/, /proc/, /sys/)
  • 命令注入 (cmd, exec, system, eval, base64_decode)
  • 敏感账户名 (admin, root, administrator, sa, dbo)

3. 安全头中间件 (Security Headers)

• 功能: 自动添加安全相关的HTTP头
• 添加的头:
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: strict-origin-when-cross-origin
  • Content-Security-Policy: default-src 'self'
  • Permissions-Policy: geolocation=(), microphone=(), camera=()
• 移除的头: Server, X-Powered-By

4. 暴力破解检测

• 功能: 检测和防止暴力破解攻击
• 配置:
  • 检测窗口: 5分钟
  • 最大尝试次数: 5次
  • 封禁时间: 1小时
• 触发条件:
  • 可疑请求模式
  • 认证失败（登录相关端点）

5. IP封禁系统

• 功能: 自动封禁恶意IP地址
• 特性:
  • 基于暴力破解检测的自动封禁
  • 可配置的封禁时间
  • 自动清理过期封禁记录
  • 审计日志记录

6. JWT认证中间件

• 功能: JWT令牌验证和用户认证
• 特性:
  • Bearer token 提取
  • JWT签名验证
  • 过期时间检查
  • 用户ID注入到请求上下文

配置选项

pub struct SecurityConfig {
    /// 每分钟请求限制
    pub requests_per_minute: u32,
    /// 暴力破解检测窗口（秒）
    pub brute_force_window: u64,
    /// 暴力破解最大尝试次数
    pub brute_force_max_attempts: u32,
    /// IP封禁时间（秒）
    pub ban_duration: u64,
    /// 启用CORS
    pub enable_cors: bool,
    /// 允许的源
    pub allowed_origins: Vec<String>,
    /// 启用安全头
    pub enable_security_headers: bool,
    /// 最大请求体大小（字节）
    pub max_request_size: usize,
}

使用示例

基本集成

use rust_user_api::middleware::{SecurityConfig, SecurityState};

// 创建安全配置
let security_config = SecurityConfig::default();
let security_state = Arc::new(SecurityState::new(security_config));

// 应用中间件
let app = Router::new()
    .layer(axum::middleware::from_fn_with_state(
        security_state.clone(),
        rate_limiting_middleware,
    ))
    .layer(axum::middleware::from_fn_with_state(
        security_state.clone(),
        security_check_middleware,
    ))
    .layer(axum::middleware::from_fn(
        security_headers_middleware,
    ));

JWT认证

use rust_user_api::middleware::{create_jwt, jwt_auth_middleware};

// 创建JWT token
let token = create_jwt("user_id_123")?;

// 应用JWT认证中间件
let protected_routes = Router::new()
    .route("/protected", get(protected_handler))
    .layer(axum::middleware::from_fn(jwt_auth_middleware));

监控和日志

审计日志

所有安全事件都会记录到审计日志中：

• 可疑请求模式检测
• IP封禁事件
• 限流触发
• 认证失败

指标收集

• 请求总数
• 错误率
• 平均响应时间
• 系统资源使用情况

安全最佳实践

1. 定期更新JWT密钥: 在生产环境中使用强密钥并定期轮换
2. 监控审计日志: 定期检查安全事件和异常模式
3. 调整限流参数: 根据实际业务需求调整限流配置
4. 网络层防护: 结合防火墙和CDN提供多层防护
5. 定期安全审计: 定期检查和更新安全配置

性能考虑

• 使用高效的数据结构（DashMap）进行并发访问
• 自动清理过期记录避免内存泄漏
• 异步处理避免阻塞请求
• 可配置的检测模式减少不必要的计算

扩展性

系统设计支持：

• 自定义可疑模式
• 可插拔的认证方式
• 灵活的配置选项
• 多种存储后端支持

测试

项目包含全面的安全功能测试：

# 运行安全测试
cargo test security_tests

# 运行所有测试
cargo test

故障排除

常见问题

1. 限流过于严格: 调整 requests_per_minute 参数
2. 误报可疑模式: 检查和调整正则表达式模式
3. JWT验证失败: 检查密钥配置和token格式
4. 性能问题: 监控内存使用和清理频率

调试技巧

• 启用详细日志记录
• 使用监控API检查系统状态
• 检查审计日志了解安全事件
• 使用测试工具验证配置