Helper function reference

This reference lists the helper functions that you use in decoders and filters of the Wazuh normalization engine. For the helper call syntax and an explanation of the arguments, including their types and sources, see Helper functions.

The following tables list all 128 helper functions across three categories: 53 filter, 28 map, and 47 transformation helpers. Each table lists its helpers in alphabetical order. Each row shows the helper signature, the type and source of each argument, the expected target field type, and the helper's behavior. An example follows each table.

Filter helpers

Filter helpers evaluate conditions on the target field without modifying the event. You use them in check stages to determine whether a decoder, filter, or normalize block applies to an event. A linked name opens the helper's entry in Helper function details.

Signature

Arguments

Target field

Description

array_contains(element, [...])

element (any type; value or reference)

array (no build check)

Passes when the target array contains every listed element.

array_contains_any(element, [...])

element (any type; value or reference)

array (no build check)

Passes when the target array contains at least one listed element.

array_length_eq(expected_length)

expected_length (number; value)

array (no build check)

Passes when the target array has exactly expected_length elements.

array_not_contains(element, [...])

element (any type; value or reference)

array (no build check)

Passes when at least one listed element is missing from the target array.

array_not_contains_any(element, [...])

element (any type; value or reference)

array (no build check)

Passes when none of the listed elements is in the target array.

binary_and(hexadecimal)

hexadecimal (string; value)

string

Converts both hexadecimal values to unsigned integers and passes when their bitwise AND isn't zero. Both values need the 0x prefix, and the mask can't be zero.

contains(searched_value)

searched_value (string; value or reference)

string

Passes when the target string contains searched_value.

ends_with(substring)

substring (string; value or reference)

string

Passes when the target string ends with substring.

exists()

None

any

Passes when the target field exists in the event.

exists_key_in(object)

object (object; value or reference)

string

Passes when the target string is a key of the given object.

index_unclassified_events()

None

string (no build check)

Passes when the policy indexes unclassified events and the target value is unclassified. The target must be wazuh.integration.category.

int_equal(any_number)

any_number (number; value or reference)

number

Passes when the target integer equals the given integer.

int_greater(any_number)

any_number (number; value or reference)

number

Passes when the target integer is greater than the given integer.

int_greater_or_equal(any_number)

any_number (number; value or reference)

number

Passes when the target integer is greater than or equal to the given integer.

int_less(any_number)

any_number (number; value or reference)

number

Passes when the target integer is less than the given integer.

int_less_or_equal(any_number)

any_number (number; value or reference)

number

Passes when the target integer is less than or equal to the given integer.

int_not_equal(any_number)

any_number (number; value or reference)

number

Passes when the target integer differs from the given integer.

ip_cidr_match(subnet, mask)

subnet (string; value); mask (string; value)

IP address

Passes when the target IPv4 address is in the range that subnet and mask define. The mask is a dotted-decimal mask or a prefix length from 0 to 32. IPv6 addresses fail the check.

is_array()

None

any

Passes when the target value is an array.

is_boolean()

None

any

Passes when the target value is a boolean.

is_ipv4()

None

IP address

Passes when the target value is an IPv4 address.

is_ipv6()

None

IP address

Passes when the target value is an IPv6 address.

is_not_array()

None

any

Passes when the target value isn't an array.

is_not_boolean()

None

any

Passes when the target value isn't a boolean.

is_not_null()

None

any

Passes when the target value isn't null.

is_not_number()

None

any

Passes when the target value isn't a number.

is_not_object()

None

any

Passes when the target value isn't an object.

is_not_string()

None

any

Passes when the target value isn't a string.

is_null()

None

any

Passes when the target value is null.

is_number()

None

any

Passes when the target value is a number.

is_object()

None

any

Passes when the target value is an object.

is_public_ip()

None

IP address

Passes when the target IP address isn't in a private or loopback range. IPv6 link-local and unique local addresses also fail. IPv4 link-local addresses, such as 169.254.1.1, pass.

is_string()

None

any

Passes when the target value is a string.

