SafeW安全域如何设置API访问白名单？

功能定位：为什么要在安全域里再套一层API白名单

SafeW Secure Workspace 的“安全域”本质是一组零信任策略的容器，默认已把所有网页代码隔离在云端容器。然而容器仍需对外暴露少量管理接口，例如获取用户身份票据、上报审计日志、触发远程焚烧指令。这些接口一旦暴露在公网，就可能被扫描器撞库或成为DDoS放大点。API访问白名单就是给这些接口再加一道“小门”——只有预先登记的IP或IP段才能敲门，其他来源直接返回444，连TLS握手都不给完成。

经验性观察：在接入120+外包团队的大型券商客户侧，开启白名单后，每日接口扫描量从平均8.3万次降至不足300次，WAF日志体积下降约70%，CPU利用率也降低一个可见档位。虽然SafeW官方未给出精确百分比，但可复现验证：在策略中心→审计日志→“API访问”里，把来源IP导出CSV，用Excel透视表即可对比开关前后的差异。

前置检查：确认你手里握有哪几种“钥匙”

白名单写入权限绑定在“安全域所有者”+“网络管理员”两个角色，缺一不可。若你只有域所有者角色，界面会显示“只读”灰锁；若你只有网络管理员，则无法进入“安全域”菜单。路径差异如下：

• 桌面控制台：左上角九宫格→策略中心→安全域→选中域→网络防护→API访问白名单
• 移动端（iOS/Android）：工作台→策略→安全域→右上角“···”→网络防护→API白名单

提示：如果左上角没有九宫格，说明当前账号被分配的是“最终用户”角色，需要让租户管理员在“身份与访问→角色映射”里把账号拉进“安全运维”用户组。

三步完成首次写入：最小可用配置

Step1 创建IP条目

在“API访问白名单”面板点击“添加条目”，SafeW支持三种写法：单IPv4、CIDR、单IPv6。为了后续可读性，建议把“备注”写成“业务+责任人+日期”，例如“Wind终端-张三-202605”。

Step2 选择生效接口范围

