From ce7a01e03145d55c358ee857041e68e87afc5b8e Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 6 Apr 2020 10:40:59 -0400 Subject: [PATCH 1/7] [DOCS] EQL: Document `wildcard` function --- docs/reference/eql/functions.asciidoc | 79 +++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc index 33f9d2cab353b..271bb4acf7b82 100644 --- a/docs/reference/eql/functions.asciidoc +++ b/docs/reference/eql/functions.asciidoc @@ -12,6 +12,7 @@ experimental::[] * <> * <> * <> +* <> [discrete] [[eql-fn-endswith]] @@ -276,4 +277,82 @@ 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. Matching is case sensitive. + +[%collapsible] +==== +*Example* +[source,eql] +---- +// The following expressions are equivalent. +process.command_line == "*start*" or process.command_line == "*config*" +wildcard(process.command_line, "*start*", "*config*") + +// process.command_line = "start explorer.exe" +wildcard(process.command_line, "*start*") // returns true +wildcard(process.command_line, "*start*", "*config*") // returns true +wildcard(process.command_line, "*config*") // returns false +wildcard(process.command_line, "*config*", "*create*") // returns false + +// process.command_line = [ "start explorer.exe", "create regsvr32.exe" ] +wildcard(process.command_line, "*create*") // returns true +wildcard(process.command_line, "*create*", "*config*") // returns true +wildcard(process.command_line, "*start*") // returns false +wildcard(process.command_line, "*start*", "*create*") // returns true +wildcard(process.command_line, "*start*", "*config*") // returns false + +// case sensitivity +wildcard("start explorer.exe", "*start*") // returns true +wildcard("start explorer.exe", "*Start*") // returns false + +// null handling +wildcard(null, "*start*") // returns false +wildcard(null, null) // returns 500 error +wildcard("start explorer.exe", null) // returns 500 error +wildcard("start explorer.exe", null, "*start*") // returns 500 error +wildcard("", null) // returns 500 error +wildcard("", "") // returns true +---- + +*Syntax* + +[source,txt] +---- +wildcard(, [, ...]) +---- + +*Parameters* + +``:: ++ +-- +(Required, string) +Source string. + +If using a field as the argument, this parameter only supports the following +field datatypes: + +* <> +* <> +* <> field with a <> or + <> sub-field + +Fields containing <> use the last array item only. +-- + +``:: ++ +-- +(Required{multi-arg}, string) +Wildcard expression used to match the source string. Fields are not supported as +arguments. If `null`, the function returns a 500 error. +-- + +*Returns:* boolean ==== \ No newline at end of file From d9116060341f8c736ca03ce5ed6eee96837e85a1 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 6 Apr 2020 11:35:07 -0400 Subject: [PATCH 2/7] clarifications --- docs/reference/eql/functions.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc index 271bb4acf7b82..f06302fc65796 100644 --- a/docs/reference/eql/functions.asciidoc +++ b/docs/reference/eql/functions.asciidoc @@ -290,7 +290,7 @@ expressions. Matching is case sensitive. *Example* [source,eql] ---- -// The following expressions are equivalent. +// The two following expressions are equivalent. process.command_line == "*start*" or process.command_line == "*config*" wildcard(process.command_line, "*start*", "*config*") @@ -307,7 +307,7 @@ wildcard(process.command_line, "*start*") // returns false wildcard(process.command_line, "*start*", "*create*") // returns true wildcard(process.command_line, "*start*", "*config*") // returns false -// case sensitivity +// case sensitive matching wildcard("start explorer.exe", "*start*") // returns true wildcard("start explorer.exe", "*Start*") // returns false From 9b1e6e077d7e20e180d2b3de988eae9d7d789dbb Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 8 Apr 2020 10:06:02 -0400 Subject: [PATCH 3/7] update null and empty string examples --- docs/reference/eql/functions.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc index f06302fc65796..1eae0b818c23a 100644 --- a/docs/reference/eql/functions.asciidoc +++ b/docs/reference/eql/functions.asciidoc @@ -311,13 +311,13 @@ wildcard(process.command_line, "*start*", "*config*") // returns false wildcard("start explorer.exe", "*start*") // returns true wildcard("start explorer.exe", "*Start*") // returns false +// empty strings +wildcard("", "*start*") // returns false +wildcard("", "*") // returns true +wildcard("", "") // returns true + // null handling wildcard(null, "*start*") // returns false -wildcard(null, null) // returns 500 error -wildcard("start explorer.exe", null) // returns 500 error -wildcard("start explorer.exe", null, "*start*") // returns 500 error -wildcard("", null) // returns 500 error -wildcard("", "") // returns true ---- *Syntax* @@ -351,7 +351,7 @@ Fields containing <> use the last array item only. -- (Required{multi-arg}, string) Wildcard expression used to match the source string. Fields are not supported as -arguments. If `null`, the function returns a 500 error. +arguments. -- *Returns:* boolean From 184bd532f3775d8a480c8094eb72c985c202c4d7 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 8 Apr 2020 13:12:55 -0400 Subject: [PATCH 4/7] Remove case sensitive references matching per ##54411. --- docs/reference/eql/functions.asciidoc | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc index 1eae0b818c23a..e5322d8e7ce1b 100644 --- a/docs/reference/eql/functions.asciidoc +++ b/docs/reference/eql/functions.asciidoc @@ -283,7 +283,7 @@ Positions are zero-indexed. Negative offsets are supported. [[eql-fn-wildcard]] === `wildcard` Returns `true` if a source string matches one or more provided wildcard -expressions. Matching is case sensitive. +expressions. [%collapsible] ==== @@ -307,10 +307,6 @@ wildcard(process.command_line, "*start*") // returns false wildcard(process.command_line, "*start*", "*create*") // returns true wildcard(process.command_line, "*start*", "*config*") // returns false -// case sensitive matching -wildcard("start explorer.exe", "*start*") // returns true -wildcard("start explorer.exe", "*Start*") // returns false - // empty strings wildcard("", "*start*") // returns false wildcard("", "*") // returns true From 628906f0dd5f15d76a515d9f7a893e29acf48e08 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 8 Apr 2020 13:19:26 -0400 Subject: [PATCH 5/7] Simplify examples --- docs/reference/eql/functions.asciidoc | 36 +++++++++++++-------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc index e5322d8e7ce1b..c57cefbc3b030 100644 --- a/docs/reference/eql/functions.asciidoc +++ b/docs/reference/eql/functions.asciidoc @@ -291,29 +291,27 @@ expressions. [source,eql] ---- // The two following expressions are equivalent. -process.command_line == "*start*" or process.command_line == "*config*" -wildcard(process.command_line, "*start*", "*config*") - -// process.command_line = "start explorer.exe" -wildcard(process.command_line, "*start*") // returns true -wildcard(process.command_line, "*start*", "*config*") // returns true -wildcard(process.command_line, "*config*") // returns false -wildcard(process.command_line, "*config*", "*create*") // returns false - -// process.command_line = [ "start explorer.exe", "create regsvr32.exe" ] -wildcard(process.command_line, "*create*") // returns true -wildcard(process.command_line, "*create*", "*config*") // returns true -wildcard(process.command_line, "*start*") // returns false -wildcard(process.command_line, "*start*", "*create*") // returns true -wildcard(process.command_line, "*start*", "*config*") // returns false +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 + +// process.name = [ "explorer.exe", "regsvr32.exe" ] +wildcard(process.name, "*regsvr32*") // returns true +wildcard(process.name, "*regsvr32*", "*scrobj*") // returns true +wildcard(process.name, "*scrobj*") // returns false // empty strings -wildcard("", "*start*") // returns false -wildcard("", "*") // returns true -wildcard("", "") // returns true +wildcard("", "*start*") // returns false +wildcard("", "*") // returns true +wildcard("", "") // returns true // null handling -wildcard(null, "*start*") // returns false +wildcard(null, "*regsvr32*") // returns false ---- *Syntax* From 1c2ae7a0394a966ea43376c1ff9ba9b5bf6fa78a Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 10 Apr 2020 08:40:22 -0400 Subject: [PATCH 6/7] updates for array and null values --- docs/reference/eql/functions.asciidoc | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc index c57cefbc3b030..d9776f303c5cf 100644 --- a/docs/reference/eql/functions.asciidoc +++ b/docs/reference/eql/functions.asciidoc @@ -300,18 +300,14 @@ wildcard(process.name, "*regsvr32*", "*explorer*") // returns true wildcard(process.name, "*explorer*") // returns false wildcard(process.name, "*explorer*", "*scrobj*") // returns false -// process.name = [ "explorer.exe", "regsvr32.exe" ] -wildcard(process.name, "*regsvr32*") // returns true -wildcard(process.name, "*regsvr32*", "*scrobj*") // returns true -wildcard(process.name, "*scrobj*") // returns false - // empty strings wildcard("", "*start*") // returns false wildcard("", "*") // returns true wildcard("", "") // returns true // null handling -wildcard(null, "*regsvr32*") // returns false +wildcard(null, "*regsvr32*") // returns null +wildcard(process.name, null) // returns null ---- *Syntax* @@ -327,7 +323,7 @@ wildcard(, [, ...]) + -- (Required, string) -Source string. +Source string. If `null`, the function returns `null`. If using a field as the argument, this parameter only supports the following field datatypes: @@ -336,16 +332,14 @@ field datatypes: * <> * <> field with a <> or <> sub-field - -Fields containing <> use the last array item only. -- ``:: + -- (Required{multi-arg}, string) -Wildcard expression used to match the source string. Fields are not supported as -arguments. +Wildcard expression used to match the source string. If `null`, the function +returns `null`. Fields are not supported as arguments. -- *Returns:* boolean From 77a0710fcd3ef848ff51fecdae391d5904a14b6f Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 10 Apr 2020 09:01:25 -0400 Subject: [PATCH 7/7] fix double space --- docs/reference/eql/functions.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc index d9776f303c5cf..78f34be9c0390 100644 --- a/docs/reference/eql/functions.asciidoc +++ b/docs/reference/eql/functions.asciidoc @@ -338,7 +338,7 @@ field datatypes: + -- (Required{multi-arg}, string) -Wildcard expression used to match the source string. If `null`, the function +Wildcard expression used to match the source string. If `null`, the function returns `null`. Fields are not supported as arguments. --