RumenDamyanov/nginx-waf
GitHub: RumenDamyanov/nginx-waf
一个原生 nginx 动态模块，提供基于命名列表和标签的 IP/CIDR 黑白名单访问控制。
Stars: 4 | Forks: 0
# nginx-waf
一个动态的 nginx 模块，用于基于 IP/CIDR 的访问控制，支持命名列表和基于标签的组织。
## ⚠️ 实验性项目
```
╔══════════════════════════════════════════════════════════════════╗
║ 🧪 THIS PROJECT IS EXPERIMENTAL - NOT PRODUCTION READY ║
║ ║
║ • Early development stage ║
║ • API and features may change ║
║ • Use at your own risk ║
║ • Contributions and ideas welcome! ║
╚══════════════════════════════════════════════════════════════════╝
```
📅 **开始时间：** 2025 年 12 月
🎯 **目标：** v1.0.0 稳定版发布
📊 **当前状态：** v0.2.1 - 核心功能完成，测试阶段
## 什么是 nginx-waf？
**nginx-waf** 是一个简单且专注的 nginx 模块，提供基于 IP 的访问控制。你可以把它看作一个灵活的 IP 黑名单/白名单管理器。
### 核心功能
| 功能 | 描述 |
|---------|-------------|
| 🏷️ **命名列表** | 使用有意义的名称定义列表（`tor`、`botnets`、`trusted`） |
| 🔖 **标签组织** | 使用标签对列表进行分组以进行批量管理（`tag:anonymizers`） |
| ⚫ **黑名单模式** | 阻止匹配任何已启用列表的 IP |
| ⚪ **白名单模式** | 仅允许匹配已启用列表的 IP |
| 🎯 **灵活的作用域** | 可在 http、server 或 location 级别进行配置 |
| 🌐 **IPv4 和 IPv6** | 完全支持 CIDR 范围 |
### nginx-waf 不是什么
- ❌ **不是完整的 WAF** - 没有请求体检查、SQL 注入检测等。
- ❌ **不是速率限制器** - 请使用 nginx 的 `limit_req` 模块
- ❌ **不是机器人检测器** - 仅提供 IP 列表，没有行为分析
- ❌ **不是 CDN** - 仅用于访问控制
### 为什么还要开发另一个模块？
- **比 ModSecurity 更简单** - 仅专注于基于 IP 的控制
- **适用于原生 nginx** - 不需要 OpenResty
- **带标签的命名列表** - 轻松组织数十个列表
- **按 location 配置** - 提供细粒度的控制
## 快速示例
```
http {
# Define IP lists with tags
waf_list tor "/etc/nginx/waf/tor-exits.txt" "anonymizers,privacy";
waf_list botnets "/etc/nginx/waf/botnets.txt" "security";
waf_list trusted "/etc/nginx/waf/trusted.txt" "internal";
server {
server_name api.example.com;
# Block all anonymizers by default
waf on;
waf_mode blacklist;
waf_enable_lists tag:anonymizers;
location /admin {
# Strict whitelist for admin
waf on;
waf_mode whitelist;
waf_enable_lists trusted;
}
location /public {
# No restrictions on public endpoints
waf off;
}
}
}
```
## 配置参考
| 指令 | 上下文 | 参数 | 描述 |
|-----------|---------|-----------|-------------|
| `waf` | http, server, location | `on\|off` | 启用/禁用 WAF |
| `waf_mode` | http, server, location | `blacklist\|whitelist` | 操作模式 |
| `waf_list` | http | `name path [tags]` | 定义 IP 列表 |
| `waf_enable_lists` | http, server, location | `name,...\|tag:name\|all` | 激活列表 |
| `waf_disable_lists` | http, server, location | `name,...\|tag:name` | 停用列表 |
| `waf_log_prefix` | http, server, location | `string` | 自定义日志前缀 |
## IP 列表格式
列表是纯文本文件，每行一个条目：
```
# 注释以 # 开头
# IPv4 addresses
192.168.1.100
10.0.0.50
# IPv4 CIDR ranges
192.168.0.0/24
10.0.0.0/8
# IPv6 addresses
2001:db8::1
::ffff:192.168.1.1
# IPv6 CIDR ranges
2001:db8::/32
```
## 安装
🚧 **即将通过 openSUSE Build Service (OBS) 提供安装包**
计划支持的发行版：
| 发行版 | 版本 |
|--------------|----------|
| Debian | 11, 12, 13 |
| Ubuntu | 22.04, 24.04, 25.04 |
| Fedora | 41, 42 |
| openSUSE | Tumbleweed, Leap 15.6, 16.0 |
| RHEL/Rocky/Alma | 8, 9 |
## 从源码构建
要求：
- nginx 源代码（与你的 nginx 版本相匹配）
- GCC 和 make
- PCRE 和 zlib 开发库
```
# 下载 nginx 源码
wget https://nginx.org/download/nginx-1.27.4.tar.gz
tar xzf nginx-1.27.4.tar.gz
cd nginx-1.27.4
# 使用 module 进行配置
./configure --add-dynamic-module=/path/to/nginx-waf/src
# 构建 module
make modules
# 安装（以 root 身份）
cp objs/ngx_http_waf_module.so /usr/lib64/nginx/modules/
```
## 完美配合
nginx-waf 旨在补充现有的 nginx 模块：
| 模块 | 用例 |
|--------|----------|
| `ngx_http_realip_module` | 在代理/CDN 后获取真实客户端 IP |
| `ngx_http_limit_req_module` | 速率限制 |
| `ngx_http_geo_module` | 地理位置限制 |
| `ngx_http_access_module` | 简单的允许/拒绝规则 |
使用真实 IP 的示例：
```
http {
# Trust Cloudflare IPs
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
real_ip_header CF-Connecting-IP;
# WAF checks real client IP
waf_list threats "/etc/nginx/waf/threats.txt";
waf on;
waf_mode blacklist;
waf_enable_lists threats;
}
```
## 路线图
### v0.2.1 - 核心模块 ✅ （当前版本）
- [x] 项目设置和文档
- [x] 具有 `waf on|off` 的基础模块
- [x] 单个 IP 列表支持
- [x] 带有标签的多个命名列表
- [x] 黑名单和白名单模式
- [x] 支持 CIDR 的 IPv4 和 IPv6
- [x] `waf_enable_lists` 和 `waf_disable_lists` 指令
- [x] 基于标签的列表选择（`tag:name`）
- [x] 上下文继承（http → server → location）
- [x] GitHub Actions CI/CD（x86_64 + ARM64）
- [ ] OBS 软件包（进行中）
### v1.0.0 - 稳定版发布（目标：2026 年第二季度）
- [ ] 社区测试和反馈
- [ ] 性能基准测试
- [ ] 适用于主要发行版的 OBS 软件包
- [ ] 安全审查
### v2.0.0 - 扩展（未来）
有关未来配套项目的详细信息，请参阅下方的**计划中的扩展**部分。
## 生态系统
通过管理、自动化和集成功能扩展 nginx-waf 的配套项目：
| 项目 | 语言 | 描述 |
|---------|----------|-------------|
| **[nginx-waf-api](https://github.com/RumenDamyanov/nginx-waf-api)** | Go | 用于在没有 nginx 重载的情况下进行动态 IP 列表管理的 REST API 守护进程 |
| **[nginx-waf-ui](https://github.com/RumenDamyanov/nginx-waf-ui)** | Go | 基于 Web 的仪表板，用于管理列表、查看统计信息和配置 |
| **[nginx-waf-feeds](https://github.com/RumenDamyanov/nginx-waf-feeds)** | Go | 自动威胁订阅源更新器（Cloudflare、Tor 出口节点、Spamhaus 等） |
| **[nginx-waf-lua](https://github.com/RumenDamyanov/nginx-waf-lua)** | Lua | OpenResty/Lua 集成，用于编写 WAF 逻辑和自定义响应 |
### 架构概览
```
┌─────────────────┐
│ nginx-waf-ui │
│ (Web Dashboard)│
└────────┬────────┘
│
┌─────────────────┐ ┌─────────▼────────┐ ┌─────────────────┐
│ nginx-waf-feeds │───────────▶│ nginx-waf-api │◀───────────│ CLI / Scripts │
│ (Feed Updater) │ │ (REST API) │ │ │
└─────────────────┘ └─────────┬────────┘ └─────────────────┘
│
┌─────────▼────────┐
│ IP List Files │
│ /etc/nginx/waf/ │
└─────────┬────────┘
│
┌─────────▼────────┐
│ nginx-waf │◀──── nginx-waf-lua
│ (C Module) │ (Lua bindings)
└──────────────────┘
```
### 状态
| 项目 | 状态 |
|---------|--------|
| nginx-waf | 🟡 开发中 (v0.2.1) |
| nginx-waf-api | 🟢 已发布 v0.1.0 |
| nginx-waf-ui | 🟢 已发布 v0.1.0 |
| nginx-waf-feeds | 🟢 已发布 v0.1.0 |
| nginx-waf-lua | 🟢 已发布 v0.1.0 |
## 相关项目
我们维护的其他 nginx 动态模块：
| 模块 | 描述 |
|--------|-------------|
| **[nginx-torblocker](https://github.com/RumenDamyanov/nginx-torblocker)** | 控制来自 Tor 出口节点的访问 — 阻止、允许或仅限 Tor 模式 |
| **[nginx-cf-realip](https://github.com/RumenDamyanov/nginx-cf-realip)** | 自动获取 Cloudflare 边缘 IP 列表，用于还原真实客户端 IP |
| **[nginx-gone](https://github.com/RumenDamyanov/nginx-gone)** | 对永久移除的 URI 返回 HTTP 410 Gone |
### Apache HTTP Server 版本
所有模块也适用于 Apache httpd：
| 模块 | 描述 |
|--------|-------------|
| **[apache-waf](https://github.com/RumenDamyanov/apache-waf)** | 使用命名列表进行基于 IP/CIDR 的访问控制 |
| **[apache-waf-api](https://github.com/RumenDamyanov/apache-waf-api)** | 用于动态 WAF IP 列表管理的 REST API |
| **[apache-waf-feeds](https://github.com/RumenDamyanov/apache-waf-feeds)** | 用于 apache-waf 的自动威胁订阅源更新器 |
| **[apache-waf-ui](https://github.com/RumenDamyanov/apache-waf-ui)** | apache-waf 的 Web 管理界面 |
| **[apache-torblocker](https://github.com/RumenDamyanov/apache-torblocker)** | 控制来自 Tor 出口节点的访问 |
| **[apache-cf-realip](https://github.com/RumenDamyanov/apache-cf-realip)** | 通过 `mod_remoteip` 还原 Cloudflare 真实 IP |
| **[apache-gone](https://github.com/RumenDamyanov/apache-gone)** | 对永久移除的 URI 返回 HTTP 410 Gone |
## 许可证
[BSD 3-Clause 许可证](LICENSE.md)
## 安全性
发现安全问题？请参阅我们的[安全政策](SECURITY.md)进行负责任的披露。
⚠️ 实验性项目 - 使用需自担风险
欢迎贡献和提出想法！
标签：IP黑白名单, Nginx, rizin, Streamlit, WAF, 客户端加密, 日志审计, 网络安全, 访问控制, 配置错误, 隐私保护