net.logstash.logback.mask

Class PathBasedFieldMasker

java.lang.Object

net.logstash.logback.mask.PathBasedFieldMasker

All Implemented Interfaces:

FieldMasker

public class PathBasedFieldMasker
extends Object
implements FieldMasker

Masks values of an absolute or partial path within a JSON stream.

Values for paths that match a given path string will be replaced with a given mask string.

Path String Format

The path string to match follows a format similar to (but not exactly the same as) a JSON Pointer string, with the differences being:

• At least one reference token is required (e.g. "" and "/" are not allowed)
• The path string does not need to start with "/". If a path string starts with "/" it is interpreted as an absolute path. Otherwise, it is a partial path.
• A wildcard token ("*") is supported.
• The path string must end with a field name (not an array index)

Absolute Paths

Absolute paths start with "/", followed by one or more reference tokens separated by "/". Absolute paths must match the full path from the root of the streaming context.

For example, given the following JSON:

 {
     "aaa": {
         "bbb": [
             {
                 "ccc": "ddd"
             }
         ]
     },
     "bbb": [
         {
             "eee": "fff"
         }
     ]
 }
 

Then the following matches occur:

• /aaa matches { "bbb" : [ { "ccc" : "ddd" } ] }
• /aaa/bbb matches [ { "ccc" : "ddd" } ]
• /aaa/bbb/0/ccc matches "ddd"

Partial Paths

Partial paths do NOT start with "/", and contain one or more reference tokens separated by "/". Partial paths mask a partial path anywhere in the stream.

For example, given the following JSON:

 {
     "aaa": {
         "bbb": [
             {
                 "ccc": "ddd"
             }
         ]
     },
     "bbb": [
         {
             "eee": "fff"
         }
     ]
 }
 

Then the following matches occur:

• aaa matches { "bbb" : [ { "ccc" : "ddd" } ] }
• aaa/bbb matches [ { "ccc" : "ddd" } ]
• aaa/bbb/0/ccc matches "ddd"
• bbb matches [ { "ccc" : "ddd" } ] and [ { "eee" : "fff" } ]
• bbb/0/ccc matches "ddd"
• 0/ccc matches "ddd"
• ccc matches "ddd"

For single field values (e.g. partial paths with only one token), consider using a FieldNameBasedFieldMasker instead. A single FieldNameBasedFieldMasker configured with many field names, is much more efficient than having a PathBasedFieldMasker per field name.

Wildcard Tokens

The wildcard value ("*") can be used as a token in the path string. The wildcard token will match any token.

For example, given the following JSON:

 {
     "aaa": {
         "bbb": {
             "ccc": "ddd"
         },
         "eee": {
             "ccc": "hhh",
         },
     },
     "iii": {
         "jjj": {
             "ccc": "lll"
         },
     },
     "ccc": "mmm"
 }
 

Then the following matches occur:

• aaa/*/ccc matches "ddd" and "hhh"
• */ccc matches "ddd" and "hhh" and "lll"

Escaping

JSON Pointer escaping can be used to escape '/' and '~' within tokens. Specifically, use:

• '~1' to represent '/' within a token
• '~0' to represent '~' within a token

Field Summary

Fields

Modifier and Type	Field and Description
static String	TOKEN_SEPARATOR
static String	WILDCARD_TOKEN

Constructor Summary

Constructors

Constructor and Description
PathBasedFieldMasker(String pathToMask, Object mask)

Method Summary

Modifier and Type	Method and Description
Object	mask(JsonStreamContext context) If the field at the JSON stream context's current path should be masked, then returns the masked value to write as the field's value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TOKEN_SEPARATOR

public static final String TOKEN_SEPARATOR

See Also:

Constant Field Values

WILDCARD_TOKEN

public static final String WILDCARD_TOKEN

See Also:

Constant Field Values

Constructor Detail

PathBasedFieldMasker

public PathBasedFieldMasker(String pathToMask,
                            Object mask)

Parameters:

pathToMask - the absolute or partial path to mask (see class javadoc)

mask - the value to write for any paths that match the pathToMask

Method Detail

mask

public Object mask(JsonStreamContext context)

Description copied from interface: FieldMasker

If the field at the JSON stream context's current path should be masked, then returns the masked value to write as the field's value. The MaskingJsonGenerator will write the returned masked value as the field's value (instead of the original field's value).

If the JSON stream context's current path should NOT be masked, returns null.

Specified by:

mask in interface FieldMasker

Parameters:

context - the current JSON stream context, which can be used to determine the path within the JSON output.

Returns:

A non-null masked value to write if the current field should be masked. Otherwise null if the current field should not be masked. To write a JSON null value as the masked value, return NullNode.instance. To write , the return MaskingJsonGenerator.MASK