kkFileView 安全配置实战trust.host 白名单、黑名单与 TrustHostFilter 防 SSRF 机制详解【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView本篇指南基于 kkFileView 仓库根目录的 SECURITY_CONFIG.md 展开系统讲解 4.4.0 之后版本默认拒绝外部文件源、trust.host白名单与not.trust.host黑名单的完整配置方式、Docker 环境下的环境变量注入、配置验证方法与安全事件响应流程并结合 TrustHostFilter.java 等源码深入剖析主机匹配算法精确、通配符、IPv4 通配、CIDR与黑名单优先于白名单的判定链路帮助你把 kkFileView 的 SSRF服务器端请求伪造防护真正落到生产环境。一、为什么要做主机信任校验4.4.0 之后的默认拒绝策略kkFileView 是一个基于 Spring Boot 的通用文件在线预览项目。它的核心入口onlinePreview、getCorsFile、addTask等接口都接收一个“文件源 URL”参数由服务端去拉取并转换该 URL 指向的文件。这类“服务端替你请求任意 URL”的设计天然存在 SSRF 风险攻击者可以构造http://127.0.0.1:8080/admin、云厂商元数据地址http://169.254.169.254/...之类的 URL诱导预览服务去探测内网。因此从 4.4.0 之后版本开始kkFileView 增强了安全性默认拒绝所有未配置的外部文件预览请求。这一点在 application.properties 的“安全与访问控制配置”小节中也有明确注释# 信任站点白名单配置多个用,隔开 # ⚠️ 安全提示为防止SSRF攻击强烈建议配置信任主机白名单 # ⚠️ 如果不配置系统将默认拒绝所有外部文件预览请求 # 配置示例 # trust.host kkview.cn,yourdomain.com,cdn.example.com # 如果需要允许所有域名不推荐仅用于测试环境请设置为 # trust.host * # 当前配置默认本机测试 正式启用请修改 trust.host ${KK_TRUST_HOST:default} # 不信任站点黑名单配置多个用逗号隔开 # 黑名单优先级高于白名单设置后将禁止预览来自这些站点的文件 # 建议配置禁止访问内网地址和本地地址防止内部信息泄露 not.trust.host ${KK_NOT_TRUST_HOST:default}注意default占位值在 ConfigConstants.java 中当trust.host取值为default未配置时对应的主机集合会被初始化为空集合而不是“放行所有”。这个“空集合 默认拒绝”的组合就是 4.4.0 行为变化的实现基础也是很多团队升级后“预览突然全部失效”的根因。1.1 校验发生在哪些接口在 WebConfig.java 中TrustHostFilter通过FilterRegistrationBean注册只拦截以下四个预览入口SetString filterUri new HashSet(); filterUri.add(/onlinePreview); filterUri.add(/picturesPreview); filterUri.add(/getCorsFile); filterUri.add(/addTask);也就是说任何最终指向外部文件源的请求——无论是页面预览onlinePreview、图片预览picturesPreview、跨域取文件getCorsFile还是大文件异步转换任务addTask——在进入 Controller 之前都会先经过主机信任校验。1.2 源 URL 是怎么被取出来的WebUtils.getSourceUrl() 按优先级从请求参数url、currentUrl、urlPath、urls中提取文件源地址并支持 Base64 / AES 解码decodeUrl见 WebUtils.java。这意味着即使攻击者把恶意 URL 做 Base64 编码绕开前端审查TrustHostFilter仍然能拿到解码后的真实地址再做判定——校验发生在解码之后、转换之前这是该防护链路能够成立的第一个关键点。二、信任主机白名单配置trust.host2.1 两种配置方式方式 1通过配置文件。在 application.properties 中配置允许预览的域名多个域名用英文逗号分隔trust.host kkview.cn,yourdomain.com,cdn.example.com方式 2通过环境变量。适合 Docker / K8s 等不便改配置文件的部署形态KK_TRUST_HOSTkkview.cn,yourdomain.com,cdn.example.com两者等价因为属性值本身就是trust.host ${KK_TRUST_HOST:default}环境变量会覆盖配置文件默认值。示例场景只允许预览来自oss.aliyuncs.com和cdn.example.com的文件trust.host oss.aliyuncs.com,cdn.example.com2.2 配置的解析细节源码佐证从 ConfigConstants.setTrustHostValue() 的实现看白名单字符串在入库前有三次规范化处理private static CopyOnWriteArraySetString getHostValue(String trustHost) { return DEFAULT_VALUE.equalsIgnoreCase(trustHost) ? new CopyOnWriteArraySet() : new CopyOnWriteArraySet(Arrays.asList(trustHost.toLowerCase().replaceAll(\\s, ).split(,))); }小写化trustHost.toLowerCase()配合TrustHostFilter中对请求主机同样toLowerCase的处理域名大小写实际不影响匹配结果去空白replaceAll(\\s, )a.com, b.com与a.com,b.com等价按逗号切分存入CopyOnWriteArraySet该集合类型保证了动态刷新时读线程不受写影响。此外ConfigRefreshComponent.java 会周期性间隔由kk.refreshschedule控制application.properties 中默认为 2 秒重新读取trust.host与not.trust.host并调用对应的setXxxValue热更新内存值。结论白名单/黑名单修改后无需重启服务即可生效这对线上应急加黑名单尤其重要。三、允许所有主机trust.host *仅测试环境trust.host *⚠️警告此配置会允许访问任意外部地址存在安全风险仅应在测试环境使用源码层面*在 TrustHostFilter.isNotTrustHost() 中是白名单的“超级开关”// 支持通配符 * 表示允许所有主机 if (ConfigConstants.getTrustHostSet().contains(*)) { logger.debug(允许所有主机访问通配符模式: {}, host); return false; }但要注意即使白名单是*黑名单依然先生效见下文第四节。因此trust.host *not.trust.host 127.0.0.1,192.168.*是比裸*安全的折中写法测试环境也建议保留内网黑名单。四、黑名单配置not.trust.host高级禁止特定域名或内网地址# 禁止访问内网地址强烈推荐 not.trust.host localhost,127.0.0.1,192.168.*,10.*,172.16.*,169.254.* # 禁止特定恶意域名 not.trust.host malicious-site.com,spam-domain.net优先级黑名单 白名单。这一优先级不是约定俗成而是判定顺序决定的——isNotTrustHost()先查黑名单、后查白名单// 如果配置了黑名单优先检查黑名单 if (CollectionUtils.isNotEmpty(ConfigConstants.getNotTrustHostSet()) matchAnyPattern(host, ConfigConstants.getNotTrustHostSet())) { return true; // 命中黑名单直接拒绝 } // 如果配置了白名单检查是否在白名单中 if (CollectionUtils.isNotEmpty(ConfigConstants.getTrustHostSet())) { if (ConfigConstants.getTrustHostSet().contains(*)) { return false; } return !matchAnyPattern(host, ConfigConstants.getTrustHostSet()); } // 安全加固默认拒绝所有未配置的主机防止SSRF攻击 logger.warn(未配置信任主机列表拒绝访问主机: {}请在配置文件中设置 trust.host 或 KK_TRUST_HOST 环境变量, host); return true;TrustHostFilterTests.java 中的shouldKeepBlacklistHigherPriorityThanWhitelist用例对该行为做了回归验证白名单为*时127.0.0.1、10.1.2.3仍被黑名单拦截而8.8.8.8放行。4.1 四种匹配模式源码级解析matchHostPattern() 支持四种匹配方式白名单和黑名单通用模式示例说明精确匹配example.com与主机小写形式完全相等全局通配*仅白名单有意义放行一切黑名单仍优先生效域名通配*.example.com编译为正则*.example.com匹配cdn.example.com、api.internal.example.com不匹配根域example.comIPv4 通配192.168.*仅对字面量 IPv4地址逐段匹配不匹配任何域名如192.168.evil.comIPv4 CIDR192.168.0.0/16按网络掩码位运算判断支持 /0–/32其中两处实现细节值得注意1IPv4 通配只认字面量 IP。isIpv4WildcardPattern()要求模式形如^[0-9.*]$matchIpv4Wildcard()还强制要求被匹配的主机本身是合法的 4 段 IPv4 字面量。配合 TrustHostFilterTests.shouldBlockWildcardNotTrustHostPattern 的用例192.168.*拦截192.168.1.10但不拦截域名形式的192.168.evil.com——它会被当作普通域名走白名单逻辑而不是被 IP 规则误伤。2CIDR 匹配刻意不做 DNS 解析。parseLiteralIpv4() 的注释写得很直白/** * 仅解析字面量 IPv4 地址不做 DNS 解析防止 DNS rebinding/TOCTOU 风险。 */如果实现中先做 DNS 解析再判 CIDR攻击者可以用一个“检查时解析为公网 IP、请求时解析为内网 IP”的域名实施 DNS rebinding 绕过。只认字面量 IP 就从根上排除了这条攻击路径对应的测试shouldBlockCidrNotTrustHostPattern也断言了localhost这类域名不会被 CIDR 规则匹配因为它不是字面量 IP。测试集还覆盖了高位字节200.0.0.0/8与上界255.255.255.255/32的位运算正确性。3通配符编译带缓存。域名通配会经wildcardToRegex()编译成正则并缓存进wildcardPatternCacheConcurrentHashMap高频请求下不会重复编译Pattern.quote保证了字面量片段不被解释为正则元字符。五、拒绝响应的完整链路理解“配置如何变成一次 403”需要把三段代码串起来TrustHostFilter.doFilter()取址WebUtils.getSourceUrl(request)从url/currentUrl/urlPath/urls参数取文件源Base64/AES 解码后WebUtils.getHost(url)WebUtils.java解析出小写主机判定isNotTrustHost(host) || !WebUtils.isValidUrl(url)任一为真即拒绝。isValidUrl只放行http/https/ftp/rtsp/mms/file六种协议头WebUtils.javagopher://、jar://这类常用于 SSRF 探测的协议直接出局主机为null如 file 协议、URL 解析失败时isNotTrustHost也返回 true响应HTTP 状态码置为403 FORBIDDEN输出类路径下web/notTrustHost.html页面init()时预读入内存并把${current_host}占位符替换为实际主机名让用户看到“当前预览文件来自不受信任的站点xxx”。这套“协议白名单 主机信任 明确 403 页面”的组合与配置层的prohibit禁止exe,dll,dat等文件类型一起构成了 kkFileView 预览侧的纵深防御。六、Docker 环境配置在容器化部署中通过-e注入环境变量即可无需改镜像内配置docker run -d \ -e KK_TRUST_HOSTyourdomain.com,cdn.example.com \ -e KK_NOT_TRUST_HOSTlocalhost,127.0.0.1 \ -p 8012:8012 \ keking/kkfileview:4.4.0该方式与 K8s 完全兼容env段写入同名变量即可。由于trust.host/not.trust.host支持ConfigRefreshComponent热刷新通过挂载配置卷修改 properties 后也无需重启容器默认 2 秒周期内生效这为滚动升级期间的临时策略调整提供了便利。仓库中同时提供 Dockerfile 与 docker/kkfileview-base 基础镜像可在其基础上做二次构建。七、生产环境推荐配置与反例7.1 推荐配置# 1. 明确配置信任主机白名单 trust.host your-cdn.com,your-storage.com # 2. 配置黑名单防止内网访问 not.trust.host localhost,127.0.0.1,192.168.*,10.*,172.16.* # 3. 禁用文件上传生产环境 file.upload.disable true # 4. 配置基础URL使用反向代理时 base.url https://preview.yourdomain.com补充两点与上述配置相关的说明file.upload.disable true在 application.properties 中当前默认值即为 true“十一、首页与文件管理配置”小节生产环境保持默认即可base.url在使用 Nginx 等反向代理时必须显式配置为对外服务地址否则预览页面拼出的资源地址会指向代理内部地址而无法加载。7.2 不推荐配置# 危险允许所有主机访问 trust.host * # 危险启用文件上传生产环境 file.upload.disable false另外两个常被忽略的相关开关也建议在生产环境保持收紧状态application.properties 当前默认值kk.ignore.ssl false启用完整证书验证避免中间人降级风险与kk.enable.redirect false禁用 URL 重定向跟随防止借 302 跳转到未受控主机绕过白名单直觉。八、配置验证确认白名单/黑名单真的生效8.1 测试白名单是否生效配置白名单trust.host kkview.cn尝试预览白名单内的文件注意实际接口中 url 参数为 Base64 编码后的值此处为语义示意http://localhost:8012/onlinePreview?urlhttps://kkview.cn/test.pdf ✅ 应该可以正常预览尝试预览白名单外的文件http://localhost:8012/onlinePreview?urlhttps://other-domain.com/test.pdf ❌ 应该被拒绝返回 403 并显示“不信任的文件源”页面notTrustHost.html8.2 测试黑名单是否生效配置黑名单not.trust.host localhost,127.0.0.1尝试访问本地文件http://localhost:8012/getCorsFile?urlPathhttp://127.0.0.1:8080/admin ❌ 应该被拒绝8.3 用单元测试做本地回归如果要在本地确认匹配引擎行为而不是起服务可直接运行 TrustHostFilterTests.java8 个用例覆盖IPv4 通配、CIDR、高位/上界 CIDR、空白主机拒绝、白名单通配、黑名单优先级、黑名单存在时白名单仍强制。测试通过ConfigConstants.setTrustHostValue(...)直接注入内存配置AfterEach统一还原为default互不污染——这也是官方验证“配置语义”的权威依据。九、常见问题FAQQ1升级后无法预览文件了原因新版本默认拒绝未配置的主机即trust.host仍为default时主机集合为空全部请求落入“默认拒绝”分支。解决在配置文件中添加信任主机列表trust.host your-file-server.comQ2如何临时恢复旧版本行为不推荐但如果确实需要trust.host *Q3配置了白名单但还是无法访问排查清单域名是否完全匹配。需要说明的是从源码看getHostValue与isNotTrustHost两侧均做小写归一化域名大小写差异不会导致匹配失败若仍失败重点检查拼写、多余空格空格会被自动去除一般无影响以及是否写成了带协议的完整 URL 而非纯主机名是否配置了黑名单——黑名单优先级更高可能命中了意料之外的条目查看日志中的 WARNING 信息默认拒绝分支会打印“未配置信任主机列表拒绝访问主机: xxx”主机为空时会打印“主机名为空或无效拒绝访问”这两条日志能快速定位是“没配白名单”还是“URL 解析失败”确认环境变量KK_TRUST_HOST/KK_NOT_TRUST_HOST是否设置正确——注意环境变量会覆盖配置文件中的属性占位默认值确认改动是否已完成热刷新默认kk.refreshschedule 2秒必要时查看刷新组件日志。Q4如何允许子域名已支持通配符域名匹配可使用*.example.comtrust.host *.example.com说明*.example.com会匹配cdn.example.com、api.internal.example.com但不匹配根域example.com——需要根域时请显式追加example.com对于 IP 风格通配如192.168.*、10.*仅匹配字面量 IPv4 地址不匹配域名对应isIpv4WildcardPatternmatchIpv4Wildcard实现。此外若内网段较复杂黑名单可直接使用 CIDR 写法如192.168.0.0/16、172.16.0.0/12源码已支持且同样不做 DNS 解析。十、安全事件响应如果发现可疑的预览请求按以下流程处置查日志搜索 “拒绝访问主机” 关键字默认拒绝分支与 “主机名为空或无效拒绝访问” 关键字统计被拦截主机的分布核对白名单确认trust.host配置是否合理是否存在过宽的*或宽泛通配查网络面检查是否有异常的外发网络请求结合代理/防火墙日志重点关注对169.254.*元数据地址与内网管理端口的探测动态加黑名单利用配置热刷新能力将可疑域名/网段追加到not.trust.host支持通配与 CIDR无需重启即生效上报若怀疑存在通用漏洞与个人配置无关按 SECURITY.md 的安全策略通过项目的私密漏洞报告渠道提交受影响版本、部署方式、复现步骤与脱敏日志不要在公开渠道披露细节。十一、小结最小权限原则落地清单配置项属性 / 环境变量生产建议默认值当前仓库信任白名单trust.host/KK_TRUST_HOST明确列出文件源域名不用*default 全部拒绝不信任黑名单not.trust.host/KK_NOT_TRUST_HOST至少覆盖localhost,127.0.0.1,192.168.*,10.*,172.16.*,169.254.*default 空文件上传开关file.upload.disabletruetrue反向代理地址base.url代理部署时必填defaultSSL 验证kk.ignore.sslfalse生产收紧false重定向跟随kk.enable.redirectfalsefalsekkFileView 的这套 SSRF 防护可以概括为三层入口层协议白名单isValidUrl→判定层黑名单优先 白名单 默认拒绝TrustHostFilter含 CIDR/通配匹配且不解析 DNS→响应层403 明确的拒绝页面。配置侧只需维护trust.host与not.trust.host两个逗号分隔列表支持热刷新即可在“可用性”与“安全性”之间获得可控的平衡点。遵循最小权限原则、定期复核信任主机列表是保持这套机制长期有效的基本要求。【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
