EQL function reference

This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.

Elasticsearch supports the following EQL functions.

add

Returns the sum of two provided addends.

Example

  1. add(4, 5)                                           // returns 9
  2. add(4, 0.5)                                         // returns 4.5
  3. add(0.5, 0.25)                                      // returns 0.75
  4. add(4, -2)                                          // returns 2
  5. add(-2, -2)                                         // returns -4
  7. // process.args_count = 4
  8. add(process.args_count, 5)                          // returns 9
  9. add(process.args_count, 0.5)                        // returns 4.5
  11. // process.parent.args_count = 2
  12. add(process.args_count, process.parent.args_count)  // returns 6
  14. // null handling
  15. add(null, 4)                                        // returns null
  16. add(4. null)                                        // returns null
  17. add(null, process.args_count)                       // returns null
  18. add(process.args_count null)                        // returns null

Syntax

  1. add(<addend>, <addend>)

Parameters:

<addend>

(Required, integer or float or null) Addend to add. If null, the function returns null.

Two addends are required. No more than two addends can be provided.

If using a field as the argument, this parameter supports only numeric field data types.

Returns: integer, float, or null

between

Extracts a substring that’s between a provided left and right text in a source string.

Example

  1. // file.path = "C:\\Windows\\System32\\cmd.exe"
  2. between(file.path, "system32\\\\", ".exe")                // returns "cmd"
  3. between(file.path, "workspace\\\\", ".exe")               // returns ""
  5. // Greedy matching defaults to false.
  6. between(file.path, "\\\\", "\\\\", false)                 // returns "Windows"
  8. // Sets greedy matching to true
  9. between(file.path, "\\\\", "\\\\", true)                  // returns "Windows\\System32"
  11. // Case sensitivity defaults to false.
  12. between(file.path, "system32\\\\", ".exe", false, false)  // returns "cmd"
  13. // Sets case sensitivity to true
  14. between(file.path, "system32\\\\", ".exe", false, true)   // returns ""
  15. between(file.path, "System32\\\\", ".exe", false, true)   // returns "cmd"
  17. // empty source string
  18. between("", "system32\\\\", ".exe")                       // returns ""
  19. between("", "", "")                                       // returns ""
  21. // null handling
  22. between(null, "system32\\\\", ".exe")                     // returns null

Syntax

  1. between(<source>, <left>, <right>[, <greedy_matching>, <case_sensitive>])

Parameters

<source>

(Required, string or null) Source string. Empty strings return an empty string (""), regardless of the <left> or <right> parameters. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

<left>

(Required, string) Text to the left of the substring to extract. This text should include whitespace.

If using a field as the argument, this parameter supports only the following field data types:

<right>

(Required, string) Text to the right of the substring to extract. This text should include whitespace.

If using a field as the argument, this parameter supports only the following field data types:

<greedy_matching>

(Optional, boolean) If true, match the longest possible substring, similar to .* in regular expressions. If false, match the shortest possible substring, similar to .*? in regular expressions. Defaults to false.

<case_sensitive>

(Optional, boolean) If true, matching is case-sensitive. Defaults to false.

Returns: string or null

cidrMatch

Returns true if an IP address is contained in one or more provided CIDR blocks.

Example

  1. // source.address = "192.168.152.12"
  2. cidrMatch(source.address, "192.168.0.0/16")               // returns true
  3. cidrMatch(source.address, "192.168.0.0/16", "10.0.0.0/8") // returns true
  4. cidrMatch(source.address, "10.0.0.0/8")                   // returns false
  5. cidrMatch(source.address, "10.0.0.0/8", "10.128.0.0/9")   // returns false
  7. // null handling
  8. cidrMatch(null, "10.0.0.0/8")                             // returns null
  9. cidrMatch(source.address, null)                           // returns null

Syntax

  1. `cidrMatch(<ip_address>, <cidr_block>[, ...])`

Parameters

<ip_address>

