Secure Your Java Logs: A Step‑by‑Step Guide to Logback Desensitization

When writing code we often add many log statements, but some log data contain sensitive information that must be masked for security.

Common log‑masking methods include (1) using a conversionRule tag that inherits from MessageConverter, and (2) writing a utility class that masks specific fields at log time. The first method violates the Open/Closed principle because it requires code changes, while the second method intrusively modifies log parameters.

Custom Desensitization Component (slf4j + logback)

A project with extensive logging can adopt this component to achieve masking by simple configuration, avoiding massive code changes.

1. Desensitization Effect Demo

2. Usage

1) Add the JAR dependency

The JAR must be installed in the local Maven repository; the dependency coordinates are shown below.

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

2) Replace the appender classes in logback.xml

Swap the original Logback appender classes with the provided desensitization classes. 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

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

Place the file under resources. Example snippet:

# Log desensitization
log-desensitize:
  ignore: true   # case‑insensitive matching
  open: true     # enable masking
  pattern:
    email: "@>(4,7)"   # mask 4‑7 characters before '@'
    qqemail: "@<(1,3)" # mask 1‑3 characters after '@'
    name: 1,1            # mask first character of a name
    password: password   # full masking
  patterns:
    - key: identity,idcard
      custom:
        - defaultRegex: identity
          position: 9,13
        - defaultRegex: other
          position: 9,10
    - 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
    - key: localMobile
      custom:
        customRegex: "^0[0-9]{2,3}-[0-9]{7,8}"
        position: 1,3

The configuration must follow the hierarchical format strictly.

Supported Data Types

Eight primitive types and their wrappers, Map, List, POJOs, List<POJO>, JSON strings.

Note: In the configuration file you only need to specify the property values of the objects.

Unsupported Types

List<primitive/wrapper> (cannot determine the source field).

Matching Rules

Key + delimiter + value; only colon (:) and equal sign (=) are supported as delimiters. Example:

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

key

: defines the keyword to be masked (e.g., email, phone, POJO field, Map key, JSON key). value: the actual value to mask (e.g., [email protected], 15310763497).

Log Writing Guidelines

Avoid using Chinese keys because they cannot be masked; follow the pattern shown in the demo.

3. Desensitization Specification

1) key:value style

phone: 4,7 – mask characters 4‑7 of the phone field.

Original: 13610357861 Masked:

136****7861

2) Symbol‑based start/end markers

Use @>(4,7) to mask four to seven characters before ‘@’, and @<(1,3) to mask after ‘@’. The symbols ‘>’ and ‘<’ indicate end and start of the masking region respectively.

Note: Double quotes and parentheses cannot be omitted, and the characters ‘:’ and ‘=’ must not be used as markers because they conflict with rule syntax.

Original: [email protected] Mask @>(4,7) → 123****[email protected] Mask @<(1,3) →

123456789@***com

3) Custom regex masking

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

customRegex

defines a regular expression; if a value matches, the specified position is masked.

4) Multi‑value field masking

When a field (e.g., username) may contain different types such as phone or email, define multiple rules under the same key.

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

Remember that double quotes and parentheses are mandatory in the rule definitions.

The component provides four built‑in matching rules (phone, identity, email, other) and a built‑in masking method password for full masking.

5) Installing the JAR into the local Maven repository

Download the JAR, then run:

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

Parameters:

-DgroupId      → pers.liuchengyin
-DartifactId   → logback-desensitization
-Dversion      → 1.0.0