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 (no build check) |
Passes when the target array contains every listed element. |
|
|
array (no build check) |
Passes when the target array contains at least one listed element. |
|
|
array (no build check) |
Passes when the target array has exactly |
|
|
array (no build check) |
Passes when at least one listed element is missing from the target array. |
|
|
array (no build check) |
Passes when none of the listed elements is in the target array. |
|
|
|
string |
Converts both hexadecimal values to unsigned integers and passes when their
bitwise AND isn't zero. Both values need the |
|
|
string |
Passes when the target string contains |
|
|
string |
Passes when the target string ends with |
|
None |
any |
Passes when the target field exists in the event. |
|
|
string |
Passes when the target string is a key of the given object. |
None |
string (no build check) |
Passes when the policy indexes unclassified events and the target value is
|
|
|
|
number |
Passes when the target integer equals the given integer. |
|
|
number |
Passes when the target integer is greater than the given integer. |
|
|
number |
Passes when the target integer is greater than or equal to the given integer. |
|
|
number |
Passes when the target integer is less than the given integer. |
|
|
number |
Passes when the target integer is less than or equal to the given integer. |
|
|
number |
Passes when the target integer differs from the given integer. |
|
IP address |
Passes when the target IPv4 address is in the range that |
|
|
None |
any |
Passes when the target value is an array. |
|
None |
any |
Passes when the target value is a boolean. |
|
None |
IP address |
Passes when the target value is an IPv4 address. |
|
None |
IP address |
Passes when the target value is an IPv6 address. |
|
None |
any |
Passes when the target value isn't an array. |
|
None |
any |
Passes when the target value isn't a boolean. |
|
None |
any |
Passes when the target value isn't null. |
|
None |
any |
Passes when the target value isn't a number. |
|
None |
any |
Passes when the target value isn't an object. |
|
None |
any |
Passes when the target value isn't a string. |
|
None |
any |
Passes when the target value is null. |
|
None |
any |
Passes when the target value is a number. |
|
None |
any |
Passes when the target value is an object. |
|
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 |
|
None |
any |
Passes when the target value is a string. |
|
object |
Passes when every key of the target object appears in |
|
|
|
string (no build check) |
Passes when the target string is a key in the key-value database (KVDB)
|
|
|
string (no build check) |
Passes when the target string isn't a key in the KVDB |
|
|
any |
Passes when the target value is an element of the given array. |
|
None |
any |
Passes when the target field doesn't exist in the event. |
|
|
number |
Passes when the target number equals the given number. |
|
|
number |
Passes when the target number is greater than the given number. |
|
|
number |
Passes when the target number is greater than or equal to the given number. |
|
|
number |
Passes when the target number is less than the given number. |
|
|
number |
Passes when the target number is less than or equal to the given number. |
|
|
number |
Passes when the target number differs from the given number. |
|
string |
Passes when the target string matches the RE2 regular expression. |
|
|
|
string |
Passes when the target string doesn't match the RE2 regular expression. |
|
|
string |
Passes when the target string starts with |
|
|
string |
Passes when the target string equals the given string, byte for byte. |
|
|
string |
Passes when the target string is lexicographically greater than the given string. |
|
|
string |
Passes when the target string is lexicographically greater than or equal to the given string. |
|
|
string |
Passes when the target string is lexicographically less than the given string. |
|
|
string |
Passes when the target string is lexicographically less than or equal to the given string. |
|
|
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 |
|---|---|---|---|
|
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]) |
|
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. |
|
|
object |
Looks up the IP address in the GeoLite2-ASN database and returns the autonomous
system |
|
|
string |
Joins two or more strings, numbers, or objects into one string. Fails when a reference is missing. |
|
|
string |
Joins two or more strings, numbers, or objects into one string. Skips missing references. |
|
|
|
Converts UNIX epoch seconds to a UTC date with microseconds, such as
|
|
|
Converts a date string to UNIX epoch seconds as a double. The default format is
|
|
|
|
string |
Decodes a string of hexadecimal digits into an ASCII string. |
|
|
string |
Returns the string in lowercase. |
float_calculate(operator, operand_left, operand_right, [...]) |
|
number |
Applies |
|
object |
Looks up the IP address in the GeoLite2-City database and returns a location
object with fields such as |
|
|
None |
|
Returns the current UTC date in the |
|
|
number |
Converts a hexadecimal string such as |
|
|
|
Returns the Internet Assigned Numbers Authority (IANA) protocol number, as a
string, for a protocol keyword such as |
|
|
|
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. |
|
number |
Applies |
|
|
string |
Returns |
|
|
|
string |
Joins the strings of an array with |
network_community_id(source_ip, destination_ip, source_port, destination_port, protocol) |
|
string |
Returns the Community ID v1 flow hash, |
|
string |
Returns the group that the RE2 regular expression captures in |
|
|
|
string |
Returns the SHA-1 hash of the string as 40 hexadecimal digits. |
|
|
object |
Returns the syslog facility |
|
|
object |
Returns the syslog severity |
|
None |
|
Returns the current UNIX epoch time in seconds from the system clock. |
|
|
boolean |
Returns |
|
number |
Converts a number to an integer. The mode is |
|
|
|
string |
Converts a number to a string. |
|
|
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 (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 (no build check) |
Appends the values to the target array and creates the array if it doesn't exist. Skips missing references. |
|
|
array (no build check) |
Appends only the values that the target array doesn't hold yet. Fails when a reference is missing. |
|
|
array (no build check) |
Appends only the values that the target array doesn't hold yet. Skips missing references. |
|
|
None |
any |
Removes the target field from the event. |
|
|
object (no build check) |
Removes every direct child of the target object whose value equals the argument. |
None |
boolean (no build check) |
Sets the target to |
|
|
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,
|
|
|
any |
Copies to the target the value stored under |
|
string array |
Decodes the hexadecimal |
|
|
any |
Copies to the target the value of |
|
|
array (no build check) |
Looks up each key of |
|
|
object |
Merges the value of |
|
|
object |
Merges the value of |
|
|
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. |
|
|
object |
Merges into the target the value stored under |
|
|
object |
Merges the referenced field into the target, recursively, and deletes the referenced field. Both fields must exist and have the same type. |
|
|
object |
Merges into the target, recursively, the value stored under |
|
|
|
|
Stores the input when it holds only letters, digits, and the extra characters you list. |
|
|
|
Stores the text between |
|
|
|
Stores the input when it is valid base64 data. |
|
|
boolean |
Stores a boolean when the input is the string |
|
|
|
Stores the input as a byte when it is a number from -128 to 127. |
|
object |
Splits a comma-separated input and stores each value in the output field you name. |
|
|
|
|
Parses a date string with a strftime-style format or a sample date, and an optional locale. |
|
|
|
Stores the input as a double-precision floating-point number. |
parse_dsv(input_field, delim_char, quote_char, esc_char, out1, out2, [...]) |
|
object |
Splits an input separated by |
|
|
object |
Parses a file path and stores its parts in an object. |
|
|
|
Stores the input as a floating-point number. |
|
|
|
Stores the input when it is a valid domain name of up to 253 characters. |
|
|
|
Stores the input as a half-precision floating-point number. |
|
|
|
Stores the input as an integer. |
|
IP address |
Stores the input when it is a valid IPv4 or IPv6 address. |
|
|
object |
Parses a JSON string and stores the result. |
|
parse_key_value(input_field, sep_token, delim_token, quote_char, esc_char) |
|
object |
Parses a key-value list and stores each value under its key. |
|
|
|
Stores the input as a 64-bit integer. |
|
|
Stores the text between quote characters. The default quote is |
|
|
|
|
Stores the input as a short integer. |
|
|
|
Stores the input as an unsigned long integer. |
|
object |
Parses a URI and stores its parts as string fields of a URL object. |
|
|
object |
Stores the user agent string, without changes, in the |
|
|
object |
Parses an XML string into an object. The |
|
|
|
any |
Moves the referenced field to the target field. Fails when the target field already exists. |
|
|
string |
Replaces every occurrence of |
|
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 |
|
|
string array |
Splits the input string at |
|
|
|
string |
Removes the leading, trailing, or leading and trailing runs of |
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! "
}