ContiNew

切换日光/暗黑模式

XSS 过滤 ​

最后更新: 4 天前
实践版本: v2.16.0
提示文档具有版本时效性，部分内容可能已不适用于当前版本。如发现过时内容，请联系作者进行更新。

简介 ​

continew-starter-security-xss 是 ContiNew Starter 安全模块提供的 XSS（跨站脚本攻击）过滤模块（@since 2.0.0），通过 Servlet 过滤器对请求参数与请求体进行统一清理或转义，防止恶意脚本注入。

主要特性 ​

  • 无侵入： 基于 Servlet Filter 全局过滤，业务代码零改动
  • 双模式： 支持 CLEAN（清理 HTML 标签）与 ESCAPE（HTML 转义）两种处理模式
  • 路由粒度控制： 支持按路由配置拦截/放行范围
  • 全覆盖： 同时处理 GET 查询参数与 POST/PATCH/PUT 请求体

快速开始 ​

引入依赖 ​

pom.xml
xml
<dependency>
    <groupId>top.continew.starter</groupId>
    <artifactId>continew-starter-security-xss</artifactId>
</dependency>

添加配置 ​

配置详情请查看：top.continew.starter.security.xss.autoconfigure.XssProperties（@since 2.0.0）。

application.yml
yaml
--- ### XSS 过滤配置
continew-starter.security:
  xss:
    # 是否启用
    enabled: true
    # XSS 模式：CLEAN-清理 | ESCAPE-转义
    mode: CLEAN
    # 拦截路由（默认为空，为空时全量过滤；不为空时仅过滤命中路由）
    include-patterns: []
    # 放行路由（默认为空）
    exclude-patterns: []

自动装配需显式开启

自动装配条件为 continew-starter.security.xss.enabled=true，且未设置缺省匹配（matchIfMissing = false），即未显式配置该属性时自动装配不生效（注意：这与属性字段的默认值 true 语义不同）。引入依赖后请务必显式配置该项。

过滤规则 ​

启用后，模块注册全局过滤器（匹配 /*，仅处理 REQUEST 类型请求，执行顺序为最高优先级 + 200）：

  1. 请求路径命中 exclude-patterns → 跳过过滤；
  2. include-patterns 不为空 → 仅过滤命中的路由；
  3. 两者均为空 → 全量过滤。

对 GET 查询参数及 POST/PATCH/PUT 请求体：CLEAN 模式清理 HTML 标签，ESCAPE 模式进行 HTML 转义。

变更历史 ​

  • v2.0.0：web 模块新增 XSS 过滤器
  • v2.10.0：独立为 security-xss 模块（原 web 模块内组件）
  • v2.15.0：修复读取请求体数据不全的问题

核心依赖 ​

依赖描述
top.continew.starter:continew-starter-core核心模块

参考资料 ​

  1. OWASP 跨站脚本防御手册：https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html