EQL function reference

Elasticsearch supports the following EQL functions.

Returns the sum of two provided addends.

Example

add(4, 5)                                          1
add(4, 0.5)                                        2
add(0.5, 0.25)                                     3
add(4, -2)                                         4
add(-2, -2)                                        5

// process.args_count = 4
add(process.args_count, 5)                         6
add(process.args_count, 0.5)                       7

// process.parent.args_count = 2
add(process.args_count, process.parent.args_count) 8

// null handling
add(null, 4)                                       9
add(4. null)                                       10
add(null, process.args_count)                      11
add(process.args_count null)                       12

1. returns 9
2. returns 4.5
3. returns 0.75
4. returns 2
5. returns -4
6. returns 9
7. returns 4.5
8. returns 6
9. returns null
10. returns null
11. returns null
12. returns null

Syntax

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

Extracts a substring that’s between a provided left and right text in a source string. Matching is case-sensitive by default.

Example

// file.path = "C:\\Windows\\System32\\cmd.exe"
between(file.path, "System32\\\\", ".exe")                // returns "cmd"
between(file.path, "system32\\\\", ".exe")                // returns ""
between(file.path, "workspace\\\\", ".exe")               // returns ""

// Make matching case-insensitive
between~(file.path, "system32\\\\", ".exe")               // returns "cmd"

// Greedy matching defaults to false.
between(file.path, "\\\\", "\\\\", false)                 // returns "Windows"

// Sets greedy matching to true
between(file.path, "\\\\", "\\\\", true)                  // returns "Windows\\System32"

// empty source string
between("", "System32\\\\", ".exe")                       // returns ""
between("", "", "")                                       // returns ""

// null handling
between(null, "System32\\\\", ".exe")                    1

1. returns null

Syntax

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

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:

• A type in the keyword family
• text field with a keyword sub-field

<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:

• A type in the keyword family
• text field with a keyword sub-field

<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:

• A type in the keyword family
• text field with a keyword sub-field

<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.

Returns: string or null

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

Example

// source.address = "192.168.152.12"
cidrMatch(source.address, "192.168.0.0/16")              1
cidrMatch(source.address, "192.168.0.0/16", "10.0.0.0/8")2
cidrMatch(source.address, "10.0.0.0/8")                  3
cidrMatch(source.address, "10.0.0.0/8", "10.128.0.0/9")  4

// null handling
cidrMatch(null, "10.0.0.0/8")                            5
cidrMatch(source.address, null)                          6

1. returns true
2. returns true
3. returns false
4. returns false
5. returns null
6. returns null

Syntax

