716 lines
18 KiB
Plaintext
716 lines
18 KiB
Plaintext
[[eql-function-ref]]
|
|
== EQL function reference
|
|
++++
|
|
<titleabbrev>Function reference</titleabbrev>
|
|
++++
|
|
|
|
experimental::[]
|
|
|
|
{es} supports the following EQL functions:
|
|
|
|
* <<eql-fn-between>>
|
|
* <<eql-fn-cidrmatch>>
|
|
* <<eql-fn-endswith>>
|
|
* <<eql-fn-indexof>>
|
|
* <<eql-fn-length>>
|
|
* <<eql-fn-startswith>>
|
|
* <<eql-fn-string>>
|
|
* <<eql-fn-stringcontains>>
|
|
* <<eql-fn-substring>>
|
|
* <<eql-fn-wildcard>>
|
|
|
|
[discrete]
|
|
[[eql-fn-between]]
|
|
=== `between`
|
|
|
|
Extracts a substring that's between a provided `left` and `right` text in a
|
|
source string.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
// file.path = "C:\\Windows\\System32\\cmd.exe"
|
|
between(file.path, "system32\\\\", ".exe") // returns "cmd"
|
|
between(file.path, "workspace\\\\", ".exe") // returns ""
|
|
|
|
|
|
// Greedy matching defaults to false.
|
|
between(file.path, "\\\\", "\\\\", false) // returns "Windows"
|
|
// Sets greedy matching to true
|
|
between(file.path, "\\\\", "\\\\", true) // returns "Windows\\System32"
|
|
|
|
// Case sensitivity defaults to false.
|
|
between(file.path, "system32\\\\", ".exe", false, false) // returns "cmd"
|
|
// Sets case sensitivity to true
|
|
between(file.path, "system32\\\\", ".exe", false, true) // returns ""
|
|
between(file.path, "System32\\\\", ".exe", false, true) // returns "cmd"
|
|
|
|
// empty source string
|
|
between("", "system32\\\\", ".exe") // returns ""
|
|
between("", "", "") // returns ""
|
|
|
|
// null handling
|
|
between(null, "system32\\\\", ".exe") // returns null
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
|
|
Fields containing <<array,array values>> use the first array item only.
|
|
--
|
|
|
|
`<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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
|
|
<<array,Array values>> are not supported.
|
|
--
|
|
|
|
`<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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
|
|
<<array,Array values>> are not supported.
|
|
--
|
|
|
|
`<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`
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-cidrmatch]]
|
|
==== `cidrMatch`
|
|
|
|
Returns `true` if an IP address is contained in one or more provided
|
|
https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing[CIDR] blocks.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
|
|
[source,eql]
|
|
----
|
|
// source.address = "192.168.152.12"
|
|
cidrMatch(source.address, "192.168.0.0/16") // returns true
|
|
cidrMatch(source.address, "192.168.0.0/16", "10.0.0.0/8") // returns true
|
|
cidrMatch(source.address, "10.0.0.0/8") // returns false
|
|
cidrMatch(source.address, "10.0.0.0/8", "10.128.0.0/9") // returns false
|
|
|
|
// null handling
|
|
cidrMatch(null, "10.0.0.0/8") // returns null
|
|
cidrMatch(source.address, null) // returns null
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
`cidrMatch(<ip_address>, <cidr_block>[, ...])`
|
|
----
|
|
|
|
*Parameters*
|
|
|
|
`<ip_address>`::
|
|
(Required, string or `null`)
|
|
IP address. Supports
|
|
https://en.wikipedia.org/wiki/IPv4[IPv4] and
|
|
https://en.wikipedia.org/wiki/IPv6[IPv6] addresses. If `null`, the function
|
|
returns `null`.
|
|
+
|
|
If using a field as the argument, this parameter supports only the <<ip,`ip`>>
|
|
field datatype.
|
|
|
|
`<cidr_block>`::
|
|
(Required{multi-arg}, string or `null`)
|
|
CIDR block you wish to search. If `null`, the function returns `null`.
|
|
|
|
*Returns:* boolean or `null`
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-endswith]]
|
|
=== `endsWith`
|
|
|
|
Returns `true` if a source string ends with a provided substring. Matching is
|
|
case insensitive.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
endsWith("regsvr32.exe", ".exe") // returns true
|
|
endsWith("regsvr32.exe", ".EXE") // returns true
|
|
endsWith("regsvr32.exe", ".dll") // returns false
|
|
endsWith("", "") // returns true
|
|
|
|
// file.name = "regsvr32.exe"
|
|
endsWith(file.name, ".exe") // returns true
|
|
endsWith(file.name, ".dll") // returns false
|
|
|
|
// file.extension = ".exe"
|
|
endsWith("regsvr32.exe", file.extension) // returns true
|
|
endsWith("ntdll.dll", file.name) // returns false
|
|
|
|
// file.name = [ "ntdll.dll", "regsvr32.exe" ]
|
|
endsWith(file.name, ".dll") // returns true
|
|
endsWith(file.name, ".exe") // returns false
|
|
|
|
// null handling
|
|
endsWith("regsvr32.exe", null) // returns null
|
|
endsWith("", null) // returns null
|
|
endsWith(null, ".exe") // returns null
|
|
endsWith(null, null) // returns null
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
|
|
Fields containing <<array,array values>> use the first array item only.
|
|
--
|
|
|
|
`<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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
--
|
|
|
|
*Returns:* boolean or `null`
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-indexof]]
|
|
=== `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.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
// url.domain = "subdomain.example.com"
|
|
indexOf(url.domain, ".") // returns 9
|
|
indexOf(url.domain, ".", 9) // returns 9
|
|
indexOf(url.domain, ".", 10) // returns 17
|
|
indexOf(url.domain, ".", -6) // returns 9
|
|
|
|
// empty strings
|
|
indexOf("", "") // returns 0
|
|
indexOf(url.domain, "") // returns 0
|
|
indexOf(url.domain, "", 9) // returns 9
|
|
indexOf(url.domain, "", 10) // returns 10
|
|
indexOf(url.domain, "", -6) // returns 0
|
|
|
|
// missing substrings
|
|
indexOf(url.domain, "z") // returns null
|
|
indexOf(url.domain, "z", 9) // returns null
|
|
|
|
// start position is higher than string length
|
|
indexOf(url.domain, ".", 30) // returns null
|
|
|
|
// null handling
|
|
indexOf(null, ".", 9) // returns null
|
|
indexOf(url.domain, null, 9) // returns null
|
|
indexOf(url.domain, ".", null) // returns null
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_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
|
|
<<number,numeric>> field datatypes:
|
|
|
|
* `long`
|
|
* `integer`
|
|
* `short`
|
|
* `byte`
|
|
--
|
|
|
|
*Returns:* integer or `null`
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-length]]
|
|
=== `length`
|
|
|
|
Returns the character length of a provided string, including whitespace and
|
|
punctuation.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
length("explorer.exe") // returns 12
|
|
length("start explorer.exe") // returns 18
|
|
length("") // returns 0
|
|
length(null) // returns null
|
|
|
|
// process.name = "regsvr32.exe"
|
|
length(process.name) // returns 12
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
|
|
<<array,Array values>> are not supported.
|
|
--
|
|
|
|
*Returns:* integer or `null`
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-startswith]]
|
|
=== `startsWith`
|
|
|
|
Returns `true` if a source string begins with a provided substring. Matching is
|
|
case insensitive.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
startsWith("regsvr32.exe", "regsvr32") // returns true
|
|
startsWith("regsvr32.exe", "RegSvr32") // returns true
|
|
startsWith("regsvr32.exe", "explorer") // returns false
|
|
startsWith("", "") // returns true
|
|
|
|
// process.name = "regsvr32.exe"
|
|
startsWith(process.name, "regsvr32") // returns true
|
|
startsWith(process.name, "explorer") // returns false
|
|
|
|
// process.name = "regsvr32"
|
|
startsWith("regsvr32.exe", process.name) // returns true
|
|
startsWith("explorer.exe", process.name) // returns false
|
|
|
|
// process.name = [ "explorer.exe", "regsvr32.exe" ]
|
|
startsWith(process.name, "explorer") // returns true
|
|
startsWith(process.name, "regsvr32") // returns false
|
|
|
|
// null handling
|
|
startsWith("regsvr32.exe", null) // returns null
|
|
startsWith("", null) // returns null
|
|
startsWith(null, "regsvr32") // returns null
|
|
startsWith(null, null) // returns null
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
|
|
Fields containing <<array,array values>> use the first array item only.
|
|
--
|
|
|
|
`<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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
--
|
|
|
|
*Returns:* boolean or `null`
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-string]]
|
|
=== `string`
|
|
|
|
Converts a value to a string.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
string(42) // returns "42"
|
|
string(42.5) // returns "42.5"
|
|
string("regsvr32.exe") // returns "regsvr32.exe"
|
|
string(true) // returns "true"
|
|
|
|
// null handling
|
|
string(null) // returns null
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
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,`text`>> field datatype.
|
|
|
|
*Returns:* string or `null`
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-stringcontains]]
|
|
=== `stringContains`
|
|
|
|
Returns `true` if a source string contains a provided substring.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
// process.command_line = "start regsvr32.exe"
|
|
stringContains(process.command_line, "regsvr32") // returns true
|
|
stringContains(process.command_line, "start ") // returns true
|
|
stringContains(process.command_line, "explorer") // returns false
|
|
|
|
// process.name = "regsvr32.exe"
|
|
stringContains(command_line, process.name) // returns true
|
|
|
|
// empty strings
|
|
stringContains("", "") // returns false
|
|
stringContains(process.command_line, "") // returns false
|
|
|
|
// null handling
|
|
stringContains(null, "regsvr32") // returns null
|
|
stringContains(process.command_line, null) // returns null
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
|
|
*Returns:* boolean or `null`
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-substring]]
|
|
=== `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.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
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*
|
|
[source,txt]
|
|
----
|
|
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
|
|
====
|
|
|
|
[discrete]
|
|
[[eql-fn-wildcard]]
|
|
=== `wildcard`
|
|
Returns `true` if a source string matches one or more provided wildcard
|
|
expressions.
|
|
|
|
[%collapsible]
|
|
====
|
|
*Example*
|
|
[source,eql]
|
|
----
|
|
// The two following expressions are equivalent.
|
|
process.name == "*regsvr32*" or process.name == "*explorer*"
|
|
wildcard(process.name, "*regsvr32*", "*explorer*")
|
|
|
|
// process.name = "regsvr32.exe"
|
|
wildcard(process.name, "*regsvr32*") // returns true
|
|
wildcard(process.name, "*regsvr32*", "*explorer*") // returns true
|
|
wildcard(process.name, "*explorer*") // returns false
|
|
wildcard(process.name, "*explorer*", "*scrobj*") // returns false
|
|
|
|
// empty strings
|
|
wildcard("", "*start*") // returns false
|
|
wildcard("", "*") // returns true
|
|
wildcard("", "") // returns true
|
|
|
|
// null handling
|
|
wildcard(null, "*regsvr32*") // returns null
|
|
wildcard(process.name, null) // returns null
|
|
----
|
|
|
|
*Syntax*
|
|
[source,txt]
|
|
----
|
|
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 datatypes:
|
|
|
|
* <<keyword,`keyword`>>
|
|
* <<constant-keyword,`constant_keyword`>>
|
|
* <<text,`text`>> field with a <<keyword,`keyword`>> or
|
|
<<constant-keyword,`constant_keyword`>> sub-field
|
|
--
|
|
|
|
`<wildcard_exp>`::
|
|
+
|
|
--
|
|
(Required{multi-arg}, string)
|
|
Wildcard expression used to match the source string. If `null`, the function
|
|
returns `null`. Fields are not supported as arguments.
|
|
--
|
|
|
|
*Returns:* boolean
|
|
==== |