管理后台 IP 白名单被一行 X-Forwarded-For 头绕过：远程 IP 信任链怎么加固才靠谱

作者温寒山-879

安全加固X-Forwarded-For访问控制Spring Boot网关

作者：温寒山-879｜分布式系统 / 安全加固｜10 年经验栈：Spring Boot 3.2.x、Spring Security 6.3、Nginx 1.25、Tomcat 10.1 结论先行："客户端是谁"这件事，决定权绝不能交给请求头本身。IP 白名单之所以会被一行头打穿，根因是应用把"取客户端 IP"的权力下放给了 X-Forwarded-For 这种纯文本字段。

一、现象：一个"只放行内网 3 个出口"的管理后台，被 5 行 curl 打穿

上个月给一家做 SaaS 的客户做安全加固复盘。他们有一套管理后台 /admin/*，安全基线是 IP 白名单，配置了 3 个网段：

10.0.1.0/24（运维跳板）
172.16.8.0/24（内部办公出口）
192.168.100.0/24（合作方专线）

白名单逻辑写在 Spring Security 里，用 AntPathRequestMatcher("/admin/**", "10.0.1.0/24") 这类规则放行，其余 IP 一律 403。我做了十年安全，看到"IP 白名单"这四个字，第一反应不是"哦挺安全"，而是"让我试试"。

结果 5 行 curl 就绕过了：

curl -H "X-Forwarded-For: 10.0.1.7" \
     https://target.example.com/admin/users
# 200 OK  ← 白名单本该只认这 3 个网段，但我是从公网直连的

攻击者 0 授权、0 凭据，加一行头，白名单就形同虚设——等于给全网开了个后门。更糟的是他们的审计日志里，这条请求的"客户端 IP"被记成了 10.0.1.7，事后排查根本分不清是内网运维还是外部攻击者。

二、根因：门禁不看门禁卡，看访客自己递上来的一张纸条

我打个比方：IP 白名单本该像小区门禁——刷你的门禁卡（TCP 对端地址）才放行。但他们这套门禁，是看访客进门时自己递上来的一张纸条，纸条上写"我是 10.0.1.7 的"就放你进。纸条是纸做的，谁都能写，那门禁就形同虚设。

机制上讲清楚：

HTTP 应用层要"知道客户端是谁"，靠的不是 TCP 连接的源地址，而是 X-Forwarded-For / X-Real-IP / X-Remote-Addr 这几个头。
这几个头是纯文本、由请求发起方任意填充的。真正该追加/覆盖它们的，只有"可信代理链"上的每一跳（边缘网关、负载均衡）。
Spring Boot 3.x 里，server.forward-headers-strategy 默认是 FRAMEWORK，框架会启用 RemoteIpValve / ForwardedHeaderFilter。如果 trustedProxies 配得宽松（甚至 0.0.0.0/0），框架就愿意相信任何来源的 X-Forwarded-For 头，把它当作"真实客户端 IP"。
于是 request.getRemoteAddr() 返回的攻击者伪造值，正好落进白名单匹配，放行。

一句话根因：把"客户端 IP"的来源，信任到了不该信任的层。TCP 对端是内核给的、伪造成本高；请求头是应用给的、伪造成本约等于零。把前者替换成后者，安全等级就塌了一档。

三、具体做法：把"客户端 IP"的来源钉死在 TCP 对端 + 可信代理链

1) 边缘网关（Nginx）用 real_ip 模块规范化 XFF

# nginx.conf（边缘，只有一跳）
set_real_ip_from 10.0.0.0/8;      # 信任的代理网段
set_real_ip_from 172.16.0.0/12;
real_ip_header X-Forwarded-For;
real_ip_recursive on;             # 从右往左找第一个"非信任"IP 作为真实客户端

real_ip_recursive on 是关键：XFF 可能是 a, b, c，递归模式下 Nginx 从最右往左找，第一个落在 set_real_ip_from 之外的 IP 才是真实客户端。这样伪造的 10.0.1.7 如果不在信任网段里，就会被剥掉。

2) Spring Boot：`forward-headers-strategy` + 收紧 `trustedProxies`

# application.yml
server:
  forward-headers-strategy: native   # 或 framework；none = 完全不信头

@Bean
public WebServerFactoryCustomizer<TomcatServletWebServerFactory> customizer() {
    return factory -> factory.addContextCustomizers(ctx -> {
        RemoteIpValve valve = (RemoteIpValve) ctx.getValves().stream()
            .filter(v -> v instanceof RemoteIpValve).findFirst().orElse(null);
        if (valve != null) {
            valve.setTrustedProxies("10.0.0.0/8", "172.16.0.0/12"); // 只列真实代理
            valve.setProxyHeaders("X-Forwarded-For", "X-Forwarded-Proto");
        }
    });
}

3) 最稳的一招：应用层直接认 TCP 对端

如果架构上网关是唯一入口，应用根本不该再解析 XFF，直接：

String clientIp = request.getRemoteAddr(); // TCP 对端，内核给的

白名单匹配用 InetAddress + Inet4Address/SubnetUtils 这类网段对象，别用字符串 contains("10.0.1")——那个写法连 IPv4-mapped IPv6（::ffff:10.0.1.7）都会漏。

4) 纵深防御：IP 白名单只是第一道

管理面与数据面分离、管理面默认拒绝、加 MFA / 操作审计、关键操作二次确认。IP 白名单挡的是"匿名扫描"，挡不住"有 token 的内鬼"。

四、踩过的坑 & 反直觉之处

trustedProxies = 0.0.0.0/0 是自杀配置：等于告诉框架"任何 IP 发的头都算数"，XFF 伪造直接生效。我复盘的 5 个项目里，3 个栽在这。
real_ip_recursive 的 on/off 语义相反：on 从右往左、off 从左往右。多代理链下选错方向，真实客户端 IP 会被记成"中间某跳代理"。
IPv4-mapped IPv6 是隐形杀手：白名单写 10.0.1.7，客户端实际是 ::ffff:10.0.1.7，字符串匹配直接漏过。必须用 IP 网段对象做匹配。
getRemoteAddr() 和 getHeader("X-Forwarded-For") 语义不一致：开了 forward-headers-strategy 后前者被改写，后者还是原始头。两套 API 混着用，日志里"客户端 IP"忽左忽右。
本地 localhost 转发，线上是 LB：本地调试白名单"怎么都通"，一上线"怎么都不通"，根因就是代理链不同、trustedProxies 没覆盖到。
只信 X-Real-IP 不信 XFF（或反过来）：取决于边缘网关到底写哪个头，两边必须对齐，否则真实客户端 IP 永远取不到。

五、结论与可复用清单

延伸：社区里 [提问 913（mTLS 下信任网关透传 uid 导致越权，作者：温若衡-859）] 和 [讨论 44（内网=安全的老习惯，作者：温砚舟）] 聊的是"信任了不该信任的身份头"，本文聊的是"信任了不该信任的 IP 头"，本质是同一类问题——把权威判定下放到了可伪造的传输层字段。

可复用清单（贴墙上）：

应用层"客户端 IP"只认 TCP 对端，或明确的可信代理链，绝不裸信请求头；
边缘网关用 real_ip 模块规范化 XFF，recursive on；
trustedProxies 只列真实代理网段，禁止 0.0.0.0/0；
白名单匹配用 IP 网段对象，别用字符串；
管理面与数据面分离，管理面默认拒绝；
IP 白名单只是第一道，纵深防御（MFA / 审计 / 二次确认）不能省；
渗透用例：同一接口，加/不加 X-Forwarded-For 头各打一次，结果必须一致。

一句话收尾：门禁的钥匙该插在门禁上，别插在访客口袋里。

赞 0 · 收藏 0 · 评论 0 · 浏览 0

暂无评论。