関数リファレンス（Function reference）

EQL 関数リファレンス

Elasticsearch は次の EQL 関数 をサポートしています。

add

提供された 2 つの加算子の合計を返します。

例

Eql

add(4, 5)                                           // returns 9
add(4, 0.5)                                         // returns 4.5
add(0.5, 0.25)                                      // returns 0.75
add(4, -2)                                          // returns 2
add(-2, -2)                                         // returns -4
// process.args_count = 4
add(process.args_count, 5)                          // returns 9
add(process.args_count, 0.5)                        // returns 4.5
// process.parent.args_count = 2
add(process.args_count, process.parent.args_count)  // returns 6
// null handling
add(null, 4)                                        // returns null
add(4. null)                                        // returns null
add(null, process.args_count)                       // returns null
add(process.args_count null)                        // returns null

構文

Txt

add(<addend>, <addend>)

パラメータ:

• <addend>
• (必須、整数または浮動小数点数または null) 加算する加算子。もし null の場合、関数は null を返します。
  2 つの加算子が必要です。2 つ以上の加算子を提供することはできません。
  フィールドを引数として使用する場合、このパラメータは numeric フィールドデータ型のみをサポートします。

返り値: 整数、浮動小数点数、または null

between

ソース文字列内の提供された left と right テキストの間にある部分文字列を抽出します。デフォルトでは、大文字と小文字を区別して一致します。

例

Eql

// 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")                     // returns null

構文

Txt

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

パラメータ

• <source>
• (必須、文字列または null) ソース文字列。空の文字列は空の文字列 ("") を返します。<left> または <right> パラメータに関係なく、空の文字列は "" を返します。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド
• <left>
• (必須、文字列) 抽出する部分文字列の左側のテキスト。このテキストには空白が含まれている必要があります。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド
• <right>
• (必須、文字列) 抽出する部分文字列の右側のテキスト。このテキストには空白が含まれている必要があります。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド
• <greedy_matching>
• (オプション、Boolean) true の場合、正規表現の .* に似て、可能な限り長い部分文字列と一致します。false の場合、正規表現の .*? に似て、可能な限り短い部分文字列と一致します。デフォルトは false です。

返り値: 文字列または null

cidrMatch

IP アドレスが 1 つ以上の提供された CIDR ブロックに含まれている場合、true を返します。

例

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

構文

Txt

パラメータ

• <ip_address>
• (必須、文字列または null) IP アドレス。IPv4 および IPv6 アドレスをサポートします。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは ip フィールドデータ型のみをサポートします。
• <cidr_block>
• (必須†[1], 文字列または null) 検索したい CIDR ブロック。もし null の場合、関数は null を返します。

返り値: ブール値または null

concat

提供された値の連結された文字列を返します。

例

Eql

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")                  // returns null
concat(process.name, null)                    // returns null
concat(null)                                  // returns null

構文

Txt

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

パラメータ

• <value>
• (必須†[1]) 連結する値。引数のいずれかが null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは text フィールドデータ型をサポートしません。

返り値: 文字列または null

divide

提供された被除数と除数の商を返します。

被除数と除数の両方が整数の場合、divide 関数は返される浮動小数点数を最も近い整数に 切り捨て ます。切り捨てを避けるには、被除数または除数のいずれかを浮動小数点数に変換します。

例

process.args_count フィールドは long 整数フィールドで、プロセス引数のカウントを含んでいます。

ユーザーは次の EQL クエリが process.args_count 値が 4 のイベントのみを一致させることを期待するかもしれません。

Eql

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

しかし、EQL クエリは process.args_count 値が 3 または 4 のイベントと一致します。

process.args_count 値が 3 のイベントの場合、divide 関数は 1.333... の浮動小数点数を返し、これは 1 に切り捨てられます。

process.args_count 値が 4 のイベントのみを一致させるには、被除数または除数のいずれかを浮動小数点数に変換します。

次の EQL クエリは整数 4 を同等の浮動小数点数 4.0 に変換します。

Eql

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

例

Eql