keys_exist_in_list(elements)

elements (array; value or reference)

object

Passes when every key of the target object appears in elements.

kvdb_match(db_name)

db_name (string; value)

string (no build check)

Passes when the target string is a key in the key-value database (KVDB) db_name.

kvdb_not_match(db_name)

db_name (string; value)

string (no build check)

Passes when the target string isn't a key in the KVDB db_name.

match_value(array)

array (array; value or reference)

any

Passes when the target value is an element of the given array.

not_exists()

None

any

Passes when the target field doesn't exist in the event.

number_equal(any_number)

any_number (number; value or reference)

number

Passes when the target number equals the given number.

number_greater(any_number)

any_number (number; value or reference)

number

Passes when the target number is greater than the given number.

number_greater_or_equal(any_number)

any_number (number; value or reference)

number

Passes when the target number is greater than or equal to the given number.

number_less(any_number)

any_number (number; value or reference)

number

Passes when the target number is less than the given number.

number_less_or_equal(any_number)

any_number (number; value or reference)

number

Passes when the target number is less than or equal to the given number.

number_not_equal(any_number)

any_number (number; value or reference)

number

Passes when the target number differs from the given number.

regex_match(regxp)

regxp (string; value)

string

Passes when the target string matches the RE2 regular expression.

regex_not_match(regxp)

regxp (string; value)

string

Passes when the target string doesn't match the RE2 regular expression.

starts_with(substring)

substring (string; value or reference)

string

Passes when the target string starts with substring.

string_equal(any_string)

any_string (string; value or reference)

string

Passes when the target string equals the given string, byte for byte.

string_greater(any_string)

any_string (string; value or reference)

string

Passes when the target string is lexicographically greater than the given string.

string_greater_or_equal(any_string)

any_string (string; value or reference)

string

Passes when the target string is lexicographically greater than or equal to the given string.

string_less(any_string)

any_string (string; value or reference)

string

Passes when the target string is lexicographically less than the given string.

string_less_or_equal(any_string)

any_string (string; value or reference)

string

Passes when the target string is lexicographically less than or equal to the given string.

string_not_equal(any_string)

any_string (string; value or reference)

string

Passes when the target string differs from the given string.

The is_* and is_not_* helpers fail when the target field doesn't exist. For example, is_not_null fails for a missing field.

Filter helper example

The ip_cidr_match helper checks whether an IP address belongs to a network range. In this decoder check, the decoder accepts only events whose _target_field is in 192.168.0.0/16.

check:
  - _target_field: ip_cidr_match('192.168.0.0', '255.255.0.0')

The check passes for the following input event:

{
  "_target_field": "192.168.1.5"
}

The decoder rejects the following input event because the check fails:

{
  "_target_field": "111.111.1.11"
}

Map helpers

Map helpers compute a value from their arguments and write it to the target field. If the target field exists, the helper replaces its value. You use them in the map stage of a normalize block. A linked name opens the helper's entry in Helper function details.

Signature

Arguments

Returns

Description

array_extract_key_obj(source_array, key_pointer, new_value_pointer, old_value_pointer, [skip_serializer])

source_array (array; reference); key_pointer (string; value); new_value_pointer (string; value); old_value_pointer (string; value); skip_serializer (boolean; value; optional)

object

Builds an object from an array of objects. JSON pointers select each key and its new and old values. Fails when it adds no entry. Use a temporary target field, because a WCS object target fails the build.

array_obj_to_mapkv(source_array, key_pointer, value_pointer, [skip_serializer])

source_array (array; reference); key_pointer (string; value); value_pointer (string; value); skip_serializer (boolean; value; optional)

object

Builds an object from an array of objects. JSON pointers select each key and value. Fails when no entry is added. Use a temporary target field, because a WCS object target fails the build.

as(ip)

ip (string; reference)

object

Looks up the IP address in the GeoLite2-ASN database and returns the autonomous system number and organization.name.

concat(operand_left, operand_right, [...])

operand_left (string, number, or object; value or reference); operand_right (string, number, or object; value or reference)

