Functions Reference

The following list describes the built-in functions that ship with Graylog.

Function	Category	Description	Syntax
abbreviate	String	Abbreviates a string using ellipses. The width defines the maximum length of the resulting string.	`abbreviate(value: string, width: long)`
abusech_ransom_lookup_domain	String	Matches a domain name against the abuse.ch Ransomware Domain Blocklist `RW_DOMBL`.	`abusech_ransom_lookup_domain(domain_name) : GenericLookupResult`
abusech_ransom_lookup_ip	String	Matches a IPv4 or IPv6 address against the abuse.ch Ransomware Domain Blocklist `RW_DOMBL`.	`abusech_ransom_lookup_ip(ip_address) : GenericLookupResult`
add_asset_categories	Asset Enrichment	Adds a list of categories to an asset.	`add_asset_categories(asset_name: string, categories: list)`
anonymize_ip	Anonymization	Anonymizes an IP address by setting the last octet to `0`.	`anonymize_ip(ip) : IpAddress`
array_contains	Message Handling	Checks if the specified element is contained in the array. See example	`array_contains (elements, value, [case-sensitive]): boolean`
array_remove	Message Handling	Removes the specified element from the array. See example	`array_remove (elements, value, [remove_all]) : list`
base16_decode	String	Provides base16 decoding of the string that returns lower-case letters. It requires regular hexadecimals, 0-9 A-F.	`base16_decode (value, [omit_padding: boolean])`
base16_encode	String	Provides standard case-insensitive hexadecimal encoding using a 16-character subset. It requires regular hexadecimals, 0-9 A-F.	`base16_encode (value, [omit_padding: boolean])`
base32_decode	String	Decodes a string using a 32-character subset. Uses the "numerical" base 32 and is extended from the traditional hexadecimal alphabet, 0-9 A-V.	`base32_decode (value, [omit_padding: boolean])`
base32_encode	String	Encodes a string using a 32-character subset. Uses the "numerical" base 32 and is extended from the traditional hexadecimal alphabet, 0-9 A-V.	`base32_encode (value, [omit_padding: boolean])`
base32human_decode	String	Decodes a string in human-readable format using a 32-character subset. It is a "readable" base 32, so there is no possibility of confusing 0/O or 1/I, A-Z 2-7.	`base32human_decode (value, [omit_padding: boolean])`
base32human_encode	String	Encodes a string in human-readable format using a 32-character subset. It is a "readable" base 32, so there is no possibility of confusing 0/O or 1/I, A-Z 2-7.	`base32human_encode (value, [omit_padding: boolean])`
base64_decode	String	Decodes a string using a 64-character subset. Regular base64 allows both upper and lowercase letters. It does not need to be human readable.	`base64_decode (value, [omit_padding: boolean])`
base64_encode	String	Decodes a string using a 64-character subset. Regular base64 allows both upper and lowercase letters. It does not need to be human readable.	`base64_encode (value, [omit_padding: boolean])`
base64url_decode	String	Provides URL-safe decoding of a string using a 64-character subset. It is safe to use as file names or to pass in URLs without escaping.	`base64url_decode (value, [omit_padding: boolean])`
base64url_encode	String	Provides URL-safe encoding of the string using a 64-character subset. It is safe to use as file names or to pass in URLs without escaping.	`base64url_encode (value, [omit_padding: boolean])`
capitalize	String	Capitalizes a string, changing the first letter to title case.	`capitalize(value: string)`
cidr_match	Boolean/Message Function	Checks whether the given IP address object matches the cidr pattern. See also: to_ip	`cidr_match(cidr: string, ip: IpAddress)`
clone_message	Message Handling	Clones a message. If `message` is omitted, this function uses the currently processed message.	`clone_message([message: Message])`
concat	String	Returns a new string combining the text of `first` and `second`. The `concat` function only concatenates two strings. If you want to build a string from more than two sub-strings, you must use `concat` multiple times. See example	`concat(first: string, second: string)`
contains	String	Checks if a string contains another string. It ignores the case. See example	`contains(value: string, search: string, [ignore_case: boolean])`
crc32	String Function/Encoding	Returns the hex-encoded CRC32 digest of the given string.	`crc32(value: string)`
crc32c	String Function/Encoding	Returns the hex-encoded CRC32C (RFC 3720, Section 12.1) digest of the given string.	`crc32c(value: string)`
create_message	Message Handling	Creates a new message from the given parameters. If any of these parameters is omitted, their value is taken from the corresponding fields of the currently processed message. If `timestamp` is omitted, the timestamp of the created message will be the timestamp at that moment in time.	`create_message([message: string], [source: string], [timestamp: DateTime])`
csv_to_map	Conversion	Converts a single line of a CSV string into a map usable by `set_fields`. See also: set_fields	`csv_to_map(value, fieldNames, [separator], [quoteChar], [escapeChar], [strictQuotes], [trimLeadingWhitespace], [ignoreExtraFieldNames])`
days	Date/Time	Creates a time period with `value` number of days. See also: is_period, period	`days(value: long)`
debug	Debug	Prints the passed value as a string in the Graylog log. Note that the debug message will only appear in the log of the Graylog node processing the message you are trying to debug. See example	`debug(value: any)`
drop_message	Message Handling	Removes the given `message` after the rule is finished executing. This does not prevent later stages of the same pipeline from being applied to the message. If `message` is omitted, this function uses the currently processed message. This can be used to implement flexible blacklisting based on various conditions. See example	`drop_message(message: Message)`
ends_with	String	Checks if `value` ends with `suffix`, optionally ignoring the case of the string. See example	`ends_with(value: string, suffix: string, [ignore_case: boolean])`
expand_syslog_priority	Conversion	Converts a syslog priority number to its level and facility.	`expand_syslog_priority(value: any)`
expand_syslog_priority_as_string	Conversion	Converts the syslog priority number in value to its severity and facility string representations.	`expand_syslog_priority_as_string(value: any)`
first_non_null	List	Returns first element found in the specified list that is not `null`. Returns null for an empty list.	`first_non_null (value: list)`
flatten_json	String	Parses the `value` string as a JSON tree while flattening all containers to a single level. Parsing of JSON arrays is determined by the `array_handler` parameter value. Available options for `array_handler` are: `ignore`: Ignores all top-level arrays. `json`: Returns top-level arrays as valid JSON strings. `flatten`: Explodes all arrays and objects into top-level key/values.	`flatten_json(value, array_handler) : JsonNode`
flex_parse_date	Date/Time	Uses the Natty date parser to parse a date and time `value`. If no timezone is detected in the pattern, the optional `timezone` parameter is used as the assumed timezone. If omitted the timezone defaults to `UTC`. In case the parser fails to detect a valid date and time, the default date and time is being returned; otherwise, the expression fails to evaluate and will be aborted. See also: is_date	`flex_parse_date(value: string, [default: DateTime], [timezone: string])`
format_date	Date/Time	Returns the given date and time `value` formatted according to the `format` string. If no timezone is given, it defaults to `UTC`.	`format_date(value: DateTime, format: string, [timezone: string])`
from_forwarder_input	Message Handling	Checks whether the currently processed message was received on the given forwarder input. The input can be looked up by either specifying its `name` (the comparison ignores the case) or the `id`.	`from_forwarder_input(id: string \| name: string)`
from_input	Message Handling	Checks whether the currently processed message was received on the given (non-forwarder) input. The input can be looked up by either specifying its `name` (the comparison ignores the case) or the `id`.	`from_input(id: string \| name: string)`
get_field	Message Handling	Retrieves the `value` for a field.	`get_field(field, [message]) : Object`
grok	Pattern Matching	Applies the grok pattern `grok` to `value`. Returns a match object, containing a map of field names and values. You can set `only_named_captures` to `true` to return only matches using named captures. The result of executing the `grok` function can be passed as argument for `set_fields` to set the extracted fields into a message. See also: set_fields	`grok(pattern: string, value: string, [only_named_captures: boolean])`
grok_exists	Boolean	Checks if the given Grok pattern exists. `log_missing` determines whether a log message is generated when no matching pattern is found.	`grok_exists (pattern:string, [log_missing:boolean])`
has_field	Boolean/Message Function	Checks whether the given `message` contains a field with the name `field`. If `message` is omitted, this function uses the currently processed message.	`has_field(field: string, [message: Message])`
hours	Date/Time	Creates a time period with `value` number of hours.	`hours(value: long)`
in_private_net	Message Handling	Checks if an IP address is in a private network as defined in RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) or RFC 4193 (fc00::/7).	`in_private_net(ip_address) : Boolean`
is_bool	Boolean	Checks whether the given `value` is a Boolean value (`true` or `false`).	`is_bool(value: any)`
is_collection	Boolean	Checks whether the given `value` is an iterable collection.	`is_collection(value: any)`
is_date	Boolean	Checks whether the given `value` is a date (of type `DateTime`). See also: now, parse_date, flex_parse_date, parse_unix_milliseconds	`is_date(value: any)`
is_double	Boolean	Checks whether the given `value` is a floating point value (of type `double`). See also: to_double	`is_double(value: any)`
is_ip	Boolean	Checks whether the given `value` is an IP address (IPv4 or IPv6). See also: to_ip	`is_ip(value: any)`
is_json	Boolean	Checks whether the given `value` is a parsed JSON tree. See also: parse_json	`is_json(value: any)`
is_list	Boolean	Checks whether a `value` is an iterable list.	`is_list(value: any)`
is_long	Boolean	Checks whether a `value` is an integer value (of type `long`). See also: to_long	`is_long(value: any)`
is_map	Boolean	Checks whether the given `value` is a map. See also: to_map	`is_map(value: any)`
is_not_null	Boolean	Checks whether a `value` is not `null`. See example	`is_not_null(value: any)`
is_null	Boolean	Checks whether a `value` is `null`. See example	`is_null(value: any)`
is_number	Boolean	Checks whether the given `value` is a numeric value (of type `long` or `double`). See also: is_double, to_double, is_long, to_long	`is_number(value: any)`
is_period	Boolean	Checks whether the given `value` is a time period (of type `period`). See also: years, months, weeks, days, hours, minutes, seconds, millis, period	`is_period(value: any)`
is_string	Boolean	Checks whether a `value` is a string. See also: to_string	`is_string(value: any)`
is_url	Boolean	Checks whether the given `value` is a parsed URL. See also: to_url	`is_url(value: any)`
join	String	Joins the specified range of elements of the provided array into a single string. Start index defaults to `0`, and end index defaults to the last element index of the list. If specified, the elements are separated by the delimiter in the resulting string.	`join (elements: list, [delimiter:string], [start:long], [end:long])`
key_value	Boolean	Extracts key-value pairs from the given `value` and returns them as a map of field names and values. You can optionally specify: `delimiters`: Characters used to separate pairs. We will use each character in the string, so you do not need to separate them. Default value: `<[whitespace]>`. `kv_delimiters`: Characters used to separate keys from values. Again, there is no need to separate each character. Default value: `=`. `ignore_empty_values`: Ignores keys containing empty values. Default value: `true`. `allow_dup_keys`: Indicates if duplicated keys are allowed. Default value: `true`. `handle_dup_keys`: How to handle duplicated keys (if `allow_dup_keysis` is set). It can take the values `take_first`, which will only use the first value for the key, or `take_last`, which will only use the last value for the key. Setting this option to any other value will change the handling to concatenate, which will combine all values given to the key, separating them with the value set in this option. For example, setting `handle_dup_keys: ","` would combine all values given to a key `a`, separating them with a comma, such as `1,2,foo`. Default value: `take_first`. `trim_key_chars`: Characters to trim (remove from the beginning and end) from keys. Default value: `no trim`. `trim_value_chars`: Characters to trim (remove from the beginning and end) from values. Default value: `no trim`. Also note the result of executing the `key_value` function can be passed as argument for `set_fields` to set the extracted fields into a message. See also: set_fields	`key_value ( value : string , [ delimiters : string ], [ kv_delimiters : string ], [ ignore_empty_values : boolean ], [ allow_dup_keys : boolean ], [ handle_dup_keys : string ], [ trim_key_chars : string ], [ trim_value_chars : string ] )`
length	String	Counts the characters in a string. If bytes=true, it counts the number of bytes instead (assumes UTF-8 encoding).	`length (value:string, [bytes: boolean])`
list_count	List	Gets number of elements in list.	`list_count(list:list) : Long`
list_get	List	Gets a value from a list.	`list_get(list:list, index:long) : Object`
lookup	Lookup	Looks up a multi value in the named lookup table. See example	`lookup(lookup_table: string, key: any, [default: any])`
lookup_add_string_list	Lookup	Adds a string list in the named lookup table and returns the updated list on success or returns `null` on failure. This function only supports the MongoDB Lookup Table at the time of writing.	`lookup_add_string_list(lookup_table, key, value,[keep_duplicates])`
lookup_all	Lookup	Looks up all provided values in the named lookup table and returns all results as an array. See example	`lookup_all(lookup_table, keys) : list`
lookup_assign_ttl	Lookup	Add a time to live to the key in the named lookup table. Returns the updated entry on success and `null` on failure.	`lookup_assign_ttl(lookup_table, key, ttl) : Object`
lookup_clear_key	Lookup	Clears (removes) a key in the named lookup table. This function only supports the MongoDB Lookup Table at the time of writing.	`lookup_clear_key(lookup_table, key)`
lookup_has_value	Lookup	Determines whether a given `key` is present in a lookup table. Will return `true` if the key is present and `false` if the key is not present.	`lookup_has_value (lookup_table, key)`
lookup_remove_string_list	Lookup	Removes the entries of the given string list from the named lookup table. Returns the updated list on success and returns `null` on failure.This function only supports the MongoDB Lookup Table at the time of writing.	`lookup_remove_string_list(lookup_table, key, value)`
lookup_set_string_list	Lookup	Sets a string list in the named lookup table. Returns the new value on success and returns `null` on failure.This function only supports the MongoDB Lookup Table at the time of writing.	`lookup_set_string_list(lookup_table:string, key:string, value:list)`
lookup_set_value	Lookup	Sets a single value in the named lookup table. Returns the new value on success and returns `null` on failure.This function only supports the MongoDB Lookup Table at the time of writing.	`lookup_set_value(lookup_table, key, value)`
lookup_string_list	Lookup	Looks up a string list value in the named lookup table.This function only supports the MongoDB Lookup Table at the time of writing.	`lookup_string_list(lookup_table, key, [default])`
lookup_string_list_contains	Boolean	Looks up `value` in the string list referenced by the key in the named lookup table. Returns `true` only if the key/value mapping is present, otherwise it returns `false`.	`lookup_string_list_contains (lookup_table, key, value)`
lookup_value	Lookup	Looks up a single `value` in the named lookup table. See example	`lookup_value(lookup_table: string, key: any, [default: any])`
lowercase	String	Converts a `String` to lower case. The locale (IETF BCP 47 language tag) defaults to `en`.	`lowercase(value: string, [locale: string])`
machine_asset_lookup	Asset Enrichment	Looks up a single machine asset. If multiple assets match the input parameters, only one will be returned.	`machine_asset_lookup(lookup_type, value) : Map`
machine_asset_update	Asset Enrichment	Updates the IP or MAC addresses for a machine asset. If multiple assets match the input parameters, only one will be selected.	`machine_asset_update(lookup_type, lookup_value, [ip_addresses], [hostnames]) : Void`
map_copy	Map	Retrieves a value from a map.	`map_copy(map) : Map`
map_get	Map	Copies a map to a new map.	`map_get(map, key) : Object`
map_remove	Map	Removes a key from the map.	`map_remove(map, key) : Map`
map_set	Map	Sets a key in the map.	`map_set(map, key, value) : Map`
md5	String	Creates the hex-encoded MD5 digest of the `value`.	`md5(value: string)`
metric_counter_inc	Debug	Counts specific metric criteria. The counter metric `name` will always be prefixed with `org.graylog.rulemetrics`. The default value is `1` if no increment value is specified.	`metric_counter_inc (name, [value]): Void`
millis	Date/Time	Creates a time period with a `value` number of milliseconds. See also: is_period, period	`millis(value: long)`
minutes	Date/Time	Creates a time period with `value` number of minutes. See also: is_period, period	`minutes(value: long)`
months	Date/Time	Creates a time period with `value` number of months. See also: is_period, period	`months(value: long)`
multi_grok		Applies a list of Grok patterns to a string and returns the first match. See example	`multi_grok(patterns, value, [only_named_captures]) : GrokMatch$GrokResult`
murmur3_128	Encoding	Creates the hex-encoded MurmurHash3 (128-bit) digest of the `value`.	`murmur3_128(value: string)`
murmur3_32	Encoding	Creates the hex-encoded MurmurHash3 (32-bit) digest of the `value`.	`murmur3_32(value: string)`
normalize_fields	Message Handling	Normalizes all field names by setting them to lowercase.	`normalize_fields([message]) : Void`
now	Date/Time	Returns the current `date` and `time`. Uses the default time zone `UTC`. See also: is_date	`now([timezone: string])`
otx_lookup_domain	String	Looks up AlienVault OTX threat intelligence data for a domain name. Requires a configured lookup table named `otx-api-domain`. See example	`otx_lookup_domain (domain_name: string) : OTXLookupResult`
otx_lookup_ip	String	Looks up AlienVault OTX threat intelligence data for an IPv4 or IPv6 address. Requires a configured lookup table named `otx-api-ip`. See example	`otx_lookup_ip (ip_address: string) : OTXLookupResult`
parse_cef	String	Parses any CEF-formatted string into its fields. This is the CEF string (starting with `CEF:`) without a syslog envelope.	`parse_cef(cef_string, use_full_names) : CEFParserResult`
parse_date	Date/Time	Parses a date string using the given date format.	`parse_date(value: string, pattern: string, [locale: string], [timezone: string])`
parse_json	String	Parses the `value` string as JSON, returning the resulting JSON tree. See also: to_map	`parse_json(value: string)`
parse_unix_milliseconds	Date/Time	Attempts to parse a UNIX millisecond timestamp (milliseconds since 1970-01-01T00:00:00.000Z) into a proper `DateTime` object. See also: is_date See example	`parse_unix_milliseconds(value: long)`
period	Date/Time	Parses an ISO 8601 time period from `value`. See also: is_period, years, months, weeks, days, hours, minutes, seconds, millis	`period(value: string)`
regex	Pattern Matching	Matches a string with a regular expression. Uses Java syntax.	`regex(pattern: string, value: string, [group_names: array[string])`
regex_replace	Pattern Matching	Matches the regular expression in pattern against value and replaces it, if matched, with `replacement`. You can use numbered capturing groups and reuse them in the replacement string. If `replace_all` is set to `true`, then all matches will be replaced; otherwise, only the first match will be replaced. See example	`regex_replace(pattern: string, value: string, replacement: string,[replace_all: boolean])`
remove_asset_categories	Asset Enrichment	Remove a list of categories from an asset.	`remove_asset_categories(asset_name, categories) : Void`
remove_field (legacy)	Message Handling	Removes the given field with the name `field` from the given `message`, unless the field is reserved. If `message` is omitted, this function uses the currently processed message. See instead: remove_single_field, remove_multiple_fields	`remove_field(field: string, [message: Message])`
remove_from_stream	Message Handling	Removes the `message` from the given stream. The stream can be looked up by either specifying its `name` or the `id`. If `message` is omitted, this function uses the currently processed message. If the message ends up being on no stream, it is implicitly routed back to the default stream “All messages.” This ensures that the message is not lost due to complex stream routing rules. If you want to discard the message entirely, use the `drop_message` function. With `remove_from_stream`, the message continues to be processed in following stages. To abort processing, use `drop_message`, or structure the stage conditions so that the following stages are not executed after `remove_from_stream` has been called.	`remove_from_stream(id: string \| name: string, [message: Message])`
remove_multiple_fields	Message Handling	Removes fields matching a regular expression (regex) pattern and/or list of names, unless the field name is reserved.	`remove_multiple_fields ([pattern: string],[names: list],[message: Message])`
remove_single_field	Message Handling	Removes a single field from a message, unless the field name is reserved.	`remove_single_field (field: string, [message: Message])`
rename_field	Message Handling	Modifies the field name `old_field` to `new_field` in the given message, keeping the field value unchanged.	`rename_field(old_field: string, new_field: string, [message: Message])`
replace	String	Replaces the first `max` or all occurrences of a string within another string. `max` is `-1` per defaults, which means to replace all occurrences, use `1` only for the first one, `2` for the first two, and so on. See example	`replace(value: string, search: string, [replacement: string], [max: long])`
route_to_stream	Message Handling	Sets a stream assignment of the message to the given stream. Functions as 'copy' and does not remove the message from the current stream. If `message` is omitted, this function uses the currently processed message. This causes the message to be evaluated on the pipelines connected to that stream, unless the stream has already been processed for this message. If `remove_from_default` is `true`, the message is also removed from the default stream, “All messages”. `remove_from_default` will take effect after the current pipeline has finished resolving. This rule does not prevent later stages of the pipeline from being applied to the message. The stream can also be looked up by either specifying its `name` or the `id`. See example	`route_to_stream(id: string \| name: string, [message: Message], [remove_from_default: boolean])`
seconds	Date/Time	Create a time period with `value` number of seconds. See also: is_period, period	`seconds(value: long)`
select_jsonpath	Map	Evaluates the given `paths` against the json tree and returns the map of the resulting values. See also: is_json, parse_json	`select_jsonpath(json: JsonNode, paths: Map<string, string>)`
set_associated_assets	Asset Enrichment	Adds associated asset information.	`set_associated_assets([message]) : Void`
set_field	Message Handling	Sets the given `field` to the new value. The `field` name must be valid and specifically cannot include a period character. It is trimmed of leading and trailing whitespace. String values are trimmed of whitespace as well. The optional `prefix` and `suffix` parameters specify which prefix or suffix should be added to the inserted field name. The optional `clean_field` parameter replaces invalid field name characters with underscores. If `message` is omitted, this function uses the currently processed message. Use the `default` when no value is available (i.e. it is `null` or throws an exception). See also: set_fields	`set_field(field: string, value: any, [prefix: string], [suffix: string], [message: Message], [default: any, [clean_field: boolean])`
set_fields	Message Handling	Sets all of the given name-value pairs in `field` in the given message. This is a convenience function acting like `set_field`. It can be helpful for using the result of a function like `select_jsonpath` or `regex` in the currently processed message, especially when the key names are the result of a regular expression. The optional `prefix` and `suffix` parameters specify which prefix or suffix should be added to the inserted field names. The optional `clean_fields` parameter replaces invalid field name characters with underscores. If `message` is omitted, this function uses the currently processed message. See also: set_field, to_map, grok, key_value	`set_fields(fields: Map<string, any>, [prefix: string], [suffix: string], [message: Message], [clean_fields: boolean)`
sha1	Encoding	Creates the hex-encoded SHA1 digest of the `value`.	`sha1(value: string)`
sha256	Encoding	Creates the hex-encoded SHA256 digest of the `value`.	`sha256(value: string)`
sha512	Encoding	Creates the hex-encoded SHA512 digest of the `value`.	`sha512(value: string)`
spamhaus_lookup_ip	Lookup	Matches an IP address against the Spamhaus DROP and EDROP lists.	`spamhaus_lookup_ip(ip_address) : GenericLookupResult`
split	String	Splits a string around matches of this pattern. Uses Java syntax.	`split(pattern: string, value: string, [limit: int])`
starts_with	String	Checks if `value` starts with `prefix`, optionally ignoring the case of the string. See example	`starts_with(value: string, prefix: string, [ignore_case: boolean])`
string_array_add	String	Adds the specified string (or string array) `value` to the supplied string array. Casts the input array and value/value array to strings. See example	`string_array_add(elements, value, [only_unique]) : list`
string_entropy	String	Computes Shannon's entropy of the character distribution in the given string.	`string_entropy (value: string, [default: double])`
substring	String	Returns a substring of `value` starting at the `start` offset (zero based indices), optionally ending at the end offset. Both offsets can be negative, indicating positions relative to the end of `value`. See example	`substring(value: string, start: long, [end: long])`
swapcase	String	Swaps the case of a `String` changing upper and title case to lower case and lower case to upper case.	`swapcase(value: string)`
syslog_facility	Conversion	Converts the syslog facility number in `value` to its string representation.	`syslog_facility(value: any)`
syslog_level	Conversion	Converts the syslog severity number in `value` to its string representation.	`syslog_level(value: any)`
threat_intel_lookup_domain	Lookup	Matches a domain name against all enabled threat intel sources, except OTX.	`threat_intel_lookup_domain(domain_name, prefix) : GlobalLookupResult`
threat_intel_lookup_ip	Lookup	Matches an IP address against all enabled threat intel sources, except OTX.	`threat_intel_lookup_ip(ip_address, prefix) : GlobalLookupResult`
to_bool	Conversion	Converts the single parameter to a Boolean value using its string value.	`to_bool(value: any)`
to_date	Conversion	Converts `value` to a date. If no `timezone` is given, it defaults to `UTC`. See also: is_date	`to_date(value: any, [timezone: string])`
to_double	Conversion	Converts the first parameter to a double floating point value.	`to_double(value: any, [default: double])`
to_ip	Conversion	Converts the given `ip` string to an `IpAddress` object. See also: cidr_match	`to_ip(ip: string)`
to_long	Conversion	Converts the first parameter to a long integer value.	`to_long(value: any, [default: long])`
to_map	Conversion	Converts the given map-like value to a valid map. The `to_map` function currently only supports converting a parsed JSON tree into a map so that it can be used together with `set_fields`. See also: set_fields, parse_json See example	`to_map(value: any)`
to_string	Conversion	Converts the first parameter to its string representation.	`to_string(value: any, [default: string])`
to_url	Conversion	Converts the given `url` to a valid URL.	`to_url(url: any, [default: string])`
tor_lookup	Lookup	Matches an IP address against known Tor exit nodes to identify connections from the Tor network.	`tor_lookup(ip_address) : GenericLookupResult`
traffic_accounting_size	Message Handling	Calculates the size of the entire message, including all extra fields. This is also the value used to determine how much the message counts toward license usage. See example	`traffic_accounting_size [(message)]: long`
uncapitalize	String	Uncapitalizes a string, changing the first letter to lower case.	`uncapitalize(value: string)`
uppercase	String	Converts a string to upper case. The locale (IETF BCP 47 language tag) defaults to `en`.	`uppercase(value: string, [locale: string])`
urldecode	String	Decodes an application/x-www-form-urlencoded string using a specific encoding scheme.	`url decode (value:string, [charset:string])`
urlencode	String	Translates a string into application/x-www-form-urlencoded format using a specific encoding scheme. Valid charsets are, for example, `UTF-8`, `US-ASCII`, etc. Default is `UTF-8`.	`url encode (value, [charset])`
user_asset_lookup	Asset Enrichment	Looks up a single user asset. If multiple assets match the input parameters, only one will be returned.	`user_asset_lookup(lookup_type, value) : Map`
watchlist_add	Watchlist	Adds a value to a watchlist referenced by type. Returns `true` on success and `false` on failure and throws an exception if the watchlist is not configured correctly.	`watchlist_add(type, value) : Boolean`
watchlist_contains	Watchlist	Looks up a value in the watchlist referenced by the type. Returns `true` on success and `false` on failure and throws an exception if the watchlist is not configured correctly.	`watchlist_contains(type, value) : Boolean`
watchlist_remove	Watchlist	Removes a value from a watchlist referenced by type. Returns `true` on success and `false` on failure and throws an exception if the watchlist is not configured correctly.	`watchlist_remove(type, value) : Boolean`
weeks	Date/Time	Creates a time period with `value` number of weeks. See also: is_period, period	`weeks(value: long)`
whois_lookup_ip	Lookup	Retrieves WHOIS information for an IP address	`whois_lookup_ip(ip_address, prefix) : WhoisIpLookupResult`
years	Date/Time	Creates a time period with `value` number of years. See also: is_period, period	`years(value: long)`

