Mask

Security Cribl Compatible

Synopsis

Provides data masking capabilities using various hashing functions.

Schema

- mask:
    field: <ident>
    masking_rules: <rule[]>
    target_fields: <string[]>
    depth: <numeric>
    hash_type: <enum>
    hash_key: <string>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	N	-	Accepted but not applied. The value is never read — use target_fields to choose what is masked
masking_rules	Y	-	List of masking rules to apply
target_fields	N	["message"]	Fields to apply masking to
depth	N	5	Maximum depth to traverse nested fields
hash_key	N	-	Key for hmac-sha256/hmac-sha512 masking rules. Required when any rule uses one of them; ignored for every other hash_type
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue if masking fails
ignore_missing	N	false	Continue if source field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

Masking Rules

Field	Required	Default	Description
match_regex	Y	-	Pattern to match sensitive data
hash_type	N	sha256	Hash algorithm for this rule: md5, sha1, sha256, sha512, sha3-256, sha3-512, hmac-sha256, hmac-sha512. The hmac-* types require the processor's hash_key
enabled	N	true	Whether this rule is active
keep_first	N	0	Number of characters to preserve from start
keep_last	N	0	Number of characters to preserve from end

Details

This processor is particularly useful for protecting sensitive data like Personally Identifiable Information (PII) by applying hash functions while optionally preserving portions of the original value.

The processor uses regular expressions to identify sensitive data. It supports multiple hash algorithms (MD5, SHA1, SHA256, SHA512, SHA3-256, SHA3-512, HMAC-SHA256, HMAC-SHA512) for different security requirements.

warning

MD5 is cryptographically broken and should not be used for security purposes. It is only included for Cribl compatibility.

VirtualMetric highly recommends using at least SHA-256 for any sensitive data, which the system defaults to if no hash type is specified.

note

hmac-sha256 and hmac-sha512 are keyed hash types: set the processor's hash_key, and every masking rule using one of these two types hashes with it. Configuring hmac-sha256/hmac-sha512 on a rule without a processor-level hash_key fails the pipeline at load time, rather than silently masking with a downgraded, unkeyed hash. hash_key is ignored (and may be omitted) for every other hash_type.

The result is still deterministic — the same input hashed with the same hash_key always masks to the same digest, so correlation across events survives masking — but it is a confidentiality control only as long as hash_key stays secret: anyone who obtains the key can rebuild the digest for a guessed value.

Multiple fields can be selected. The masking rules are configurable.

Empty field content is treated as non-matching. If no rules match, the field remains unchanged. Non-string field values, missing fields, and invalid regex patterns will cause errors which must be handled.

warning

Complex regular expressions may impact performance.

Conditional execution is also available.

Examples

Basic

Masking social security numbers...	{ "message": "social=123456789" } - mask: target_fields: ["message"] masking_rules: - match_regex: "(social=)(\\d+)" hash_type: "md5" keep_first: 7
preserves "social=" and hashes the numbers:	{ "message": "social=a1b2c3d4e5f6g7h8i9" }

Credit Cards

Masking the credit card partially...	{ "message": "cardNumber=4111-1111-1111-1111" } - mask: target_fields: ["message"] masking_rules: - match_regex: "\\b(\\d{4})[- ]?(\\d{4})[- ]?(\\d{4})[- ]?(\\d{4})\\b" hash_type: "sha256" keep_first: 4 keep_last: 4
keeps the first and last 4 digits:	{ "message": "cardNumber=4111********1111" }

Multiple Fields

Applying masking to multiple fields...	{ "field1": "secret123", "field2": "secret456" } - mask: target_fields: ["field1", "field2"] masking_rules: - match_regex: "secret\\d+" hash_type: "md5"
masks all of them:	{ "field1": "d4e5f6g7h8i9", "field2": "j0k1l2m3n4o5" }

Conditionals

Masking only when a condition is met...	{ "message": "secret123", "level": "info" } - mask: if: "ctx.level == 'secure'" target_fields: ["message"] masking_rules: - match_regex: "secret\\d+" hash_type: "md5"
skips unmatching parts:	{ "message": "secret123", "level": "info" }

Missing Fields

Handling missing fields gracefully...	{} - mask: target_fields: ["nonexistent"] masking_rules: - match_regex: "secret\\d+" hash_type: "md5" ignore_missing: true
continues the execution:	{}

Hash Types

Using SHA256 specifically...	{ "message": "secret123" } - mask: target_fields: ["message"] masking_rules: - match_regex: "secret\\d+" hash_type: "sha256"
applies the algorithm:	{ "message": "e7cf3ef4f17c3999a94f2c6f612e8a888e5b1026878e4e19398b23bd38ec221a" }

HMAC Keyed Hash

Masking with a keyed hash, so the digest correlates across events without being reproducible by anyone who lacks the key...	{ "message": "secret123" } - mask: target_fields: ["message"] hash_key: "correlation-secret-2024" masking_rules: - match_regex: "secret\\d+" hash_type: "hmac-sha256"
hashes with the key instead of a bare SHA-256:	{ "message": "fe0fb67cf051f757183860cfee2df533340e6800d4932ff5df66065087f97451" }

Missing Hash Key

An hmac-* rule with no processor-level hash_key...	- mask: target_fields: ["message"] masking_rules: - match_regex: "secret\\d+" hash_type: "hmac-sha256"
fails the pipeline at load time, before any record is processed:	mask processor: hash_key required for hmac hash types: hmac-sha256