security-rust

🌐 Language: English · 한국어 · Русский · Deutsch · Français · Español · Português · हिन्दी · العربية · বাংলা · Bahasa Indonesia · 日本語

Rust 编写的攻击检测库，覆盖注入攻击、协议攻击、数据/序列化攻击、文件/敏感数据泄露 4 大类共 32 个检测器；另提供会话安全、限流封禁、风险评分三个有状态安全模块。零外部框架依赖，[dependencies] 只有 regex。

设计思路

为什么用「检测」而非「拦截」

32 个检测器定位为纯输入扫描器——接收字符串，返回结构化检测结果，不绑定任何 Web 框架，不做 HTTP 请求/响应解析。这样你可以把它嵌入到任何链路中：WAF 规则引擎、日志审计、API 网关前置校验、CLI 安全扫描工具等。

会话安全（session）与限流封禁（throttle）是有状态、身份相关的，因此与检测器分开：它们要读写的输入是「token + 指纹 + 位置 + 时间」这类复合值，还要访问存储后端，Detector::detect(&str) 表达不了，所以不实现 Detector trait。两者的共同点仍是「不替你拦截」——session 给处置建议、throttle 给额度与封禁状态，是否拒绝请求由调用方决定。

架构原则

• 单一职责 — 每个检测器只管一种攻击类型，内部持有编译好的正则模式集
• 统一接口 — Detector trait 是所有检测器的唯一契约：fn detect(&self, input: &str) -> Option<DetectionResult>
• 默认覆盖 — Scanner::default() 一键装配全部 32 个检测器，零配置可用
• 可选配置 — Scanner::builder() 支持按需定制，通过 .with_detector() 选择性装配检测器
• 状态外置 — session / throttle 用 SessionStore / ThrottleStore trait 抽象存储，多实例部署实现该 trait 接 Redis 即可，库自身不绑定任何后端
• 零新增依赖 — [dependencies] 始终只有 regex = "1"：token 与签名由调用方提供，位置由调用方解析
• fail-closed 是默认，例外要说明理由 — SessionGuard 在存储后端故障时返回 Decision::Block，绝不放行；Throttle 是唯一例外，故障时返回 Unavailable 交调用方处置

权衡

设计架构

                       ┌──────────────────────────────────┐
                       │             Scanner              │
                       │  ┌────────────────────────────┐  │
    user input ───────►│  │ scan(input)                │  │      Vec<DetectionResult>
                       │  │ scan_with(input, &[...])   │──┼──►──────────────────────►
                       │  └─────────────┬──────────────┘  │
                       │                │                  │
                       │  ┌─────────────▼──────────────┐  │
                       │  │   Vec<Box<dyn Detector>>   │  │
                       │  │   ├─ XssDetector           │  │
                       │  │   ├─ SqlInjectionDetector  │  │
                       │  │   ├─ ... ×32               │  │
                       │  └────────────────────────────┘  │
                       └──────────────┬───────────────────┘
                                      │
       ┌──────────────────────────────┐
       │       Detector trait         │
       │  fn name(&self) -> &str      │
       │  fn detect(&self, &str)      │
       │       -> Option<Result>      │
       └──────────────┬───────────────┘
                      │
       ┌──────────────┼──────────────┐
       │              │              │
  ┌────┴────┐  ┌──────┴──────┐  ┌───┴────┐  ┌────┴────┐
  │injection│  │  protocol   │  │  data  │  │  file   │
  │  11 个  │  │   11 个     │  │ 7 个   │  │  3 个   │
  └─────────┘  └─────────────┘  └────────┘  └─────────┘

session / throttle / score 不在这张图里：它们不实现 Detector，输入也不是单个字符串。score 消费上图的扫描结果，session / throttle 则各自独立作答（详见下节）。

模块职责

session 与 throttle 是有状态的，不对应任何检测器：它们不在 Scanner 的装配范围内，也不能用 scan() 调用。

检测结果结构

DetectionResult 结构化返回 attack_type、category、severity、matched_pattern、offset、message 六项字段。Scanner::assess() 在此之上给出聚合后的风险等级（RiskAssessment）。完整定义见 API 参考。

实现功能

注入类攻击（11 个检测器）

协议与请求攻击（11 个检测器）

数据与序列化攻击（7 个检测器）

文件与敏感数据（3 个检测器）

使用说明

零配置即可使用：

use security_rust::Scanner;