Examples

Review the following examples for select functions referenced above.

array_contains

Copy

rule "array_contains"
when
    true
then
    set_field("contains_number", array_contains([1, 2, 3, 4, 5], 1));
    set_field("does_not_contain_number", array_contains([1, 2, 3, 4, 5], 7));
    set_field("contains_string", array_contains(["test", "test2"], "test"));
    set_field("contains_string_case_insensitive", array_contains(["test", "test2"], "TEST"));
    set_field("contains_string_case_sensitive", array_contains(["test", "test2"], "TEST", true));
end

array_remove

Copy

rule "array_remove"
when
    true
then
    set_field("remove_number", array_remove([1, 2, 3], 2));
    set_field("remove_string", array_remove(["one", "two", "three"], "two"));
    set_field("remove_missing", array_remove([1, 2, 3], 4));
    set_field("remove_only_one", array_remove([1, 2, 2], 2));
    set_field("remove_all", array_remove([1, 2, 2], 2, true));
end

concat

Copy

let build_message_0 = concat(to_string($message.protocol), " connect from ");
let build_message_1 = concat(build_message_0, to_string($message.src_ip));
let build_message_2 = concat(build_message_1, " to ");
let build_message_3 = concat(build_message_2, to_string($message.dst_ip));
let build_message_4 = concat(build_message_3, " Port ");
let build_message_5 = concat(build_message_4, to_string($message.dst_port));
set_field("message", build_message_5);