divide(4, 2)                                            // returns 2
divide(4, 3)                                            // returns 1
divide(4, 3.0)                                          // returns 1.333...
divide(4, 0.5)                                          // returns 8
divide(0.5, 4)                                          // returns 0.125
divide(0.5, 0.25)                                       // returns 2.0
divide(4, -2)                                           // returns -2
divide(-4, -2)                                          // returns 2
// process.args_count = 4
divide(process.args_count, 2)                           // returns 2
divide(process.args_count, 3)                           // returns 1
divide(process.args_count, 3.0)                         // returns 1.333...
divide(12, process.args_count)                          // returns 3
divide(process.args_count, 0.5)                         // returns 8
divide(0.5, process.args_count)                         // returns 0.125
// process.parent.args_count = 2
divide(process.args_count, process.parent.args_count)   // returns 2
// null handling
divide(null, 4)                                         // returns null
divide(4, null)                                         // returns null
divide(null, process.args_count)                        // returns null
divide(process.args_count, null)                        // returns null

構文

Txt

divide(<dividend>, <divisor>)

パラメータ

• <dividend>
• (必須、整数または浮動小数点数または null) 除算する被除数。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは numeric フィールドデータ型のみをサポートします。
• <divisor>
• (必須、整数または浮動小数点数または null) 除数。もし null の場合、関数は null を返します。この値はゼロであってはなりません (0)。
  フィールドを引数として使用する場合、このパラメータは numeric フィールドデータ型のみをサポートします。

返り値: 整数、浮動小数点数、または null

endsWith

ソース文字列が提供された部分文字列で終わる場合、true を返します。デフォルトでは、大文字と小文字を区別して一致します。

例

Eql

endsWith("regsvr32.exe", ".exe")          // returns true
endsWith("regsvr32.exe", ".EXE")          // returns false
endsWith("regsvr32.exe", ".dll")          // returns false
endsWith("", "")                          // returns true
// Make matching case-insensitive
endsWith~("regsvr32.exe", ".EXE")         // 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
// null handling
endsWith("regsvr32.exe", null)            // returns null
endsWith("", null)                        // returns null
endsWith(null, ".exe")                    // returns null
endsWith(null, null)                      // returns null

構文

Txt

endsWith(<source>, <substring>)

パラメータ

• <source>
• (必須、文字列または null) ソース文字列。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド
• <substring>
• (必須、文字列または null) 検索する部分文字列。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド

返り値: ブール値または null

indexOf

ソース文字列内の提供された部分文字列の最初の位置を返します。デフォルトでは、大文字と小文字を区別して一致します。

オプションの開始位置が提供されている場合、この関数は開始位置以降の部分文字列の最初の出現を返します。

例

Eql

// url.domain = "subdomain.example.com"
indexOf(url.domain, "d")        // returns 3
indexOf(url.domain, "D")        // returns null
indexOf(url.domain, ".")        // returns 9
indexOf(url.domain, ".", 9)     // returns 9
indexOf(url.domain, ".", 10)    // returns 17
indexOf(url.domain, ".", -6)    // returns 9
// Make matching case-insensitive
indexOf~(url.domain, "D")        // returns 4
// 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

構文

Txt

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

パラメータ

• <source>
• (必須、文字列または null) ソース文字列。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド
• <substring>
• (必須、文字列または null) 検索する部分文字列。
  この引数が null または <source> 文字列がこの部分文字列を含まない場合、関数は null を返します。
  <start_pos> が正の場合、空の文字列 ("") は <start_pos> を返します。そうでない場合、空の文字列は 0 を返します。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド
• <start_pos>
• (オプション、整数または null) 一致のための開始位置。関数はこの位置より前の位置を返しません。デフォルトは 0 です。
  位置はゼロインデックスです。負のオフセットは 0 として扱われます。
  この引数が null 以上または <source> 文字列の長さより大きい場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは次の numeric フィールドデータ型のみをサポートします:
  • long
  • integer
  • short
  • byte

返り値: 整数または null

length

提供された文字列の文字数を返します。空白や句読点を含みます。

例

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

構文

Txt

length(<string>)

パラメータ

• <string>
• (必須、文字列または null) 文字数を返す文字列。もし null の場合、関数は null を返します。空の文字列は 0 を返します。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド

返り値: 整数または null

modulo

提供された被除数と除数の剰余を返します。

例

Eql

