mica-xss 使用文档

说明

  • 对表单绑定的字符串类型进行 xss 处理。
  • 对 json 字符串数据进行 xss 处理。
  • 提供路由和控制器方法级别的放行规则。
  • 对表单和 json 字符串 trim 处理。

使用

maven

<dependency>
<groupId>net.dreamlu</groupId>
<artifactId>mica-xss</artifactId>
<version>${version}</version>
</dependency>

gradle

compile("net.dreamlu:mica-xss:${version}")

配置

配置项 默认值 说明
mica.xss.enabled true 开启xss
mica.xss.trim-text true 【全局】是否去除文本首尾空格
mica.xss.mode clear 模式:clear 清理(默认),escape 转义
mica.xss.pretty-print false clear 专用 prettyPrint,默认关闭: 保留换行
mica.xss.enable-escape false clear 专用 转义,默认关闭
mica.xss.path-patterns /** 拦截的路由,例如: /api/order/**
mica.xss.path-exclude-patterns 放行的路由,默认为空

注解

可以使用 @XssCleanIgnore 注解对方法和类级别进行忽略。

自定义 xss 清理

如果内置的 xss 清理规则不满足需求,可以自己实现 XssCleaner,注册成 Spring bean 即可。

1. 注册成 Spring bean

@Bean
public XssCleaner xssCleaner() {
return new MyXssCleaner();
}

2. MyXssCleaner

public class MyXssCleaner implements XssCleaner {

@Override
public String clean(String html) {
Document.OutputSettings settings = new Document.OutputSettings()
// 1. 转义用最少的规则,没找到关闭的方法
.escapeMode(Entities.EscapeMode.xhtml)
// 2. 保留换行
.prettyPrint(false);
// 注意会被转义
String escapedText = Jsoup.clean(html, "", XssUtil.HtmlWhitelist.INSTANCE, settings);
// 3. 反转义
return Entities.unescape(escapedText);
}

}

mica-xss 不生效???

  1. Spring 5.0 (Spring boot 2.0) 开始项目里有继承 WebMvcConfigurerAdapterWebMvcConfigurationSupport 的要改成实现 WebMvcConfigurer
  2. 排查是否自定义了 Jackson ObjectMapper bean 或者是自定义了 String 字符串序列化。

微信 vs 公众号

如梦技术

精彩内容每日推荐!!!