contains

Copy

contains(to_string($message.hostname), "example.org", true)

debug

Copy

Dropped message from <source>"let debug_message = concat("Dropped message from ", to_string($message.source));
debug(debug_message);`

drop_message

Copy

rule "drop messages over 16383 characters"
when    
    has_field("message") AND    
    regex(pattern: "^.{16383,}$", value: to_string($message.message)).matches == true
then   
    drop_message();    
    // added debug message to be notified about the dropped message    
    debug( concat("dropped oversized message from ", to_string($message.source)));
end

ends_with

Returns true:

Copy

ends_with (  "Foobar Baz Quux" , "quux" , true  );

Returns false:

Copy

ends_with (  "Foobar Baz Quux" , "Baz"  ); `

is_not_null

Copy

is_not_null(src_addr)

is_null

Copy

is_null(src_addr)

lookup

Copy

rule "dst_ip geoip lookup"
when 
    has_field("dst_ip")
then  
    let geo = lookup("geoip-lookup", to_string($message.dst_ip));
    set_field("dst_ip_geolocation", geo["coordinates"]); 
    set_field("dst_ip_geo_country_code", geo["country"].iso_code); 
    set_field("dst_ip_geo_country_name", geo["country"].names.en); 
    set_field("dst_ip_geo_city_name", geo["city"].names.en);
 end

