# zihao_waf

**Repository Path**: homecommunity_admin/zihao_waf

## Basic Information

- **Project Name**: zihao_waf
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-26
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 梓豪 WAF 系统

企业级 Web 应用防火墙（WAF）系统，支持高并发（10k+ QPS）、低延迟、稳定性保障。

## 架构概述

系统采用三层解耦架构：

1. **数据转发层 (Data Plane - C++)**: 基于 Drogon 框架的高性能反向代理
2. **管理控制层 (Control Plane - Python)**: 基于 FastAPI 的策略管理和日志分析
3. **展示层 (View Plane - Vue2)**: 基于 Vue 2.7 + Element UI 的管理界面

## 项目结构

```
zihao_waf/
├── backend/          # Python 后端（FastAPI）
│   ├── models.py     # 数据库模型
│   ├── database.py   # 数据库初始化
│   ├── rule_sync.py  # 规则文件同步
│   └── main.py       # FastAPI 主应用
├── data_plane/       # C++ 引擎（Drogon）
│   ├── main.cpp
│   ├── WafFilter.h
│   ├── WafFilter.cc
│   ├── CMakeLists.txt
│   └── conanfile.txt # Conan 依赖配置
├── waf_web/          # Vue2 前端
│   └── src/
├── deploy/           # 部署配置
│   ├── install.sh    # 安装脚本
│   ├── systemd/      # Systemd 服务文件
│   └── logrotate/    # 日志轮转配置
└── doc/              # 文档
    ├── waf方案.md
    └── 补充需求.md
```

## 功能特性

### 核心防御功能
- ✅ SQL 注入检测
- ✅ XSS 攻击检测
- ✅ 命令注入检测
- ✅ 路径穿越检测
- ✅ 文件上传检测
- ✅ IP 黑白名单
- ✅ User-Agent 黑名单
- ✅ HTTP 协议合规性检测

### 流量控制
- ✅ CC 攻击防御（频率限制）
- ✅ 自动封禁机制

### 数据安全
- ✅ 敏感信息防泄露（DLP）
- ✅ 状态码屏蔽（500/502/503）

### 运维管理
- ✅ 规则管理（增删改查、开关控制）
- ✅ 实时日志采集
- ✅ 统计数据分析
- ✅ 检测/阻断模式切换
- ✅ Bypass 机制（异常时自动放行）

## 技术栈

- **后端**: FastAPI, SQLAlchemy
- **引擎**: C++17, Drogon 1.9.11, spdlog, jsoncpp
- **前端**: Vue 2.7, Element UI, ECharts
- **依赖管理**: Conan（C++ 包管理器）

## 快速开始

### 前置要求

- **Linux** 操作系统（Ubuntu 20.04+, CentOS 7+）
- Python 3.11+
- Node.js 16+
- C++17 编译器 (GCC 9+ 或 Clang 10+)
- CMake 3.16+
- **Conan** - C++ 包管理器（`pip install conan`）

### 1. 初始化数据库和默认规则

```bash
cd backend
pip install -r requirements.txt
python init_default_rules.py
```

### 2. 启动后端服务

```bash
cd backend
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

后端 API 文档：http://localhost:8000/docs

### 3. 编译 C++ 引擎

```bash
cd data_plane

# 安装 Conan（如果未安装）
pip install conan
conan profile detect --force

# 使用构建脚本（推荐）
chmod +x build.sh
./build.sh                    # Release 构建（默认）
./build.sh --debug            # Debug 构建
./build.sh --clean            # 清理后重新构建
./build.sh -j 4               # 指定并行任务数
./build.sh --help             # 查看所有选项

# 或手动编译
mkdir build && cd build
conan install .. --build=missing -s build_type=Release
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=../conan_toolchain.cmake
cmake --build . -j$(nproc)
```

### 4. 启动 C++ 引擎

```bash
# 方式1：从可执行文件目录运行（推荐）
cd data_plane/build/bin
./zihao_waf

# 方式2：指定配置文件路径（可选）
cd data_plane
./build/bin/zihao_waf /path/to/config/zihao.conf