string

Joins two or more strings, numbers, or objects into one string. Fails when a reference is missing.

concat_any(operand_left, operand_right, [...])

operand_left (string, number, or object; value or reference); operand_right (string, number, or object; value or reference)

string

Joins two or more strings, numbers, or objects into one string. Skips missing references.

date_from_epoch(epoch)

epoch (number; reference)

date string

Converts UNIX epoch seconds to a UTC date with microseconds, such as 2024-05-17T15:10:58.000000Z.

date_to_epoch(date, [format])

date (string; reference); format (string; value; optional)

double number

Converts a date string to UNIX epoch seconds as a double. The default format is %Y-%m-%dT%H:%M:%SZ.

decode_base16(hex)

hex (string; reference)

string

Decodes a string of hexadecimal digits into an ASCII string.

downcase(upper_characters)

upper_characters (string; value or reference)

string

Returns the string in lowercase.

float_calculate(operator, operand_left, operand_right, [...])

operator (string; value); operand_left (number; value or reference); operand_right (number; value or reference)

number

Applies sum, sub, mul, or div to the operands from left to right and returns the result.

geoip(ip)

ip (string; reference)

object

Looks up the IP address in the GeoLite2-City database and returns a location object with fields such as city_name and country_iso_code.

get_date()

None

date string

Returns the current UTC date in the %Y-%m-%dT%H:%M:%SZ format.

hex_to_number(hex)

hex (string; reference)

number

Converts a hexadecimal string such as 0x1F to a base 10 number.

iana_protocol_name_to_number(protocol_name)

protocol_name (string; reference)

keyword string

Returns the Internet Assigned Numbers Authority (IANA) protocol number, as a string, for a protocol keyword such as tcp.

iana_protocol_number_to_name(protocol_code)

protocol_code (string or number; reference)

keyword string

Returns the IANA protocol keyword for a protocol number from 0 to 255. Fails for an unassigned number, such as 61 or 148 to 255.

int_calculate(operator, operand_left, operand_right, [...])

operator (string; value); operand_left (number; value or reference); operand_right (number; value or reference)

number

Applies sum, sub, mul, or div to integer operands from left to right and returns the result.

ip_version(ip)

ip (string; reference)

string

Returns IPv4 or IPv6 for the IP address.

join(array, separator)

array (array; reference); separator (string; value)

string

Joins the strings of an array with separator.

network_community_id(source_ip, destination_ip, source_port, destination_port, protocol)

source_ip (string; reference); destination_ip (string; reference); source_port (number; reference); destination_port (number; reference); protocol (number; value or reference)

string

Returns the Community ID v1 flow hash, 1:<BASE64_HASH>, for the addresses, ports, and IANA protocol number.

regex_extract(fieldToMatch, regex)

fieldToMatch (string; reference); regex (string; value)

string

Returns the group that the RE2 regular expression captures in fieldToMatch.

sha1(any_string)

any_string (string; reference)

string

Returns the SHA-1 hash of the string as 40 hexadecimal digits.

syslog_extract_facility(priority)

priority (number; reference)

object

Returns the syslog facility code and name for a priority from 0 to 191.

syslog_extract_severity(priority)

priority (number; reference)

object

Returns the syslog severity code and name for a priority from 0 to 191.

system_epoch()

None

long number

Returns the current UNIX epoch time in seconds from the system clock.

to_bool(number_to_convert)

number_to_convert (number; reference)

boolean

Returns false for zero and true for any other number.

to_int(number_to_transform, [operation_mode])

number_to_transform (number; reference); operation_mode (string; value; optional)

number

Converts a number to an integer. The mode is truncate, the default, or round.

to_string(any_number)

any_number (number; reference)

string

Converts a number to a string.

upcase(lower_characters)

lower_characters (string; value or reference)

string

Returns the string in uppercase.

Map helper example

The downcase helper returns its argument in lowercase. In this map, the helper reads _upper_characters and writes the result to _target_field.

