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/                  8 个集成测试套件：会话、限流、生命周期、不变量、鲁棒性、端到端、多维限流、现实语料
├── 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 交调用方处置

权衡

两档判定：强信号与弱信号

检测器不是「命中即按声明严重度上报」。32 个检测器里有 18 个存在弱信号档（命中一律上报固定 Severity::Low）：其中 17 个同时有强档与弱档 —— 15 个用源码里的 STRONG_PATTERNS / WEAK_PATTERNS 两个静态常量分档，cors / hpp 的强档是内联的条件判定；剩下 dns_rebinding 全档皆弱：

两档走的是同一个检测器、同一个 attack_type，只有 severity 不同。弱信号仍然被检出，不会静默漏报：scan() 里看得到，assess() 里照常累加。

对调用方的直接后果是：单条弱信号不构成拒绝理由。 参考流水线（examples/waf.rs:166）的拒绝线是 risk.level >= RiskLevel::High（40 分），而单条弱信号只有 5 分，进不了这一支。要看穿弱信号背后的攻击，得看 assess() 把多个检测器的命中叠起来之后的分数：

let scanner = Scanner::default();

// 三条都是弱信号，各自命中不同的检测器 —— 叠起来才升级
let a = scanner.assess("<script src=\"/app.js\"></script>\n../config\n__proto__");
// a.results == 3，a.score == 15（3 × Low）→ RiskLevel::Medium
// 仍低于 High；同一请求里再叠加别的命中就会越线

被降为弱信号的是「出现即正常」的那类 token，例如：

上表只是举例。判据是形态不是文件名：同样是 ../，单级 ../x 是弱信号、多级 ../../ 是强信号（src/file/path_traversal.rs）。完整名单见各检测器的 WEAK_PATTERNS，以及下节各表中的 弱 标记。

设计架构

五层自上而下：调用方（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()。

表内标注 弱 的模式属弱信号，上报 Severity::Low（5 分），不单独越过拒绝线（详见上节）。「严重度」一列为该检测器能达到的上限；标了 弱 的检测器同时存在强档与弱档，上半部分仍是其声明的等级。全档皆弱的检测器（dns_rebinding）上限即为 Low。

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

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

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

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

已知上限

以下几处是已知且有意保留的边界，不是待修的缺陷。改动前请先读依据 —— 每一条都出自实测，且都有人试过收紧后撞上同一堵墙。

dns_rebinding 只上报，不拦截

它的判据是「Host: 头里出现内网地址」，而同一个形状也正是 k8s 里每个 pod 间调用（Host: 10.244.1.5:8080）、每次本地开发（Host: localhost:8000）、每个 Docker 容器网络请求（172.18.0.2）。真正的 rebinding 看的是「公网域名 + 解析结果指向内网」，而浏览器发出的 Host 恰恰是那个公网域名 —— 单条字符串里看不到解析历史，本检测器测的形态与攻击形态并不重合，收紧成什么样都还是「内网地址出现」。因此整个检测器只有弱档，一律 Low；无论叠加多少条，它自己都不会越过拒绝线。防护在解析之后比对结果 IP，不在字符串层。

这个库扫不动自己的源码、测试和文档

签名扫描器的天花板：把仓库目录下所有 UTF-8 文本文件（跳过 target/ 与 .git/）逐个喂给 Scanner，实测 383 个文件里有 85 个越过拒绝线，而它们按构造全都含有攻击串 —— 测试载荷、检测器源码里的正则字面量自身，以及列出这些模式的 README 与 OWASP 表格。一份 README 不会因为写了 (a+)+ 而变成缺陷。要扫自己的产物，得先把这些语料排除，或者换一个判据。

upload 一律把 <%@ / <?php 报为 Critical

该检测器的契约是「这个 blob 是服务端可执行代码」—— 出现即成立，因此不设强弱分层。JSP 页面与 JSP webshell 的前导字节逐字节相同（<%@ page language="java" … %> 与 <%@ page import="java.io.*" %> 是同一形态），把 <%@/<%= 降档等于让 webshell 落到拒绝线以下 —— 那是换个方式删检测。代价是扫描正在对外提供的页面（而不是上传的文件）时也会命中，那属于输入域不符 —— 命中消息 Malicious file upload detected 已点明域。

path_traversal 把 (?:\.\./){2,} 报为 Critical

monorepo 里的深层相对路径（from '../../../shared/domain'）会命中。没有进一步收紧，因为唯一能把它与攻击分开的约束是目标文件名列表（../etc/passwd 那一类），而那只覆盖系统文件 —— 攻方换一个 LFI 目标就绕过去了。

生命周期

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

两条容易踩的边界：

• 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("<img src=x onerror=alert(1)>");
// [CRITICAL] XSS cross-site scripting detected — offset: 11, pattern: onerror=

// 弱信号：token 出现而已 ⇒ 固定 Low，不单独越过拒绝线（见「两档判定」）
let weak = scanner.scan("<script src=\"/app.js\"></script>");
// [LOW] XSS tag present (weak signal) — 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

# 测试（594 个：445 单元 + 148 集成 + 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