userList;
@SensitiveEntry
private User[] userArray;
//...
}
```
# 自定义注解
- v0.0.4 新增功能。允许功能自定义条件注解和策略注解。
- v0.0.11 新增功能。允许功能自定义级联脱敏注解。
## 案例1
### 自定义密码脱敏策略&自定义密码脱敏策略生效条件
- 策略脱敏
```java
/**
* 自定义密码脱敏策略
* @author binbin.hou
* date 2019/1/17
* @since 0.0.4
*/
@Inherited
@Documented
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@SensitiveStrategy(CustomPasswordStrategy.class)
public @interface SensitiveCustomPasswordStrategy {
}
```
- 脱敏生效条件
```java
/**
* 自定义密码脱敏策略生效条件
* @author binbin.hou
* date 2019/1/17
* @since 0.0.4
*/
@Inherited
@Documented
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@SensitiveCondition(ConditionFooPassword.class)
public @interface SensitiveCustomPasswordCondition{
}
```
- TIPS
`@SensitiveStrategy` 策略单独使用的时候，默认是生效的。
如果有 `@SensitiveCondition` 注解，则只有当条件满足时，才会执行脱敏策略。
`@SensitiveCondition` 只会对系统内置注解和自定义注解生效，因为 `@Sensitive` 有属于自己的策略生效条件。
- 策略优先级
`@Sensitive` 优先生效，然后是系统内置注解，最后是用户自定义注解。
### 对应的实现
两个元注解 `@SensitiveStrategy`、`@SensitiveCondition` 分别指定了对应的实现。
- CustomPasswordStrategy.java
```java
public class CustomPasswordStrategy implements IStrategy {
@Override
public Object des(Object original, IContext context) {
return "**********************";
}
}
```
- ConditionFooPassword.java
```java
/**
* 让这些 123456 的密码不进行脱敏
* @author binbin.hou
* date 2019/1/2
* @since 0.0.1
*/
public class ConditionFooPassword implements ICondition {
@Override
public boolean valid(IContext context) {
try {
Field field = context.getCurrentField();
final Object currentObj = context.getCurrentObject();
final String name = (String) field.get(currentObj);
return !name.equals("123456");
} catch (IllegalAccessException e) {
throw new RuntimeException(e);
}
}
}
```
### 定义测试对象
定义一个使用自定义注解的对象。
```java
public class CustomPasswordModel {
@SensitiveCustomPasswordCondition
@SensitiveCustomPasswordStrategy
private String password;
@SensitiveCustomPasswordCondition
@SensitiveStrategyPassword
private String fooPassword;
//其他方法
}
```
### 测试
```java
/**
* 自定义注解测试
*/
@Test
public void customAnnotationTest() {
final String originalStr = "CustomPasswordModel{password='hello', fooPassword='123456'}";
final String sensitiveStr = "CustomPasswordModel{password='**********************', fooPassword='123456'}";
CustomPasswordModel model = buildCustomPasswordModel();
Assert.assertEquals(originalStr, model.toString());
CustomPasswordModel sensitive = SensitiveUtil.desCopy(model);
Assert.assertEquals(sensitiveStr, sensitive.toString());
Assert.assertEquals(originalStr, model.toString());
}
```
构建对象的方法如下：
```java
/**
* 构建自定义密码对象
* @return 对象
*/
private CustomPasswordModel buildCustomPasswordModel(){
CustomPasswordModel model = new CustomPasswordModel();
model.setPassword("hello");
model.setFooPassword("123456");
return model;
}
```
## 案例2
- v0.0.11 新增功能。允许功能自定义级联脱敏注解。
### 自定义级联脱敏注解
- 自定义级联脱敏注解
可以根据自己的业务需要，在自定义的注解上使用 `@SensitiveEntry`。
使用方式保持和 `@SensitiveEntry` 一样即可。
```java
/**
* 级联脱敏注解,如果对象中属性为另外一个对象(集合)，则可以使用这个注解指定。
*
* 1. 如果属性为 Iterable 的子类集合，则当做列表处理，遍历其中的对象
* 2. 如果是普通对象，则处理对象中的脱敏信息
* 3. 如果是普通字段/MAP，则不做处理
* @since 0.0.11
*/
@Inherited
@Documented
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@SensitiveEntry
public @interface SensitiveEntryCustom {
}
```
### 定义测试对象
定义一个使用自定义注解的对象。
```java
public class CustomUserEntryObject {
@SensitiveEntryCustom
private User user;
@SensitiveEntryCustom
private List userList;
@SensitiveEntryCustom
private User[] userArray;
// 其他方法...
}
```
# 生成脱敏后的 JSON
## 说明
为了避免生成中间脱敏对象，v0.0.6 之后直接支持生成脱敏后的 JSON。
## 使用方法
新增工具类方法，可以直接返回脱敏后的 JSON。
生成的 JSON 是脱敏的，原对象属性值不受影响。
```java
public static String desJson(Object object)
```
## 注解的使用方式
和 `SensitiveUtil.desCopy()` 完全一致。
## 使用示例代码
所有的测试案例中，都添加了对应的 `desJson(Object)` 测试代码，可以参考。
此处只展示最基本的使用。
```java
final String originalStr = "SystemBuiltInAt{phone='18888888888', password='1234567', name='脱敏君', email='12345@qq.com', cardId='123456190001011234'}";
final String sensitiveJson = "{\"cardId\":\"123456**********34\",\"email\":\"12******.com\",\"name\":\"脱**\",\"phone\":\"1888****888\"}";
SystemBuiltInAt systemBuiltInAt = DataPrepareTest.buildSystemBuiltInAt();
Assert.assertEquals(sensitiveJson, SensitiveUtil.desJson(systemBuiltInAt));
Assert.assertEquals(originalStr, systemBuiltInAt.toString());
```
## 注意
本次 JSON 脱敏基于 [FastJSON](https://github.com/alibaba/fastjson)。
FastJSON 在序列化本身存在一定限制。当对象中有集合，集合中还是对象时，结果不尽如人意。
### 示例代码
本测试案例可见测试代码。
```java
final String originalStr = "UserCollection{userList=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userSet=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userCollection=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userMap={map=User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}}}";
final String commonJson = "{\"userArray\":[{\"email\":\"12345@qq.com\",\"idCard\":\"123456190001011234\",\"password\":\"1234567\",\"phone\":\"18888888888\",\"username\":\"脱敏君\"}],\"userCollection\":[{\"$ref\":\"$.userArray[0]\"}],\"userList\":[{\"$ref\":\"$.userArray[0]\"}],\"userMap\":{\"map\":{\"$ref\":\"$.userArray[0]\"}},\"userSet\":[{\"$ref\":\"$.userArray[0]\"}]}";
final String sensitiveJson = "{\"userArray\":[{\"email\":\"12******.com\",\"idCard\":\"123456**********34\",\"phone\":\"1888****888\",\"username\":\"脱**\"}],\"userCollection\":[{\"$ref\":\"$.userArray[0]\"}],\"userList\":[{\"$ref\":\"$.userArray[0]\"}],\"userMap\":{\"map\":{\"$ref\":\"$.userArray[0]\"}},\"userSet\":[{\"$ref\":\"$.userArray[0]\"}]}";
UserCollection userCollection = DataPrepareTest.buildUserCollection();
Assert.assertEquals(commonJson, JSON.toJSONString(userCollection));
Assert.assertEquals(sensitiveJson, SensitiveUtil.desJson(userCollection));
Assert.assertEquals(originalStr, userCollection.toString());
```
### 解决方案
如果有这种需求，建议使用原来的 `desCopy(Object)`。
# 脱敏引导类
为了配置的灵活性，引入了引导类。
## 配置属性
引导类 SensitiveBs 的默认配置属性如下：
```java
SensitiveBs.newInstance()
.deepCopy(FastJsonDeepCopy.getInstance())
.hash(Hashes.empty())
```
## 核心 api 简介
`SensitiveBs` 引导类的核心方法列表如下：
| 序号 | 方法 | 参数 | 结果 | 说明 |
|:---|:---|:---|:---|:---|
| 1 | desCopy() | 目标对象 | 深度拷贝脱敏对象 | 适应性更强 |
| 2 | desJson() | 目标对象 | 脱敏对象 json | 性能较好 |
## 使用示例
使用方式和工具类一致，示意如下：
```java
SensitiveBs.newInstance().desCopy(user);
```
## 配置哈希策略
直接指定哈希策略即可，比如下面以 md5 作为值的哈希策略。
```java
// 指定哈希策略
final SensitiveBs sensitiveBs = SensitiveBs.newInstance().hash(Hashes.md5());
```
效果如下：
```
final String originalStr = "User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}";
final String sensitiveStr = "User{username='脱**|00871641C1724BB717DD01E7E5F7D98A', idCard='123456**********34|1421E4C0F5BF57D3CC557CFC3D667C4E', password='null', email='12******.com|6EAA6A25C8D832B63429C1BEF149109C', phone='1888****888|5425DE6EC14A0722EC09A6C2E72AAE18'}";
final String expectJson = "{\"email\":\"12******.com|6EAA6A25C8D832B63429C1BEF149109C\",\"idCard\":\"123456**********34|1421E4C0F5BF57D3CC557CFC3D667C4E\",\"phone\":\"1888****888|5425DE6EC14A0722EC09A6C2E72AAE18\",\"username\":\"脱**|00871641C1724BB717DD01E7E5F7D98A\"}";
```
## 配置深度拷贝实现
默认的使用 FastJson 进行对象的深度拷贝，等价于：
```java
SensitiveBs.newInstance()
.deepCopy(FastJsonDeepCopy.getInstance())
.desJson(user);
```
参见 [SensitiveBsTest.java](https://github.com/houbb/sensitive/blob/master/sensitive-test/src/test/java/com/github/houbb/sensitive/test/bs/SensitiveBsTest.java)
deepCopy 用于指定深度复制的具体实现，支持用户自定义。
# 深度复制（DeepCopy）
## 说明
深度复制可以保证我们日志输出对象脱敏，同时不影响正常业务代码的使用。
可以实现深度复制的方式有很多种，默认基于 [fastjson](https://github.com/alibaba/fastjson) 实现的。
为保证后续良性发展，v0.0.13 版本之后将深度复制接口抽离为单独的项目：
> [deep-copy](https://github.com/houbb/deep-copy)
## 内置策略
目前支持 6 种基于序列化实现的深度复制，便于用户替换使用。
每一种都可以单独使用，保证依赖更加轻量。
## 自定义
为满足不同场景的需求，深度复制策略支持用户自定义。
> [自定义深度复制](https://github.com/houbb/deep-copy#%E8%87%AA%E5%AE%9A%E4%B9%89)
# log4j2 插件统一脱敏
## 说明
上面的方法非常适用于新的项目，按照响应的规范进行推广。
但是很多金融公司都有很多历史遗留项目，或者使用不规范，比如使用 map 等，导致上面的方法在脱敏技改时需要耗费大量的时间，而且回溯成本很高。
有没有什么方法，可以直接在日志层统一处理呢？
## log4j2 Rewrite
我们可以基于 log4j2 RewritePolicy 统一使用脱敏策略。
说明：如果使用 slf4j 接口，实现为 log4j2 时也是支持的。
## 使用入门
### maven 引入
引入核心脱敏包。
```xml
com.github.houbb
sensitive-log4j2
1.7.0
```
其他的一般项目中也有，如 log4j2 包：
```xml
org.apache.logging.log4j
log4j-api
${log4j2.version}
org.apache.logging.log4j
log4j-core
${log4j2.version}
```
### log4j2.xml 配置
例子如下:
```xml
%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n
UTF-8
```
几个步骤：
1. 指定 package 为 `packages = "com.github.houbb.sensitive.log4j2.layout"`
2. 按照 log4j2 layout 规范，指定 Layout 策略为 `SensitivePatternLayout`
### 测试
正常的日志打印：
```java
private static final String TEST_LOG = "mobile:13088887777; bankCard:6217004470007335024, email:mahuateng@qq.com, amount:123.00, " +
"IdNo:340110199801016666, name1:李明, name2:李晓明, name3:李泽明天, name4:山东小栗旬" +
", birthday:20220517, GPS:120.882222, IPV4:127.0.0.1, address:中国上海市徐汇区888号;";
logger.info(TEST_LOG);
```
自动脱敏效果如下：
```
01:37:28.010 [main] INFO com.github.houbb.sensitive.test.log4j2.Log4j2AndSlf4jLayoutTest - mobile:130****7777|9FC4D36D63D2B6DC5AE1297544FBC5A2; bankCard:6217***********5024|444F49289B30944AB8C6C856AEA21180, email:mahu*****@qq.com|897915594C94D981BA86C9E83ADD449C, amount:123.00, IdNo:340110199801016666, name1:李明, name2:李晓明, name3:李泽明天, name4:山东小栗旬, birthday:20220517, GPS:120.882222, IPV4:127.0.0.1, address:中国上海市徐******|821A601949B1BD18DCBAAE27F2E27147;
```
ps: 这里是为了演示各种效果，实际默认对应为 1,2,3,4,9 这几种策略。
## log4j2 配置定制化
为了满足各种用户的场景，在 V1.6.0 引入了 SensitivePatternLayout 策略的可配置化。
用户可以在应用 resources 下通过 `chars-scan-config.properties` 配置文件指定。
### 默认配置
log4j2 配置中，`SensitivePatternLayout` 配置默认为：
```properties
chars.scan.prefix=:：,，'"‘“=| +()（）
chars.scan.scanList=1,2,3,4,9
chars.scan.replaceList=1,2,3,4,9
chars.scan.defaultReplace=12
chars.scan.replaceHash=md5
chars.scan.whiteList=""
```
### 属性说明
SensitivePatternLayout 策略的属性说明。
| 属性 | 说明 | 默认值 | 备注 |
|:---|:------------|:-------------------|:-----------------------------------------|
| prefix | 需要脱敏信息的匹配前缀 | `:：,，'"‘“= +()（）` 和英文竖线 | 降低误判率 |
| replaceHash | 哈希策略模式 | `md5` | 支持 md5/none 两种模式 |
| scanList | 敏感扫描策略列表 | `1,2,3,4` | 1~10 内置的10种敏感信息扫描策略，多个用逗号隔开 |
| replaceList | 敏感替换策略列表 | `1,2,3,4` | 1~10 内置的10种敏感信息替换策略，多个用逗号隔开 |
| defaultReplace | 敏感替换默认策略 | `12` | 1~13 内置的13种敏感信息替换策略，指定一个。当列表没有匹配时，默认使用这个 |
| whiteList | 白名单 | `` | 希望跳过处理的白名单信息 |
其中 1-13 的内置策略说明如下：
| 策略标识 | 说明 |
|:-----|:-----------------------|
| 1 | 手机号 |
| 2 | 身份证 |
| 3 | 银行卡 |
| 4 | 邮箱 |
| 5 | 中国人名 |
| 6 | 出生日期 |
| 7 | GPS |
| 8 | IPV4 |
| 9 | 地址 |
| 10 | 护照 |
| 11 | 匹配任意不掩盖 |
| 12 | 匹配任意半掩盖 |
| 13 | 匹配任意全掩盖 |
| m1 | 数字类合并操作(m1:1&2&3) 性能更好 |
| m3 | 拓展类合并操作(m3:4&5&9) 性能更好 |
### 不足之处
这里的策略自定义和 log4j2 的插件化比起来，确实算不上强大，但是可以满足 99% 的脱敏场景。
后续有时间考虑类似 log4j2 的 plugins 思想，实现更加灵活的自定义策略。
# logback 脱敏插件
## 说明
为了便于用户使用，v1.6.0 开始支持 logback 插件模式。
## 使用入门
### maven 引入
引入核心脱敏包。
```xml
com.github.houbb
sensitive-logback
1.7.0
```
引入 logback 依赖包
```xml
ch.qos.logback
logback-classic
${logback.version}
```
### 指定 logback.xml 配置
```xml
%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %sensitive%n
%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
```
这里共计支持 Converter 和 Layout 两种模式，任选一个即可。
建议使用 SensitiveLogbackConverter，脱敏日志内容。
## 日志效果
脱密效果和 log4j2 类似，如下：
```
01:42:32.579 [main] INFO c.g.h.sensitive.test2.LogbackMain - mobile:130****7777|9FC4D36D63D2B6DC5AE1297544FBC5A2; bankCard:6217***********5024|444F49289B30944AB8C6C856AEA21180, email:mahu*****@qq.com|897915594C94D981BA86C9E83ADD449C, amount:123.00, " + "IdNo:340110199801016666, name1:李明, name2:李晓明, name3:李泽明天, name4:山东小栗旬" + ", birthday:20220517, GPS:120.882222, IPV4:127.0.0.1, address:中国上海市徐******|821A601949B1BD18DCBAAE27F2E27147;
```
## 配置属性
同 log4j2，此处不再赘述。
# 性能耗时
## 注解
100W 次耗时统计
| 方法 | 耗时(ms) | 说明 |
|:--------|:--------|:---------------------------|
| 原始工具类方法 | 122 | 性能最好，但是最麻烦。拓展性最差 |
| JSON.toJSONString(user) | 304 | 性能较好，拓展性不错。缺点是强依赖 fastjson |
| SensitiveUtil.desJson(user) | 1541 | 性能较差，拓展性最好，比较灵活 |
# ROAD-MAP
- [x] 添加统一的工具类方法，便于开发单独使用
喜欢重载 toString()，或特殊的场景
- [x] 考虑添加针对 MAP 的脱敏支持
- [x] 针对身份证的默认脱敏策略
- [x] log4j2 等日志组件的脱敏策略
提升可拓展性
- [x] log4j2 layout 对应的脱敏策略
- [x] 优化代码实现，直接继承自 patternLayout
- [x] log4j2 脱敏配置添加指定配置文件，而不是放在 pattern 中
- [ ] 日志插件脱敏的 benchmark 性能报告