aiwaf-project/aiwaf
GitHub: aiwaf-project/aiwaf
AIWAF 是一个基于人工智能的自适应 Web 应用防火墙，专为 Python Web 框架设计，用于实时检测和拦截网络攻击。
Stars: 55 | Forks: 5
# AIWAF
AIWAF 提供基于上下文的防护，包含速率限制、异常检测、蜜罐、UUID篡改防护、智能关键词学习、文件扩展名探测检测、路径/ IP豁免感知以及定时重训练等功能。
## 最新增强功能
- 智能关键词过滤，避免误拦截如 `/profile/` 等合法路径
- 针对黑名单、关键词和豁免项提供细粒度重置控制
- 基于上下文的学习机制，优先处理可疑流量而非常规路由
- 通过 `AIWAF_ALLOWED_PATH_KEYWORDS` 和 `AIWAF_EXEMPT_KEYWORDS` 增强关键词控制
- 蜜罐逻辑中增加全面的 HTTP 方法验证
- 蜜罐计时增强，包含页面过期/重载流程
- 头部验证结合质量评分与机器人模式检测
## 快速安装
```
pip install aiwaf
```
可选框架附加组件：
```
pip install "aiwaf[django]"
pip install "aiwaf[flask]"
pip install "aiwaf[fastapi]"
pip install "aiwaf[rust]"
```
Rust 附加组件会安装可选的 `aiwaf-rust` 加速包。
重要说明：
- 请使用与您框架对应的适配器包（`aiwaf.django`、`aiwaf.flask` 或 `aiwaf.fast`）。
- 有关 Django 的设置和命令详情，请参阅 `INSTALLATION.md` 和 `REPO_GUIDE_DJANGO.md`。
## 系统要求
- Python 3.8+
- 仅 CPU 运行（无需 GPU）
- 小型部署：约 1 个 vCPU 和 ~512 MB 内存
- 中型部署：建议 2 至 4 个 vCPU 和 2 至 4 GB 内存
- 生产环境中需计划检测/训练任务并轮换日志
## 包结构
```
aiwaf/
core/ # framework-agnostic helpers, training, storage abstractions
core/geolock/ipinfo_lite.mmdb # bundled GeoIP database
django/ # Django adapter (middleware, models, trainer, commands)
flask/ # Flask adapter (integration class, middleware, CLI helpers)
fast/ # FastAPI adapter (middleware, decorators, CLI helpers)
```
框架入口点：
```
# Django
import aiwaf.django as aiwaf
# Flask
import aiwaf.flask as aiwaf
# FastAPI
import aiwaf.fast as aiwaf
```
## 功能特性
- **IP 黑名单**
- 快速拦截已知可疑来源
- 支持通过适配器存储进行运行时更新
- **速率限制**
- 滑动窗口请求控制（`AIWAF_RATE_WINDOW`、`AIWAF_RATE_MAX`）
- 支持洪水攻击阈值（`AIWAF_RATE_FLOOD`）以应对恶意滥用
- **AI 异常检测**
- 基于 IsolationForest 的行为检测
- 随流量增长进行模型训练更新
- **动态关键词学习**
- 从类攻击流量中学习可疑路径关键词
- 排除豁免/允许的术语以减少误报
- **文件扩展名探测检测**
- 检测对 `.php`、`.asp`、`.jsp` 等扩展名的重复探测
- **头部验证**
- 检测缺失必要头部
- 检查可疑的用户代理和头部组合
- 头部质量评分
- 支持静态资源豁免
- **增强蜜罐计时**
- 通过 `AIWAF_MIN_FORM_TIME` 进行 GET 到 POST 的计时检查
- 通过 `AIWAF_MAX_PAGE_TIME` 进行页面年龄验证
- 方法误用检查（例如向只读端点发送 POST 请求）
- **UUID 篡改防护**
- 基于评分的 UUID 滥用检测
- 格式错误的 UUID 会增加高分并可能立即被拦截
- 有效 UUID 请求若反复以 `404` 结束会增加分数
- 成功的 UUID 请求会使分数衰减
- 当单个 IP 的 UUID 分数超过阈值时进行拦截
- **GeoIP 支持**
- 可选国家级别的允许/拦截行为
- 默认支持本地捆绑的 MMDB 文件
- **内置日志路径**
- 适配器级别的请求日志可在主访问日志不可用时用于训练
- **被拦截请求的调试日志**
- 在调试模式下捕获原因、IP、方法、路径和用户代理
## 头部验证详情
检测内容：
- 缺少类似浏览器的核心头部
- 简单机器人典型的头部多样性低
- 可疑或以自动化为导向的用户代理
- 不现实的头部组合
允许内容：
- 带有完整头部的正常浏览器流量
- 标识明确的客户端和已知的合法机器人
- 配置了豁免模式时的静态文件请求
有用的测试模式：
```
# 常为低质量头部画像
curl http://your-app.example/
# 对比正常浏览器流量
```
## 豁免与安全路由
AIWAF 支持：
- 豁免路径（`AIWAF_EXEMPT_PATHS`）
- 豁免 IP（由适配器管理的白名单）
- 豁免关键词（`AIWAF_EXEMPT_KEYWORDS`）
- 允许的路由关键词（`AIWAF_ALLOWED_PATH_KEYWORDS`）
豁免的影响：
- 不参与关键词学习
- 绕过选定的拦截路径
- 降低对受信任业务路由（webhook、健康检查、静态资源）的误报率
基于装饰器的豁免：
- Django 适配器和 Flask 适配器均在其适配器模块中暴露了豁免装饰器。
## 训练与重训练
训练流程：
1. 读取配置的访问日志或适配器日志器输出
2. 检测可疑模式（包括大量的 404 探测行为）
3. 当满足 AI 阈值时，训练/更新 IsolationForest 模型
4. 从可疑流量中刷新动态关键词
5. 从学习到的关键词集中移除豁免/允许的噪声
阈值：
- `AIWAF_MIN_AI_LOGS` 默认为 10,000 用于完整 AI 训练
- `AIWAF_MIN_TRAIN_LOGS` 默认为 50 用于关键词聚焦的回退训练
- `AIWAF_FORCE_AI_TRAINING` 可以覆盖 AI 阈值门控
## 配置（`AIWAF_*`）
AIWAF 使用扁平的 `AIWAF_*` 设置/配置键。
部分配置项是特定适配器的；核心控制是共享的。
大多数部署中必需的配置：
```
AIWAF_ACCESS_LOG = "/var/log/nginx/access.log"
```
核心默认值（示例）：
```
AIWAF_DISABLE_AI = False
AIWAF_MIN_AI_LOGS = 10000
AIWAF_MIN_TRAIN_LOGS = 50
AIWAF_FORCE_AI_TRAINING = False
AIWAF_AI_CONTAMINATION = 0.05
AIWAF_RATE_WINDOW = 10
AIWAF_RATE_MAX = 20
AIWAF_RATE_FLOOD = 10
AIWAF_WINDOW_SECONDS = 60
AIWAF_MIN_FORM_TIME = 1.0
AIWAF_MAX_PAGE_TIME = 240
AIWAF_FILE_EXTENSIONS = [".php", ".asp", ".jsp"]
AIWAF_UUID_SCORE_ENABLED = True
AIWAF_UUID_SCORE_WINDOW_SECONDS = 60
AIWAF_UUID_SCORE_BLOCK_THRESHOLD = 5
AIWAF_UUID_SCORE_MALFORMED_WEIGHT = 5
AIWAF_UUID_SCORE_NOT_FOUND_WEIGHT = 1
AIWAF_UUID_SCORE_SUCCESS_DECAY = 2
AIWAF_ALLOWED_PATH_KEYWORDS = ["profile", "user", "account", "dashboard"]
AIWAF_EXEMPT_KEYWORDS = ["api", "webhook", "health", "static", "media"]
AIWAF_EXEMPT_PATHS = ["/favicon.ico", "/robots.txt", "/static/", "/health/"]
```
模型存储：
```
AIWAF_MODEL_PATH = "aiwaf/resources/model.pkl"
AIWAF_MODEL_STORAGE = "file" # file | db | cache
AIWAF_MODEL_CACHE_KEY = "aiwaf:model"
AIWAF_MODEL_CACHE_TIMEOUT = None
AIWAF_MODEL_STORAGE_FALLBACK = True
```
头部控制：
```
AIWAF_REQUIRED_HEADERS = None # list or method->list mapping
AIWAF_HEADER_QUALITY_MIN_SCORE = 3
```
GeoIP：
```
AIWAF_GEO_BLOCK_ENABLED = False
AIWAF_GEOIP_DB_PATH = "aiwaf/core/geolock/ipinfo_lite.mmdb"
AIWAF_GEO_BLOCK_COUNTRIES = ["CN", "RU"]
AIWAF_GEO_ALLOW_COUNTRIES = []
AIWAF_GEO_CACHE_SECONDS = 3600
AIWAF_GEO_CACHE_PREFIX = "aiwaf:geo:"
```
Rust 加速：
```
AIWAF_USE_RUST = False
```
启用后，AIWAF 会尝试使用 Rust 辅助功能，并在失败时自动回退到 Python。
旧版兼容性：
- 如果您仍在使用嵌套的 `AIWAF_SETTINGS`，AIWAF 会在启动时将常见键映射到扁平的 `AIWAF_*` 值。
## 中间件设置
在所有适配器中顺序都很重要。将防护中间件放在前面，日志记录中间件放在末尾附近。
### 统一的 `all` / `auto` 选择
AIWAF 现在支持跨适配器的集中式“启用所有功能并使用智能默认值”模式。
- FastAPI 和 Flask：传递 `middlewares=["all"]`（或 `["auto"]`）
- Django：在 `MIDDLEWARE` 中使用 `"aiwaf.django.middleware.all"`
自动行为：
- 当 `AIWAF_ACCESS_LOG` 缺失或为空时，启用日志记录中间件
- 当 `AIWAF_ACCESS_LOG` 已配置时，禁用日志记录中间件
- 当以下任一条件为真时，启用地理中间件：
- 显式的地理启用标志已开启
- 静态地理拦截列表包含国家
- 动态地理拦截存储/表包含国家
Django 示例顺序：
```
MIDDLEWARE = [
"aiwaf.django.middleware.JsonExceptionMiddleware",
"aiwaf.django.middleware.GeoBlockMiddleware",
"aiwaf.django.middleware.IPAndKeywordBlockMiddleware",
"aiwaf.django.middleware.RateLimitMiddleware",
"aiwaf.django.middleware.AIAnomalyMiddleware",
"aiwaf.django.middleware.HoneypotTimingMiddleware",
"aiwaf.django.middleware.UUIDTamperMiddleware",
"aiwaf.django.middleware.HeaderValidationMiddleware",
"aiwaf.django.middleware_logger.AIWAFLoggerMiddleware",
]
```
如果 JSON API 客户端需要 JSON 格式的 403 响应体，请将 `JsonExceptionMiddleware` 保持在顶部附近。
Django 别名示例：
```
MIDDLEWARE = [
"django.middleware.security.SecurityMiddleware",
"aiwaf.django.middleware.all",
]
```
FastAPI 快速集成：
```
from fastapi import FastAPI
from aiwaf.fast import AIWAF
app = FastAPI()
aiwaf = AIWAF(
app,
middlewares=["all"],
storage={"backend": "memory"},
header_validation={"enabled": True, "quality_threshold": 3},
rate_limiting={"enabled": True, "window_seconds": 10, "max_requests": 20},
logging_middleware={"enabled": True, "log_dir": "aiwaf_logs", "log_format": "json"},
)
```
Flask 快速集成：
```
from flask import Flask
from aiwaf.flask import AIWAF
app = Flask(__name__)
aiwaf = AIWAF(app, middlewares=["all"])
```
## 操作
Django 适配器示例：
```
python manage.py detect_and_train
python manage.py regenerate_model
python manage.py aiwaf_reset --keywords --confirm
python manage.py add_ipexemption 203.0.113.10 --reason "trusted integration"
python manage.py add_pathexemption /api/webhooks/ --reason "partner callbacks"
python manage.py aiwaf_logging --status
python manage.py geo_block_country list
python manage.py geo_block_country add US
python manage.py geo_block_country remove US
```
Flask 适配器：
- 使用 `aiwaf.flask.AIWAF` 进行中间件注册
- 使用 `aiwaf.flask.cli.AIWAFManager` 处理基于 CSV 的操作任务
FastAPI 适配器：
- 使用 `aiwaf.fast.AIWAF` 进行中间件注册
- 使用 `aiwaf fast ...` 或 `aiwaf-fast ...` 进行 CLI 操作
### Django 命令参考
常用管理命令：
```
python manage.py detect_and_train
python manage.py regenerate_model
python manage.py aiwaf_reset --confirm
python manage.py aiwaf_reset --blacklist --confirm
python manage.py aiwaf_reset --keywords --confirm
python manage.py aiwaf_reset --exemptions --confirm
python manage.py add_ipexemption --reason "optional reason"
python manage.py add_pathexemption /path/prefix/ --reason "optional reason"
python manage.py aiwaf_pathshell
python manage.py aiwaf_logging --status
python manage.py geo_block_country list
python manage.py geo_block_country add US
python manage.py geo_block_country remove US
python manage.py aiwaf_diagnose
```
`aiwaf_pathshell` 辅助工具：
```
ls # list path tree at current node
cd # enter child path node
up / cd .. # move up
pwd # current path prefix
exempt # add exemption for selected/current path
exit # quit shell
```
### Flask 适配器参考
编程式集成：
```
from flask import Flask
from aiwaf.flask import AIWAF
app = Flask(__name__)
app.config["AIWAF_USE_RUST"] = True
app.config["AIWAF_GEO_BLOCK_ENABLED"] = False
app.config["AIWAF_MIN_AI_LOGS"] = 10000
aiwaf = AIWAF(
app,
middlewares=[
"logging",
"header_validation",
"ip_keyword_block",
"rate_limit",
"geo_block",
"ai_anomaly",
"uuid_tamper",
],
)
```
可选的 Flask CLI 管理器：
```
python -m aiwaf.flask.cli list all
python -m aiwaf.flask.cli add whitelist 203.0.113.10
python -m aiwaf.flask.cli add blacklist 203.0.113.99 --reason "manual test"
python -m aiwaf.flask.cli add keyword ../etc/passwd
python -m aiwaf.flask.cli status
```
### FastAPI 适配器参考
编程式集成：
```
from fastapi import FastAPI
from aiwaf.fast import AIWAF
app = FastAPI()
AIWAF(app)
```
CLI 用法：
```
aiwaf fast --help
aiwaf-fast --help
```
### 路径特定规则
使用路径规则选择性禁用中间件或覆盖速率限制，而不会在全局上削弱防护：
```
AIWAF_SETTINGS = {
"PATH_RULES": [
{
"PREFIX": "/api/webhooks/",
"DISABLE": ["HeaderValidationMiddleware"],
"RATE_LIMIT": {"WINDOW": 60, "MAX": 2000},
},
{
"PREFIX": "/api/public/",
"RATE_LIMIT": {"WINDOW": 60, "MAX": 500},
},
]
}
```
规则按路径前缀匹配，应用最具体的匹配规则。
### 拦截行为
- 默认行为：被拦截的请求抛出 `PermissionDenied("blocked")` 并返回 `403`。
- 对于 JSON API（Django）：`JsonExceptionMiddleware` 将被拦截的 JSON 请求转换为 JSON 格式的 `403` 响应体。
- 速率限制可以对软限流路径发出 `429`，同时仍将重复滥用升级至黑名单流程。
### 速率限制缓存（多 worker）
默认情况下，Flask 和 FastAPI 的速率限制使用进程内缓存（每个 worker 一个）。对于多 worker / 多实例部署，需要配置速率限制器使用 Redis，以便所有 worker 共享相同的计数器。
**Flask**
```
app.config["AIWAF_RATE_CACHE_BACKEND"] = "redis"
app.config["AIWAF_REDIS_URL"] = "redis://localhost:6379/0"
# 可选 (默认为 "aiwaf:rate:")
app.config["AIWAF_RATE_CACHE_KEY_PREFIX"] = "aiwaf:rate:"
```
**FastAPI**
```
from aiwaf.fast import AIWAF
AIWAF(
app,
rate_limiting={
"enabled": True,
"cache_backend": "redis",
"redis_url": "redis://localhost:6379/0",
"cache_key_prefix": "aiwaf:rate:", # optional
},
)
```
环境变量（适用于两个适配器）：
```
set AIWAF_RATE_CACHE_BACKEND=redis
set AIWAF_REDIS_URL=redis://localhost:6379/0
set AIWAF_RATE_CACHE_KEY_PREFIX=aiwaf:rate:
```
### 日志记录与训练数据源
AIWAF 训练器可以从以下来源获取数据：
1. `AIWAF_ACCESS_LOG`（主要来源，在适用情况下支持轮换/压缩日志的解析）
2. 中间件捕获的日志（根据适配器设置存储为 CSV/数据库）
这使得在无法获取反向代理日志的情况下仍能进行训练。
## 沙盒与基准测试
`examples/sandbox/` 目录下的沙盒提供：
- `direct`（无 AIWAF）
- `protected_django`
- `protected_flask`
- `protected_fastapi`
运行完整基准测试：
```
cd examples/sandbox
python run-and-compare.py -n 5
```
生成的输出：
- `results_direct_*.json`
- `results_protected_django_*.json`
- `results_protected_flask_*.json`
- `comparison_modes_*.json`
- `comparison_aggregate_*.json`
结果解读指南：
- `direct` 模式下攻击拦截率应低/为零（基线）
- 受保护的目标应使正常流量的拦截率接近 `0%`
- 比较不同迭代中的攻击拦截率和中位数延迟，而非单次运行的平均值
## 发布清单
发布新包版本前：
1. 运行两个适配器的测试套件
2. 验证沙盒比较（至少运行 `run-and-compare.py -n 3`）
3. 在 `setup.py` 中更新包版本号
4. 构建产物（`python -m build`）
5. 在干净的虚拟环境中冒烟测试 wheel 安装
6. 验证 `README.md` 和附加组件（`django`、`flask`）与实际包行为匹配
## 重置与恢复
细粒度重置（Django 适配器）：
```
python manage.py aiwaf_reset --blacklist
python manage.py aiwaf_reset --keywords
python manage.py aiwaf_reset --exemptions
python manage.py aiwaf_reset --blacklist --keywords
python manage.py aiwaf_reset --confirm
```
误报的常见恢复路径：
1. 清除已学习的关键词
2. 将合法的路由术语添加到 `AIWAF_ALLOWED_PATH_KEYWORDS`
3. 将永不拦截的术语添加到 `AIWAF_EXEMPT_KEYWORDS`
4. 重新训练
## 故障排除
### 合法页面被拦截
原因：
- 学习到的关键词包含了合法的应用程序词汇
解决方法：
```
python manage.py aiwaf_reset --keywords --confirm
python manage.py detect_and_train
```
然后调整：
- `AIWAF_ALLOWED_PATH_KEYWORDS`
- `AIWAF_EXEMPT_KEYWORDS`
### AI 模型未训练
- 检查日志路径和权限
- 检查日志量是否达到 `AIWAF_MIN_AI_LOGS` / `AIWAF_MIN_TRAIN_LOGS` 的阈值
- 仅在适当时使用 `AIWAF_FORCE_AI_TRAINING=True`
### 地理拦截未激活
- 验证 `AIWAF_GEO_BLOCK_ENABLED=True`
- 验证 `AIWAF_GEOIP_DB_PATH`
- 确认地理中间件已在您的适配器链中启用
### Rust 模式似乎未激活
- 设置 `AIWAF_USE_RUST=True`
- 验证环境可以导入 Rust 扩展
- 在 Rust 导入/运行时失败时回退到 Python 是预期行为
## 工作原理
| 层级 | 目的 |
|---|---|
| 地理拦截 | 国家级别的允许/拦截过滤 |
| IP/关键词拦截 | 已知恶意源和关键词防御 |
| 速率限制 | 在滑动窗口内进行突发/洪水控制 |
| AI 异常 | 基于机器学习的行为离群点检测 |
| 蜜罐计时 | 自动化/计时/方法误用检查 |
| UUID 篡改 | 基于评分的格式错误 UUID + 重复 UUID-404 滥用检测 |
| 头部验证 | 类机器人头部特征检测 |
| 请求日志器 | 用于分析/训练的可选遥测捕获 |
## 请求生命周期（详细）
对于一个典型的受保护请求：
1. 请求进入适配器中间件链。
2. 首先运行路径/视图/IP 豁免检查。
3. 头部验证评估必要头部和质量得分。
4. IP/关键词检查应用静态规则和学习到的规则。
5. 速率限制检查应用窗口/洪水逻辑。
6. 地理检查应用国家级别的允许/拦截规则（如果启用）。
7. AI 异常评估提取的行为特征（如果启用且模型可用）。
8. 蜜罐计时/方法检查评估表单计时和方法误用。
9. UUID 篡改检查验证 UUID 格式并应用基于评分的重复未命中检测。
10. 可选的日志器记录请求/响应元数据。
如果任何拦截阶段拒绝了请求：
- 状态码通常为 `403`（`PermissionDenied("blocked")`）
- JSON API 可以通过 JSON 异常中间件接收到 JSON 格式的 `403`
- 某些限流路径可能返回 `429`
## 中间件说明
`IPAndKeywordBlockMiddleware`：
- 快速拦截已在黑名单中的 IP
- 检查静态可疑关键词和学习到的动态关键词
- 支持豁免关键词和允许路径关键词逻辑
`RateLimitMiddleware`：
- 强制执行短时间窗口内的最大请求预算
- 可以将持续的洪水攻击者加入黑名单
- 支持路径规则覆盖
`GeoBlockMiddleware`：
- 通过 MMDB 从源 IP 解析国家
- 支持拦截列表模式和可选的允许列表模式
- 可以缓存查找以提高性能
`AIAnomalyMiddleware`：
- 需要模型加载和阈值配置
- 当模型/依赖项不可用时会优雅地自行禁用
- 根据配置/运行时，可以运行 Python 路径或 Rust 辅助路径
`HoneypotTimingMiddleware`：
- 强制执行最短提交计时
- 在启用的地方强制执行最大页面年龄语义
- 包含方法误用检测逻辑
`UUIDTamperMiddleware`：
- 保护 UUID 访问模式
- 在没有 UUID 模型规则适用的地方通常为空操作
`HeaderValidationMiddleware`：
- 根据方法检查必要头部
- 对请求真实性评分，并可以拦截低质量特征的请求
- 通常通过 `PATH_RULES` 为 API/webhook/socket 端点进行调优
## 高级配置矩阵
流量控制：
```
AIWAF_RATE_WINDOW = 10
AIWAF_RATE_MAX = 20
AIWAF_RATE_FLOOD = 10
AIWAF_WINDOW_SECONDS = 60
```
头部验证：
```
AIWAF_REQUIRED_HEADERS = None
AIWAF_HEADER_QUALITY_MIN_SCORE = 3
AIWAF_MAX_ACCEPT_LENGTH = 4096
```
AI/模型行为：
```
AIWAF_DISABLE_AI = False
AIWAF_MIN_AI_LOGS = 10000
AIWAF_MIN_TRAIN_LOGS = 50
AIWAF_FORCE_AI_TRAINING = False
AIWAF_AI_CONTAMINATION = 0.05
```
模型存储：
```
AIWAF_MODEL_STORAGE = "file" # file | db | cache
AIWAF_MODEL_PATH = "aiwaf/resources/model.pkl"
AIWAF_MODEL_CACHE_KEY = "aiwaf:model"
AIWAF_MODEL_CACHE_TIMEOUT = None
AIWAF_MODEL_STORAGE_FALLBACK = True
```
关键词与误报控制：
```
AIWAF_ALLOWED_PATH_KEYWORDS = ["profile", "user", "dashboard"]
AIWAF_EXEMPT_KEYWORDS = ["api", "health", "static", "webhook"]
AIWAF_DYNAMIC_TOP_N = 10
```
豁免：
```
AIWAF_EXEMPT_PATHS = ["/health/", "/static/", "/favicon.ico"]
AIWAF_EXEMPT_IPS = ["127.0.0.1", "::1"]
```
## 调优手册
在不全局削弱防护的情况下减少误报：
1. 重置已学习的关键词（`--keywords`）
2. 将合法的域术语添加到 `AIWAF_ALLOWED_PATH_KEYWORDS`
3. 将操作术语添加到 `AIWAF_EXEMPT_KEYWORDS`
4. 为 webhook/socket 端点添加路由级别的 `PATH_RULES`
5. 重新训练并再次进行基准测试
针对持续攻击流量进行加固：
1. 调整 `AIWAF_RATE_WINDOW`、`AIWAF_RATE_MAX`、`AIWAF_RATE_FLOOD`
2. 对公共路径保持头部验证启用
3. 保持地理规则明确且最小化
4. 启用中间件日志记录 + 定期重训练
5. 在添加宽泛的关键词规则前，先审查拦截原因
稳定实时路径：
1. 保持全局防护启用
2. 仅通过 `PATH_RULES` 禁用 `/socket.io/` 或等效路径的严格检查
3. 对非实时路径保留黑名单逻辑
4. 需要时将受信任的内部集成 IP 加入白名单
## Rust 验证
启用：
```
AIWAF_USE_RUST = True
```
运行时行为：
- Rust 扩展可用：选定路径使用 Rust 加速
- Rust 扩展不可用：自动回退到 Python
验证清单：
1. 以 `AIWAF_USE_RUST=True` 启动应用
2. 确认启动/运行时日志显示 Rust 可用性或回退路径
3. 使用多次迭代进行基准测试并比较中位数（`run-and-compare.py -n 5`）
## 故障排除决策树
页面空白但 `/` 返回 `200`：
- 检查 JS/CSS/API 请求是否返回 `403`/`4xx`
- 检查客户端 IP 是否被列入黑名单
- 确认 socket/静态资源/API 路径的 `PATH_RULES`
一次被拦截请求后立即出现大量 `403`：
- 可能是黑名单级联
- 清除黑名单并添加有针对性的豁免/路径规则
- 避免全局禁用所有中间件
AI 异常未激活：
- 验证模型是否可加载
- 验证 AI 依赖项已安装
- 验证 `AIWAF_DISABLE_AI=False`
- 验证阈值（`AIWAF_MIN_AI_LOGS`、`AIWAF_MIN_TRAIN_LOGS`）
地理拦截似乎未激活：
- 确认中间件已启用
- 确认 MMDB 路径有效
- 确认允许/拦截列表已按预期配置
## 部署模式
### 反向代理 + 应用服务器
典型的生产路径：
1. 互联网 -> CDN/WAF 边缘（可选）
2. 反向代理（Nginx/Traefik/Caddy）
3. 应用服务器（带有 AIWAF 中间件的 Django/Flask）
4. 应用数据库/缓存 + 模型/日志存储
建议：
- 正确保留客户端 IP 转发（`X-Forwarded-For`）
- 保持时钟同步（NTP）以确保日志计时功能可靠
- 轮换日志并强制执行保留限制
- 作为计划任务定期运行重训练
### 多实例部署
当运行多个应用实例时：
- 对于模型工件，首选共享存储模式（`db` 或集中式缓存）
- 确保黑名单/豁免更新能一致传播
- 如果实例会自动扩缩容，避免使用仅限主机本地的模型路径
### 蓝绿/滚动更新
为了更安全的发布：
1. 以保守的阈值部署
2. 验证拦截指标和误报率
3. 逐步收紧控制
4. 仅在稳定基准测试 + 生产金丝雀行为正常后才推广
## 可观察性与 KPI
按适配器跟踪这些指标：
- **正常流量拦截率**：目标接近 `0%`
- **攻击流量拦截率**：在重放测试套件下目标应高且稳定
- **P95/P99 响应延迟**：比较调优前后的变化
- **黑名单变动率**：突然激增可能表明规则过于嘈杂
- **主要拦截原因**：有助于调整头部/关键词/速率限制
- **重训练成功/失败次数**：检测模型流程回归
最小看板切片：
- 按端点族（`/api`、`/socket.io`、静态资源）
- 按源 ASN/国家（如果启用了地理功能）
- 按中间件原因代码
- 按部署版本
## 安全边界与注意事项
AIWAF 增强了应用层防护，但并非完整的安全边界。
重要注意事项：
- 不能替代安全编码、授权、密钥管理、打补丁或网络控制
- ML 异常检测是概率性的，可能随流量特征变化而漂移
- 激进的关键词/速率设置如果不分阶段进行，可能导致自我引发的故障
- websocket/实时路径通常需要显式的路径规则调优
- 白名单/豁免应范围严格并定期审查
## 贡献者测试策略
推荐的本地验证流程：
1. 单元测试和适配器测试
2. 沙盒启动验证（直接模式 + 受保护目标）
3. 使用多次迭代进行重放基准测试
4. 审查聚合检测率和延迟中位数
5. 检查一部分被拦截和允许的请求以查找回归
建议的基准测试命令：
```
cd examples/sandbox
python run-and-compare.py -n 5
```
回归门控（策略示例）：
- 正常流量拦截率不增加
- 攻击拦截率无显著下降
- 无超出约定预算的、无法解释的延迟回归
## 常见问题解答
**为什么我在 `curl` 上看到 `403` 而浏览器可以访问？**
头部验证可能将低质量的客户端头部归类为自动化流量。
**为什么突然所有请求都开始返回 `403`？**
可能是在初始拦截事件后发生了黑名单级联；清除黑名单并添加有针对性的路径/IP 调优。
**我可以为单个路由禁用一个中间件吗？**
可以，使用 `AIWAF_SETTINGS["PATH_RULES"]` 并为该前缀设置 `DISABLE`。
**Rust 模式会改变检测结果吗？**
它应该在改善某些执行路径的同时保持行为一致；请通过 A/B 多次迭代基准测试进行验证。
**我需要 Django 才能使用 AIWAF 吗？**
不需要。核心支持 Django 和 Flask 适配器，但某些操作命令是 Django 特有的。
## CLI 入口点
```
aiwaf-detect
```
当前行为：
- 调度至 Django 训练器（`aiwaf.django.trainer.train`）
- 需要 Django 适配器可用
## 致谢
[DigitalOcean](https://www.digitalocean.com/) 提供了支撑 AIWAF 开发的云基础设施。
## 许可证
MIT。详见 `LICENSE`。
标签：Apex, AppImage, AV绕过, Django, DNS枚举, Elastic, FastAPI, Flask, IP黑名单, Python, Rust, UUID安全, Web应用防火墙, 上下文感知, 人工智能, 入侵防御系统, 关键词过滤, 可视化界面, 基于日志的安全, 威胁猎捕, 威胁防御, 安全防护, 异常检测, 性能优化, 文件探测, 无后门, 智能学习, 机器学习, 框架集成, 检测绕过, 用户模式Hook绕过, 网络安全, 网络安全工具, 网络流量审计, 自适应系统, 蜜罐技术, 路径豁免, 逆向工具, 重训练, 隐私保护