re.capture

Supported in:

Rules Search

re.capture(stringText, regex)

Description

Captures (extracts) data from a string using the regular expression pattern provided in the argument.

This function takes two arguments:

• stringText: the original string to search.
• regex: the regular expression indicating the pattern to search for.

The regular expression can contain 0 or 1 capture groups in parentheses. If the regular expression contains 0 capture groups, the function returns the first entire matching substring. If the regular expression contains 1 capture group, it returns the first matching substring for the capture group. Defining two or more capture groups returns a compiler error.

Param data types

STRING, STRING

Return type

STRING

Code samples

Example 1

In this example, if $e.principal.hostname contains "aaa1bbaa2" the following would be true, because the function returns the first instance. This example has no capture groups.

"aaa1" = re.capture($e.principal.hostname, "a+[1-9]")

Example 2

This example captures everything after the @ symbol in an email. If the $e.network.email.from field is [e-mail], the example returns google.com. The following example contains one capture group.

"google.com" = re.capture($e.network.email.from , "@(.*)")

Example 3

If the regular expression does not match any substring in the text, the function returns an empty string. You can omit events where no match occurs by excluding the empty string, which is especially important when you are using re.capture() with an inequality:

// Exclude the empty string to omit events where no match occurs.
"" != re.capture($e.network.email.from , "@(.*)")

// Exclude a specific string with an inequality.
"google.com" != re.capture($e.network.email.from , "@(.*)")