normalize:
  - map:
      - _target_field: downcase($_upper_characters)

Input event:

{
  "_upper_characters": "AbcD"
}

Output event:

{
  "_upper_characters": "AbcD",
  "_target_field": "abcd"
}

Transformation helpers

Transformation helpers change the target field in place or act on the whole event. They append to arrays, merge objects, delete or rename fields, parse strings, and look up KVDB values. You use them in the map stage of a normalize block. A linked name opens the helper's entry in Helper function details.

Signature

Arguments

Target field

Description

array_append(any_object, [...])

any_object (any type; value or reference)

array (no build check)

Appends the values to the target array and creates the array if it doesn't exist. Fails when a reference is missing.

array_append_any(any_object, [...])

any_object (any type; value or reference)

array (no build check)

Appends the values to the target array and creates the array if it doesn't exist. Skips missing references.

array_append_unique(any_object, [...])

any_object (any type; value or reference)

array (no build check)

Appends only the values that the target array doesn't hold yet. Fails when a reference is missing.

array_append_unique_any(any_object, [...])

any_object (any type; value or reference)

array (no build check)

Appends only the values that the target array doesn't hold yet. Skips missing references.

delete()

None

any

Removes the target field from the event.

delete_fields_with_value(any_object)

any_object (any type; value or reference)

object (no build check)

Removes every direct child of the target object whose value equals the argument.

discard_events()

None

boolean (no build check)

Sets the target to true to mark the event as discarded. The target must be wazuh.space.event_discarded. When the policy enables index_discarded_events, the helper also erases every other event field.

erase_custom_fields()

None

any

Removes each top-level key of the target object that isn't a top-level WCS field. It doesn't check nested fields. You usually call it on the event root, ..

get_key_in(any_object, key)

any_object (object; value or reference); key (string; reference)

any

Copies to the target the value stored under key in the given object.

kvdb_decode_bitmask(db_name, table_name, mask)

db_name (string; value); table_name (string; value); mask (string; reference)

string array

Decodes the hexadecimal mask into an array of values with the bit table table_name in the KVDB db_name.

kvdb_get(db_name, key)

db_name (string; value); key (string; value or reference)

any

Copies to the target the value of key in the KVDB db_name.

kvdb_get_array(db_name, array_key)

db_name (string; value); array_key (array; value or reference)

array (no build check)

Looks up each key of array_key in the KVDB db_name and appends the values to the target array.

kvdb_get_merge(db_name, key)

db_name (string; value); key (string; value or reference)

object

Merges the value of key in the KVDB db_name into the target. Objects merge one level deep, and arrays gain only the items that the target doesn't already have.

kvdb_get_merge_recursive(db_name, key)

db_name (string; value); key (string; value or reference)

object

Merges the value of key in the KVDB db_name into the target, recursively.

merge(any_object)

any_object (object or array; reference)

object or array (no build check)

Merges the referenced field into the target and deletes the referenced field. Both fields must exist and have the same type.

merge_key_in(any_object, key)

any_object (object; value or reference); key (string; reference)

object

Merges into the target the value stored under key in the given object.

merge_recursive(any_object)

any_object (object or array; reference)

object

Merges the referenced field into the target, recursively, and deletes the referenced field. Both fields must exist and have the same type.

merge_recursive_key_in(any_object, key)

any_object (object; value or reference); key (string; reference)

object

Merges into the target, recursively, the value stored under key in the given object.

parse_alphanumeric(field_to_parse, [extra_chars])

field_to_parse (string; reference); extra_chars (string; value; optional)

text string

Stores the input when it holds only letters, digits, and the extra characters you list.

parse_between(input_field, start, end)

input_field (string; reference); start (string; value); end (string; value)

text string

Stores the text between start and end. The input must start with start and end with the first end.

parse_binary(input_field)

input_field (string; reference)

binary string

Stores the input when it is valid base64 data.

parse_bool(input_field)

input_field (string; reference)

boolean

Stores a boolean when the input is the string true or false.

parse_byte(input_field)

input_field (string; reference)