# 方式3：从项目根目录运行（会自动查找 config/zihao.conf）
cd ..
./data_plane/build/bin/zihao_waf
```

**启动成功标志**：
- 看到 "WAF Engine starting..." 消息
- 看到 "统一配置文件加载成功" 或 "Loading config from: ..."
- 看到 "Internal API port: 8889 (for Python backend)"
- 没有错误信息

**测试连接**：
```bash
# 测试内部 API（8889 端口）
curl http://127.0.0.1:8889/api/internal/health
```

**如果连接被拒绝**：
1. 检查程序是否正在运行：`ps aux | grep zihao_waf`
2. 检查端口是否被占用：`netstat -tlnp | grep 8889`
3. 检查配置文件路径是否正确
4. 查看启动日志中的错误信息

详细故障排查请参考 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)

### 清理构建文件

```bash
cd data_plane
chmod +x clean.sh
./clean.sh           # 清理构建目录和生成文件
./clean.sh --conan   # 同时清理 Conan 缓存
./clean.sh --all     # 清理所有文件（包括 Conan 缓存）
```

引擎将在 8889 端口监听（内部 API，供 Python 后端调用）。

### 5. 启动前端

```bash
cd waf_web
npm install
npm run serve
```

前端访问：http://localhost:8080

## 配置说明

### 统一配置文件

编辑 `config/zihao.conf` 来配置 Python 后端和 C++ 引擎：

```json
{
  "python": {
    "host": "0.0.0.0",
    "port": 8000,
    "database": {
      "url": "sqlite:///./waf.db"
    }
  },
  "cpp": {
    "internal_api": {
      "host": "0.0.0.0",
      "port": 8889
    },
    "backend_url": "http://127.0.0.1:8000",
    "rules_file_path": "/var/lib/zihao_waf/rules.json",
    "rules_version_file": "/var/lib/zihao_waf/rules.version",
    "log_path": "/var/log/waf/access.log"
  },
  "waf_client": {
    "api_url": "http://127.0.0.1:8889",
    "timeout": 5
  }
}
```

详细配置说明请参考 [config/README.md](config/README.md)

### 规则同步机制

- Python 后端更新规则时，写入 JSON 文件并更新版本号
- C++ 引擎每秒检查版本文件，发现变化时重新加载规则
- 规则文件路径：`/var/lib/zihao_waf/rules.json`

## 生产环境部署

### 使用安装脚本

```bash
sudo chmod +x deploy/install.sh
sudo ./deploy/install.sh
```

### 手动部署

1. **编译 C++ 引擎**：参考快速开始步骤 3
2. **配置服务**：复制 systemd 服务文件到 `/etc/systemd/system/`
3. **配置日志轮转**：复制 logrotate 配置到 `/etc/logrotate.d/`
4. **启动服务**：
   ```bash
   systemctl start zihao-waf
   systemctl start zihao-waf-backend
   systemctl enable zihao-waf
   systemctl enable zihao-waf-backend
   ```

## API 接口

### 规则管理
- `GET /api/rules` - 获取所有规则
- `POST /api/rules` - 创建规则
- `PUT /api/rules/{id}` - 更新规则
- `DELETE /api/rules/{id}` - 删除规则
- `PATCH /api/rules/{id}/toggle` - 切换规则状态

### IP 管理
- `GET /api/ip/whitelist` - 获取 IP 白名单
- `POST /api/ip/whitelist` - 添加 IP 白名单
- `GET /api/ip/blacklist` - 获取 IP 黑名单
- `POST /api/ip/blacklist` - 添加 IP 黑名单

### 系统配置
- `GET /api/system/config/detection_mode` - 获取检测模式
- `PUT /api/system/config/detection_mode` - 设置检测模式

### 统计信息
- `GET /api/dashboard/stats` - 获取仪表盘统计数据
- `GET /api/logs` - 获取访问日志

完整 API 文档：http://localhost:8000/docs

## 责任链检查顺序

C++ 引擎采用责任链模式，按以下顺序执行检查：

1. **IP 白名单检查**（最快，直接放行）
2. **IP 黑名单检查**（快速阻断）
3. **CC/频率限制检查**（内存计数器）
4. **扫描器/User-Agent 检查**
5. **HTTP 协议合规性检查**
6. **文件上传检查**
7. **SQLi/XSS/RCE 检查**（正则匹配）

任何一步触发阻断，立即停止处理并返回 403。

## 故障排除

### Conan 依赖问题

```bash
# 检查 Conan 是否安装
conan --version

# 更新依赖
conan install .. --build=missing --update

# 清理并重新安装
rm -rf build
conan install .. --build=missing -s build_type=Release
```

### 规则文件权限问题

```bash
sudo mkdir -p /var/lib/zihao_waf
sudo chmod 755 /var/lib/zihao_waf
```

### 日志文件权限问题

```bash
sudo mkdir -p /var/log/waf
sudo chmod 755 /var/log/waf
```

## 许可证

MIT