1. 问题背景与发现过程上周在给客户部署若依Plus框架时意外触发了系统内置XSS过滤器的异常行为。当时我们正在测试一个普通的富文本编辑器提交功能当用户输入包含特定HTML标签组合时后端竟然返回了500错误。经过层层排查最终定位到是框架自带的XSSFilter组件在处理某些特殊字符序列时存在逻辑缺陷。这个bug的隐蔽性在于它不会在常规XSS攻击场景下暴露比如简单的 而是在处理某些合法的HTML片段时错误地拦截了内容。更麻烦的是错误信息被吞没在框架底层前端只能收到模糊的服务器内部错误提示。2. 漏洞原理深度解析2.1 若依Plus的XSS防御机制若依Plus基于Spring Boot的XSS防护方案主要包含三个层级前端使用vue-xss进行基础过滤后端通过XSSFilter进行请求参数过滤响应阶段通过Jackson的JSON序列化进行二次转义问题出在第二层的XSSFilter实现上。其核心逻辑是对所有请求参数值进行HTML标签剥离关键代码如下public String filter(String value) { if (value null) return null; String cleanValue StringEscapeUtils.escapeHtml4(value); cleanValue Jsoup.clean(cleanValue, Safelist.relaxed()); return cleanValue; }2.2 具体缺陷分析当遇到类似下面的HTML片段时就会触发异常div classchart-container stylewidth:100% svg width100% height300px rect x10 y10 width90% height90%/ /svg /div问题根源在于StringEscapeUtils.escapeHtml4() 会将所有特殊字符转为HTML实体Jsoup.clean() 处理时遇到90%这样的CSS百分比值多层转义导致解析器状态混乱最终抛出IllegalArgumentException2.3 影响范围评估该缺陷影响所有使用若依Plus 3.6.0以下版本的项目特别是包含富文本编辑功能的模块需要处理SVG图形的系统使用CSS百分比布局的管理后台需要提交复杂HTML片段的工单系统3. 解决方案与修复步骤3.1 临时解决方案对于无法立即升级的项目建议在Filter中添加白名单机制// 添加对特定路径的豁免 String uri ((HttpServletRequest) request).getRequestURI(); if (uri.startsWith(/editor/save)) { chain.doFilter(request, response); return; }3.2 永久修复方案官方在3.6.0版本中重构了过滤逻辑移除了冗余的StringEscapeUtils转义改用更安全的Jsoup配置Safelist safelist Safelist.relaxed() .addAttributes(:all, style) .addProtocols(img, src, data); Jsoup.clean(input, , safelist, new OutputSettings().prettyPrint(false));添加了异常捕获机制try { return Jsoup.clean(value, safelist); } catch (Exception e) { log.warn(XSS过滤异常: {}, e.getMessage()); return value.replace(, lt;).replace(, gt;); }3.3 升级操作步骤修改pom.xml中的版本号ruoyi.version3.6.0/ruoyi.version清理并重新编译项目mvn clean package -DskipTests特别检查以下配置文件application.yml中的xss配置项自定义的XSS过滤规则富文本编辑器的白名单配置4. 验证与测试方案4.1 测试用例设计建议构造以下测试场景包含数学公式的HTMLdiv当xy时成立/divSVG矢量图形svgcircle cx50% cy50% r40%//svg复杂CSS样式div stylewidth:calc(100% - 20px)/div4.2 自动化测试脚本使用TestNG编写验证用例Test public void testXssFilterWithSpecialChars() { String input div1 2 3 1/div; String output xssFilter.filter(input); Assert.assertFalse(output.contains(lt;)); Assert.assertTrue(output.contains(div)); } Test public void testSvgHandling() { String input svg width100%rect x10%//svg; String output xssFilter.filter(input); Assert.assertTrue(output.contains(svg)); }5. 深度防御建议5.1 防御层优化方案建议采用分层防御策略防御层实现方式防护目标前端DOMPurify 内容安全策略(CSP)即时反馈网关ModSecurity规则阻断已知攻击模式后端定制化XSSFilter业务逻辑防护持久层存储前二次校验数据一致性5.2 关键配置参数在application.yml中建议配置xss: enabled: true exclude-urls: - /api/editor/save - /chart/data level: medium # [low|medium|high] allow-svg: false5.3 监控与日志添加专门的审计日志Aspect public class XssAuditLog { AfterReturning(execution(* com.ruoyi.framework.web.filter.XssFilter..*(..))) public void logFilterOperation(JoinPoint jp) { String param (String) jp.getArgs()[0]; if(param ! null param.length() 1000) { log.warn(Large content filtered: {}, param.substring(0, 100)); } } }6. 经验总结与避坑指南在实际项目中我们总结出以下经验教训转义顺序陷阱错误做法先HTML转义再JS转义正确顺序先解析再统一转义性能优化点对已知安全路径添加跳过逻辑对大文件上传接口禁用过滤使用缓存已验证的安全内容典型误判场景数学公式中的比较运算符代码片段展示功能国际化内容中的特殊符号应急处理方案// 在全局异常处理器中添加 ExceptionHandler(IllegalArgumentException.class) public R handleXssException(IllegalArgumentException e) { if (e.getMessage().contains(jsoup)) { return R.error(内容包含不安全字符); } return R.error(参数错误); }这个案例给我们的核心启示是安全过滤组件的实现需要同时考虑防护有效性和内容兼容性。特别是在现代Web应用中需要谨慎处理各类合法HTML5和CSS3特性避免因过度防御导致业务功能异常。建议所有使用若依Plus的团队都检查自己的XSS过滤策略确保不会拦截合法的内容输入。 
长河君 · 2026/9/17 16:18:21 · 阅读 1.2k 若依Plus框架XSS过滤器缺陷分析与修复方案
1. 问题背景与发现过程上周在给客户部署若依Plus框架时意外触发了系统内置XSS过滤器的异常行为。当时我们正在测试一个普通的富文本编辑器提交功能当用户输入包含特定HTML标签组合时后端竟然返回了500错误。经过层层排查最终定位到是框架自带的XSSFilter组件在处理某些特殊字符序列时存在逻辑缺陷。这个bug的隐蔽性在于它不会在常规XSS攻击场景下暴露比如简单的 而是在处理某些合法的HTML片段时错误地拦截了内容。更麻烦的是错误信息被吞没在框架底层前端只能收到模糊的服务器内部错误提示。2. 漏洞原理深度解析2.1 若依Plus的XSS防御机制若依Plus基于Spring Boot的XSS防护方案主要包含三个层级前端使用vue-xss进行基础过滤后端通过XSSFilter进行请求参数过滤响应阶段通过Jackson的JSON序列化进行二次转义问题出在第二层的XSSFilter实现上。其核心逻辑是对所有请求参数值进行HTML标签剥离关键代码如下public String filter(String value) { if (value null) return null; String cleanValue StringEscapeUtils.escapeHtml4(value); cleanValue Jsoup.clean(cleanValue, Safelist.relaxed()); return cleanValue; }2.2 具体缺陷分析当遇到类似下面的HTML片段时就会触发异常div classchart-container stylewidth:100% svg width100% height300px rect x10 y10 width90% height90%/ /svg /div问题根源在于StringEscapeUtils.escapeHtml4() 会将所有特殊字符转为HTML实体Jsoup.clean() 处理时遇到90%这样的CSS百分比值多层转义导致解析器状态混乱最终抛出IllegalArgumentException2.3 影响范围评估该缺陷影响所有使用若依Plus 3.6.0以下版本的项目特别是包含富文本编辑功能的模块需要处理SVG图形的系统使用CSS百分比布局的管理后台需要提交复杂HTML片段的工单系统3. 解决方案与修复步骤3.1 临时解决方案对于无法立即升级的项目建议在Filter中添加白名单机制// 添加对特定路径的豁免 String uri ((HttpServletRequest) request).getRequestURI(); if (uri.startsWith(/editor/save)) { chain.doFilter(request, response); return; }3.2 永久修复方案官方在3.6.0版本中重构了过滤逻辑移除了冗余的StringEscapeUtils转义改用更安全的Jsoup配置Safelist safelist Safelist.relaxed() .addAttributes(:all, style) .addProtocols(img, src, data); Jsoup.clean(input, , safelist, new OutputSettings().prettyPrint(false));添加了异常捕获机制try { return Jsoup.clean(value, safelist); } catch (Exception e) { log.warn(XSS过滤异常: {}, e.getMessage()); return value.replace(, lt;).replace(, gt;); }3.3 升级操作步骤修改pom.xml中的版本号ruoyi.version3.6.0/ruoyi.version清理并重新编译项目mvn clean package -DskipTests特别检查以下配置文件application.yml中的xss配置项自定义的XSS过滤规则富文本编辑器的白名单配置4. 验证与测试方案4.1 测试用例设计建议构造以下测试场景包含数学公式的HTMLdiv当xy时成立/divSVG矢量图形svgcircle cx50% cy50% r40%//svg复杂CSS样式div stylewidth:calc(100% - 20px)/div4.2 自动化测试脚本使用TestNG编写验证用例Test public void testXssFilterWithSpecialChars() { String input div1 2 3 1/div; String output xssFilter.filter(input); Assert.assertFalse(output.contains(lt;)); Assert.assertTrue(output.contains(div)); } Test public void testSvgHandling() { String input svg width100%rect x10%//svg; String output xssFilter.filter(input); Assert.assertTrue(output.contains(svg)); }5. 深度防御建议5.1 防御层优化方案建议采用分层防御策略防御层实现方式防护目标前端DOMPurify 内容安全策略(CSP)即时反馈网关ModSecurity规则阻断已知攻击模式后端定制化XSSFilter业务逻辑防护持久层存储前二次校验数据一致性5.2 关键配置参数在application.yml中建议配置xss: enabled: true exclude-urls: - /api/editor/save - /chart/data level: medium # [low|medium|high] allow-svg: false5.3 监控与日志添加专门的审计日志Aspect public class XssAuditLog { AfterReturning(execution(* com.ruoyi.framework.web.filter.XssFilter..*(..))) public void logFilterOperation(JoinPoint jp) { String param (String) jp.getArgs()[0]; if(param ! null param.length() 1000) { log.warn(Large content filtered: {}, param.substring(0, 100)); } } }6. 经验总结与避坑指南在实际项目中我们总结出以下经验教训转义顺序陷阱错误做法先HTML转义再JS转义正确顺序先解析再统一转义性能优化点对已知安全路径添加跳过逻辑对大文件上传接口禁用过滤使用缓存已验证的安全内容典型误判场景数学公式中的比较运算符代码片段展示功能国际化内容中的特殊符号应急处理方案// 在全局异常处理器中添加 ExceptionHandler(IllegalArgumentException.class) public R handleXssException(IllegalArgumentException e) { if (e.getMessage().contains(jsoup)) { return R.error(内容包含不安全字符); } return R.error(参数错误); }这个案例给我们的核心启示是安全过滤组件的实现需要同时考虑防护有效性和内容兼容性。特别是在现代Web应用中需要谨慎处理各类合法HTML5和CSS3特性避免因过度防御导致业务功能异常。建议所有使用若依Plus的团队都检查自己的XSS过滤策略确保不会拦截合法的内容输入。