fix: VUL-003 完整修复,启发式/精确双模式 XFF 解析
VUL-003 (中): X-Forwarded-For 信任链可被伪造 IP 绕过限流
本服务定位为公网入口,即使单人使用,公网暴露意味着攻击面
与公开服务等同,不能"够用就行"。
采用渐进式披露设计,平衡易用性与功能性:
1. 启发式模式(默认, 不设环境变量 或 TRUSTED_PROXY_HOPS=0)
- 从 XFF 链尾扫描,跳过私有 IP,返回第一个公网 IP
- 适合 90% 部署(单跳/多跳/直出),无需了解精确跳数
- 限制:多跳 CDN 场景下,限流粒度为"按 CDN 边缘 IP"
- 直出部署:整个 XFF 分支不会执行
2. 精确模式(TRUSTED_PROXY_HOPS=N, N>0)
- 从 XFF 链尾倒数第 N+1 个位置取值
- 精准到真实 client,需按实际反代跳数正确配置
- N=1:单跳反代;N=2:CDN+反代;以此类推
3. 两种模式都从链尾扫描
- XFF 首值是客户端可控的,信任首值等于信任攻击者
- 链尾由受控的反代添加,天然免疫伪造绕过
4. 默认值从 1 改为 0(行为变化)
- 旧默认:精确模式 N=1,取 XFF 末值
- 新默认:启发式模式,跳过链尾私有 IP
- 对单跳场景行为相同
- 对多跳/链尾含私有 IP 场景新版更准确(返回真实公网 IP)
5. 配套
- middleware/ratelimit_test.go:24 个表驱动测试用例,
覆盖直出/单跳/多跳/伪造/畸形/精确 N 边界,全部通过
- setting/config.go:LogStartupSummary 显示当前 XFF 模式
- .env.example:重写说明,标注默认行为 + 何时需配
- README.md:新增"反代拓扑与 X-Forwarded-For 解析"章节
(何时需要/两种模式/行为对比/为什么从链尾/启动日志验证)
6. 已知边界:TRUSTED_PROXY_HOPS=00 等被 Atoi 解析为 0 的
输入归入启发式模式,日志不会出现"精确模式 0 跳"矛盾输出。
This commit is contained in:
@@ -80,9 +80,86 @@ tts-api.exe
|
||||
| 变量名 | 说明 | 默认值 |
|
||||
|--------|------|--------|
|
||||
| `OPENAI_TTS_API_KEY` | OpenAI 兼容接口的 API Key(逗号分隔支持多个) | 无(不鉴权) |
|
||||
| `TRUSTED_PROXY_HOPS` | X-Forwarded-For 解析模式(0=启发式/默认,>0=精确 N 跳) | `0`(启发式) |
|
||||
| `PORT` | 服务监听端口 | `8080` |
|
||||
| `ALLOWED_ORIGINS` | CORS 跨域白名单(逗号分隔,调试可设 `*`;空则拒绝所有跨域) | 无 |
|
||||
|
||||
### 反代拓扑与 X-Forwarded-For 解析
|
||||
|
||||
当服务部署在反代(nginx / caddy / CDN)后面时,反代会通过 `X-Forwarded-For`(XFF)头传递真实客户端 IP。本服务通过 `TRUSTED_PROXY_HOPS` 环境变量控制 XFF 解析方式,支持两种模式。
|
||||
|
||||
#### 何时需要关心这个配置
|
||||
|
||||
| 部署方式 | 是否需要配置 |
|
||||
|---|---|
|
||||
| 服务直接暴露公网 IP(无反代)| ❌ 不适用,跳过本节 |
|
||||
| 服务前有 1 个反代(nginx / caddy)| ❌ 不必配置,启发式模式自动处理 |
|
||||
| 服务前有 2 跳以上反代(CDN + 自建反代)| ⚠️ 启发式模式"够用",需要精准按真实 client 限流时再设 |
|
||||
|
||||
> **直出部署(无反代)的用户**:本节不适用,跳过阅读。`TRUSTED_PROXY_HOPS` 在你的部署下不会被读取。
|
||||
|
||||
#### 启发式模式(默认 / `TRUSTED_PROXY_HOPS=0`)
|
||||
|
||||
从 XFF 链尾向前扫描,**跳过私有 IP,返回第一个公网 IP**。
|
||||
|
||||
适用场景:单跳反代(最常见)、多跳含公网代理(CDN + nginx)。
|
||||
|
||||
**行为示例**:
|
||||
|
||||
| XFF 链 | 启发式返回 | 备注 |
|
||||
|---|---|---|
|
||||
| `1.2.3.4` | `1.2.3.4` | 单跳,真实 client |
|
||||
| `fake, 1.2.3.4` | `1.2.3.4` | 攻击者伪造首值,跳过 fake |
|
||||
| `1.2.3.4, 5.6.7.8, 10.0.0.1` | `5.6.7.8` | 多跳,返回最末公网 IP(CDN 边缘) |
|
||||
| `1.2.3.4, 192.168.1.1` | `1.2.3.4` | 链尾是私有 IP,跳过 |
|
||||
|
||||
**优点**:零配置,大多数部署自动正确。
|
||||
|
||||
**限制**:多跳 CDN 场景下,限流粒度为"按 CDN 边缘 IP"而非"按真实 client"。攻击者填满某 CDN 边缘配额可能影响该 CDN 下的其他用户——但无法伪造身份、无法越权。
|
||||
|
||||
#### 精确模式(`TRUSTED_PROXY_HOPS=N`,N > 0)
|
||||
|
||||
从 XFF 链尾倒数第 N+1 个位置取值,即"信任最近 N 跳反代,取该信任链之前那一跳的 IP"。
|
||||
|
||||
适用场景:多跳 CDN + 反代,且需要精准按真实 client 限流。
|
||||
|
||||
**N 的确定方法**:统计客户端到本服务之间的反代跳数。
|
||||
|
||||
| 拓扑 | 跳数 | 配置 |
|
||||
|---|---|---|
|
||||
| `client → nginx → 本服务` | 1 | `TRUSTED_PROXY_HOPS=1` |
|
||||
| `client → Cloudflare → nginx → 本服务` | 2 | `TRUSTED_PROXY_HOPS=2` |
|
||||
| `client → CDN → WAF → nginx → 本服务` | 3 | `TRUSTED_PROXY_HOPS=3` |
|
||||
|
||||
**行为对比**(以 `client(1.2.3.4) → CDN(203.0.113.5) → nginx(10.0.0.1) → 本服务` 为例,XFF 链 = `1.2.3.4, 203.0.113.5`):
|
||||
|
||||
| `TRUSTED_PROXY_HOPS` | 返回 | 评价 |
|
||||
|---|---|---|
|
||||
| 0(默认启发式)| `203.0.113.5` | CDN 边缘 IP,限流粒度粗 |
|
||||
| 1(数到 nginx,未穿透)| `203.0.113.5` | 配置不当,与默认相同 |
|
||||
| 2(穿透到真实 client)| `1.2.3.4` | 精准到真实 client ✓ |
|
||||
| 3(超出实际跳数)| `directIP`(链长不足保护)| 配置错误,需修正 |
|
||||
|
||||
#### 为什么两种模式都从链尾扫描
|
||||
|
||||
XFF 链的第一个值是**客户端可控**的:攻击者可以发送任意 `X-Forwarded-For: 1.2.3.4`,若反代用追加模式(如 nginx 默认的 `$proxy_add_x_forwarded_for`),链尾才会追加真实 IP。
|
||||
|
||||
若代码取首值,攻击者每次换伪造 IP 即可绕过 IP 限流,也可伪装成受害 IP 把其配额耗尽(间接 DoS)。两种模式都从链尾扫描,天然免疫这种攻击。
|
||||
|
||||
#### 验证当前模式
|
||||
|
||||
启动期日志会显示当前模式:
|
||||
|
||||
```
|
||||
TRUSTED_PROXY_HOPS 未设置,使用默认启发式模式(XFF 链尾第一个公网 IP)
|
||||
# 或
|
||||
已配置 TRUSTED_PROXY_HOPS=0(启发式模式,等同默认)
|
||||
# 或
|
||||
已配置 TRUSTED_PROXY_HOPS=2(精确模式,信任 2 跳反代)
|
||||
```
|
||||
|
||||
也可在 `GetClientIP` 临时加 `log.Printf` 打印解析结果,或写一个 Go 测试用例(参见 DEBT-1 单元测试任务)来覆盖不同 XFF 链场景。生产环境不要保留 debug 日志。
|
||||
|
||||
### Resource ID 说明
|
||||
|
||||
| Resource ID | 模型说明 |
|
||||
|
||||
Reference in New Issue
Block a user