(Required, string or null) IP address. Supports IPv4 and IPv6 addresses. If null, the function returns null.

If using a field as the argument, this parameter supports only the ip field data type.

<cidr_block>

(Required†[1], string or null) CIDR block you wish to search. If null, the function returns null.

Returns: boolean or null

concat

Returns a concatenated string of provided values.

Example

  1. concat("process is ", "regsvr32.exe")         // returns "process is regsvr32.exe"
  2. concat("regsvr32.exe", " ", 42)               // returns "regsvr32.exe 42"
  3. concat("regsvr32.exe", " ", 42.5)             // returns "regsvr32.exe 42.5"
  4. concat("regsvr32.exe", " ", true)             // returns "regsvr32.exe true"
  5. concat("regsvr32.exe")                        // returns "regsvr32.exe"
  7. // process.name = "regsvr32.exe"
  8. concat(process.name, " ", 42)                 // returns "regsvr32.exe 42"
  9. concat(process.name, " ", 42.5)               // returns "regsvr32.exe 42.5"
  10. concat("process is ", process.name)           // returns "process is regsvr32.exe"
  11. concat(process.name, " ", true)               // returns "regsvr32.exe true"
  12. concat(process.name)                          // returns "regsvr32.exe"
  14. // process.arg_count = 4
  15. concat(process.name, " ", process.arg_count)  // returns "regsvr32.exe 4"
  17. // null handling
  18. concat(null, "regsvr32.exe")                  // returns null
  19. concat(process.name, null)                    // returns null
  20. concat(null)                                  // returns null

Syntax

  1. concat(<value>[, <value>])

Parameters

<value>

(Required†[1]) Value to concatenate. If any of the arguments are null, the function returns null.

If using a field as the argument, this parameter does not support the text field data type.

Returns: string or null

divide

Returns the quotient of a provided dividend and divisor.

If both the dividend and divisor are integers, the divide function rounds down any returned floating point numbers to the nearest integer.

EQL queries in Elasticsearch should account for this rounding. To avoid rounding, convert either the dividend or divisor to a float.

Example

The process.args_count field is a long integer field containing a count of process arguments.

A user might expect the following EQL query to only match events with a process.args_count value of 4.

  1. process where divide(4, process.args_count) == 1

However, the EQL query matches events with a process.args_count value of 3 or 4.

For events with a process.args_count value of 3, the divide function returns a floating point number of 1.333..., which is rounded down to 1.

To match only events with a process.args_count value of 4, convert either the dividend or divisor to a float.

The following EQL query changes the integer 4 to the equivalent float 4.0.

  1. process where divide(4.0, process.args_count) == 1

Example

  1. divide(4, 2)                                            // returns 2
  2. divide(4, 3)                                            // returns 1
  3. divide(4, 3.0)                                          // returns 1.333...
  4. divide(4, 0.5)                                          // returns 8
  5. divide(0.5, 4)                                          // returns 0.125
  6. divide(0.5, 0.25)                                       // returns 2.0
  7. divide(4, -2)                                           // returns -2
  8. divide(-4, -2)                                          // returns 2
  10. // process.args_count = 4
  11. divide(process.args_count, 2)                           // returns 2
  12. divide(process.args_count, 3)                           // returns 1
  13. divide(process.args_count, 3.0)                         // returns 1.333...
  14. divide(12, process.args_count)                          // returns 3
  15. divide(process.args_count, 0.5)                         // returns 8
  16. divide(0.5, process.args_count)                         // returns 0.125
  18. // process.parent.args_count = 2
  19. divide(process.args_count, process.parent.args_count)   // returns 2
  21. // null handling
  22. divide(null, 4)                                         // returns null
  23. divide(4, null)                                         // returns null
  24. divide(null, process.args_count)                        // returns null
  25. divide(process.args_count, null)                        // returns null

Syntax

  1. divide(<dividend>, <divisor>)

Parameters

<dividend>

(Required, integer or float or null) Dividend to divide. If null, the function returns null.

