# Rust-Gateway-WAF

**Repository Path**: sycapple/Rust-Gateway-WAF

## Basic Information

- **Project Name**: Rust-Gateway-WAF
- **Description**: No description available
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 2
- **Created**: 2026-03-21
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rust Gateway WAF

![Version](https://img.shields.io/badge/version-0.1.0-blue)
![Language](https://img.shields.io/badge/language-Rust-orange)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey)

轻量、可审计、规则驱动的 Rust Web 应用防火墙（WAF）。

它作为独立反向代理工作：请求先经过 WAF 检测，再转发到后端服务。适合用于本地安全实验、规则验证、教学演示和小型服务前置防护。

## Why This Project

- 单进程 Rust 实现，易部署、易调试
- 规则文件外置，便于快速迭代与灰度验证
- 拦截链路清晰，方便定位误报与漏报
- 自带全覆盖测试脚本，可一键验证核心防护能力

## Core Features

- 请求检测链路：
  `IP 白名单 -> IP 黑名单 -> CC 限流 -> 扫描器 Header -> URL 白名单 -> UA -> URL -> Query Args -> Cookie -> POST Body -> multipart 后缀`
- 支持规则文件：
  `wafconf/url`、`wafconf/args`、`wafconf/post`、`wafconf/cookie`、`wafconf/user-agent`、`wafconf/whiteurl`
- 拦截动作：返回 `403`（规则命中）、`503`（CC 触发）
- 安全日志：按日期输出命中日志到 `logs/`

## How It Works

```text
Client
  |
  v
Rust WAF (axum)
  |-- 读取配置(config.toml)
  |-- 加载并编译规则(wafconf/*)
  |-- 逐阶段检测请求
  |-- 命中则记录日志并拦截
  v
Upstream Backend
```

关键实现位置：
- 启动入口：`src/main.rs`
- 检测主链路：`src/waf.rs`
- 反向代理：`src/proxy.rs`
- 规则加载：`src/rules.rs`
- CC 限流：`src/rate_limiter.rs`
- 攻击日志：`src/logging.rs`

## Quick Start

### 1) Prerequisites

- Rust `1.75+`
- `cargo`
- 可选：`docker`（仅用于启动测试后端）

### 2) Build

```bash
cargo build --release
```

### 3) Start Backend (for local experiments)

```bash
make up
```

默认后端地址：`http://127.0.0.1:8080`

### 4) Start WAF

```bash
make run
```

默认 WAF 地址：`http://127.0.0.1:8081`

## Configuration

主配置文件：`config.toml`

常用项：
- `rule_path`: 规则目录
- `log_dir`: 命中日志目录
- `url_deny` / `cookie_match` / `post_match` / `white_module`: 功能开关
- `ip_whitelist` / `ip_blocklist`: 白/黑名单
- `cc_deny` / `cc_rate`: CC 限流（如 `100/60`）
- `listen`: WAF 监听地址
- `upstream`: 上游服务地址

## Full Experiment Script

项目提供了全覆盖能力测试脚本：

```bash
make test-all
```

等价命令：

```bash
./scripts/test_all_features.sh
```

可选端口（避免冲突）：

```bash
BACKEND_PORT=28080 WAF_PORT=28081 make test-all
```

## Experiment Coverage

`test_all_features.sh` 覆盖以下防护点：

- 正常请求放行
- URL 白名单绕过
- 扫描器 Header 拦截（`Acunetix-Aspect`、`X-Scan-Memo`）
- UA 拦截
- URL 拦截
- Query Args 拦截
- Cookie 拦截
- POST Body 拦截
- multipart 危险后缀拦截（`.php`）
- IP 黑名单拦截
- IP 白名单优先放行
- CC 超频拦截

## Sample Test Output

以下是一次成功运行的输出形态（示例）：

```text
[Phase A] baseline rules
...
[Phase B] ip blocklist
...
[Phase C] ip whitelist precedence
...
[Phase D] cc deny
...
Summary: total=16 pass=16 fail=0
Result: ALL PASS
```

## Repository Layout

```text
.
├── Cargo.toml
├── Cargo.lock
├── config.toml
├── docker-compose.yml
├── Makefile
├── src/
├── wafconf/
├── scripts/test_all_features.sh
└── logs/
```

## Useful Commands

```bash
make all      # 启动后端 + 编译
make run      # 运行 WAF
make test-all # 全覆盖测试
make logs     # 查看后端日志
make down     # 停止后端
```