let scanner = Scanner::default();
let results = scanner.scan("<script>alert('xss')</script>");
// [CRITICAL] XSS cross-site scripting detected — offset: 0, pattern: <script>

完整 API 参考（安装、选择性扫描、自定义配置、风险评分、严重度展示、会话安全、限流与封禁、性能）见 API 参考。

会话安全（session）

use security_rust::session::{Decision, MemoryStore, RequestContext, SessionConfig, SessionGuard};

let guard = SessionGuard::new(MemoryStore::new(), SessionConfig::default());

let login = RequestContext {
    token: "tok-abc",
    subject: "u-1",
    fingerprint: "ip=1.2.3.4|ua=curl",   // 客户端指纹，登录时绑定
    location: Some("CN-BJ"),
    coords: Some((39.9042, 116.4074)),
    signature: None,                      // MAC 由调用方签发
    at: None,
};

// 登录：建会话 + 绑指纹 + 记位置；异地只影响 verdict，不阻断登录
guard.bind(&login, 1_700_000_000).unwrap();

// 每请求校验：同一个 token，换一个指纹 ⇒ 客户端劫持
let verdict = guard.verify(&RequestContext { fingerprint: "ip=5.6.7.8|ua=curl", ..login }, 1_700_000_010);

match verdict.decision {
    Decision::Allow => { /* 放行 */ }
    Decision::Challenge => { /* 放行但要求二次验证：异地、时钟偏离、签名意外 */ }
    Decision::Block => { /* 拒绝 */ }
}

限流与封禁（throttle）

use security_rust::throttle::{MemoryThrottleStore, Throttle, ThrottleConfig, ThrottleDecision};

let throttle = Throttle::new(MemoryThrottleStore::new(), ThrottleConfig::default());
let key = "acct:u-1"; // key 由调用方构造并规范化，不要直接拿原始输入当 key
let now = 1_700_000_000;

// 真实请求有两个维度：IP 与账户。check_any 一次问完，按严格度合并
match throttle.check_any(&["ip:1.2.3.4", key], now) {
    // remaining 可写进 X-RateLimit-*；**remaining == 0 表示本请求应被拒绝**
    ThrottleDecision::Allow { remaining } => { /* 剩余额度 remaining */ }
    // now >= until 即视为已解封
    ThrottleDecision::Banned { until } => { /* 封禁中，until 解封 */ }
    // 后端故障：本模块不替调用方做决定（建议放行 + 告警）
    ThrottleDecision::Unavailable => { /* 限流后端不可用 */ }
}

// 认证失败记一笔：达到 threshold 即封禁。返回 ThrottleOutcome（两态），
// 存储故障走 Err —— 不必为一个永不执行的 Unavailable 臂写死代码
let _ = throttle.record_failure(key, now);

开发

# 构建
cargo build --release

# 测试（462 个：354 单元 + 108 集成）
cargo test

# 代码检查
cargo clippy -- -D warnings

打赏 / 赞助

如果这个项目对你有帮助，欢迎打赏支持（自愿）。

支付宝	微信支付

全球转账（国际汇款）

【收款人信息】

• 收款人姓名：WANG KEXUN
• 收款账户号码：881015918251

【收款银行】

• ZA Bank SWIFT Code：AABLHKHHXXX
• 银行名称：ZA Bank Limited
• 银行编号：387
• 银行地址：Core F, Cyberport 3, 100 Cyberport Road, Hong Kong

【跨境汇款代理银行（如需）】

请留意，此为跨境汇款代理银行（中转银行）信息，非收款银行信息。请向汇款银行查询是否需要提供跨境汇款代理银行信息。

汇入港元、人民币及美元的代理银行为 Citibank：

• 银行名称：Citibank N.A. Hong Kong
• SWIFT Code：CITIHKHXXXX
• 银行编号：006
• 分行名称：Hong Kong Branch
• 分行编号：391
• 银行地址：Citibank Tower, Citibank Plaza, 3 Garden Road, Central, Hong Kong

汇入其他币种时的代理银行为 BNY Mellon：

• 银行名称：THE BANK OF NEW YORK MELLON
• SWIFT Code：IRVTUS3NXXX
• 银行地址：THE BANK OF NEW YORK MELLON, 240 GREENWICH STREET, NEW YORK, United States

许可

MIT — Copyright (c) 2026 erik erik@erik.xyz — https://erik.xyz