If using a field as the argument, this parameter supports only numeric field data types.

<divisor>

(Required, integer or float or null) Divisor to divide by. If null, the function returns null. This value cannot be zero (0).

If using a field as the argument, this parameter supports only numeric field data types.

Returns: integer, float, or null

endsWith

Returns true if a source string ends with a provided substring.

Example

  1. endsWith("regsvr32.exe", ".exe")          // returns true
  2. endsWith("regsvr32.exe", ".dll")          // returns false
  3. endsWith("", "")                          // returns true
  5. // file.name = "regsvr32.exe"
  6. endsWith(file.name, ".exe")               // returns true
  7. endsWith(file.name, ".dll")               // returns false
  9. // file.extension = ".exe"
  10. endsWith("regsvr32.exe", file.extension)  // returns true
  11. endsWith("ntdll.dll", file.name)          // returns false
  13. // null handling
  14. endsWith("regsvr32.exe", null)            // returns null
  15. endsWith("", null)                        // returns null
  16. endsWith(null, ".exe")                    // returns null
  17. endsWith(null, null)                      // returns null

Syntax

  1. endsWith(<source>, <substring>)

Parameters

<source>

(Required, string or null) Source string. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

<substring>

(Required, string or null) Substring to search for. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

Returns: boolean or null

indexOf

Returns the first position of a provided substring in a source string.

If an optional start position is provided, this function returns the first occurrence of the substring at or after the start position.

Example

  1. // url.domain = "subdomain.example.com"
  2. indexOf(url.domain, ".")        // returns 9
  3. indexOf(url.domain, ".", 9)     // returns 9
  4. indexOf(url.domain, ".", 10)    // returns 17
  5. indexOf(url.domain, ".", -6)    // returns 9
  7. // empty strings
  8. indexOf("", "")                 // returns 0
  9. indexOf(url.domain, "")         // returns 0
  10. indexOf(url.domain, "", 9)      // returns 9
  11. indexOf(url.domain, "", 10)     // returns 10
  12. indexOf(url.domain, "", -6)     // returns 0
  14. // missing substrings
  15. indexOf(url.domain, "z")        // returns null
  16. indexOf(url.domain, "z", 9)     // returns null
  18. // start position is higher than string length
  19. indexOf(url.domain, ".", 30)    // returns null
  21. // null handling
  22. indexOf(null, ".", 9)           // returns null
  23. indexOf(url.domain, null, 9)    // returns null
  24. indexOf(url.domain, ".", null)  // returns null

Syntax

  1. indexOf(<source>, <substring>[, <start_pos>])

Parameters

<source>

(Required, string or null) Source string. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

<substring>

(Required, string or null) Substring to search for.

If this argument is null or the <source> string does not contain this substring, the function returns null.

If the <start_pos> is positive, empty strings ("") return the <start_pos>. Otherwise, empty strings return 0.

If using a field as the argument, this parameter supports only the following field data types:

<start_pos>

(Optional, integer or null) Starting position for matching. The function will not return positions before this one. Defaults to 0.

Positions are zero-indexed. Negative offsets are treated as 0.

If this argument is null or higher than the length of the <source> string, the function returns null.

If using a field as the argument, this parameter supports only the following numeric field data types:

  • long
  • integer
  • short
  • byte

Returns: integer or null

length

Returns the character length of a provided string, including whitespace and punctuation.

Example

  1. length("explorer.exe")         // returns 12
  2. length("start explorer.exe")   // returns 18
  3. length("")                     // returns 0
  4. length(null)                   // returns null
  6. // process.name = "regsvr32.exe"
  7. length(process.name)           // returns 12

Syntax

  1. length(<string>)

Parameters

<string>

(Required, string or null) String for which to return the character length. If null, the function returns null. Empty strings return 0.

If using a field as the argument, this parameter supports only the following field data types:

Returns: integer or null

match

Returns true if a source string matches one or more provided regular expressions.