modulo(10, 6)                                       // returns 4
modulo(10, 5)                                       // returns 0
modulo(10, 0.5)                                     // returns 0
modulo(10, -6)                                      // returns 4
modulo(-10, -6)                                     // returns -4
// process.args_count = 10
modulo(process.args_count, 6)                       // returns 4
modulo(process.args_count, 5)                       // returns 0
modulo(106, process.args_count)                     // returns 6
modulo(process.args_count, -6)                      // returns 4
modulo(process.args_count, 0.5)                     // returns 0
// process.parent.args_count = 6
modulo(process.args_count, process.parent.args_count)  // returns 4
// null handling
modulo(null, 5)                                     // returns null
modulo(7, null)                                     // returns null
modulo(null, process.args_count)                    // returns null
modulo(process.args_count, null)                    // returns null

構文

Txt

modulo(<dividend>, <divisor>)

パラメータ

• <dividend>
• (必須、整数または浮動小数点数または null) 除算する被除数。もし null の場合、関数は null を返します。浮動小数点数は 0 を返します。
  フィールドを引数として使用する場合、このパラメータは numeric フィールドデータ型のみをサポートします。
• <divisor>
• (必須、整数または浮動小数点数または null) 除数。もし null の場合、関数は null を返します。浮動小数点数は 0 を返します。この値はゼロであってはなりません (0)。
  フィールドを引数として使用する場合、このパラメータは numeric フィールドデータ型のみをサポートします。

返り値: 整数、浮動小数点数、または null

multiply

提供された 2 つの因子の積を返します。

例

Eql

multiply(2, 2)                                           // returns 4
multiply(0.5, 2)                                         // returns 1
multiply(0.25, 2)                                        // returns 0.5
multiply(-2, 2)                                          // returns -4
multiply(-2, -2)                                         // returns 4
// process.args_count = 2
multiply(process.args_count, 2)                          // returns 4
multiply(0.5, process.args_count)                        // returns 1
multiply(0.25, process.args_count)                       // returns 0.5
// process.parent.args_count = 3
multiply(process.args_count, process.parent.args_count)  // returns 6
// null handling
multiply(null, 2)                                        // returns null
multiply(2, null)                                        // returns null

構文

Txt

multiply(<factor, <factor>)

パラメータ

• <factor>
• (必須、整数または浮動小数点数または null) 乗算する因子。もし null の場合、関数は null を返します。
  2 つの因子が必要です。2 つ以上の因子を提供することはできません。
  フィールドを引数として使用する場合、このパラメータは numeric フィールドデータ型のみをサポートします。

返り値: 整数、浮動小数点数、または null

number

文字列を対応する整数または浮動小数点数に変換します。

例

Eql

number("1337")              // returns 1337
number("42.5")              // returns 42.5
number("deadbeef", 16)      // returns 3735928559
// integer literals beginning with "0x" are auto-detected as hexadecimal
number("0xdeadbeef")        // returns 3735928559
number("0xdeadbeef", 16)    // returns 3735928559
// "+" and "-" are supported
number("+1337")             // returns 1337
number("-1337")             // returns -1337
// surrounding whitespace is ignored
number("  1337  ")          // returns 1337
// process.pid = "1337"
number(process.pid)         // returns 1337
// null handling
number(null)                // returns null
number(null, 16)            // returns null
// strings beginning with "0x" are treated as hexadecimal (base 16),
// even if the <base_num> is explicitly null.
number("0xdeadbeef", null) // returns 3735928559
// otherwise, strings are treated as decimal (base 10)
// if the <base_num> is explicitly null.
number("1337", null)        // returns 1337

構文

Txt

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

パラメータ

• <string>
• (必須、文字列または null) 整数または浮動小数点数に変換する文字列。この値が文字列の場合、次のいずれかである必要があります:
  • 整数の文字列表現 (例: "42")
  • 浮動小数点数の文字列表現 (例: "9.5")
  • <base_num> パラメータが指定されている場合、基数表記の整数リテラルを含む文字列 (例: "0xDECAFBAD" 16 進数または基数 16)
    0x で始まる文字列は自動的に 16 進数として検出され、デフォルトの <base_num> は 16 です。
    - と + はスペースなしでサポートされます。周囲の空白は無視されます。空の文字列 ("") はサポートされていません。
    フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド
    この引数が null の場合、関数は null を返します。
• <base_num>
• (オプション、整数または null) 文字列を変換するために使用される基数または基。<string> が 0x で始まる場合、このパラメータは 16 (16 進数) にデフォルト設定されます。そうでない場合、基数 10 にデフォルト設定されます。
  この引数が明示的に null の場合、デフォルト値が使用されます。
  フィールドは引数としてサポートされません。

返り値: 整数または浮動小数点数または null

startsWith

