Helper function details
The helper functions below need more detail than a one-line table row holds. Their entries give the accepted argument values, every condition that makes the helper fail, and a worked example.
Each entry uses the following conventions:
Source:
valuemeans a literal argument or a reference to a name in the assetdefinitionssection. The engine replaces a definition reference with its value before it builds the helper.referencemeans a field of the event, written with$.Build failure: The asset fails to build, and the engine does not load it.
Run failure: The helper fails for the current event. The stage that holds the call decides what happens next, as described in Failed helper behavior.
Map helpers: For a Wazuh Common Schema (WCS) target field, the engine checks each result against the field type for every event. A result that does not fit is a run failure.
The examples use temporary fields, whose names start with _.
Filter helper details
These filter helpers test arrays, IP ranges, object keys, regular expressions, and the policy setting for unclassified events.
array_contains
Passes when the target array contains every listed element. An element matches only an array item of the same JSON type and value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Any JSON type |
Value or reference |
A string, number, boolean, null, object, or array. Pass 1 to 150 elements. |
Behavior:
Fails when the target field is missing or not an array.
Fails when at least one element is missing from the array.
Counts a reference to a field that does not exist as a missing element, so the check fails.
Does not check the target type when it builds the asset (no build check).
Build failure: no elements or more than 150 elements.
Example:
check:
- _target_field: array_contains('dracut', 'vz-start', 'thin-provisioning-tools')
Input event:
{
"_target_field": ["mkinitramfs", "dracut", "thin-provisioning-tools", "lvm2", "vz-start"]
}
The check passes. With 'iscsi' in place of 'vz-start', the check fails.
array_contains_any
Passes when the target array contains at least one listed element. An element matches only an array item of the same JSON type and value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Any JSON type |
Value or reference |
A string, number, boolean, null, object, or array. Pass 1 to 150 elements. |
Behavior:
Passes as soon as it finds one element in the array.
Skips a reference to a field that does not exist.
Fails when the target field is missing or not an array.
Fails when no element is in the array, including when every reference is missing.
Does not check the target type when it builds the asset (no build check).
Build failure: no elements or more than 150 elements.
Example:
check:
- _target_field: array_contains_any('dracut', 'hello', 'wazuh')
Input event:
{
"_target_field": ["mkinitramfs", "cryptroot", "dracut", "lvm2"]
}
The check passes because dracut is in the array.
array_length_eq
Passes when the target array has exactly the number of elements you give.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Number |
Value |
An integer from |
Behavior:
Fails when the target field is missing or not an array.
Fails when the array length differs from
expected_length.Does not check the target type when it builds the asset (no build check).
Build failure: a reference, a negative number, a decimal number, or a non-number as
expected_length, or not exactly one argument.
Example:
check:
- _target_field: array_length_eq(3)
Input event:
{
"_target_field": ["first", "second", "third"]
}
The check passes. A target that holds the string "not_an_array" fails the check.
array_not_contains
Passes when at least one listed element is missing from the target array. An element matches only an array item of the same JSON type and value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Any JSON type |
Value or reference |
A string, number, boolean, null, object, or array. Pass 1 to 150 elements. |
Behavior:
Passes as soon as it finds one element that is not in the array.
Fails when every listed element is in the array.
Skips a reference to a field that does not exist. It does not count as a missing element. When every reference is missing, the check fails.
Fails when the target field is missing or not an array.
Does not check the target type when it builds the asset (no build check).
Build failure: no elements or more than 150 elements.
Example:
check:
- _target_field: array_not_contains('dracut', 'vz-start', 'iscsi')
Input event:
{
"_target_field": ["mkinitramfs", "dracut", "thin-provisioning-tools", "vz-start"]
}
The check passes because iscsi is not in the array.
array_not_contains_any
Passes when none of the listed elements is in the target array. An element matches only an array item of the same JSON type and value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Any JSON type |
Value or reference |
A string, number, boolean, null, object, or array. Pass 1 to 150 elements. |
Behavior:
Fails as soon as it finds one listed element in the array.
Fails when a reference points to a field that does not exist. The engine cannot confirm that a missing value is absent.
Fails when the target field is missing or not an array.
Does not check the target type when it builds the asset (no build check).
Build failure: no elements or more than 150 elements.
Example:
check:
- _target_field: array_not_contains_any('dracut', 'hello', 'wazuh')
Input event:
{
"_target_field": ["mkinitramfs", "cryptroot", "dracut", "lvm2"]
}
The check fails because dracut is in the array.
index_unclassified_events
Passes when the policy indexes unclassified events and the event category is unclassified. Outputs use it to route events that no integration decoder classified.
The helper takes no arguments.
Behavior:
Reads the
index_unclassified_eventspolicy setting when it builds the asset. Every policy must set it totrueorfalse.Fails for every event when the setting is
false.Fails when
wazuh.integration.categoryis missing, is not a string, or is not exactlyunclassified.Does not check the target type when it builds the asset (no build check).
Build failure: a target other than
wazuh.integration.category, or any argument.
Example, with index_unclassified_events set to true in the policy:
check:
- wazuh.integration.category: index_unclassified_events()
Input event:
{
"wazuh": {
"integration": {
"category": "unclassified"
}
}
}
The check passes. The category security fails the check.
ip_cidr_match
Passes when the target IPv4 address is in the network range that a subnet and a mask define. The range includes the network and broadcast addresses.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
An IPv4 address in dotted-decimal form, with each octet from |
|
String |
Value |
A dotted-decimal mask, such as |
Behavior:
Fails when the target field is missing or not a string.
Fails when the target value is not a valid IPv4 address. IPv6 addresses always fail.
Fails when the address is outside the range.
Expects a WCS field of type
ipas the target.Build failure: a reference as an argument, a non-string argument, an invalid subnet, an invalid mask, or not exactly two arguments.
Example:
check:
- _target_field: ip_cidr_match('192.168.0.0', '255.255.0.0')
Input event:
{
"_target_field": "192.168.1.5"
}
The check passes. The address 111.111.1.11 fails the check.
keys_exist_in_list
Passes when every top-level key of the target object appears in a list of allowed keys. Use it to reject objects that carry unexpected keys.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Array of strings |
Value or reference |
An array whose items are all strings, such as |
Behavior:
Fails when the target field is missing or not an object.
Fails when the target object has a key that is not in the list.
Fails when the referenced field is missing, is not an array, or holds an item that is not a string.
Expects a WCS field of type
objectas the target.Build failure: a literal argument that is not an array of strings, or not exactly one argument.
Build failure: a reference to a WCS field that does not hold strings.
Example:
check:
- _target_field: keys_exist_in_list(["ts", "host", "other"])
Input event:
{
"_target_field": {
"ts": "2021-01-03T01:19:32.488179Z",
"host": "192.168.4.43"
}
}
The check passes. An extra key, such as other_key, makes it fail.
regex_match
Passes when the RE2 regular expression matches the target string. The match is partial, so the expression can match any part of the string.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
A valid RE2 regular expression. Add |
Behavior:
Fails when the target field is missing or not a string.
Fails when the expression does not match.
Expects a WCS string field as the target.
Build failure: a reference as the argument, a non-string argument, an invalid RE2 expression, or not exactly one argument.
Example:
check:
- _target_field: regex_match('^(bye pcre\\d)$')
Input event:
{
"_target_field": "bye pcre2"
}
The check passes. The string ye pcre2 fails the check.
Map helper details
These map helpers build objects from arrays, convert dates and numbers, look up locations, and compute network values. Each one writes its result to the target field and replaces any existing value.
array_extract_key_obj
Builds an object from an array of objects. Each array element gives a key, a new value, and an old value, which the helper reads with JSON pointers.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Array of objects |
Reference |
A field that holds an array of objects. |
|
String |
Value |
A JSON pointer that starts with |
|
String |
Value |
A JSON pointer that starts with |
|
String |
Value |
A JSON pointer that starts with |
|
Boolean |
Value (optional) |
|
Behavior:
Writes one entry per element:
<KEY>holds the new value and the old value under their pointer paths.Normalizes each key unless
skip_serializeristrue. It lowercases ASCII letters, turns spaces and/,.,-,\, and:into one_, drops other symbols, and removes leading and trailing_.Skips elements that are not objects, have no non-empty string key, lack the new value, or produce an empty key.
Leaves out an old value that is an empty or blank string.
Run failure: the referenced field is missing or not an array, or no entry is added.
The registry expects a string target. A WCS object field as the target fails the build, so use a temporary field.
Build failure: fewer than four or more than five arguments, or a value as
source_array.Build failure: a pointer that is empty or does not start with
/, or a non-booleanskip_serializer.Build failure: a WCS
source_arrayreference that is not anobjectfield.
Example:
normalize:
- map:
- _target_field: array_extract_key_obj($_props, '/Name', '/NewValue', '/OldValue', false)
Input event:
{
"_props": [
{"Name": "RequiredResourceAccess", "NewValue": "new-data", "OldValue": "old-data"},
{"Name": "Included Updated Properties", "NewValue": "RequiredResourceAccess", "OldValue": ""}
]
}
Output event:
{
"_props": [
{"Name": "RequiredResourceAccess", "NewValue": "new-data", "OldValue": "old-data"},
{"Name": "Included Updated Properties", "NewValue": "RequiredResourceAccess", "OldValue": ""}
],
"_target_field": {
"requiredresourceaccess": {"NewValue": "new-data", "OldValue": "old-data"},
"included_updated_properties": {"NewValue": "RequiredResourceAccess"}
}
}
array_obj_to_mapkv
Builds a key-value object from an array of objects. Each array element gives a key and a value, which the helper reads with JSON pointers.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Array of objects |
Reference |
A field that holds an array of objects. |
|
String |
Value |
A JSON pointer that starts with |
|
String |
Value |
A JSON pointer that starts with |
|
Boolean |
Value (optional) |
|
Behavior:
Writes one
<KEY>: <VALUE>entry per element. The value keeps its JSON type.Normalizes each key unless
skip_serializeristrue. It lowercases ASCII letters, turns spaces and/,.,-,\, and:into one_, drops other symbols, and removes leading and trailing_.Skips elements that are not objects, have no non-empty string key, lack the value, or produce an empty key.
Run failure: the referenced field is missing or not an array, or no entry is added.
The registry expects a string target. A WCS object field as the target fails the build, so use a temporary field.
Build failure: fewer than three or more than four arguments, or a value as
source_array.Build failure: a pointer that is empty or does not start with
/, or a non-booleanskip_serializer.Build failure: a WCS
source_arrayreference that is not anobjectfield.
Example:
normalize:
- map:
- _target_field: array_obj_to_mapkv($_props, '/Name', '/Value', false)
Input event:
{
"_props": [
{"Name": "UserAgent", "Value": "Mozilla/5.0"},
{"Name": "Request.Type", "Value": "OAuth2:Authorize"}
]
}
Output event:
{
"_props": [
{"Name": "UserAgent", "Value": "Mozilla/5.0"},
{"Name": "Request.Type", "Value": "OAuth2:Authorize"}
],
"_target_field": {
"useragent": "Mozilla/5.0",
"request_type": "OAuth2:Authorize"
}
}
date_to_epoch
Converts a date string to UNIX epoch seconds. The result is a double that keeps fractional seconds to the microsecond.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A date string that matches |
|
String |
Value (optional) |
A strftime-style format of 1 to 64 characters, such as |
Behavior:
Fails when any text is left after the format matches.
Applies the UTC offset that
%zor%Ezreads, such as-03:00.Looks up the time zone name that
%Zreads, such asEurope/Berlin. An unknown zone fails.Treats a date without offset or zone as UTC.
Fails when a local time does not exist or is ambiguous because of a daylight saving change.
Run failure: the referenced field is missing or not a string, the date does not match, or the result is out of range.
Expects a WCS field of type
doubleas the target.Build failure: a value as
date, or more than two arguments.Build failure: a format that is not a string, is empty, or is longer than 64 characters.
Example:
normalize:
- map:
- _target_field: date_to_epoch($_date, '%FT%T%Ez')
Input event:
{
"_date": "2024-05-17T12:10:58-03:00"
}
Output event:
{
"_date": "2024-05-17T12:10:58-03:00",
"_target_field": 1715958658.0
}
float_calculate
Applies an arithmetic operator to two or more numbers from left to right and returns a double. For example, sub with 10, 2, and 3 returns (10 - 2) - 3.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
|
|
Number |
Value or reference |
Integers or decimal numbers. Pass 2 to 149 operands. A WCS reference must be a numeric field. |
Behavior:
Converts integer operands to doubles.
Run failure: a referenced field is missing or not a number, a division by zero occurs, or the result is infinite or not a number.
Expects a WCS numeric field as the target.
Build failure: fewer than two operands, an unknown or non-string operator, or a literal operand that is not a number.
Build failure: a literal
0divisor after the first operand ofdiv, or a WCS reference that is not numeric.
Example:
normalize:
- map:
- _target_field: float_calculate('sum', 2.676, 3.756)
Input event:
{}
Output event:
{
"_target_field": 6.432
}
geoip
Looks up an IP address in the GeoLite2-City database and returns its location. The object holds only the fields that the database has for that address.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
An IPv4 or IPv6 address string. A WCS reference must be an |
Behavior:
Can return
city_name,continent_code,continent_name,country_iso_code,country_name,location.lat,location.lon,postal_code,timezone,region_iso_code, andregion_name.Run failure: the referenced field is missing or not a string, or the lookup returns no data. An invalid address or an address without an entry returns no data.
Accepts up to 150 arguments, but reads only the first one.
Expects a WCS field of type
objectas the target.Build failure: the City database is not available, the first argument is a value, or a WCS reference is not an
ipfield.
Example, with the test database that the engine helper tests use:
normalize:
- map:
- _target_field: geoip($_ip)
Input event:
{
"_ip": "1.2.3.4"
}
Output event:
{
"_ip": "1.2.3.4",
"_target_field": {
"city_name": "Wazuh city",
"continent_code": "WC",
"continent_name": "Wazuh Continent",
"country_iso_code": "WCtry",
"country_name": "Wazuh Country",
"location": {"lat": 41.7776, "lon": 88.4293},
"postal_code": "7777",
"timezone": "Wazuh/Timezone"
}
}
int_calculate
Applies an arithmetic operator to two or more 64-bit integers from left to right and returns an integer. Division drops the fractional part.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
|
|
Integer |
Value or reference |
Integers from |
Behavior:
Run failure: a referenced field does not exist or does not hold an integer.
Run failure: a division by zero, or a result outside the 64-bit integer range.
Expects a WCS numeric field as the target.
Build failure: fewer than two operands, an unknown or non-string operator, or a literal operand that is not an integer.
Build failure: a literal
0divisor after the first operand ofdiv, or a WCS reference of another type.
Example:
normalize:
- map:
- _target_field: int_calculate('sub', $_bytes_in, $_bytes_out)
Input event:
{
"_bytes_in": 1500,
"_bytes_out": 400
}
Output event:
{
"_bytes_in": 1500,
"_bytes_out": 400,
"_target_field": 1100
}
ip_version
Returns IPv4 or IPv6 for an IP address string.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
An IPv4 address in dotted-decimal form or an IPv6 address in text form. |
Behavior:
Run failure: the referenced field is missing, is not a string, or is not a valid IPv4 or IPv6 address.
Expects a WCS string field as the target.
Build failure: a value as the argument, a WCS reference to a non-string field, or not exactly one argument.
Example:
normalize:
- map:
- _target_field: ip_version($_ip)
Input event:
{
"_ip": "3002:0bd6:0000:0000:0000:ee00:0033:6778"
}
Output event:
{
"_ip": "3002:0bd6:0000:0000:0000:ee00:0033:6778",
"_target_field": "IPv6"
}
network_community_id
Returns the Community ID v1 hash of a network flow, in the form 1:<BASE64_HASH>. The hash uses seed 0 and does not depend on flow direction.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
An IPv4 or IPv6 address. |
|
String |
Reference |
An address of the same IP family as |
|
Integer |
Reference |
|
|
Integer |
Reference |
The same ranges as |
|
Integer |
Value or reference |
An IANA protocol number from |
Behavior:
Uses
0for a port field that does not exist. TCP, UDP, and SCTP flows then fail, because they need ports from1.Run failure: an address field is missing, is not a string, or is not a valid address, or the two addresses belong to different families.
Run failure: the protocol field is missing, is not an integer, or is out of range.
Run failure: a port field is not an integer, or a port is out of range for the protocol.
Build failure: a value as one of the first four arguments, or a literal protocol that is not an integer from
0to255.Build failure: a WCS address reference to a non-string field.
Build failure: a WCS port or protocol reference to a field that is not
integer,short, orlong.
Example:
normalize:
- map:
- _target_field: network_community_id($_src_ip, $_dst_ip, $_src_port, $_dst_port, 6)
Input event:
{
"_src_ip": "192.168.0.1",
"_dst_ip": "10.0.0.5",
"_src_port": 12345,
"_dst_port": 80
}
Output event:
{
"_src_ip": "192.168.0.1",
"_dst_ip": "10.0.0.5",
"_src_port": 12345,
"_dst_port": 80,
"_target_field": "1:JHvDxB6S6/K68OntUBf4DJZYvkM="
}
regex_extract
Returns the text that the first capture group of an RE2 regular expression captures. The match is partial, so the expression can match any part of the string.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A string field. |
|
String |
Value |
A valid RE2 regular expression. Put the text to extract in the first capture
group, |
Behavior:
Run failure: the referenced field is missing or not a string, or the expression does not match.
Expects a WCS string field as the target.
Build failure: a value as
fieldToMatch, a WCS reference to a non-string field, or not exactly two arguments.Build failure: a reference or a non-string as
regex, or an invalid RE2 expression.
Example:
normalize:
- map:
- _target_field: regex_extract($_message, '^(bye pcre\\d)$')
Input event:
{
"_message": "bye pcre2"
}
Output event:
{
"_message": "bye pcre2",
"_target_field": "bye pcre2"
}
to_int
Converts a number to a 64-bit integer. The truncate mode drops the fractional part, and the round mode rounds to the nearest integer, with halves away from zero.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Number |
Reference |
An integer or a decimal number. A WCS reference must be a numeric field. |
|
String |
Value (optional) |
|
Behavior:
Returns an integer input without changes.
Run failure: the referenced field is missing or not a number.
Expects a WCS numeric field as the target.
Build failure: a value as
number_to_transform, a WCS reference that is not numeric, or more than two arguments.Build failure: a reference, a non-string, or another mode name as
operation_mode.
Example:
normalize:
- map:
- _target_field: to_int($_value, 'round')
Input event:
{
"_value": -4.716666736602783
}
Output event:
{
"_value": -4.716666736602783,
"_target_field": -5
}
Transformation helper details
These transformation helpers append to arrays, mark events as discarded, read key-value databases (KVDBs), merge objects, parse strings, and normalize keys. They change the target field in place.
array_append
Appends one or more values to the target array, in order. The helper creates the array when the target field does not exist.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Any JSON type |
Value or reference |
A string, number, boolean, object, or array. Every value must have the element type of the array. Pass 1 to 150 values. |
Behavior:
Sets the element type from the WCS field type, then from the first item of the existing array, then from the first value.
Run failure: the target exists and is not an array, a referenced field does not exist, or a value has a different JSON type.
Run failure: the new array does not pass the WCS field validation.
Does not check the target type when it builds the asset (no build check).
Build failure: no values, more than 150 values, or a literal value whose type differs from the WCS field type.
Example:
normalize:
- map:
- _target_field: array_append(5)
Input event:
{
"_target_field": [1, 2, 3, 4]
}
Output event:
{
"_target_field": [1, 2, 3, 4, 5]
}
array_append_any
Appends one or more values to the target array and skips references to fields that do not exist. The helper creates the array when the target field does not exist.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Any JSON type |
Value or reference |
A string, number, boolean, object, or array. Every value must have the element type of the array. Pass 1 to 150 values. |
Behavior:
Sets the element type from the WCS field type, then from the first item of the existing array, then from the first value.
Run failure: the target exists and is not an array, or a value has a different JSON type.
Run failure: nothing is appended because every reference is missing.
Run failure: the new array does not pass the WCS field validation.
Does not check the target type when it builds the asset (no build check).
Build failure: no values, more than 150 values, or a literal value whose type differs from the WCS field type.
Example:
normalize:
- map:
- _target_field: array_append_any($_missing, $_value)
Input event:
{
"_value": 6,
"_target_field": [1, 2, 3, 4]
}
Output event:
{
"_value": 6,
"_target_field": [1, 2, 3, 4, 6]
}
array_append_unique
Appends only the values that the target array does not hold yet. The helper creates the array when the target field does not exist.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Any JSON type |
Value or reference |
A string, number, boolean, object, or array. Every value must have the element type of the array. Pass 1 to 150 values. |
Behavior:
Skips a value that is already in the array, including a value appended earlier in the same call.
Run failure: nothing new is appended because every value is already in the array.
Run failure: the target exists and is not an array, a referenced field does not exist, or a value has a different JSON type.
Run failure: the new array does not pass the WCS field validation.
Does not check the target type when it builds the asset (no build check).
Build failure: no values, more than 150 values, or a literal value whose type differs from the WCS field type.
Example:
normalize:
- map:
- _target_field: array_append_unique(5)
Input event:
{
"_target_field": [1, 2, 3, 4]
}
Output event:
{
"_target_field": [1, 2, 3, 4, 5]
}
With [1, 2, 3, 4, 5] as the target, the helper fails and the target does not change.
array_append_unique_any
Appends only the values that the target array does not hold yet, and skips references to fields that do not exist. The helper creates the array when the target field does not exist.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Any JSON type |
Value or reference |
A string, number, boolean, object, or array. Every value must have the element type of the array. Pass 1 to 150 values. |
Behavior:
Skips a value that is already in the array, and a reference to a field that does not exist.
Run failure: nothing new is appended.
Run failure: the target exists and is not an array, or a value has a different JSON type.
Run failure: the new array does not pass the WCS field validation.
Does not check the target type when it builds the asset (no build check).
Build failure: no values, more than 150 values, or a literal value whose type differs from the WCS field type.
Example:
normalize:
- map:
- _target_field: array_append_unique_any(5, 6)
Input event:
{
"_target_field": [1, 2, 3, 4, 5]
}
Output event:
{
"_target_field": [1, 2, 3, 4, 5, 6]
}
discard_events
Sets wazuh.space.event_discarded to true to mark the event as discarded. The helper does not stop processing, so the operations after it still run.
The helper takes no arguments.
Behavior:
Reads the
index_discarded_eventspolicy setting when it builds the asset. Every policy must set it totrueorfalse.Keeps every event field when the setting is
false. The pipeline then drops the event before enrichment.Erases every event field before it sets the flag when the setting is
true. The event continues to the outputs with the flag.Does not check the target type when it builds the asset (no build check).
Build failure: a target other than
wazuh.space.event_discarded, or any argument.
Example, with index_discarded_events set to false in the policy:
normalize:
- map:
- wazuh.space.event_discarded: discard_events()
Input event:
{
"event": {
"original": "healthcheck OK"
}
}
Output event:
{
"event": {
"original": "healthcheck OK"
},
"wazuh": {
"space": {
"event_discarded": true
}
}
}
kvdb_decode_bitmask
Decodes a hexadecimal bitmask into an array of values. A bit table stored in a KVDB maps each bit position to a value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
The name of a KVDB that exists. When the integration lists its KVDBs, the KVDB must be in the list and enabled. |
|
String |
Value |
A key of that KVDB whose value is the bit table. |
|
String |
Reference |
A hexadecimal string that fits in 64 bits, such as |
Behavior:
Requires a bit table that is a non-empty JSON object. Its keys are decimal bit positions from
"0"to"63", and all its values share one JSON type.Loads the table once, when it builds the asset, not for each event.
Appends the value of each set bit, from bit 0 upward, and skips bits that the table does not map. A target that is not an array is replaced.
Run failure: the mask field is missing, is not a string, doesn't start with a hexadecimal number, or doesn't fit in 64 bits. The helper ignores text after the leading hexadecimal digits.
Run failure: no set bit maps to a value, including a mask of
0.A WCS target must hold strings.
Build failure: the KVDB cannot be loaded, the table key does not exist, or the table breaks a rule above.
Build failure: a reference as
db_nameortable_name, a value asmask, a non-string argument, or not exactly three arguments.
Example, with the KVDB windows_kerberos_status_code_to_code_name from the engine helper tests, whose access_mask table maps "0" to Create Child and "4" to Read Property:
normalize:
- map:
- _target_field: kvdb_decode_bitmask('windows_kerberos_status_code_to_code_name', 'access_mask', $_mask)
Input event:
{
"_mask": "11"
}
Output event:
{
"_mask": "11",
"_target_field": ["Create Child", "Read Property"]
}
kvdb_get
Copies to the target field the value of a key in a KVDB. The value keeps its JSON type: string, number, boolean, null, object, or array.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
The name of a KVDB that exists. When the integration lists its KVDBs, the KVDB must be in the list and enabled. |
|
String |
Value or reference |
A key string. A WCS reference must be a string field. |
Behavior:
Replaces the current value of the target field.
Run failure: the key field is missing or not a string, or the key is not in the KVDB.
Run failure: the value does not pass the WCS field validation.
Does not check the target type when it builds the asset (no build check).
Build failure: the KVDB is not declared, is disabled, or cannot be loaded.
Build failure: a reference or a non-string as
db_name, a non-string literalkey, or not exactly two arguments.
Example, with the KVDB windows_kerberos_status_code_to_code_name from the engine helper tests:
normalize:
- map:
- _target_field: kvdb_get('windows_kerberos_status_code_to_code_name', $_status)
Input event:
{
"_status": "0x0"
}
Output event:
{
"_status": "0x0",
"_target_field": "KDC_ERR_NONE"
}
kvdb_get_array
Looks up each key of an array in a KVDB and appends the values to the target array. The helper creates the array when the target field does not exist.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
The name of a KVDB that exists. When the integration lists its KVDBs, the KVDB must be in the list and enabled. |
|
Array of strings |
Value or reference |
An array whose items are all strings, such as |
Behavior:
Appends nothing unless every key is in the KVDB.
Requires values of one JSON type. Mixed types fail.
Replaces a target that is not an array.
Run failure: the referenced field is missing, is not an array, or holds a non-string item.
Run failure: a key is not in the KVDB, the values have different types, or the array does not pass the WCS field validation.
Does not check the target type when it builds the asset (no build check).
Build failure: the KVDB is not declared, is disabled, or cannot be loaded.
Build failure: a reference or a non-string as
db_name, a literalarray_keythat is not an array of strings, or not exactly two arguments.
Example, with the KVDB windows_kerberos_status_code_to_code_name from the engine helper tests:
normalize:
- map:
- _target_field: kvdb_get_array('windows_kerberos_status_code_to_code_name', ["0x0", "0x1"])
Input event:
{
"_target_field": []
}
Output event:
{
"_target_field": ["KDC_ERR_NONE", "KDC_ERR_NAME_EXP"]
}
kvdb_get_merge
Merges the value of a KVDB key into the target field, one level deep. Use it to add default fields from a KVDB to an existing object.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
The name of a KVDB that exists. When the integration lists its KVDBs, the KVDB must be in the list and enabled. |
|
String |
Value or reference |
A key string. A WCS reference must be a string field. |
Behavior:
Requires a target and a KVDB value of the same type: both objects or both arrays.
Objects: Copies each top-level key of the KVDB value and replaces the target value on a key collision.
Arrays: Appends only the KVDB items that the target array does not hold yet.
Run failure: the target does not exist, the types differ, or the value is not an object or array.
Run failure: the key field is missing or not a string, or the key is not in the KVDB.
Run failure: the value does not pass the WCS field validation.
Expects a WCS field of type
objectas the target. Only temporary targets can merge arrays.Build failure: the KVDB is not declared, is disabled, or cannot be loaded, or the arguments break the
kvdb_getrules.
Example, for a KVDB <KVDB_NAME> whose key defaults holds {"severity": "low", "tags": {"source": "kvdb"}}:
normalize:
- map:
- _target_field: kvdb_get_merge('<KVDB_NAME>', 'defaults')
Input event:
{
"_target_field": {
"severity": "high",
"tags": {"team": "soc"}
}
}
Output event:
{
"_target_field": {
"severity": "low",
"tags": {"source": "kvdb"}
}
}
Replace <KVDB_NAME> with the name of your KVDB.
kvdb_get_merge_recursive
Merges the value of a KVDB key into the target field at every level. Nested objects merge key by key instead of being replaced.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Value |
The name of a KVDB that exists. When the integration lists its KVDBs, the KVDB must be in the list and enabled. |
|
String |
Value or reference |
A key string. A WCS reference must be a string field. |
Behavior:
Requires a target and a KVDB value of the same type: both objects or both arrays.
Objects: Merges nested objects and arrays recursively, and replaces other values on a key collision.
Arrays: Appends only the KVDB items that the target array does not hold yet.
Run failure: the target does not exist, the types differ, or the value is not an object or array.
Run failure: the key field is missing or not a string, or the key is not in the KVDB.
Run failure: the value does not pass the WCS field validation.
Expects a WCS field of type
objectas the target. Only temporary targets can merge arrays.Build failure: the KVDB is not declared, is disabled, or cannot be loaded, or the arguments break the
kvdb_getrules.
Example, for a KVDB <KVDB_NAME> whose key defaults holds {"severity": "low", "tags": {"source": "kvdb"}}:
normalize:
- map:
- _target_field: kvdb_get_merge_recursive('<KVDB_NAME>', 'defaults')
Input event:
{
"_target_field": {
"severity": "high",
"tags": {"team": "soc"}
}
}
Output event:
{
"_target_field": {
"severity": "low",
"tags": {"team": "soc", "source": "kvdb"}
}
}
Replace <KVDB_NAME> with the name of your KVDB.
merge
Merges a referenced object or array into the target field, one level deep, and then deletes the referenced field.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Object or array |
Reference |
A field of the same type as the target field. |
Behavior:
Objects: Copies each top-level key of the source and replaces the target value on a key collision.
Arrays: Appends only the source items that the target array does not hold yet, after the existing items.
Deletes the referenced field after the merge.
Run failure: the target or the referenced field does not exist, their types differ, or they are not objects or arrays. Neither field changes.
Does not check the target type when it builds the asset (no build check).
Build failure: a value as the argument, or not exactly one argument.
Example:
normalize:
- map:
- _target_field: merge($_source)
Input event:
{
"_source": {
"key": "name",
"key2": {"age": 27, "address": "new york"}
},
"_target_field": {"key3": "surname"}
}
Output event:
{
"_target_field": {
"key3": "surname",
"key": "name",
"key2": {"age": 27, "address": "new york"}
}
}
merge_key_in
Looks up a key in an object and merges the value under that key into the target field, one level deep. The key name comes from an event field.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Object |
Value or reference |
A JSON object literal, a definition, or a reference to an object field. |
|
String |
Reference |
A string field that holds the key. Dots in the key, such as |
Behavior:
Copies each top-level key of the value and replaces the target value on a key collision.
Does not change or delete the source object.
Run failure: the key field is missing or not a string, or the key is not in the object.
Run failure: the object field is missing or not an object.
Run failure: the value does not pass WCS validation, or the merge fails. The merge needs an existing target of the same type: both objects or both arrays.
Expects a WCS field of type
objectas the target.Build failure: a literal
any_objectthat is not an object, a value askey, or not exactly two arguments.Build failure: a WCS
any_objectreference that is not anobjectfield, or a WCSkeyreference that is not a string field.
Example:
normalize:
- map:
- _target_field: merge_key_in($_lookup, $_key)
Input event:
{
"_lookup": {
"input_key_1": {"v1": "k1"},
"input_key_2": {"v2": "k2"}
},
"_key": "input_key_1",
"_target_field": {"v0": "k0"}
}
Output event:
{
"_lookup": {
"input_key_1": {"v1": "k1"},
"input_key_2": {"v2": "k2"}
},
"_key": "input_key_1",
"_target_field": {"v0": "k0", "v1": "k1"}
}
merge_recursive
Merges a referenced object or array into the target field at every level, and then deletes the referenced field.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Object or array |
Reference |
A field of the same type as the target field. |
Behavior:
Objects: Merges nested objects and arrays recursively, and replaces other values on a key collision.
Arrays: Appends only the source items that the target array does not hold yet, after the existing items.
Deletes the referenced field after the merge.
Run failure: the target or the referenced field does not exist, their types differ, or they are not objects or arrays. Neither field changes.
Expects a WCS field of type
objectas the target. Only temporary targets can merge arrays.Build failure: a value as the argument, or not exactly one argument.
Example:
normalize:
- map:
- _target_field: merge_recursive($_source)
Input event:
{
"_source": {"a": {"d": "e"}},
"_target_field": {"a": {"b": "c"}}
}
Output event:
{
"_target_field": {"a": {"b": "c", "d": "e"}}
}
merge_recursive_key_in
Looks up a key in an object and merges the value under that key into the target field at every level. The key name comes from an event field.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Object |
Value or reference |
A JSON object literal, a definition, or a reference to an object field. |
|
String |
Reference |
A string field that holds the key. Dots in the key, such as |
Behavior:
Merges nested objects and arrays recursively, and replaces other values on a key collision.
Does not change or delete the source object.
Run failure: the key field is missing or not a string, or the key is not in the object.
Run failure: the object field is missing or not an object.
Run failure: the value does not pass WCS validation, or the merge fails. The merge needs an existing target of the same type: both objects or both arrays.
Expects a WCS field of type
objectas the target.Build failure: a literal
any_objectthat is not an object, a value askey, or not exactly two arguments.Build failure: a WCS
any_objectreference that is not anobjectfield, or a WCSkeyreference that is not a string field.
Example:
normalize:
- map:
- _target_field: merge_recursive_key_in($_lookup, $_key)
Input event:
{
"_lookup": {
"input_key_1": {"v1": "k1", "nested": {"n1": "value1"}},
"input_key_2": {"v2": "k2"}
},
"_key": "input_key_1",
"_target_field": {"v0": "k0", "nested": {"n2": "value2"}}
}
Output event:
{
"_lookup": {
"input_key_1": {"v1": "k1", "nested": {"n1": "value1"}},
"input_key_2": {"v2": "k2"}
},
"_key": "input_key_1",
"_target_field": {"v0": "k0", "v1": "k1", "nested": {"n2": "value2", "n1": "value1"}}
}
parse_csv
Splits a comma-separated string and stores each value in the output field you name. The result is an object that replaces the target value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A string field. A WCS reference must be a string field. |
|
String |
Value |
Output field names. A |
Behavior:
Uses
,as the delimiter and"as the quote and escape character. Quoted values can contain commas, and""stands for a literal quote.Stores every value as a string, and an empty value as
null.Run failure: the input field is missing or not a string, or the number of values differs from the number of output names.
Run failure: the quotes are not balanced, or text is left after the last value.
Expects a WCS field of type
objectas the target.Build failure: fewer than two output names, or a reference or non-string as an output name.
Build failure: a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_csv($_input, 'out1', 'out2', 'out3')
Input event:
{
"_input": "value1,value2,value3"
}
Output event:
{
"_input": "value1,value2,value3",
"_target_field": {"out1": "value1", "out2": "value2", "out3": "value3"}
}
parse_dsv
Splits a string at a delimiter character you choose and stores each value in the output field you name. The result is an object that replaces the target value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A string field. A WCS reference must be a string field. |
|
String |
Value |
Exactly one character, such as |
|
String |
Value |
Exactly one character, such as |
|
String |
Value |
Exactly one character that escapes the quote character inside quoted values. |
|
String |
Value |
Output field names. A |
Behavior:
Stores every value as a string, and an empty value as
null.Run failure: the input field is missing or not a string, or the number of values differs from the number of output names.
Run failure: the quotes are not balanced, or text is left after the last value.
Expects a WCS field of type
objectas the target.Build failure: fewer than two output names, a
delim_char,quote_char, oresc_charthat is not exactly one character, or a non-string value argument.Build failure: a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_dsv($_input, '|', "'", '\\', 'out1', 'out2')
Input event:
{
"_input": "value1|value2"
}
Output event:
{
"_input": "value1|value2",
"_target_field": {"out1": "value1", "out2": "value2"}
}
parse_ip
Stores the input string in the target field when it is a valid IPv4 or IPv6 address. The helper does not change the address text.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A dotted-decimal IPv4 address with octets from |
Behavior:
Run failure: the input field is missing or not a string, or the text is not a valid address.
Run failure: text is left after the address, such as a port.
Expects a WCS field of type
ipas the target.Build failure: more than one argument, a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_ip($_input)
Input event:
{
"_input": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}
Output event:
{
"_input": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
"_target_field": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}
The input 999.999.999.999 fails, and the target does not change.
parse_json
Parses a JSON string and stores the resulting value in the target field, replacing any existing value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A string that holds one JSON value, nested 256 levels deep at most. |
Behavior:
Run failure: the input field is missing or not a string, or the text is not valid JSON.
Run failure: the JSON is nested more than 256 levels deep, or text is left after the JSON value.
Expects a WCS field of type
objectas the target.Build failure: more than one argument, a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_json($_input)
Input event:
{
"_input": "{\"key\": {\"innerKey\": \"value\"}}"
}
Output event:
{
"_input": "{\"key\": {\"innerKey\": \"value\"}}",
"_target_field": {"key": {"innerKey": "value"}}
}
parse_key_value
Parses a list of key-value pairs and stores each value under its key. The result is an object that replaces the target value.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A string field. A WCS reference must be a string field. |
|
String |
Value |
One or more characters between a key and its value, such as |
|
String |
Value |
One or more characters between pairs, such as a space or |
|
String |
Value |
Exactly one character. Quoted keys and values can contain both tokens. |
|
String |
Value |
Exactly one character that escapes the quote character, the escape character, or a token. |
Behavior:
Removes the quotes around a quoted key or value.
Stores every value as a string, and an empty value as
null. A.in a key creates a nested field.Run failure: the input field is missing or not a string, no pair parses, or text is left after the last pair.
Run failure: a key creates fields nested more than 256 levels deep.
Expects a WCS field of type
objectas the target.Build failure: not exactly five arguments, an empty or equal
sep_tokenanddelim_token, or aquote_charoresc_charthat is not one character.Build failure: a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_key_value($_input, '=', ' ', "'", '\\')
Input event:
{
"_input": "key1=value1 key2=value2 key3=value3"
}
Output event:
{
"_input": "key1=value1 key2=value2 key3=value3",
"_target_field": {"key1": "value1", "key2": "value2", "key3": "value3"}
}
parse_quoted
Stores the text between a pair of quote characters, without the quotes and escape characters.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A string that starts with the quote character and ends with the closing quote. |
|
String |
Value (optional) |
Exactly one character. The default is |
|
String |
Value (optional) |
Exactly one character that differs from |
Behavior:
Accepts the escape character only before the quote character or another escape character.
Run failure: the input field is missing or not a string, or the input does not start with the quote character.
Run failure: the closing quote is missing, an escape character precedes another character, or text is left after the closing quote.
Expects a WCS field of type
textas the target.Build failure: more than three arguments, a
quote_charoresc_charthat is not one character, or the same character for both.Build failure: a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_quoted($_input)
Input event:
{
"_input": "\"Hello, my name is 'Wazuh'.\""
}
Output event:
{
"_input": "\"Hello, my name is 'Wazuh'.\"",
"_target_field": "Hello, my name is 'Wazuh'."
}
parse_uri
Parses a URI and stores its parts as string fields of a URL object in the target field.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
An absolute URI with a scheme, such as |
Behavior:
Writes the parts that the URI has:
original,scheme,domain,port,path,query,fragment,username, andpassword.Stores every part as a string. The
originalpart is the normalized URI, sohttp://someurl.combecomeshttp://someurl.com/.Run failure: the input field is missing or not a string, or the URI does not parse. A URI without a scheme, such as
www.someurl.com, fails.Expects a WCS field of type
objectas the target.Build failure: more than one argument, a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_uri($_input)
Input event:
{
"_input": "http://someurl.com"
}
Output event:
{
"_input": "http://someurl.com",
"_target_field": {
"original": "http://someurl.com/",
"scheme": "http",
"domain": "someurl.com",
"path": "/"
}
}
parse_useragent
Stores a user agent string, without changes, in the original field of the target object. The helper does not split the string into browser or operating system fields.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A user agent string. |
Behavior:
Writes
<TARGET_FIELD>.originaland keeps the other fields of the target object.Run failure: the input field is missing or not a string.
Expects a WCS field of type
objectas the target.Build failure: more than one argument, a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_useragent($_input)
Input event:
{
"_input": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110"
}
Output event:
{
"_input": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110",
"_target_field": {
"original": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110"
}
}
parse_xml
Parses an XML string into an object that replaces the target value. The optional windows module reshapes Windows Event Log XML.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A well-formed XML string, nested 256 levels deep at most. |
|
String |
Value (optional) |
|
Behavior:
Default mapping: Each element becomes a key, element text goes in
#text, and each attribute goes in@<ATTRIBUTE_NAME>. Repeated sibling elements become an array.The
windowsmodule: Each<Data Name="X">element becomes the keyXwith the element text as its value. A<Data>element withoutNameadds its text to an array.Run failure: the input field is missing or not a string.
Run failure: the XML is not valid, or it is nested more than 256 levels deep.
Expects a WCS field of type
objectas the target.Build failure: more than two arguments, or a module name other than
windowsordefault.Build failure: a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: parse_xml($_input)
Input event:
{
"_input": "<greeting>some greeting</greeting>"
}
Output event:
{
"_input": "<greeting>some greeting</greeting>",
"_target_field": {"greeting": {"#text": "some greeting"}}
}
sanitize_fields
Normalizes the keys of the target object, or the strings of the target array or string, to lowercase snake case.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
Boolean |
Value (optional) |
|
Behavior:
Normalization lowercases ASCII letters, turns spaces and
/,.,-,\, and:into one_, drops other symbols, and removes leading and trailing_.Object target: Renames the keys and does not change string values.
Array target: Normalizes each string item and the keys of each object item.
String target: Normalizes the string.
Applies no change when it fails.
Run failure: the target is missing or not an object, array, or string, or two keys normalize to the same key.
Run failure: a key or string normalizes to an empty value, or an array holds a number, boolean, or null.
Does not check the target type when it builds the asset (no build check).
Build failure: a reference or a non-boolean as the argument, or more than one argument.
Example:
normalize:
- map:
- _target_field: sanitize_fields(false)
Input event:
{
"_target_field": {"Full Name": "Ana", "e-mail": "x", "Pais": "AR"}
}
Output event:
{
"_target_field": {"full_name": "Ana", "e_mail": "x", "pais": "AR"}
}
split
Splits a string at a separator character and appends the parts to the target array. The helper keeps the spaces around each part.
Argument |
Type |
Source |
Accepted values |
|---|---|---|---|
|
String |
Reference |
A string field. A WCS reference must be a string field. |
|
String |
Value |
Exactly one character, such as |
Behavior:
Ignores a separator at the start of the string and drops an empty part at the end. Keeps empty parts between two separators.
Appends to an existing array, and replaces a target that is not an array.
Run failure: the input field is missing or not a string.
Expects a WCS string field as the target.
Build failure: a separator that is not exactly one character, or not exactly two arguments.
Build failure: a value as
input_field, or a WCS input reference to a non-string field.
Example:
normalize:
- map:
- _target_field: split($_input, '|')
Input event:
{
"_input": "val 1 | val 2 | val 3"
}
Output event:
{
"_input": "val 1 | val 2 | val 3",
"_target_field": ["val 1 ", " val 2 ", " val 3"]
}