IP 访问控制与 WAF
平台提供两层来源安全能力：接口级 IP 黑白名单可按环境和接口精细配置；网关内置 WAF 对所有开放接口统一检测 SQL 注入、XSS 与路径遍历攻击。两者与认证、限流相互独立。
第一层：IP 访问控制
入口
安全管理 → 流控规则 → IP访问控制。
列表字段
| 列 | 说明 |
|---|---|
| 规则ID | IP 规则编号 |
| 规则名称 | 便于识别的名称 |
| 规则类型 | 黑名单 / 白名单 |
| ip地址 | 规则包含的 IP 或 IP 段 |
| 关联API | 已绑定该规则的接口数量 |
| 修改时间 | 最近更新时间 |
支持按规则名称和环境筛选。
新建 IP 规则
- 点击「新建」；
- 选择所属环境（创建后不可修改）；
- 填写规则名称；
- 选择控制类型：
- 黑名单：列表中的 IP 被拒绝，其余放行；
- 白名单：只有列表中的 IP 被放行，其余拒绝；
- 填写 IP 地址，多个地址用英文逗号分隔，支持
起始IP~结束IP的区间写法； - 保存后关联接口。
IP 列表会逐个校验 IPv4 格式，区间两端都必须是合法 IPv4 地址。
执行逻辑
- 网关在认证之后读取接口的 IP 规则；
- 接口未配置 IP 规则时直接放行；
- 规则类型为空或为
white时按白名单处理，black时按黑名单处理； - 命中拒绝条件时返回 HTTP 200，业务码
40012，消息为“该IP地址不在有效范围内,{客户端IP}”； - 客户端 IP 由网关从请求头与连接信息中解析，代理部署时应确保网关能拿到真实来源 IP；
- MCP
tools/call反解到目标接口时会跳过接口级 IP 校验，因为应用级 IP 白名单已在 MCP 入口校验，避免同一请求被二次拦截。
与凭证 IP 白名单的区别
| 维度 | 接口级 IP 规则 | 应用凭证 IP 白名单 |
|---|---|---|
| 配置位置 | 安全管理 → IP访问控制 | 账户中心 → 应用凭证 |
| 作用范围 | 指定环境下的指定接口 | 整个应用凭证 |
| 错误码 | 40012 | 40018 |
| 适用认证 | 所有认证方式 | 使用该凭证的请求 |
两者的判断相互独立，可以同时配置。凭证维度还会校验应用状态、MCP 开关等条件，详见应用凭证与授权。
第二层：WAF 安全防护
WAF 在网关内执行，对开放接口流量做统一攻击特征检测，当前没有独立的管理页面，由部署配置控制开关。
开关与默认值
| 配置项 | 默认值 | 说明 |
|---|---|---|
apigo.waf.enabled | true | WAF 总开关，关闭后所有请求直接放行 |
| 请求体大小上限 | 10 MB | 超过直接拦截，不读取请求体内容 |
| 管理后台流量 | 跳过 | 管理后台路由不经过 WAF |
检测范围
| 检测对象 | 规则类型 | 说明 |
|---|---|---|
| 路径 | 路径遍历 | 归一化后匹配 ../、..\ |
| 全部 Query 参数 | SQL 注入、XSS、路径遍历 | 逐个参数值检测 |
| 高风险请求头 | SQL 注入、XSS | 仅检测 User-Agent、Referer、X-Forwarded-For、X-Real-IP、X-Requested-With |
| 请求体 | 仅大小检查 | 不读取内容，避免大文件与二进制请求的内存开销 |
Cookie、Authorization、X-Sign 等签名或编码类请求头不参与 WAF 扫描，避免误报。
规则特征
SQL 注入：联合查询、恒等条件（or 1=1、and '1'='1'）、into outfile、xp_cmdshell、information_schema、延时函数、benchmark( 等。
XSS：<script>、javascript:、事件处理器（onload=、onerror= 等）、<iframe>、<svg>、eval(、document.cookie。
路径遍历：解码后的 ../ 或 ..\。
归一化处理
为降低编码绕过风险，检测前会对文本做以下处理：
- 循环 URL 解码，最多 5 次；
- 剥离
/* */块注释和--行注释； - 去除控制字符、折叠空白；
- 统一转为小写。
因此，对参数做多次 URL 编码并不能绕过检测。
拦截响应
命中 WAF 时返回 HTTP 400，业务码 40017，消息为“请求包含非法字符，已被WAF拦截”，并设置 Api-Response-Type=error，调用日志会记录为失败。
误报处理
WAF 基于特征匹配，业务参数中正常出现以下内容时可能被误判：
- 文本中包含
javascript:、<script、onclick=等字样； - 自由文本中包含
1 or 1=1这类相似表达； - 参数值中出现
';或../。
处理建议：
- 调整业务参数，避免直接传递脚本片段或 SQL 片段；
- 将富文本、代码片 段等放入请求体（WAF 不扫描 body 内容）；
- 确属业务需要时，评估关闭全局 WAF 的影响后再调整部署配置；
- 通过调用日志中的
traceId与来源 IP 定位具体命中的请求。
治理链路中的位置
WAF 位于认证之前，因此未认证的恶意请求也会被拦截；IP 规则位于认证之后，需要先通过认证才能进入接口级 IP 判断。
限制与注意事项
- IP 规则只支持 IPv4，不支持 CIDR 网段写法，区间请使用
起始IP~结束IP； - 同一接口同时命中多条 IP 规则时的最终结果取决于接口当前绑定的规则，建设时避免给同一接口配置相互矛盾的黑白名单；
- WAF 不扫描请求体，不能替代接口入参校验与参数化查询；
- WAF 关闭是全局行为，会影响所有开放接口；
- 所有拦截都会进入调用日志，可结合数据分析仪表盘观察攻击趋势。