ソース文字列が提供された部分文字列で始まる場合、true を返します。デフォルトでは、大文字と小文字を区別して一致します。

例

Eql

startsWith("regsvr32.exe", "regsvr32")  // returns true
startsWith("regsvr32.exe", "Regsvr32")  // returns false
startsWith("regsvr32.exe", "explorer")  // returns false
startsWith("", "")                      // returns true
// Make matching case-insensitive
startsWith~("regsvr32.exe", "Regsvr32")  // 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
// null handling
startsWith("regsvr32.exe", null)        // returns null
startsWith("", null)                    // returns null
startsWith(null, "regsvr32")            // returns null
startsWith(null, null)                  // returns null

構文

Txt

startsWith(<source>, <substring>)

パラメータ

• <source>
• (必須、文字列または null) ソース文字列。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド
• <substring>
• (必須、文字列または null) 検索する部分文字列。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:
  • keyword ファミリーの型
  • text フィールドの keyword サブフィールド

返り値: ブール値または null

string

値を文字列に変換します。

例

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

構文

Txt

string(<value>)

パラメータ

• <value>
• (必須) 文字列に変換する値。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは text フィールドデータ型をサポートしません。

返り値: 文字列または null

stringContains

ソース文字列が提供された部分文字列を含む場合、true を返します。デフォルトでは、大文字と小文字を区別して一致します。

例

Eql

// process.command_line = "start regsvr32.exe"
stringContains(process.command_line, "regsvr32")  // returns true
stringContains(process.command_line, "Regsvr32")  // returns false
stringContains(process.command_line, "start ")    // returns true
stringContains(process.command_line, "explorer")  // returns false
// Make matching case-insensitive
stringContains~(process.command_line, "Regsvr32")  // 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

構文

Txt

stringContains(<source>, <substring>)

パラメータ

• <source>
• (必須、文字列または null) 検索するソース文字列。もし null の場合、関数は null を返します。

フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:

• keyword ファミリーの型
• text フィールドの keyword サブフィールド
  • <substring>
  • (必須、文字列または null) 検索する部分文字列。もし null の場合、関数は null を返します。

フィールドを引数として使用する場合、このパラメータは次のフィールドデータ型のみをサポートします:

• keyword ファミリーの型
• text フィールドの keyword サブフィールド

返り値: ブール値または null

substring

提供された開始位置と終了位置でソース文字列から部分文字列を抽出します。

終了位置が提供されていない場合、関数は残りの文字列を抽出します。

例

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"

構文

Txt

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

パラメータ

• <source>
• (必須、文字列) ソース文字列。
• <start_pos>
• (必須、整数) 抽出の開始位置。
  この位置が <end_pos> 位置または <source> 文字列の長さよりも大きい場合、関数は空の文字列を返します。
  位置はゼロインデックスです。負のオフセットはサポートされています。
• <end_pos>
• (オプション、整数) 抽出のための排他的終了位置。この位置が提供されていない場合、関数は残りの文字列を返します。
  位置はゼロインデックスです。負のオフセットはサポートされています。

返り値: 文字列

subtract

提供された減数と被減数の差を返します。

例

Eql

subtract(10, 2)                                          // returns 8
subtract(10.5, 0.5)                                      // returns 10
subtract(1, 0.2)                                         // returns 0.8
subtract(-2, 4)                                          // returns -8
subtract(-2, -4)                                         // returns 8
// process.args_count = 10
subtract(process.args_count, 6)                          // returns 4
subtract(process.args_count, 5)                          // returns 5
subtract(15, process.args_count)                         // returns 5
subtract(process.args_count, 0.5)                        // returns 9.5
// process.parent.args_count = 6
subtract(process.args_count, process.parent.args_count)  // returns 4
// null handling
subtract(null, 2)                                        // returns null
subtract(2, null)                                        // returns null

構文

Txt

subtract(<minuend>, <subtrahend>)

パラメータ

• <minuend>
• (必須、整数または浮動小数点数または null) 減算する被減数。
  フィールドを引数として使用する場合、このパラメータは numeric フィールドデータ型のみをサポートします。
• <subtrahend>
• (オプション、整数または浮動小数点数または null) 減算する減数。もし null の場合、関数は null を返します。
  フィールドを引数として使用する場合、このパラメータは numeric フィールドデータ型のみをサポートします。

返り値: 整数、浮動小数点数、または null

^[1] このパラメータは複数の引数を受け入れます。