security-rust

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

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

项目宠物 甲哨 Sentri（docs/pet.svg）—— 32 片甲片对应 32 个检测器，只报告，不拦截。

项目宠物：甲哨 Sentri

一只举着放大镜与告示牌的哨蟹。人设不是装饰，是把本库的设计画出来了：

座右铭：只报告，不拦截。

形象以 include_str! 打进库里（零运行时开销，不用就不链接），ASCII 版可直接打进终端或日志：

println!("{}", security_rust::pet::ASCII);

项目结构

security-rust/
├── src/
│   ├── lib.rs              Detector trait（唯一契约）、regex_detect 辅助、crate 文档
│   ├── scanner.rs          Scanner / ScannerBuilder：默认装配 32 个检测器
│   ├── result.rs           DetectionResult / AttackCategory / Severity
│   ├── score.rs            风险评分：权重累加 + 分档 → RiskAssessment
│   ├── pet.rs              项目宠物形象（NAME / TAGLINE / ASCII / SVG）
│   ├── injection/          11 个注入类检测器
│   ├── protocol/           11 个协议类检测器
│   ├── data/               7 个数据类检测器
│   ├── file/               3 个文件类检测器
│   ├── session/            SessionGuard + SessionStore（guard / store / geo）
│   └── throttle/           Throttle + ThrottleStore（guard / store）
├── tests/                  7 个集成测试套件：会话、限流、生命周期、不变量、鲁棒性、端到端、多维限流
├── examples/
│   ├── waf.rs              端到端流水线示例（扫描 → 限流 → 会话 → 处置）
│   └── axum_middleware.rs  axum 中间件接入参考
├── docs/
│   ├── API.md              完整 API 参考
│   ├── OWASP-COVERAGE.md   与 OWASP 各类攻击的覆盖对照
│   ├── pet.svg             项目宠物形象
│   ├── diagrams/           架构 / 功能 / 生命周期三张图（SVG）
│   ├── i18n/               12 语言 README 与 API 文档
│   └── ...                 打赏码、代码评审与测试报告
└── Cargo.toml              唯一的运行时依赖：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 交调用方处置

权衡

设计架构

五层自上而下：调用方（WAF / 网关 / 审计 / CLI）→ 检测层（Scanner 持有 Vec<Box<dyn Detector>>，四大类共 32 个）→ 评分层（score::assess）→ 守卫层（SessionGuard / Throttle，各自绑定一个 store trait）→ 存储抽象（内置 MemoryStore，Redis 由调用方实现）。

Detector trait 是检测层唯一的契约：fn detect(&self, input: &str) -> Option<DetectionResult>。session / throttle / score 不实现它 —— 它们要么输入不是单个字符串（token + 指纹 + 位置 + 时间），要么消费的是扫描结果而非原始输入，因此各自独立作答（详见下节）。图中右侧那条红色回传线是本库的边界：判定结果交回调用方执行，库自己不碰请求。

模块职责

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

检测结果结构

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

实现功能

32 个检测器按四大类装配，Scanner::default() 零配置全量启用；下表逐个列出各自覆盖的攻击模式与严重度。严重度只描述单条命中的危害，聚合后的整体风险看 Scanner::assess()。

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

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

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

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

生命周期

三条生命周期互相独立，唯一的交汇点是调用方的请求处理函数：

两条容易踩的边界：

• remaining == 0 表示本请求应被拒绝 —— 额度已耗尽，不是「还能再试一次」。要写进 X-RateLimit-* 时别写反。
• 存储故障的处置两边相反：SessionGuard fail-closed（StoreUnavailable ⇒ Block，绝不放行，否则攻击者诱导故障就能换掉一整类判定）；Throttle fail-open（Unavailable 交调用方，后端抖动时把全体用户挡在门外是自我 DoS，主闸门 SessionGuard 仍在拦）。这是写死的设计，不是漏写的兜底。

使用说明

零配置即可使用：

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>

风险评分把命中列表汇成一个等级，避免多条低危信号被静默忽略：

let assessment = scanner.assess("=cmd|' /C calc'!A0 `cat /etc/passwd` ../../../etc/passwd");
// assessment.level   >= RiskLevel::High
// assessment.results >= 3
// assessment.score   — 原始加权分

完整 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

# 测试（494 个：365 单元 + 128 集成 + 1 文档测试）
cargo test

# 端到端流水线示例（扫描 → 限流 → 会话 → 处置）
cargo run --example waf

# 代码检查
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