Example

  1. match("explorer.exe", "[a-z]*?.exe")           // returns true
  2. match("explorer.exe", "[a-z]*?.exe", "[1-9]")  // returns true
  3. match("explorer.exe", "[1-9]")                 // returns false
  4. match("explorer.exe", "")                      // returns false
  6. // process.name = "explorer.exe"
  7. match(process.name, "[a-z]*?.exe")             // returns true
  8. match(process.name, "[a-z]*?.exe", "[1-9]")    // returns true
  9. match(process.name, "[1-9]")                   // returns false
  10. match(process.name, "")                        // returns false
  12. // null handling
  13. match(null, "[a-z]*?.exe")                     // returns null

Syntax

  1. match(<source>, <reg_exp>[, ...])

Parameters

<source>

(Required, string or null) Source string. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

<reg_exp>

(Required†[1], string) Regular expression used to match the source string. For supported syntax, see Regular expression syntax. Predefined character classes are not supported.

Fields are not supported as arguments.

Returns: boolean or null

modulo

Returns the remainder of the division of a provided dividend and divisor.

Example

  1. modulo(10, 6)                                       // returns 4
  2. modulo(10, 5)                                       // returns 0
  3. modulo(10, 0.5)                                     // returns 0
  4. modulo(10, -6)                                      // returns 4
  5. modulo(-10, -6)                                     // returns -4
  7. // process.args_count = 10
  8. modulo(process.args_count, 6)                       // returns 4
  9. modulo(process.args_count, 5)                       // returns 0
  10. modulo(106, process.args_count)                     // returns 6
  11. modulo(process.args_count, -6)                      // returns 4
  12. modulo(process.args_count, 0.5)                     // returns 0
  14. // process.parent.args_count = 6
  15. add(process.args_count, process.parent.args_count)  // returns 4
  17. // null handling
  18. modulo(null, 5)                                     // returns null
  19. modulo(7, null)                                     // returns null
  20. modulo(null, process.args_count)                    // returns null
  21. modulo(process.args_count, null)                    // returns null

Syntax

  1. modulo(<dividend>, <divisor>)

Parameters

<dividend>

(Required, integer or float or null) Dividend to divide. If null, the function returns null. Floating point numbers return 0.

If using a field as the argument, this parameter supports only numeric field data types.

<divisor>

(Required, integer or float or null) Divisor to divide by. If null, the function returns null. Floating point numbers return 0. This value cannot be zero (0).

If using a field as the argument, this parameter supports only numeric field data types.

Returns: integer, float, or null

multiply

Returns the product of two provided factors.

Example

  1. multiply(2, 2)                                           // returns 4
  2. multiply(0.5, 2)                                         // returns 1
  3. multiply(0.25, 2)                                        // returns 0.5
  4. multiply(-2, 2)                                          // returns -4
  5. multiply(-2, -2)                                         // returns 4
  7. // process.args_count = 2
  8. multiply(process.args_count, 2)                          // returns 4
  9. multiply(0.5, process.args_count)                        // returns 1
  10. multiply(0.25, process.args_count)                       // returns 0.5
  12. // process.parent.args_count = 3
  13. multiply(process.args_count, process.parent.args_count)  // returns 6
  15. // null handling
  16. multiply(null, 2)                                        // returns null
  17. multiply(2, null)                                        // returns null

Syntax

  1. multiply(<factor, <factor>)

Parameters

<factor>

(Required, integer or float or null) Factor to multiply. If null, the function returns null.

Two factors are required. No more than two factors can be provided.

If using a field as the argument, this parameter supports only numeric field data types.

Returns: integer, float, or null

number

Converts a string to the corresponding integer or float.

