Custom Logback Desensitization Component: Configuration and Usage Guide

When writing code we often generate many log statements, but some sensitive data must be masked for security.

Common log‑masking methods include: (1) using the conversionRule tag and inheriting MessageConverter ; (2) writing a utility class that masks specific fields during logging.

Each method has advantages and disadvantages:

The first method requires code changes and violates the open‑closed principle.

The second method modifies log method parameters, which is invasive to the original logging.

Custom Desensitization Component (slf4j + logback)

A project with many log statements can enable masking by introducing this component, requiring only three configuration steps.

1. Desensitization Effect Demonstration

2. Usage Steps

1) Add the JAR dependency

First, install the JAR into your local Maven repository. The dependency declaration is:

<dependency>
    <groupId>pers.liuchengyin</groupId>
    <artifactId>logback-desensitization</artifactId>
    <version>1.0.0</version>
</dependency>

2) Replace the logback appender classes in logback.xml

Replace the original appender classes with the desensitization versions. Example replacements:

ConsoleAppender – console masking

// Original class
ch.qos.logback.core.ConsoleAppender
// Replacement class
pers.liuchengyin.logbackadvice.LcyConsoleAppender

RollingFileAppender – rolling file masking

// Original class
ch.qos.logback.core.rolling.RollingFileAppender
// Replacement class
pers.liuchengyin.logbackadvice.LcyRollingFileAppender

FileAppender – file masking

// Original class
ch.qos.logback.core.FileAppender
// Replacement class
pers.liuchengyin.logbackadvice.LcyFileAppender

Example configuration snippet:

<property name="CONSOLE_LOG_PATTERN" value="%yellow(%date{yyyy-MM-dd HH:mm:ss}) |%highlight(%-5level) |%blue(%thread) |%blue(%file:%line) |%green(%logger) |%cyan(%msg%n)"/>

<!-- ConsoleAppender for console output -->
<appender name="CONSOLE" class="pers.liuchengyin.logbackadvice.LcyConsoleAppender">
    <encoder>
        <pattern>${CONSOLE_LOG_PATTERN}</pattern>
    </encoder>
</appender>

3) Add the desensitization configuration file ( logback-desensitize.yml ) under resources

The file defines which keys should be masked and how. Example content:

# Log desensitization
log-desensitize:
  # Whether to ignore case when matching keys (default true)
  ignore: true
  # Whether to enable desensitization (default false)
  open: true
  # Fixed patterns under "pattern"
  pattern:
    # Email – mask characters 4‑7 before '@'
    email: "@>(4,7)"
    # QQ email – mask characters 1‑3 after '@'
    qqemail: "@<(1,3)"
    # Name – mask the first character
    name: 1,1
    # Password – fully mask
    password: password
  patterns:
    # Identity card – mask positions 9‑13
    - key: identity,idcard
      custom:
        - defaultRegex: identity
          position: 9,13
        - defaultRegex: other
          position: 9,10
    # Phone numbers – mask positions 4‑7
    - key: phone,cellphone,mobile
      custom:
        - defaultRegex: phone
          position: 4,7
        - customRegex: "^0[0-9]{2,3}-[0-9]{7,8}"
          position: "-<(1,4)"
        - customRegex: "^[0-9]{7,8}"
          position: 3,5
        - defaultRegex: other
          position: 1,3
    # Fallback example
    - key: localMobile
      custom:
        customRegex: "^0[0-9]{2,3}-[0-9]{7,8}"
        position: 1,3

The configuration must follow the exact YAML hierarchy.

Supported Data Types

The component supports the eight primitive types and their wrappers, Map , List , POJOs, List<POJO> , and JSON strings. It does not support List<primitive> because the source of the data cannot be determined.

Matching Rules

Rules are defined as key + separator + value . Only colon (:) and equal sign (=) are supported as separators. Example log statements:

log.info("your email:{}, your phone:{}", "[email protected]", "15310763497");
log.info("your email={}, your cellphone={}", "[email protected]", "15310763497");

Key definitions (e.g., key ) specify which fields to mask; value definitions (e.g., value ) provide the actual data to be masked.

Custom Regex Masking

Custom regular expressions can be used to define additional masking rules. Example for phone numbers:

patterns:
  - key: phone,mobile
    custom:
      - customRegex: "^1[0-9]{10}"
        position: 4,7

Multiple Rules for a Single Field

A field can have several possible formats (e.g., a username that may be a phone number or an email). The component evaluates the rules in order and applies the first matching one.

patterns:
  - key: username
    custom:
      - defaultRegex: phone
        position: 4,7
      - defaultRegex: email
        position: "@>(3,12)"
      - defaultRegex: identity
        position: 1,3
      - customRegex: "^1[0-9]{10}"
        position: 1,3
      - defaultRegex: other
        position: 1,3

Jar Installation into Local Maven Repository

Download the JAR, place it in a folder, open a command prompt in that folder, and run:

mvn install:install-file -DgroupId=pers.liuchengyin -DartifactId=logback-desensitization -Dversion=1.0.0 -Dpackaging=jar -Dfile=logback-desensitization-1.0.0.jar

Explanation of the parameters:

-DgroupId      → groupId of the JAR (pers.liuchengyin)
-DartifactId   → artifactId of the JAR (logback-desensitization)
-Dversion      → version of the JAR (1.0.0)

For more details, see the GitHub repository:

https://github.com/liuchengyin01/LogbackDesensitization

End of guide.