`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†footnoteref:[multi-arg,This parameter accepts multiple arguments.], string or null) CIDR block you wish to search. If null, the function returns null.

Returns: boolean or null

Returns a concatenated string of provided values.

Example

concat("process is ", "regsvr32.exe")         // returns "process is regsvr32.exe"
concat("regsvr32.exe", " ", 42)               // returns "regsvr32.exe 42"
concat("regsvr32.exe", " ", 42.5)             // returns "regsvr32.exe 42.5"
concat("regsvr32.exe", " ", true)             // returns "regsvr32.exe true"
concat("regsvr32.exe")                        // returns "regsvr32.exe"

// process.name = "regsvr32.exe"
concat(process.name, " ", 42)                 // returns "regsvr32.exe 42"
concat(process.name, " ", 42.5)               // returns "regsvr32.exe 42.5"
concat("process is ", process.name)           // returns "process is regsvr32.exe"
concat(process.name, " ", true)               // returns "regsvr32.exe true"
concat(process.name)                          // returns "regsvr32.exe"

// process.arg_count = 4
concat(process.name, " ", process.arg_count)  // returns "regsvr32.exe 4"

// null handling
concat(null, "regsvr32.exe")                 1
concat(process.name, null)                   2
concat(null)                                 3

1. returns null
2. returns null
3. returns null

Syntax

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

Parameters

<value>

(Required†footnoteref:[multi-arg]) 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

Returns the quotient of a provided dividend and divisor.

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

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

Example

divide(4, 2)                                           1
divide(4, 3)                                           2
divide(4, 3.0)                                         3
divide(4, 0.5)                                         4
divide(0.5, 4)                                         5
divide(0.5, 0.25)                                      6
divide(4, -2)                                          7
divide(-4, -2)                                         8

// process.args_count = 4
divide(process.args_count, 2)                          9
divide(process.args_count, 3)                          10
divide(process.args_count, 3.0)                        11
divide(12, process.args_count)                         12
divide(process.args_count, 0.5)                        13
divide(0.5, process.args_count)                        14

// process.parent.args_count = 2
divide(process.args_count, process.parent.args_count)  15

// null handling
divide(null, 4)                                        16
divide(4, null)                                        17
divide(null, process.args_count)                       18
divide(process.args_count, null)                       19

1. returns 2
2. returns 1
3. returns 1.333...
4. returns 8
5. returns 0.125
6. returns 2.0
7. returns -2
8. returns 2
9. returns 2
10. returns 1
11. returns 1.333...
12. returns 3
13. returns 8
14. returns 0.125
15. returns 2
16. returns null
17. returns null
18. returns null
19. returns null

Syntax

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

Returns true if a source string ends with a provided substring. Matching is case-sensitive by default.

Example

endsWith("regsvr32.exe", ".exe")         1
endsWith("regsvr32.exe", ".EXE")         2
endsWith("regsvr32.exe", ".dll")         3
endsWith("", "")                         4

// Make matching case-insensitive
endsWith~("regsvr32.exe", ".EXE")        5

// file.name = "regsvr32.exe"
endsWith(file.name, ".exe")              6
endsWith(file.name, ".dll")              7

// file.extension = ".exe"
endsWith("regsvr32.exe", file.extension) 8
endsWith("ntdll.dll", file.name)         9

// null handling
endsWith("regsvr32.exe", null)           10
endsWith("", null)                       11
endsWith(null, ".exe")                   12
endsWith(null, null)                     13

1. returns true
2. returns false
3. returns false
4. returns true
5. returns true
6. returns true
7. returns false
8. returns true
9. returns false
10. returns null
11. returns null
12. returns null
13. returns null

Syntax

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:

• 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:

• A type in the keyword family
• text field with a keyword sub-field

Returns: boolean or null

Returns the first position of a provided substring in a source string. Matching is case-sensitive by default.

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

Example

// url.domain = "subdomain.example.com"
indexOf(url.domain, "d")       1
indexOf(url.domain, "D")       2
indexOf(url.domain, ".")       3
indexOf(url.domain, ".", 9)    4
indexOf(url.domain, ".", 10)   5
indexOf(url.domain, ".", -6)   6

// Make matching case-insensitive
indexOf~(url.domain, "D")       7

// empty strings
indexOf("", "")                8
indexOf(url.domain, "")        9
indexOf(url.domain, "", 9)     10
indexOf(url.domain, "", 10)    11
indexOf(url.domain, "", -6)    12

// missing substrings
indexOf(url.domain, "z")       13
indexOf(url.domain, "z", 9)    14

// start position is higher than string length
indexOf(url.domain, ".", 30)   15

// null handling
indexOf(null, ".", 9)          16
indexOf(url.domain, null, 9)   17
indexOf(url.domain, ".", null) 18

1. returns 3
2. returns null
3. returns 9
4. returns 9
5. returns 17
6. returns 9
7. returns 4
8. returns 0
9. returns 0
10. returns 9
11. returns 10
12. returns 0
13. returns null
14. returns null
15. returns null
16. returns null
17. returns null
18. returns null

Syntax

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:

• A type in the keyword family
• text field with a keyword sub-field

<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:

• A type in the keyword family
• text field with a keyword sub-field

<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

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

Example

length("explorer.exe")        1
length("start explorer.exe")  2
length("")                    3
length(null)                  4

// process.name = "regsvr32.exe"
length(process.name)          5

1. returns 12
2. returns 18
3. returns 0
4. returns null
5. returns 12

Syntax

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:

• A type in the keyword family
• text field with a keyword sub-field

Returns: integer or null

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

Example

modulo(10, 6)                                      1
modulo(10, 5)                                      2
modulo(10, 0.5)                                    3
modulo(10, -6)                                     4
modulo(-10, -6)                                    5

// process.args_count = 10
modulo(process.args_count, 6)                      6
modulo(process.args_count, 5)                      7
modulo(106, process.args_count)                    8
modulo(process.args_count, -6)                     9
modulo(process.args_count, 0.5)                    10

// process.parent.args_count = 6
modulo(process.args_count, process.parent.args_count) 11

// null handling
modulo(null, 5)                                    12
modulo(7, null)                                    13
modulo(null, process.args_count)                   14
modulo(process.args_count, null)                   15

1. returns 4
2. returns 0
3. returns 0
4. returns 4
5. returns -4
6. returns 4
7. returns 0
8. returns 6
9. returns 4
10. returns 0
11. returns 4
12. returns null
13. returns null
14. returns null
15. returns null

Syntax

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

Returns the product of two provided factors.

Example

multiply(2, 2)                                          1
multiply(0.5, 2)                                        2
multiply(0.25, 2)                                       3
multiply(-2, 2)                                         4
multiply(-2, -2)                                        5

// process.args_count = 2
multiply(process.args_count, 2)                         6
multiply(0.5, process.args_count)                       7
multiply(0.25, process.args_count)                      8

// process.parent.args_count = 3
multiply(process.args_count, process.parent.args_count) 9

// null handling
multiply(null, 2)                                       10
multiply(2, null)                                       11

1. returns 4
2. returns 1
3. returns 0.5
4. returns -4
5. returns 4
6. returns 4
7. returns 1
8. returns 0.5
9. returns 6
10. returns null
11. returns null

Syntax

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

Converts a string to the corresponding integer or float.

Example

number("1337")             1
number("42.5")             2
number("deadbeef", 16)     3

// integer literals beginning with "0x" are auto-detected as hexadecimal
number("0xdeadbeef")       4
number("0xdeadbeef", 16)   5

// "+" and "-" are supported
number("+1337")            6
number("-1337")            7

// surrounding whitespace is ignored
number("  1337  ")         8

// process.pid = "1337"
number(process.pid)        9

// null handling
number(null)               10
number(null, 16)           11

// strings beginning with "0x" are treated as hexadecimal (base 16),
// even if the <base_num> is explicitly null.
number("0xdeadbeef", null)12

// otherwise, strings are treated as decimal (base 10)
// if the <base_num> is explicitly null.
number("1337", null)       13

1. returns 1337
2. returns 42.5
3. returns 3735928559
4. returns 3735928559
5. returns 3735928559
6. returns 1337
7. returns -1337
8. returns 1337
9. returns 1337
10. returns null
11. returns null
12. returns 3735928559
13. returns 1337

Syntax

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:

• A type in the keyword family
• text field with a keyword sub-field

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

Returns true if a source string begins with a provided substring. Matching is case-sensitive by default.

Example

startsWith("regsvr32.exe", "regsvr32") 1
startsWith("regsvr32.exe", "Regsvr32") 2
startsWith("regsvr32.exe", "explorer") 3
startsWith("", "")                     4

// Make matching case-insensitive
startsWith~("regsvr32.exe", "Regsvr32") 5

// process.name = "regsvr32.exe"
startsWith(process.name, "regsvr32")   6
startsWith(process.name, "explorer")   7

// process.name = "regsvr32"
startsWith("regsvr32.exe", process.name)8
startsWith("explorer.exe", process.name)9

// null handling
startsWith("regsvr32.exe", null)       10
startsWith("", null)                   11
startsWith(null, "regsvr32")           12
startsWith(null, null)                 13

1. returns true
2. returns false
3. returns false
4. returns true
5. returns true
6. returns true
7. returns false
8. returns true
9. returns false
10. returns null
11. returns null
12. returns null
13. returns null

Syntax

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:

• 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:

• A type in the keyword family
• text field with a keyword sub-field

Returns: boolean or null

Converts a value to a string.

Example

string(42)               // returns "42"
string(42.5)             // returns "42.5"
string("regsvr32.exe")   // returns "regsvr32.exe"
string(true)             // returns "true"

// null handling
string(null)            1

1. returns null

Syntax

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

Returns true if a source string contains a provided substring. Matching is case-sensitive by default.

Example

// process.command_line = "start regsvr32.exe"
stringContains(process.command_line, "regsvr32") 1
stringContains(process.command_line, "Regsvr32") 2
stringContains(process.command_line, "start ")   3
stringContains(process.command_line, "explorer") 4

// Make matching case-insensitive
stringContains~(process.command_line, "Regsvr32") 5

// process.name = "regsvr32.exe"
stringContains(command_line, process.name)       6

// empty strings
stringContains("", "")                           7
stringContains(process.command_line, "")         8

// null handling
stringContains(null, "regsvr32")                 9
stringContains(process.command_line, null)       10

1. returns true
2. returns false
3. returns true
4. returns false
5. returns false
6. returns true
7. returns false
8. returns false
9. returns null
10. returns null

Syntax

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:

• A type in the keyword family
• text field with a keyword sub-field

Returns: boolean or null

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

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

Syntax

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

Returns the difference between a provided minuend and subtrahend.

Example

subtract(10, 2)                                         1
subtract(10.5, 0.5)                                     2
subtract(1, 0.2)                                        3
subtract(-2, 4)                                         4
subtract(-2, -4)                                        5

// process.args_count = 10
subtract(process.args_count, 6)                         6
subtract(process.args_count, 5)                         7
subtract(15, process.args_count)                        8
subtract(process.args_count, 0.5)                       9

// process.parent.args_count = 6
subtract(process.args_count, process.parent.args_count) 10

// null handling
subtract(null, 2)                                       11
subtract(2, null)                                       12

1. returns 8
2. returns 10
3. returns 0.8
4. returns -8
5. returns 8
6. returns 4
7. returns 5
8. returns 5
9. returns 9.5
10. returns 4
11. returns null
12. returns null

Syntax

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