byte number

Stores the input as a byte when it is a number from -128 to 127.

parse_csv(input_field, out1, out2, [...])

input_field (string; reference); out1 (string; value); out2 (string; value)

object

Splits a comma-separated input and stores each value in the output field you name.

parse_date(input_field, format, [locale])

input_field (string; reference); format (string; value); locale (string; value; optional)

date string

Parses a date string with a strftime-style format or a sample date, and an optional locale.

parse_double(input_field)

input_field (string; reference)

double number

Stores the input as a double-precision floating-point number.

parse_dsv(input_field, delim_char, quote_char, esc_char, out1, out2, [...])

input_field (string; reference); delim_char (string; value); quote_char (string; value); esc_char (string; value); out1 (string; value); out2 (string; value)

object

Splits an input separated by delim_char and stores each value in the output field you name.

parse_file(input_field)

input_field (string; reference)

object

Parses a file path and stores its parts in an object.

parse_float(input_field)

input_field (string; reference)

float number

Stores the input as a floating-point number.

parse_fqdn(input_field)

input_field (string; reference)

text string

Stores the input when it is a valid domain name of up to 253 characters.

parse_half_float(input_field)

input_field (string; reference)

half_float number

Stores the input as a half-precision floating-point number.

parse_integer(input_field)

input_field (string; reference)

integer number

Stores the input as an integer.

parse_ip(input_field)

input_field (string; reference)

IP address

Stores the input when it is a valid IPv4 or IPv6 address.

parse_json(input_field)

input_field (string; reference)

object

Parses a JSON string and stores the result.

parse_key_value(input_field, sep_token, delim_token, quote_char, esc_char)

input_field (string; reference); sep_token (string; value); delim_token (string; value); quote_char (string; value); esc_char (string; value)

object

Parses a key-value list and stores each value under its key.

parse_long(input_field)

input_field (string; reference)

long number

Stores the input as a 64-bit integer.

parse_quoted(input_field, [quote_char], [esc_char])

input_field (string; reference); quote_char (string; value; optional); esc_char (string; value; optional)

text string

Stores the text between quote characters. The default quote is " and the default escape is \.

parse_short(input_field)

input_field (string; reference)

short number

Stores the input as a short integer.

parse_unsigned_long(input_field)

input_field (string; reference)

unsigned_long number

Stores the input as an unsigned long integer.

parse_uri(input_field)

input_field (string; reference)

object

Parses a URI and stores its parts as string fields of a URL object.

parse_useragent(input_field)

input_field (string; reference)

object

Stores the user agent string, without changes, in the original field of the target object.

parse_xml(input_field, [module])

input_field (string; reference); module (string; value; optional)

object

Parses an XML string into an object. The windows module handles Windows Event Log XML.

rename(input_field)

input_field (string; reference)

any

Moves the referenced field to the target field. Fails when the target field already exists.

replace(old, new)

old (string; value); new (string; value)

string

Replaces every occurrence of old with new in the target string.

sanitize_fields([recursive])

recursive (boolean; value; optional)

object, array, or string (no build check)

Normalizes the keys of a target object, the items of a target array, or a target string. Set recursive to true to include nested objects.

split(input_field, character)

input_field (string; reference); character (string; value)

string array

Splits the input string at character and appends the parts to the target array.

trim(trim_place, character)

trim_place (string; value); character (string; value)

string

Removes the leading, trailing, or leading and trailing runs of character from the target string. Set trim_place to begin, end, or both. The character value must be one character.

Every array_append helper fails when the target exists and isn't an array, when the values have different JSON types, or when it adds no value. The array_append_unique and array_append_unique_any helpers skip values that the target array already holds.

Transformation helper example

The trim helper removes a character from the start, the end, or both ends of the target string. In this map, the helper removes the trailing - characters from _target_field.

normalize:
  - map:
      - _target_field: trim('end', '-')

Input event:

{
  "_target_field": "-- Hi wazuh! --"
}

Output event:

{
  "_target_field": "-- Hi wazuh! "
}