Device and network address masking policy (standard)

Edit online

The Device and Network Address category provides standard masking policy formats for IP addresses, IPv4 addresses, IPv6 addresses, and MAC addresses. Use these formats to mask network-identifying data while preserving structural validity.

Parameters

The Device and Network Address (DeviceAndNetworkAddress) masking policy accepts the following parameters.

Table 1. Device and network address masking policy parameters
Parameter	Required	Type	Description
`name`	Yes	String	The format name. Must be one of: `IP`, `Ipv4`, `Ipv6`, `MacAddress`.
`type`	Yes	String	The processor type. Accepted values depend on the format. See each format section for supported processors.
`config`	No	Object	For `IP` and `MacAddress` used with `FormatPreservingTokenizationProcessor`, set `"mode": "tokenize"` or `"mode": "detokenize"`. Pass `{}` or omit for all other processors and formats.

IP format

Masks an IP address by automatically detecting whether the input is an IPv4 or full-form IPv6 address and applying the corresponding masking rules. The IP format is a tiled union of the Ipv4 and Ipv6 sub-formats - each row is masked independently in its own sub-format space. All four processors are supported. The output type always matches the input type: an IPv4 input produces an IPv4 output, and an IPv6 input produces an IPv6 output.

Sub-format	Matches	Masking behavior
`Ipv4`	Four decimal octets; first octet `1–255`, others `0–255`	All octets fabricated; dots preserved; redaction produces `1.0.0.0`
`Ipv6`	Eight 4-hex-digit blocks separated by colons (full form only; no `::` shorthand)	All 32 hex positions fabricated; colons preserved; output is uppercase

Restriction: The first octet of an IPv4 address must be in the range 1–255. Addresses such as 0.0.0.0 are not valid IPv4 inputs for this format. Compressed IPv6 notation (for example, ::1 or 2001:db8::1) is not accepted - expand to full 8-block form before masking.

Valid input values

Example input	Why it is valid
`192.168.1.1`	Standard private IPv4 address; first octet non-zero
`255.255.255.255`	Maximum value - all octets 255
`10.0.0.1`	Private range address
`2001:0000:3238:DFE1:0063:0000:0000:FEFB`	Full-form IPv6 address - 8 blocks of 4 hex digits
`2001:0000:3238:DfE1:0063:0000:0000:fefb`	Mixed-case IPv6 - accepted; output is uppercase

Invalid input values

Example input	Reason	`FormatPreservingRedactionProcessor`	`FormatPreservingTokenizationProcessor`	`RandomFormatFabricationProcessor` / `RepeatableFormatFabricationProcessor`
`0.0.0.0`	First IPv4 octet is 0 - not valid	`IllegalArgumentException`	`MagenPayloadException`	Returns valid fabricated IP
`256.0.0.1`	Octet exceeds 255	`IllegalArgumentException`	`MagenPayloadException`	Returns valid fabricated IP
`::1`	Compressed IPv6 notation - not supported	`IllegalArgumentException`	`MagenPayloadException`	Returns valid fabricated IP
`2001:db8::1`	Compressed IPv6 - leading zeros omitted	`IllegalArgumentException`	`MagenPayloadException`	Returns valid fabricated IP
NULL	Null value	Passthrough. NULL returned unchanged	Passthrough. NULL returned unchanged	Passthrough. NULL returned unchanged

Processors

FormatPreservingRedactionProcessor

Detects the sub-format of the input and replaces all mutable positions with the zero-rank value: IPv4 inputs produce 1.0.0.0; IPv6 inputs produce 0000:0000:0000:0000:0000:0000:0000:0000. All valid inputs of the same sub-format produce the same output.

Use when: Deterministic suppression of IP address information is required and no differentiation between source values is needed.

Input	Output
`192.168.1.1`	`1.0.0.0`
`2001:0000:3238:DFE1:0063:0000:0000:FEFB`	`0000:0000:0000:0000:0000:0000:0000:0000`

FormatPreservingTokenizationProcessor

Produces a deterministic token for each valid IP address within its matched sub-format. The same input always produces the same output for the same initialization vector (IV). Requires config: {"mode": "tokenize"}. Reversible using "mode": "detokenize".

Use when: The same source IP address must consistently map to the same masked value - for example, a column used in a join or group-by.

Input	Output	Notes
`192.168.1.1`	`47.213.84.92`	Deterministic for given IV
`10.0.0.1`	`183.47.201.15`	Different input - different token

RandomFormatFabricationProcessor

Detects the sub-format and generates a fresh random valid address in that sub-format space on every invocation. Same input produces a different output each time.