Example

  1. number("1337")              // returns 1337
  2. number("42.5")              // returns 42.5
  3. number("deadbeef", 16)      // returns 3735928559
  5. // integer literals beginning with "0x" are auto-detected as hexadecimal
  6. number("0xdeadbeef")        // returns 3735928559
  7. number("0xdeadbeef", 16)    // returns 3735928559
  9. // "+" and "-" are supported
  10. number("+1337")             // returns 1337
  11. number("-1337")             // returns -1337
  13. // surrounding whitespace is ignored
  14. number("  1337  ")          // returns 1337
  16. // process.pid = "1337"
  17. number(process.pid)         // returns 1337
  19. // null handling
  20. number(null)                // returns null
  21. number(null, 16)            // returns null
  23. // strings beginning with "0x" are treated as hexadecimal (base 16),
  24. // even if the <base_num> is explicitly null.
  25. number("0xdeadbeef", null) // returns 3735928559
  27. // otherwise, strings are treated as decimal (base 10)
  28. // if the <base_num> is explicitly null.
  29. number("1337", null)        // returns 1337

Syntax

  1. number(<string>[, <base_num>])

Parameters

<string>

(Required, string or null) String to convert to an integer or float. If this value is a string, it must be one of the following:

  • A string representation of an integer (e.g., "42")
  • A string representation of a float (e.g., "9.5")
  • If the <base_num> parameter is specified, a string containing an integer literal in the base notation (e.g., "0xDECAFBAD" in hexadecimal or base 16)

Strings that begin with 0x are auto-detected as hexadecimal and use a default <base_num> of 16.

- and + are supported with no space between. Surrounding whitespace is ignored. Empty strings ("") are not supported.

If using a field as the argument, this parameter supports only the following field data types:

If this argument is null, the function returns null.

<base_num>

(Optional, integer or null) Radix or base used to convert the string. If the <string> begins with 0x, this parameter defaults to 16 (hexadecimal). Otherwise, it defaults to base 10.

If this argument is explicitly null, the default value is used.

Fields are not supported as arguments.

Returns: integer or float or null

startsWith

Returns true if a source string begins with a provided substring.

Example

  1. startsWith("regsvr32.exe", "regsvr32")  // returns true
  2. startsWith("regsvr32.exe", "explorer")  // returns false
  3. startsWith("", "")                      // returns true
  5. // process.name = "regsvr32.exe"
  6. startsWith(process.name, "regsvr32")    // returns true
  7. startsWith(process.name, "explorer")    // returns false
  9. // process.name = "regsvr32"
  10. startsWith("regsvr32.exe", process.name) // returns true
  11. startsWith("explorer.exe", process.name) // returns false
  13. // null handling
  14. startsWith("regsvr32.exe", null)        // returns null
  15. startsWith("", null)                    // returns null
  16. startsWith(null, "regsvr32")            // returns null
  17. startsWith(null, null)                  // returns null

Syntax

  1. startsWith(<source>, <substring>)

Parameters

<source>

(Required, string or null) Source string. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

<substring>

(Required, string or null) Substring to search for. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

Returns: boolean or null

string

Converts a value to a string.

Example

  1. string(42)               // returns "42"
  2. string(42.5)             // returns "42.5"
  3. string("regsvr32.exe")   // returns "regsvr32.exe"
  4. string(true)             // returns "true"
  6. // null handling
  7. string(null)             // returns null

Syntax

  1. string(<value>)

Parameters

<value>

(Required) Value to convert to a string. If null, the function returns null.

If using a field as the argument, this parameter does not support the text field data type.

Returns: string or null

stringContains

Returns true if a source string contains a provided substring.

Example

  1. // process.command_line = "start regsvr32.exe"
  2. stringContains(process.command_line, "regsvr32")  // returns true
  3. stringContains(process.command_line, "start ")    // returns true
  4. stringContains(process.command_line, "explorer")  // returns false
  6. // process.name = "regsvr32.exe"
  7. stringContains(command_line, process.name)        // returns true
  9. // empty strings
  10. stringContains("", "")                            // returns false
  11. stringContains(process.command_line, "")          // returns false
  13. // null handling
  14. stringContains(null, "regsvr32")                  // returns null
  15. stringContains(process.command_line, null)        // returns null