lookup_all

Copy

rule "function lookup all"
when
    true
then
    let values = lookup_all("lut_name", ["key1", "key2", "key3"]);
    set_field("values", values); 
end

lookup_value

Copy

("ip_lookup", to_string($message.src_addr));

multi_grok

Copy

when
  true
then
  set_fields(
    fields: multi_grok(
        patterns: [
            "^ABC %{IPORHOST:msg_ip}: %{GREEDYDATA:abc_message}",
            "^123 %{IPORHOST:msg_ip}: %{GREEDYDATA:123_message}",
            "^ABC2 %{IPORHOST:abc_ip}: %{GREEDYDATA:abc_message}"
            ],
        value: to_string($message.message),
        only_named_captures: true
    )
  );
end

otx_lookup_domain

Copy

rule "PARSE IP to DNS"
when
    has_field("source_ip")
    && regex(
        pattern: "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",
        value: to_string($message.source_ip)
        ).matches == true
then
    let rs = lookup_value("dns_lookups", to_string($message.source_ip));
    set_field("source_ip_dns", to_string(rs));
end

otx_lookup_ip

Copy

rule "PARSE source_ip - otx-api-ip"
when
    // validate message has a source_ip field
    has_field("source_ip")
    // validate that soruce IP is IPv4 format
    && regex(
        pattern: "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",
        value: to_string($message.source_ip)
        ).matches == true