Use when: Masking a non-key IP column where run-to-run consistency is not required.

Input	Output (run 1)	Output (run 2)
`192.168.1.1`	`47.213.84.92`	`201.88.14.37`

RepeatableFormatFabricationProcessor

Detects the sub-format and generates a deterministic valid address derived from the input value and the job IV. Same input always produces the same output for the same IV.

Use when: Masking a primary-key or foreign-key IP column where consistent output is required across tables and job runs.

Input	Output (run 1)	Output (run 2)
`192.168.1.1`	`47.213.84.92`	`47.213.84.92` (same)

Configuration examples

FormatPreservingTokenizationProcessor

{
  "column_name_source": "client_ip",
  "column_name_target": "client_ip",
  "masking_properties": {
    "magen_function": {
      "name": "IP",
      "type": "FormatPreservingTokenizationProcessor",
      "config": { "mode": "tokenize" }
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "client_ip",
  "column_name_target": "client_ip",
  "masking_properties": {
    "magen_function": {
      "name": "IP",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

NULL handling: NULL values are passed through unchanged.
Tokenization requires config.mode: FormatPreservingTokenizationProcessor requires config: {"mode": "tokenize"}. Omitting mode causes an error.
IPv4 first octet cannot be 0: The address 0.0.0.0 is not a valid IPv4 input. The minimum valid first octet value is 1.
Compressed IPv6 notation is not supported: Addresses using :: shorthand (for example, ::1 or 2001:db8::1) are not valid inputs. Expand to the full 8-block, 4-digits-per-block form before masking.
IPv6 output is always uppercase: The IPv6 sub-format normalizes all hex digits to uppercase in its output, regardless of the case of the input.

Ipv4 format

Masks an IPv4 address identically to the IPv4 sub-format of IP. The Ipv4 format is an explicit single-protocol format for IPv4 masking only and supports all four processors with the same behavior as the IPv4 branch of IP. Valid inputs, invalid inputs, processor behaviors, and configuration examples are identical to the IPv4 behavior described for the IP format above. Substitute "name": "Ipv4" in the configuration. Use Ipv4 when the column is guaranteed to contain only IPv4 addresses.

Ipv6 format

Masks an IPv6 address by fabricating all groups while preserving the colon-separated structure. Outputs are always valid full-form IPv6 addresses in the form xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx. Only RandomFormatFabricationProcessor and RepeatableFormatFabricationProcessor are supported. FormatPreservingRedactionProcessor and FormatPreservingTokenizationProcessor are not available for this format.

The format is structured as eight 4-hex-digit groups separated by immutable colon separators.

Valid input values

Example input	Why it is valid
`2001:0db8:85a3:0000:0000:8a2e:0370:7334`	Standard full-form IPv6 address
`fe80:0000:0000:0000:0202:b3ff:fe1e:8329`	Link-local address, full form
`0000:0000:0000:0000:0000:0000:0000:0001`	Loopback address in full form

Invalid input values

Example input	Reason	`RandomFormatFabricationProcessor` / `RepeatableFormatFabricationProcessor`
`::1`	Compressed notation - not full form	Returns valid fabricated IPv6
`2001:db8::1`	Compressed notation with `::`	Returns valid fabricated IPv6
NULL	Null value	Passthrough - NULL returned unchanged

Processors

RandomFormatFabricationProcessor

Generates a fresh random full-form IPv6 address on every invocation.

Use when: Masking a non-key IPv6 column where run-to-run consistency is not required.

Input	Output (run 1)	Output (run 2)
`2001:0db8:85a3:0000:0000:8a2e:0370:7334`	`a3f1:2b4c:...`	`7d92:1e3a:...`

RepeatableFormatFabricationProcessor

Generates a deterministic full-form IPv6 address derived from the input and the job IV. Same input always produces the same output for the same IV.

Use when: Masking a primary-key or foreign-key IPv6 column where consistent output is required.

Input	Output (run 1)	Output (run 2)
`2001:0db8:85a3:0000:0000:8a2e:0370:7334`	`a3f1:2b4c:...`	`a3f1:2b4c:...` (same)

Configuration examples

RandomFormatFabricationProcessor

{
  "column_name_source": "ipv6_address",
  "column_name_target": "ipv6_address",
  "masking_properties": {
    "magen_function": {
      "name": "Ipv6",
      "type": "RandomFormatFabricationProcessor",
      "config": {}
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "ipv6_address",
  "column_name_target": "ipv6_address",
  "masking_properties": {
    "magen_function": {
      "name": "Ipv6",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

Full form only: Only full-form IPv6 addresses (xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx) are valid inputs. Compressed notation such as ::1 or 2001:db8::1 does not match; fabrication processors silently return a valid full-form IPv6 address.
No redaction or tokenization support: FormatPreservingRedactionProcessor and FormatPreservingTokenizationProcessor are not supported for Ipv6.
NULL handling: NULL values are passed through unchanged.

MacAddress format

Masks a MAC address by replacing each hex octet with a fabricated, tokenized, or redacted equivalent while preserving the colon-separated structure. Outputs are always valid colon-separated MAC addresses in the form xx:xx:xx:xx:xx:xx. All four processors are supported.

Important: The MacAddress format accepts colon-separated MAC addresses only. Dash-separated (00-14-22-01-23-45) and dot-separated formats are not supported. Input is case-insensitive, but output is always uppercase.

Valid input values

Example input	Why it is valid
`00:25:96:12:34:56`	Standard 6-group hex MAC address; colon-separated
`FF:FF:FF:FF:FF:FF`	Broadcast address - all octets maximum, uppercase
`00:00:00:00:00:00`	All-zero MAC address
`08:00:69:aa:4a:55`	Lowercase hex octets - accepted; output is uppercase

Invalid input values

Example input	Reason	`FormatPreservingRedactionProcessor`	`FormatPreservingTokenizationProcessor`	`RandomFormatFabricationProcessor` / `RepeatableFormatFabricationProcessor`
`00-1A-2B-3C-4D-5E`	Dash separator - only colons accepted	`IllegalArgumentException`	`MagenPayloadException`	Returns valid fabricated MAC
`001A2B3C4D5E`	No separators - compact form	`IllegalArgumentException`	`MagenPayloadException`	Returns valid fabricated MAC
`GG:1A:2B:3C:4D:5E`	Invalid hex character `G`	`IllegalArgumentException`	`MagenPayloadException`	Returns valid fabricated MAC
NULL	Null value	Passthrough. NULL returned unchanged	Passthrough. NULL returned unchanged	Passthrough. NULL returned unchanged

Processors

FormatPreservingRedactionProcessor

Replaces every valid MAC address with the zero-rank canonical value (00:00:00:00:00:00). All valid inputs produce the same output. Output is uppercase.

Use when: Deterministic suppression of MAC address information is required.

FormatPreservingTokenizationProcessor

Produces a deterministic token for each valid MAC address. The same input always produces the same output for the same IV. Requires config: {"mode": "tokenize"}.

Use when: The same source MAC address must consistently map to the same masked value.

RandomFormatFabricationProcessor

Generates a fresh random valid uppercase colon-separated MAC address on every invocation.

Use when: Masking a non-key MAC column where run-to-run consistency is not required.

Input	Output (run 1)	Output (run 2)
`00:25:96:12:34:56`	`A3:F2:01:BC:7E:4D`	`5C:22:10:FF:88:91`

RepeatableFormatFabricationProcessor

Generates a deterministic valid uppercase colon-separated MAC address derived from the input and the job IV.

Use when: Masking a primary-key or foreign-key MAC column where consistent output is required across tables and job runs.

Input	Output (run 1)	Output (run 2)
`00:25:96:12:34:56`	`A3:F2:01:BC:7E:4D`	`A3:F2:01:BC:7E:4D` (same)

Configuration examples

FormatPreservingTokenizationProcessor

{
  "column_name_source": "device_mac",
  "column_name_target": "device_mac",
  "masking_properties": {
    "magen_function": {
      "name": "MacAddress",
      "type": "FormatPreservingTokenizationProcessor",
      "config": { "mode": "tokenize" }
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "device_mac",
  "column_name_target": "device_mac",
  "masking_properties": {
    "magen_function": {
      "name": "MacAddress",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

Colon separator only: Only colon-separated MAC addresses (xx:xx:xx:xx:xx:xx) are valid inputs. Dash-separated (xx-xx-xx-xx-xx-xx) and compact formats (xxxxxxxxxxxx) do not match; non-fabrication processors throw an error; fabrication processors silently return a valid colon-separated MAC address.
Output is always uppercase: All MAC address outputs are returned in uppercase regardless of input casing. For example, input 08:00:69:aa:4a:55 produces an uppercase masked output.
OUI prefix is not preserved: All 6 octets are fabricated independently. The first 3 octets (the manufacturer prefix) carry no information about the original manufacturer in the masked output.
NULL handling: NULL values are passed through unchanged.