Syntax

  1. stringContains(<source>, <substring>)

Parameters

<source>

(Required, string or null) Source string to search. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

  • A type in the keyword family

  • text field with a keyword sub-field

    <substring>

    (Required, string or null) Substring to search for. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

Returns: boolean or null

substring

Extracts a substring from a source string at provided start and end positions.

If no end position is provided, the function extracts the remaining string.

Example

  1. substring("start regsvr32.exe", 6)        // returns "regsvr32.exe"
  2. substring("start regsvr32.exe", 0, 5)     // returns "start"
  3. substring("start regsvr32.exe", 6, 14)    // returns "regsvr32"
  4. substring("start regsvr32.exe", -4)       // returns ".exe"
  5. substring("start regsvr32.exe", -4, -1)   // returns ".ex"

Syntax

  1. substring(<source>, <start_pos>[, <end_pos>])

Parameters

<source>

(Required, string) Source string.

<start_pos>

(Required, integer) Starting position for extraction.

If this position is higher than the <end_pos> position or the length of the <source> string, the function returns an empty string.

Positions are zero-indexed. Negative offsets are supported.

<end_pos>

(Optional, integer) Exclusive end position for extraction. If this position is not provided, the function returns the remaining string.

Positions are zero-indexed. Negative offsets are supported.

Returns: string

subtract

Returns the difference between a provided minuend and subtrahend.

Example

  1. subtract(10, 2)                                          // returns 8
  2. subtract(10.5, 0.5)                                      // returns 10
  3. subtract(1, 0.2)                                         // returns 0.8
  4. subtract(-2, 4)                                          // returns -8
  5. subtract(-2, -4)                                         // returns 8
  7. // process.args_count = 10
  8. subtract(process.args_count, 6)                          // returns 4
  9. subtract(process.args_count, 5)                          // returns 5
  10. subtract(15, process.args_count)                         // returns 5
  11. subtract(process.args_count, 0.5)                        // returns 9.5
  13. // process.parent.args_count = 6
  14. subtract(process.args_count, process.parent.args_count)  // returns 4
  16. // null handling
  17. subtract(null, 2)                                        // returns null
  18. subtract(2, null)                                        // returns null

Syntax

  1. subtract(<minuend>, <subtrahend>)

Parameters

<minuend>

(Required, integer or float or null) Minuend to subtract from.

If using a field as the argument, this parameter supports only numeric field data types.

<subtrahend>

(Optional, integer or float or null) Subtrahend to subtract. If null, the function returns null.

If using a field as the argument, this parameter supports only numeric field data types.

Returns: integer, float, or null

wildcard

Returns true if a source string matches one or more provided wildcard expressions.

Example

  1. // The two following expressions are equivalent.
  2. process.name == "*regsvr32*" or process.name == "*explorer*"
  3. wildcard(process.name, "*regsvr32*", "*explorer*")
  5. // process.name = "regsvr32.exe"
  6. wildcard(process.name, "*regsvr32*")                // returns true
  7. wildcard(process.name, "*regsvr32*", "*explorer*")  // returns true
  8. wildcard(process.name, "*explorer*")                // returns false
  9. wildcard(process.name, "*explorer*", "*scrobj*")    // returns false
  11. // empty strings
  12. wildcard("", "*start*")                             // returns false
  13. wildcard("", "*")                                   // returns true
  14. wildcard("", "")                                    // returns true
  16. // null handling
  17. wildcard(null, "*regsvr32*")                        // returns null
  18. wildcard(process.name, null)                        // returns null

Syntax

  1. wildcard(<source>, <wildcard_exp>[, ...])

Parameters

<source>

(Required, string) Source string. If null, the function returns null.

If using a field as the argument, this parameter supports only the following field data types:

<wildcard_exp>

(Required†[1], string) Wildcard expression used to match the source string. If null, the function returns null. Fields are not supported as arguments.

Returns: boolean

[1] This parameter accepts multiple arguments.