attack-detection

English | 中文

Rust 编写的攻击检测库，覆盖注入攻击、协议攻击、数据/序列化攻击、文件/敏感数据泄露 4 大类共 27 个检测器。零外部框架依赖，纯字符串扫描。

设计思路

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

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

架构原则

• 单一职责 — 每个检测器只管一种攻击类型，内部持有编译好的正则模式集
• 统一接口 — Detector trait 是所有检测器的唯一契约：fn detect(&self, input: &str) -> Option<DetectionResult>
• 默认覆盖 — Scanner::default() 一键装配全部 27 个检测器，零配置可用
• 可选配置 — Scanner::builder() 支持按需定制，通过 .with_detector() 选择性装配检测器

权衡

设计架构

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

模块职责

检测结果结构

pub struct DetectionResult {
    pub attack_type: String,      // "xss", "sql_injection" ...
    pub category: AttackCategory, // Injection | Protocol | Data | File
    pub severity: Severity,       // Critical | High | Medium | Low
    pub matched_pattern: String,  // 匹配到的具体模式片段
    pub offset: usize,            // 输入中的字节偏移
    pub message: String,          // 人类可读说明
}

实现功能

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

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

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

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

使用说明

安装

[dependencies]
attack-detection = { path = "." }

快速开始

use attack_detection::Scanner;

fn main() {
    // 零配置：装配全部 27 个检测器
    let scanner = Scanner::default();

    // 扫描输入，返回所有检测到的攻击
    let results = scanner.scan("<script>alert('xss')</script>");

    for r in &results {
        println!("[{}] {} — offset: {}, pattern: {}",
            r.severity, r.message, r.offset, r.matched_pattern);
    }
    // 输出:
    // [CRITICAL] XSS cross-site scripting detected — offset: 0, pattern: <script>
}

选择性扫描

let scanner = Scanner::default();

// 只运行指定的检测器
let results = scanner.scan_with(
    "1 UNION SELECT password FROM users",
    &["sql_injection", "xss"],
);

自定义配置

use attack_detection::injection::{XssDetector, SqlInjectionDetector};

// 通过 builder 只装配需要的检测器
let scanner = Scanner::builder()
    .with_detector(Box::new(XssDetector))
    .with_detector(Box::new(SqlInjectionDetector))
    .build();

只装配部分检测器

use attack_detection::injection::{XssDetector, SqlInjectionDetector};

let scanner = Scanner::builder()
    .with_detector(Box::new(XssDetector))
    .with_detector(Box::new(SqlInjectionDetector))
    .build();

严重度展示

use attack_detection::Severity;

let r = &results[0];
println!("{}", r.severity);  // CRITICAL | HIGH | MEDIUM | LOW

性能

Release 构建下，单检测器扫描 ~100ns/次（RegexSet 预编译），全量 27 检测器扫描约 ~5μs/次。适合高吞吐量场景（API 网关、日志管道）。

开发

# 构建
cargo build --release

# 测试（46 个集成测试）
cargo test

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

许可

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

English

Full English documentation is available at README.en.md.

A pure Rust attack detection library with 27 detectors across 4 categories. Zero framework dependencies — just regex and thiserror.

Categories: Injection (10), Protocol (9), Data (5), File (3).

Key API surfaces are in English (type names, method names, error messages).