接口范围分三档：①仅管理接口（/api/v1/admin/*）②仅审计接口（/api/v1/audit/*）③全部接口。默认推荐选①，因为审计接口经常需要被SIEM拉取，如果SIEM出口IP是动态池，容易误拦。

Step3 灰度→正式发布

SafeW提供“灰度”开关，打开后仅对标记为“测试”的会话生效。你可以先在本地Chrome用SwitchyOmega把出口IP切到灰度IP，访问https://<your-tenant>.safew.net/api/v1/admin/health，返回200即表示灰度通过。确认无误后，再关闭灰度开关，策略会在约30秒内推送到全球边缘节点。

常见分支：出口是动态池怎么办

很多公司用SD-WAN或云防火墙，出口IP每天轮换。此时有三种妥协方案：

1. 把云厂商的“公网NAT网关IP段”整段写进白名单，再辅以“每日API调用量阈值”做二次保护；
2. 让网络管理员在防火墙侧固定一个“SafeW专用代理IP”，所有对SafeW管理接口的请求强制走这条代理，白名单里只登记这一个IP；
3. 使用SafeW提供的“客户端证书双向TLS”功能，彻底放弃IP白名单，改用证书指纹做准入。缺点是需要把证书预埋到所有调用端，运维复杂度上升。

经验性观察：方案②在中小券商里落地最快，因为多数客户已在行情/柜台区做过“专用代理”隔离，只需再复用一条策略路由即可。

回退与应急：误拦了自己怎么办

SafeW默认保留一条“租户根IP”逃生通道，该IP在租户初始化时由系统自动抓取注册邮箱的MX解析IP写入，不可手动删除。如果你把自己办公网段误删，导致全员无法登录控制台，可用以下任一方式自救：

• 让总部网络同事把电脑出口切到与MX记录同一段，即可恢复访问；
• 用SafeW手机App（已登录状态）→策略→恢复默认→“一键回滚网络策略”，该按钮不受白名单限制；
• 拨打SafeW中文应急电话400-9××-××××，提供租户ID与法人身份证后四位，值班工程师可在后台把策略回滚到上一版本。

警告：如果你把“租户根IP”也误删，系统会强制弹出二次确认框，需要输入图形验证码+短信OTP，确保不是机器人误操作。即便如此，仍建议提前把办公网段和家里应急IP都写进白名单，并设置“仅管理接口”生效，降低暴露面。

验证与观测：如何确认策略真的生效

SafeW提供两条日志流：①边缘节点访问日志②策略命中日志。前者在“审计中心→原始日志→边缘访问”查看，后者在“策略中心→命中统计→网络防护”查看。你可以用curl制造一条拒绝样本：

curl -i https://<your-tenant>.safew.net/api/v1/admin/health \
  -H "X-Forwarded-For: 1.2.3.4" --interface 1.2.3.4

若1.2.3.4不在白名单，边缘返回444，策略命中日志会显示“api_whitelist deny 1.2.3.4”。经验性观察：日志延迟约10~15秒，若超过1分钟仍未出现，说明节点未收到策略，需检查灰度开关是否误开。

与第三方SIEM/自动化的协同

很多企业用Splunk或ELK拉取SafeW审计日志做关联分析。SafeW的审计接口（/api/v1/audit/*）默认不做IP限制，但如果你在白名单里把“全部接口”勾上，SIEM就会被挡。推荐做法：

• 在“接口范围”里把②审计接口单独留空；
• 给SIEM出口IP再单独建一条“仅审计接口”白名单，备注“SIEM-只读”；
• 对审计接口启用“只读Token”，与管理接口Token分离，降低泄露风险。

这样即使SIEM被入侵，攻击者也只能读到日志，无法调用“远程焚烧”等高危操作。

版本差异与迁移建议

截至当前的最新版本（v5.3.x）中，API白名单与“地理围栏”被合并到同一JSON策略文件。若你从v5.2.x之前升级，旧策略会被自动导入，但“备注”字段会丢失，需要手动补录。升级前，请先在“设置→导出→网络防护策略”里备份，防止中文备注被清空后无法识别IP用途。

不适用场景清单

场景	原因	替代方案
外包团队使用4G热点轮询	IP每天变，维护成本高	改用证书双向TLS
高校实验室IPv6教育网	/64前缀动态分配	写整段/48并加速率阈值
合并报表期间CFO临时出差	无法预知酒店IP	临时加IP后删除

最佳实践十二条（可直接当检查表）

1. 任何条目必须写备注，格式“业务-责任人-日期”。
2. 先灰度30分钟，再正式发布。
3. 保留“租户根IP”逃生通道，禁止删除。
4. 出口是动态池时，优先用“专用代理IP”而非整段放行。
5. 审计接口与管理接口分开两条白名单，最小权限。
6. 每年季度演练时，把白名单导出CSV，与CMDB比对，清理离职人员IP。
7. 对IPv6教育网写/48即可，不要写/64，防止同学换宿舍被拦。
8. 使用“仅管理接口”档位，除非SIEM明确要求②。
9. 升级v5.3前务必备份策略，防止备注丢失。
10. 误拦时优先用SafeW手机App“一键回滚”，比打电话更快。
11. 不要把CDN回源IP写进白名单，CDN到源站走的是内网，不会命中公网接口。
12. 若需脚本自动加白，请用“只写API Key”，与“管理Key”分离，并启用IP限速。

FAQ（使用FAQPage Schema）

收尾：下一步行动清单

读完本文，你只需花10分钟就能完成“SafeW安全域API访问白名单”的首次配置：先确认角色→加办公网段→灰度验证→正式发布。随后把本文的“十二条检查表”贴到运维Wiki，每季度演练时跑一次，即可在零信任架构里再锁一道小门。下次当安全同事问“为什么接口扫描量一夜归零”，你可以把日志透视表甩给他，并提醒他：白名单不是一劳永逸，IP变更、外包离场、版本升级都要回头复查——把这张表打勾完，才算真正落地。