then
    let rs = otx_lookup_ip(to_string($message.source_ip));
    set_fields(rs);
end

parse_unix_milliseconds

Copy

set_field ( "timestamp" , timestamp );

regex_replace

Copy

let username = regex_replace(".*user: (.*)", to_string($message.message), "$1");

replace

Copy

let new_field = replace(to_string($message.message), "oo", "u");    // "fu ruft uta"
let new_field = replace(to_string($message.message), "oo", "u", 1); // "fu rooft oota"

route_to_stream

Copy

route_to_stream(id: "512bad1a535b43bd6f3f5e86");

starts_with

Returns true:

Copy

starts_with ( "Foobar Baz Quux" , "foo" , true );

Returns false:

Copy

starts_with ( "Foobar Baz Quux" , "Quux" );

string_array_add

Copy

rule "string_array_add"
when
    true
then
    set_field("add_number_to_string_array_converted", string_array_add(["1", "2"], 3));
    set_field("add_number_array_to_string_array_converted", string_array_add(["1", "2"], [3, 4]));
    set_field("add_string", string_array_add(["one", "two"], "three"));
    set_field("add_string_again", string_array_add(["one", "two"], "two"));
    set_field("add_string_again_unique", string_array_add(["one", "two"], "two", true));
    set_field("add_array_to_array", string_array_add(["one", "two"], ["three", "four"]));
end

substring

Copy

= substring(to_string($message.message), 0, 20);

to_map

Copy

let json = parse_json(to_string($message.json_payload));
let map = to_map(json);
set_fields(map);

traffic_accounting_size

Copy

set_field(
    field: "license_usage",
    value: traffic_accounting_size() // size in bytes
    //value: traffic_accounting_size() / 1024 // size in kb
    );