関数

以下でサポートされています。

このセクションでは、ルール、検索、ダッシュボードのクエリで使用できる YARA-L 2.0 関数について説明します。

ダッシュボードの YARA-L 2.0 関数と YARA-L 2.0 を使用した検索の統計と集計もご覧ください。

これらの関数は、YARA-L クエリの次の部分で使用できます。

arrays.concat

以下でサポートされています。
arrays.concat(string_array, string_array)

説明

元の文字列配列から要素をコピーして、新しい文字列配列を返します。

パラメータのデータ型

ARRAY_STRINGS、ARRAY_STRINGS

戻り値の型

ARRAY_STRINGS

コードサンプル

例 1

次の例では、2 つの異なる文字列配列を連結しています。

arrays.concat(["test1", "test2"], ["test3"]) = ["test1", "test2", "test3"]
例 2

次の例では、空の文字列を使用して配列を連結します。

arrays.concat([""], [""]) = ["", ""]
例 3

次の例では、空の配列を連結します。

arrays.concat([], []) = []

arrays.index_to_float

以下でサポートされています。
arrays.index_to_float(array, index)

説明

配列の指定されたインデックスにある要素を返します。そのインデックスにある要素が float として返されます。

インデックスは、配列内の要素の位置を表す整数値です。デフォルトでは、配列の最初の要素のインデックスは 0、最後の要素のインデックスは n-1 です。ここで、n は配列のサイズです。負のインデックスを使用すると、配列の末尾を基準にして配列要素にアクセスできます。たとえば、インデックス -1 は配列の最後の要素を参照し、インデックス -2 は配列の最後から 2 番目の要素を参照します。

パラメータのデータ型

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS、INT

戻り値の型

FLOAT

コードサンプル

例 1

次の例では、浮動小数点数の配列からインデックス 1 の要素を取得します。

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 1) // 2.1
例 2

次の例では、浮動小数点数の配列からインデックス -1 の要素を取得します。

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 0-1) // 4.6
例 3

次の例では、配列のサイズより大きいインデックスの要素を取得します。

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 6) // 0.0
例 4

次の例では、空の配列から要素を取得します。

arrays.index_to_float([], 0) // 0.0
例 5

次の例では、文字列配列のインデックス 1 の要素を取得します。

arrays.index_to_float(["1.2", "3.3", "2.4"], 1) // 3.3
例 6

次の例では、整数の配列からインデックス 2 の要素を取得します。

arrays.index_to_float([1, 3, 2], 2) // 2.0

arrays.index_to_int

以下でサポートされています。
arrays.index_to_int(array_of_inputs, index)

説明

配列の指定されたインデックスの値を整数として返します。

インデックスは、配列内の要素の位置を表す整数値です。デフォルトでは、配列の最初の要素のインデックスは 0、最後の要素のインデックスは n-1 です。ここで、n は配列のサイズです。負のインデックスを使用すると、配列の末尾を基準にして配列要素にアクセスできます。たとえば、インデックス -1 は配列の最後の要素を参照し、インデックス -2 は配列の最後から 2 番目の要素を参照します。

パラメータのデータ型

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS、INT

戻り値の型

INT

コードサンプル

例 1

この関数呼び出しは、インデックスの値が数値以外の文字列の場合に 0 を返します。

arrays.index_to_int(["str0", "str1", "str2"], 1) = 0
例 2

この関数は、インデックス -1 の要素を返します。

arrays.index_to_int(["44", "11", "22", "33"], 0-1) = 33
例 3

範囲外の要素の場合は 0 を返します。

arrays.index_to_int(["44", "11", "22", "33"], 5) = 0
例 4

この関数は、インデックス 1 の float 配列から要素を取得します。

arrays.index_to_int([1.100000, 1.200000, 1.300000], 1) = 1
例 5

この関数は、インデックス 0 の int 配列から要素を取得します。

arrays.index_to_int([1, 2, 3], 0) = 1

arrays.index_to_str

以下でサポートされています。
arrays.index_to_str(array, index)

説明

配列の指定されたインデックスにある要素を文字列として返します。インデックスは、配列内の要素の位置を表す整数値です。デフォルトでは、配列の最初の要素のインデックスは 0、最後の要素のインデックスは n-1 です。ここで、n は配列のサイズです。負のインデックスを使用すると、配列の末尾から配列要素にアクセスできます。たとえば、インデックス -1 は配列の最後の要素を参照し、インデックス -2 は配列の最後から 2 番目の要素を参照します。

パラメータのデータ型

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS、INT

戻り値の型

STRING

コードサンプル

例 1

次の例では、文字列配列のインデックス 1 の要素を取得します。

arrays.index_to_str(["test1", "test2", "test3", "test4"], 1) // "test2"
例 2

次の例では、文字列の配列からインデックス -1（配列の最後の要素）の要素を取得します。

arrays.index_to_str(["test1", "test2", "test3", "test4"], 0-1) // "test4"
例 3

次の例では、配列のサイズより大きいインデックスの要素を取得し、空の文字列を返します。

arrays.index_to_str(["test1", "test2", "test3", "test4"], 6) // ""
例 4

次の例では、空の配列から要素を取得します。

arrays.index_to_str([], 0) // ""
例 5

次の例では、浮動小数点数の配列からインデックス 0 の要素を取得します。出力は文字列として返されます。

arrays.index_to_str([1.200000, 3.300000, 2.400000], 0) // "1.2"
例 6

次の例では、整数の配列からインデックス 2 の要素を取得します。出力は文字列の形式になります。

arrays.index_to_str([1, 3, 2], 2) // "2"

arrays.join_string

以下でサポートされています。
arrays.join_string(array_of_strings, optional_delimiter)

説明

文字列の配列を、省略可能なパラメータで区切られた単一の文字列に変換します。区切り文字が指定されていない場合は、空の文字列が使用されます。

パラメータのデータ型

ARRAY_STRINGS、STRING

戻り値の型

STRING

コードサンプル

関数の使用例をいくつかご紹介します。

例 1

この例では、非 null 要素を含む配列と区切り文字を結合します。

arrays.join_string(["foo", "bar"], ",") = "foo,bar"
例 2

この例では、null 要素と区切り文字を含む配列を結合します。

arrays.join_string(["foo", NULL, "bar"], ",") = "foo,bar"
例 3

この例では、非 null 要素を含む配列を区切り文字なしで結合します。

arrays.join_string(["foo", "bar"]) = "foobar"

arrays.length

以下でサポートされています。
arrays.length(repeatedField)

説明

繰り返しフィールド要素の数を返します。

パラメータのデータ型

LIST

戻り値の型

NUMBER

コードサンプル

例 1

繰り返しフィールド要素の数を返します。

arrays.length($e.principal.ip) = 2
例 2

パスに複数の繰り返しフィールドがある場合は、繰り返しフィールド要素の合計数を返します。

arrays.length($e.intermediary.ip) = 3

arrays.max

以下でサポートされています。
arrays.max(array_of_ints_or_floats)

説明

配列内の最大の要素を返します。配列が空の場合は 0 を返します。

パラメータのデータ型

ARRAY_INTS|ARRAY_FLOATS

戻り値の型

FLOAT

コードサンプル

関数の使用例をいくつかご紹介します。

例 1

この例では、整数の配列内の大きい方の要素を返します。

arrays.max([10, 20]) = 20.000000
例 2

この例では、浮動小数点数の配列内の大きい方の要素を返します。

arrays.max([10.000000, 20.000000]) = 20.000000

arrays.min

以下でサポートされています。
arrays.min(array_of_ints_or_floats[, ignore_zeros=false])

説明

配列内の最小要素を返します。配列が空の場合は 0 を返します。2 番目の省略可能な引数が true に設定されている場合、ゼロに等しい要素は無視されます。

パラメータのデータ型

ARRAY_INTS|ARRAY_FLOATS、BOOL

戻り値の型

FLOAT

コードサンプル

関数の使用例をいくつかご紹介します。

例 1

この例では、整数の配列内の最小の要素を返します。

arrays.min([10, 20]) = 10.000000
例 2

この例では、浮動小数点数の配列内の最小の要素を返します。

arrays.min([10.000000, 20.000000]) = 10.000000
例 3

この例では、ゼロを無視して、浮動小数点数の配列内の最小要素を返します。

arrays.min([10.000000, 20.000000, 0.0], true) = 10.000000

arrays.size

以下でサポートされています。
arrays.size( array )

説明

配列のサイズを返します。空の配列の場合は 0 を返します。

パラメータのデータ型

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS

戻り値の型

INT

コードサンプル

例 1

この例では、2 つの要素を含む文字列配列を使用します。

arrays.size(["test1", "test2"]) = 2
例 2

この例では、3 つの要素を含む整数配列を使用します。

arrays.size([1, 2, 3]) = 3
例 3

この例では、1 つの要素を含む浮動小数点配列を使用します。

arrays.size([1.200000]) = 1
例 4

この例では空の配列を使用します。

arrays.size([]) = 0

bytes.to_base64

以下でサポートされています。
bytes.to_base64(bytes, optional_default_string)

説明

関数は bytes 値を base64 encoded string に変換します。キャストできない値を含む関数呼び出しは、デフォルトで空の文字列を返します。

パラメータのデータ型

BYTES、STRING

戻り値の型

STRING

コードサンプル

未加工のバイナリ バイトから Base64 エンコードされた文字列

この関数は、未加工のバイナリ バイトを Base64 でエンコードされた文字列に変換します。

bytes.to_base64(b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000) = "AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA="
Failed Conversion（デフォルトは、任意で指定された文字列）

指定されたバイト値が無効な場合、関数はデフォルトで "invalid bytes" になります。

bytes.to_base64(b'000000006f8ec5586d", "invalid bytes") = "invalid bytes"

cast.as_bool

以下でサポートされています。
cast.as_bool(string_or_int)

説明

関数は、int 値または文字列値を bool 値に変換します。キャストできない値を含む関数呼び出しは FALSE を返します。整数 1 と大文字と小文字を区別しない文字列「true」の場合にのみ TRUE を返します。

パラメータのデータ型

INT|STRING

戻り値の型

BOOL

コードサンプル

例 1

この例では、ブール値以外の文字列をキャストする方法を示します。

cast.as_bool("123") = false
例 2

真の整数（1）

cast.as_bool(1) = true
例 3

真の文字列

cast.as_bool("true") = true
例 4

大文字の真の文字列

cast.as_bool("TRUE") = true
例 5

負の整数

cast.as_bool(0-1) = false
例 6

偽の整数（0）

cast.as_bool(0) = false
例 7

空の文字列

cast.as_bool("") = false

cast.as_float

以下でサポートされています。
cast.as_float(string_to_cast)

説明

数字の文字列を浮動小数点数に変換します。キャストできない値を含む関数呼び出しは 0 を返します。浮動小数点数は、小数点以下 7 桁までの精度を維持します。

パラメータのデータ型

STRING

戻り値の型

FLOAT

コードサンプル

例 1

数値以外の文字列をキャストすると 0 が返されます。

cast.as_float("str") = 0.0000000
例 2

空の文字列をキャストすると 0 が返されます。

cast.as_float("") = 0.0000000
例 3

有効な数値文字列をキャストすると、浮動小数点値が返されます。

cast.as_float("1.012345678") = 1.0123456

cast.as_string

以下でサポートされています。
cast.as_string(int_or_bytes_or_bool, optional_default_string)

説明

cast.as_string 関数は、INT、BYTES、または BOOL の値を文字列形式に変換します。キャストが失敗した場合を処理するために、必要に応じて default_string 引数を指定できます。default_string 引数を省略した場合、または入力が無効な UTF-8 バイト シーケンスまたは BASE64 バイト シーケンスの場合、関数は空の文字列を返します。

パラメータのデータ型

INT|BYTES|BOOL、STRING

戻り値の型

STRING

コードサンプル

整数から文字列への変換

この関数は、整数 123 を文字列 "123" に変換します。

cast.as_string(123) = "123"
浮動小数点から文字列への変換

この関数は、浮動小数点数 2.25 を文字列 "2.25" に変換します。

cast.as_string(2.25) = "2.25"
バイトから文字列への変換

この関数は、未加工のバイナリ b'01 を文字列 "\x01" に変換します。

cast.as_string(b'01, "") = "\x01"
ブール値から文字列への変換

この関数は、ブール値 true を文字列 "true" に変換します。

cast.as_string(true, "") = "true"
Failed Conversion（デフォルトは、任意で指定された文字列）

指定された値が無効な場合、関数はデフォルトで文字列 "casting error" になります。

cast.as_string(9223372036854775808, "casting error") = "casting error"

フィンガープリント

以下でサポートされています。
hash.fingerprint2011(byteOrString)

説明

この関数は、入力バイト シーケンスまたは文字列の fingerprint2011 ハッシュを計算します。この関数は、範囲 [2, 0xFFFFFFFFFFFFFFFF] の符号なし INT 値を返します。

パラメータのデータ型

BTYE、STRING

戻り値の型

INT

コードサンプル

id_fingerprint = hash.fingerprint2011("user123")

グループ

以下でサポートされています。
group(field1, field2, field3, ...)

説明

類似したタイプのフィールドをプレースホルダ変数にグループ化します。

UDM 検索では、グループ化されたフィールドを使用して、類似したタイプの複数のフィールドを検索します。グループ関数は、グループ化されたフィールドと似ていますが、グループ化するフィールドを選択して検出をトリガーできる点が異なります。グループ関数を使用すると、さまざまな名詞タイプにわたって特定のエンティティ（ホスト名、IP アドレス、ユーザー ID など）に関する情報を収集できます。

コードサンプル

例 1

すべての IP アドレスをグループ化し、スキャンされた期間で最も一般的な IP アドレスのカウントを降順で提供します。

$ip = group(principal.ip, about.ip, target.ip)
$ip != ""
match:
  $ip
outcome:
  $count = count_distinct(metadata.id)
order:
  $count desc

hash.sha256

以下でサポートされています。
hash.sha256(string)

説明

入力文字列の SHA-256 ハッシュを返します。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1

この例では、入力が有効な文字列の場合の SHA-256 ハッシュを示します。

hash.sha256("str") = "8c25cb3686462e9a86d2883c5688a22fe738b0bbc85f458d2d2b5f3f667c6d5a"
例 2

この例では、入力が空の文字列の場合の SHA-256 ハッシュを示します。

hash.sha256("") = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

math.abs

以下でサポートされています。
math.abs(numericExpression)

説明

整数式または浮動小数点式で絶対値を返します。

パラメータのデータ型

NUMBER

戻り値の型

NUMBER

コードサンプル

例 1

この例では、イベントが指定された時刻の前か後かに関係なく、指定された時刻（Unix エポックからの秒数）から 5 分以上経過した場合に True を返します。math.abs の呼び出しは、複数の変数やプレースホルダに依存できません。たとえば、次の例のハードコードされた時間値 1643687343 を $e2.metadata.event_timestamp.seconds に置き換えることはできません。

300 < math.abs($e1.metadata.event_timestamp.seconds - 1643687343)

math.ceil

以下でサポートされています。
math.ceil(number)

説明

指定された数値以上の最小の整数を返します（切り上げ）。入力が null の場合、または int64 に収まらないほど大きい場合は 0 を返します。

パラメータのデータ型

FLOAT

戻り値の型

INT

コードサンプル

このセクションでは、math.ceil の使用例を示します。

例 1

この例では、整数の天井関数を返します。

math.ceil(2.000000) = 2
例 2

この例では、負の数の ceil を返します。

math.ceil(0-1.200000) = -1
例 3

この例では、64 ビット整数には大きすぎる数値の天井関数として 0 が返されます。

math.ceil(184467440737095516160.0) = 0

math.floor

以下でサポートされています。
math.floor(float_val)

説明

指定された値以下の最大の整数値を返します（切り捨て）。入力が null であるか、int64 に収まらないほど大きい場合は 0 を返します。

パラメータのデータ型

FLOAT

戻り値の型

INT

コードサンプル

例 1

この例では、正の数値のケースを示します。

math.floor(1.234568) = 1
例 2

この例では、負の数値のケースを示します。

math.floor(0-1.234568) = -2
例 3

この例では、ゼロの場合を示します。

math.floor(0.000000) = 0

math.geo_distance

以下でサポートされています。
math.geo_distance(longitude1, latitude1, longitude2, latitude2))

説明

2 つの地理的位置（座標）間の距離をメートル単位で返します。座標が無効な場合は -1 を返します。

パラメータのデータ型

FLOAT、FLOAT、FLOAT、FLOAT

戻り値の型

FLOAT

コードサンプル

例 1

次の例では、すべてのパラメータが有効な座標である場合に距離を返します。

math.geo_distance(-122.020287, 37.407574, -122.021810, 37.407574) = 134.564318
例 2

次の例では、パラメータの 1 つが切り捨てられた座標の場合に距離を返します。

math.geo_distance(-122.000000, 37.407574, -122.021810, 37.407574) = 1926.421905
例 3

次の例では、パラメータの 1 つが無効な座標である場合に -1 を返します。

math.geo_distance(0-122.897680, 37.407574, 0-122.021810, 97.407574) = -1.000000
例 4

次の例では、座標が同じ場合に 0 を返します。

math.geo_distance(-122.897680, 37.407574, -122.897680, 37.407574) = 0.000000

math.is_increasing

以下でサポートされています。
math.is_increasing(num1, num2, num3)

説明

数値（整数または倍精度浮動小数点数）のリストを受け取り、値が昇順の場合は True を返し、それ以外の場合は False を返します。

パラメータのデータ型

INT|FLOAT, INT|FLOAT, INT|FLOAT

戻り値の型

BOOL

コードサンプル

例 1

この例には、タイムスタンプのような値が秒単位で含まれています。

math.is_increasing(1716769112, 1716769113, 1716769114) = true
例 2

この例では、1 つの負の double 値、1 つのゼロ INT64 値、1 つの正の INT64 値が含まれています。

math.is_increasing(-1.200000, 0, 3) = true
例 3

この例では、1 つの負の double 値、1 つのゼロ INT64 値、1 つの負の INT64 値が含まれています。

math.is_increasing(0-1.200000, 0, 0-3) = false
例 4

この例では、2 つの負の double 値と 1 つのゼロ INT64 値が含まれています。

math.is_increasing(0-1.200000, 0-1.50000, 0) = false
例 5

この例には、1 つの負の double 値と 2 つの同じ値が含まれています。

math.is_increasing(0-1.200000, 0, 0) = false

math.log

以下でサポートされています。
math.log(numericExpression)

説明

整数式または浮動小数点式で指定された値の自然対数を返します。

パラメータのデータ型

NUMBER

戻り値の型

NUMBER

コードサンプル

例 1
math.log($e1.network.sent_bytes) > 20

math.pow

以下でサポートされています。
math.pow(base, exponent)

説明

最初の引数を 2 番目の引数のべき乗で累乗した値を返します。オーバーフローの場合は 0 を返します。

パラメータのデータ型

base: INT|FLOAT exponent: INT|FLOAT

戻り値の型

FLOAT

コードサンプル

例 1

この例では、整数のケースを示します。

math.pow(2, 2) // 4.00
例 2

この例では、分数のベースケースを示します。

math.pow(2.200000, 3) // 10.648
例 3

この例では、小数の基数と指数を示します。

math.pow(2.200000, 1.200000) // 2.575771
例 4

この例では、負の電力ケースを示します。

math.pow(3, 0-3) // 0.037037
例 5

この例では、小数指数のケースを示します。

math.pow(3, 0-1.200000) // 0.267581
例 6

この例では、負ベースのケースを示します。

math.pow(0-3, 0-3) // -0.037037
例 7

この例では、ゼロベースのケースを示します。

math.pow(0, 3) // 0
例 8

この例では、電力がゼロの場合を示します。

math.pow(9223372036854775807, 0) // 1
例 9

この例では、大きなベースケースを示します。

math.pow(9223372036854775807, 1.200000) // 57262152889751593549824

math.random

以下でサポートされています。
math.random()

説明

[0, 1) の範囲の DOUBLE 型の疑似ランダム値を生成します。0 は含まれますが、1 は含まれません。

戻り値の型

FLOAT

コードサンプル

次の例では、ランダム値が [0, 1) の範囲内にあるかどうかを確認します。none if(math.random() >= 0 and math.random() < 1) = true

math.round

以下でサポートされています。
math.round(numericExpression, decimalPlaces)

説明

最も近い整数、または指定した小数点以下の桁数に丸めた値を返します。

パラメータのデータ型

NUMBER

戻り値の型

NUMBER

コードサンプル

math.round(10.7) // returns 11
math.round(1.2567, 2) // returns 1.25
math.round(0-10.7) // returns -11
math.round(0-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer

math.sqrt

以下でサポートされています。
math.sqrt(number)

説明

指定された数値の平方根を返します。負の数の場合は 0 を返します。

パラメータのデータ型

INT|FLOAT

戻り値の型

FLOAT

コードサンプル

例 1

この例では、int 引数の平方根を返します。

math.sqrt(3) = 1.732051
例 2

この例では、負の int 引数の平方根を返します。

math.sqrt(-3) = 0.000000
例 3

この例では、ゼロ引数の平方根を返します。

math.sqrt(0) = 0.000000
例 4

この例では、浮動小数点引数の平方根を返します。

math.sqrt(9.223372) = 3.037000
例 5

この例では、負の浮動小数点引数の平方根を返します。

math.sqrt(0-1.200000) = 0.000000

metrics

以下でサポートされています。

指標関数は、大量の履歴データを集計できます。これは、結果セクションの metrics.functionName() を使用してルールで使用できます。

詳細については、YARA-L 指標 をご覧ください。

net.ip_in_range_cidr

以下でサポートされています。
net.ip_in_range_cidr(ipAddress, subnetworkRange)

説明

指定された IP アドレスが指定されたサブネットワーク内にある場合に true を返します。

YARA-L を使用すると、net.ip_in_range_cidr() ステートメントを使用するサブネットワーク内のすべての IP アドレスにわたり UDM イベントを検索できます。IPv4 と IPv6 の両方がサポートされています。

IP アドレスの範囲を検索するには、IP UDM フィールドと CIDR 範囲を指定します。YARA-L は、単一および繰り返しの IP アドレス フィールドの両方を処理できます。

IP アドレスの範囲を検索するには、ip UDM フィールドとクラスレス ドメイン間ルーティング（CIDR）範囲を指定します。YARA-L は、単一および繰り返しの IP アドレス フィールドの両方を処理できます。

パラメータのデータ型

STRING、STRING

戻り値の型

BOOL

コードサンプル

例 1

IPv4 の例:

net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")
例 2

IPv6 の例:

net.ip_in_range_cidr($e.network.dhcp.yiaddr, "2001:db8::/32")

net.ip_in_range_cidr() ステートメントを使用したルールの例については、サンプルのルールとして IP アドレスの範囲内の単一イベントをご覧ください。

re.regex

以下でサポートされています。

YARA-L 2.0 では、次のいずれかの構文を使用して正規表現の一致を定義できます。

  • YARA 構文の使用 - イベントに関連します。この構文の一般的な表現は次のとおりです。

    $e.field = /regex/

  • YARA-L 構文の使用 - 次のパラメータを受け取る関数として使用します。

    • 正規表現が適用されるフィールド。
    • 文字列として指定された正規表現。

    この構文の一般的な表現は次のとおりです。

    re.regex($e.field, `regex`)

説明

この関数は、指定した正規表現に一致する部分文字列が文字列に含まれている場合、true を返します。正規表現の先頭または末尾に .* を追加する必要はありません。

注
  • 文字列と完全に一致する場合、またはプレフィックスまたはサフィックスのみと一致する場合は、正規表現に ^（開始）と $（終了）のアンカー文字を含めます。たとえば、/^full$/ は "full" と正確に一致しますが、/full/ は "fullest"、"lawfull"、"joyfully" と一致します。
  • UDM フィールドに改行文字が含まれている場合、regexp は UDM フィールドの最初の行にのみ一致します。完全な UDM フィールド マッチングを適用するには、(?s) を正規表現に追加します。たとえば、/.*allUDM.*/ を /(?s).*allUDM.*/ に置き換えます。
  • 文字列の後に nocase 修飾子を使用すると、検索で大文字小文字の区別が無視されるよう指定できます。

パラメータのデータ型

STRING、STRING

パラメータ式のタイプ

ANY、ANY

戻り値の型

BOOL

コードサンプル

例 1
// Equivalent to $e.principal.hostname = /google/
re.regex($e.principal.hostname, "google")

re.capture

以下でサポートされています。
re.capture(stringText, regex)

説明

引数で指定された正規表現パターンを使用して、文字列からデータをキャプチャ（抽出）します。

この関数は次の 2 つの引数を取ります。

  • stringText: 検索する元の文字列。
  • regex: 検索するパターンを示す正規表現。

正規表現では、0 または 1 つのキャプチャ グループをかっこで囲むことができます。正規表現にキャプチャ グループがない場合、この関数は最初に一致した部分文字列を返します。正規表現に 1 つのキャプチャ グループが含まれている場合、キャプチャ グループの最初の一致部分文字列が返されます。2 つ以上のキャプチャ グループを定義すると、コンパイラ エラーが返されます。

パラメータのデータ型

STRING、STRING

戻り値の型

STRING

コードサンプル

例 1

この例では、$e.principal.hostname に「aaa1bbaa2」が含まれていれば、この関数は最初のインスタンスを返すため、以下は True になります。この例にはキャプチャ グループはありません。

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

この例は、メール内の @ 記号より後ろのすべての部分を取得します。$e.network.email.from フィールドが test@google.com の場合、この例では google.com が返されます。次の例では、1 つのキャプチャ グループが含まれています。

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

正規表現がテキスト内のどの部分文字列とも一致しない場合、この関数は空の文字列を返します。空の文字列を除外することで、一致しないイベントを省略できます。これは、不等号で re.capture() を使用している場合に特に重要です。

// 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 , "@(.*)")

re.replace

以下でサポートされています。
re.replace(stringText, replaceRegex, replacementText)

説明

正規表現の置き換えを行います。

この関数は次の 3 つの引数を取ります。

  • stringText: 元の文字列。
  • replaceRegex: 検索するパターンを示す正規表現。
  • replacementText: 各一致に挿入するテキスト。

元の文字列　stringText から派生した新しい文字列を返します。ここでは、replaceRegex のパターンに一致するすべての部分文字列が、replacementText に置き換えられます。replacementText 内でバックスラッシュでエスケープされた数字（\1～\9）を使用して、replaceRegex パターン内の対応する括弧で囲まれたグループと一致するテキストを挿入できます。一致するテキスト全体を参照するには、\0 を使用します。

この関数は、重複しない一致を置き換えるもので、最初に見つかったものを優先的に置き換えます。たとえば、re.replace("banana", "ana", "111") は文字列「b111na」を返します。

パラメータのデータ型

STRING, STRING, STRING

戻り値の型

STRING

コードサンプル

例 1

この例では、メール内の @ 記号の後のすべての部分をキャプチャし、com を org に置き換えて結果を返します。ネストされた関数が使用されることに注意してください。

"email@google.org" = re.replace($e.network.email.from, "com", "org")
例 2

次の例では、replacementText 引数でバックスラッシュでエスケープされた数字を使用して、replaceRegex パターンとの一致を参照します。

"test1.com.google" = re.replace(
                       $e.principal.hostname, // holds "test1.test2.google.com"
                       "test2\.([a-z]*)\.([a-z]*)",
                       "\\2.\\1"  // \\1 holds "google", \\2 holds "com"
                     )
例 3

空の文字列と re.replace() を扱う場合は、次の点に注意してください。

replaceRegex として空の文字列を使用。

// In the function call below, if $e.principal.hostname contains "name",
// the result is: 1n1a1m1e1, because an empty string is found next to
// every character in `stringText`.
re.replace($e.principal.hostname, "", "1")

空の文字列を置き換えるには、replaceRegex として "^$" を使用します。

// In the function call below, if $e.principal.hostname contains the empty
// string, "", the result is: "none".
re.replace($e.principal.hostname, "^$", "none")

サンプルレート

以下でサポートされています。
optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

説明

この関数は、あるイベントを含めるかどうかを、決定論的なサンプリングの方法に基づいて判断します。次の結果を返します。

  • 入力値の割合（rateNumerator / rateDenominator に相当）の true。イベントをサンプルに含める必要があることを示します。
  • false: イベントをサンプルに含める必要がないことを示します。

この関数は、イベントのサブセットのみを処理する最適化シナリオで役立ちます。次と同等です。

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

パラメータのデータ型

  • byteOrString: BYTE または STRING のいずれかに評価される式。
  • rateNumerator: 'INT'
  • rateDenominator: 'INT'

戻り値の型

BOOL

コードサンプル

events:
    $e.metadata.event_type = "NETWORK_CONNECTION"
    $asset_id = $e.principal.asset.asset_id
    optimization.sample_rate($e.metadata.id, 1, 5) // Only 1 out of every 5 events

  match:
    $asset_id over 1h

  outcome:
    $event_count = count_distinct($e.metadata.id)
  // estimate the usage by multiplying by the inverse of the sample rate
    $usage_past_hour = sum(5.0 * $e.network.sent_bytes)

 condition:
  // Requiring a certain number of events after sampling avoids bias (e.g. a
  // device with just 1 connection will still show up 20% of the time and
  // if we multiply that traffic by 5, we'll get an incorrect estimate)
  $e and ($usage_past_hour > 1000000000) and $event_count >= 100

strings.base64_decode

以下でサポートされています。
strings.base64_decode(encodedString)

説明

エンコードされた文字列の Base64 デコードされたバージョンを含む文字列を返します。

この関数は、Base64 でエンコードされた 1 つの文字列を引数として受け取ります。encodedString が Base64 でエンコードされた有効な文字列でない場合、この関数は encodedString を変更せずに返します。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1
"test" = strings.base64_decode($e.principal.domain.name)

strings.coalesce

以下でサポートされています。
strings.coalesce(a, b, c, ...)

説明

この関数は引数を無制限に受け取り、空の文字列と評価されない最初の式の値を返します（「ゼロ以外の値」など）。すべての引数が空の文字列に評価される場合、関数呼び出しは空の文字列を返します。

引数には、リテラル、イベント フィールド、関数呼び出しを使用できます。すべての引数は STRING 型である必要があります。引数がイベント フィールドの場合、属性は同じイベントからのものである必要があります。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1

次の例には、引数として文字列変数が含まれています。（1）$e.network.email.from が suspicious@gmail.com であるか、（2）$e.network.email.from が空かつ$e.network.email.to が suspicious@gmail.com の場合、条件は true と評価されます。

"suspicious@gmail.com" = strings.coalesce($e.network.email.from, $e.network.email.to)
例 2

次の例では、2 つ以上の引数を使用して coalesce 関数を呼び出します。この条件は、イベント $e の最初の null 以外の IP アドレスを、リファレンス リスト ip_watchlist の値と比較します。この呼び出しで引数が結合される順序は、ルール条件で引数が列挙されている順序と同じです。

  1. $e.principal.ip が最初に評価されます。
  2. $e.src.ip が評価されます。
  3. $e.target.ip が評価されます。
  4. 最後に、以前の ip フィールドが設定されていない場合、文字列「No IP」がデフォルト値として返されます。
strings.coalesce($e.principal.ip, $e.src.ip, $e.target.ip, "No IP") in %ip_watchlist
例 3

次の例では、イベント $e1 とイベント $e2 の principal.hostname を結合しようとしています。引数が異なるイベント変数であるため、コンパイラ エラーが返されます。

// returns a compiler error
"test" = strings.coalesce($e1.principal.hostname, $e2.principal.hostname)

strings.concat

以下でサポートされています。
strings.concat(a, b, c, ...)

説明

無制限の数のアイテムを連結した値を返します。各アイテムは、文字列、整数、または浮動小数点数です。

引数がイベント フィールドの場合、属性は同じイベントからのものである必要があります。

パラメータのデータ型

STRING、FLOAT、INT

戻り値の型

STRING

コードサンプル

例 1

次の例には、引数として文字列変数と整数変数が含まれています。principal.hostname と principal.port はどちらも、同じイベント $e からのもので、文字列を返すために連結されます。

"google:80" = strings.concat($e.principal.hostname, ":", $e.principal.port)
例 2

次の例には、引数として文字列変数と文字列リテラルが含まれています。

"google-test" = strings.concat($e.principal.hostname, "-test") // Matches the event when $e.principal.hostname = "google"
例 3

次の例には、引数として文字列変数と浮動リテラルが含まれています。文字列として表現される場合、整数である浮動小数点は小数点のない形式になります（たとえば、1.0 は「1」と表されます）。また、10 進 16 桁を超える浮動小数点は小数点以下 16 桁に切り捨てられます。

"google2.5" = strings.concat($e.principal.hostname, 2.5)
例 4

次の例には、引数として文字列変数、文字列リテラル、整数変数、浮動小数点リテラルが含まれています。すべての変数は、同じイベント $e からのもので、リテラルに連結されて文字列を返します。

"google-test802.5" = strings.concat($e.principal.hostname, "-test", $e.principal.port, 2.5)
例 5

次の例では、イベント $e1 の principal.port とイベント $e2 の principal.hostname を連結しようとしています。引数が異なるイベント変数であるため、コンパイラ エラーが返されます。

// Will not compile
"test" = strings.concat($e1.principal.port, $e2.principal.hostname)

strings.contains

以下でサポートされています。
strings.contains( str, substr )

説明

指定された文字列に指定された部分文字列が含まれている場合に true を返します。それ以外の場合は false を返します。

パラメータのデータ型

STRING、STRING

戻り値の型

BOOL

コードサンプル

例 1

この例では、文字列に部分文字列「is」が含まれているため、true が返されます。

strings.contains("thisisastring", "is") = true
例 2

この例では、文字列に部分文字列「that」が含まれていないため、false が返されます。

strings.contains("thisisastring", "that") = false

strings.count_substrings

以下でサポートされています。
strings.count_substrings(string_to_search_in, substring_to_count)

説明

文字列と部分文字列を指定すると、文字列内で重複しない部分文字列の出現回数の int64 を返します。

パラメータのデータ型

STRING、STRING

戻り値の型

INT

コードサンプル

このセクションでは、特定の文字列に部分文字列が出現する回数を計算する例を示します。

例 1

この例では、null 以外の文字列と、null 以外の単一の部分文字列文字を使用しています。

strings.count_substrings("this`string`has`four`backticks", "`") = 4
例 2

この例では、null 以外の文字列と、1 文字以上の null 以外の部分文字列を使用しています。

strings.count_substrings("str", "str") = 1
例 3

この例では、null 以外の文字列と空の部分文字列を使用しています。

strings.count_substrings("str", "") = 0
例 4

この例では、空の文字列と、1 文字以上の null 以外の部分文字列を使用しています。

strings.count_substrings("", "str") = 0
例 5

この例では、空の文字列と空の部分文字列を使用しています。

strings.count_substrings("", "") = 0
例 6

この例では、null 以外の文字列と、複数文字で複数回出現する null 以外の部分文字列を使用しています。

strings.count_substrings("fooABAbarABAbazABA", "AB") = 3
例 7

この例では、null 以外の文字列と、複数文字で複数回出現する null 以外の部分文字列を使用しています。重複する部分文字列の出現に関する制限がハイライト表示されます。

strings.count_substrings("ABABABA", "ABA") = 2

strings.ends_with

以下でサポートされています。
strings.ends_with(value, suffix)

説明

関数は 2 つの文字列 (value, suffix) を取ります。接尾辞が空ではなく、値の末尾にある場合は true を返します。

パラメータのデータ型

STRING、STRING

戻り値の型

BOOL

コードサンプル

次のコードサンプルは、strings.ends_with 関数の使用方法の例を示しています。

例: true を返す

接尾辞が値の末尾にある場合は true を返します。

strings.ends_with(target.hostname, "com") = true
例: false を返す

接尾辞が値の末尾にない場合は false を返します。

strings.ends_with(target.hostname, "com") = false
例: 同一の場合は false を返す

接尾辞と値が同じ場合は false を返します。

target.hostname != "example.com"
strings.ends_with("str", "str") = true
例: 接尾辞が空の場合に false を返す

接尾辞が空の文字列の場合、false を返します。

target.hostname != "example.com"
strings.ends_with("str", "") = false
例: 値が空の場合に false を返す

値が空の文字列の場合、false を返します。

target.hostname != "example.com"
strings.ends_with("", "str") = false
例: 接尾辞と値が空の場合に false を返す

接尾辞と値が空の文字列の場合、false を返します。

target.hostname != "example.com"
strings.ends_with("", "") = false

strings.extract_domain

以下でサポートされています。
strings.extract_domain(url_string)

説明

文字列からドメインを抽出します。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1

この例では、空の文字列

strings.extract_domain("") = ""
例 2

ランダムな文字列（URL ではない）

strings.extract_domain("1234") = ""
例 3

複数のバックスラッシュ

strings.extract_domain("\\\\") = ""
例 4

アルファベット以外の文字が適切に処理される

strings.extract_domain("http://例子.卷筒纸.中国") = "卷筒纸.中国"
例 5

URI の処理

strings.extract_domain("mailto:?to=&subject=&body=") = ""
例 6

実際の URL の前に複数の文字がある

strings.extract_domain("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "google.com"
例 7

URI 内の特殊文字 #

strings.extract_domain("test#@google.com") = ""
例 8

URL 内の特殊文字 #

strings.extract_domain("https://test#@google.com") = ""
例 9

ポジティブなテストケース

strings.extract_domain("https://google.co.in") = "google.co.in"

strings.extract_hostname

以下でサポートされています。
strings.extract_hostname(string)

説明

文字列からホスト名を抽出します。この関数では大文字と小文字が区別されます。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1

この例では、空の文字列が返されます。

strings.extract_hostname("") = ""
例 2

ランダムな文字列（URL ではない）

strings.extract_hostname("1234") = "1234"
例 3

複数のバックスラッシュ

strings.extract_hostname("\\\\") = ""
例 4

英語以外の文字が適切に処理される

strings.extract_hostname("http://例子.卷筒纸.中国") = "例子.卷筒纸.中国"
例 5

URI の処理

strings.extract_hostname("mailto:?to=&subject=&body=") = "mailto"
例 6

実際の URL の前に複数の文字がある

strings.extract_hostname("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "www.google.com"
例 7

URI 内の特殊文字 #

strings.extract_hostname("test#@google.com") = "test"
例 8

URL 内の特殊文字 #

strings.extract_hostname("https://test#@google.com") = "test"

strings.from_base64

以下でサポートされています。
strings.from_base64(base64_encoded_string)

説明

関数は、base64 でエンコードされた STRING 値を未加工のバイナリ BYTES 値に変換します。キャストできない値を含む関数呼び出しは、デフォルトで空の BYTES を返します。

パラメータのデータ型

STRING

戻り値の型

BYTES

コードサンプル

Base64 エンコードされた文字列からバイトへの変換

この関数は、Base64 でエンコードされた文字列を未加工のバイナリ バイト表現に変換します。

strings.from_base64("AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA=") = b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000
Failed Conversion（デフォルトは空のバイト）

指定された値が無効な場合、関数はデフォルトで空のバイトを返します。

strings.from_base64("invalid-value") = b'

strings.from_hex

以下でサポートされています。
strings.from_hex(hex_string)

説明

指定された 16 進文字列に関連付けられたバイト列を返します。

パラメータのデータ型

STRING

戻り値の型

BYTES

コードサンプル

指定された 16 進文字列に関連付けられたバイト列を取得します。

例 1

この例では、16 進数以外の文字の変換を示します。

strings.from_hex("str") // returns empty bytes
例 2

この例では、空の文字列を含む入力を示します。

strings.from_hex("") // returns empty bytes
例 3

この例では、16 進文字列の変換を示します。

strings.from_hex("1234") // returns 1234 bytes
例 4

この例では、ASCII 以外の文字の変換を示します。

strings.from_hex("筒纸.中国") // returns empty bytes

strings.ltrim

以下でサポートされています。
strings.ltrim(string_to_trim, cutset)

説明

指定された文字列の先頭の空白を削除します。この関数は、そのカットセットにある先頭の文字を削除します。

パラメータのデータ型

STRING、STRING

戻り値の型

STRING

コードサンプル

ユースケースの例を次に示します。

例 1

この例では、同じ第 1 引数と第 2 引数を使用しています。

strings.ltrim("str", "str") = ""
例 2

この例では、2 番目の引数として空の文字列を使用しています。

strings.ltrim("str", "") = "str"
例 3

この例では、最初の引数として空の文字列を使用し、2 番目の引数として文字列を使用しています。

strings.ltrim("", "str") = ""
例 4

この例では、空白を含む文字列と、2 番目の引数として文字列を使用しています。

strings.ltrim("a aastraa aa ", " a") = "straa aa "

strings.reverse

以下でサポートされています。
strings.reverse(STRING)

説明

入力文字列の逆の文字列を返します。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1

次の例では、短い文字列を渡します。

strings.reverse("str") = "rts"  // The function returns 'rts'.
例 2

次の例では、空の文字列を渡します。

strings.reverse("") = ""
例 3

次の例では、回文を渡します。

strings.reverse("tacocat") = "tacocat"

strings.rtrim

以下でサポートされています。
strings.rtrim(string_to_trim, cutset)

説明

指定された文字列の末尾の空白文字を削除します。そのカットセットに含まれる末尾の文字を削除します。

パラメータのデータ型

STRING、STRING

戻り値の型

STRING

コードサンプル

ユースケースの例を次に示します。

例 1

次の例では、同じ文字列を最初の引数と 2 番目の引数として渡します。

strings.rtrim("str", "str") = ""
例 2

次の例では、2 番目の引数として空の文字列を渡しています。

strings.rtrim("str", "") = "str"
例 3

次の例では、最初の引数として空の文字列を渡し、2 番目の引数として空でない文字列を渡します。

strings.rtrim("", "str") = ""
例 4

次の例では、空白文字を含む文字列を最初の引数として渡し、空でない文字列を 2 番目の引数として渡しています。

strings.rtrim("a aastraa aa ", " a") = "a aasstr"

strings.split

以下でサポートされています。
strings.split(string, delimiter)

説明

区切り文字引数を使用して文字列値を分割します。デフォルトの区切り文字はカンマ（,）です。

パラメータのデータ型

STRING、STRING

戻り値の型

ARRAY_STRINGS

コードサンプル

次のコードサンプルは、strings.split 関数の使用方法の例を示しています。

例: デフォルトで文字列を分割する

次の例では、デフォルトの区切り文字（カンマ）を使用して文字列を分割します。

strings.split("a,b,c,d") = ["a", "b", "c", "d"]
例: コロンで文字列を分割する

次の例では、文字列がコロン（:）ごとに分割されます。

strings.split("a:b:c:d", ":") = ["a", "b", "c", "d"]
例: 区切り文字がない

次の例では、文字列値に区切り文字がありません。

strings.split("a,b,c,d", ":") = ["a,b,c,d"]
例: 空の区切り文字

次の例では、区切り文字の文字列が空です。

strings.split("abc", "") = ["a", "b", "c"]

strings.to_lower

以下でサポートされています。
strings.to_lower(stringText)

説明

この関数は、入力文字列を受け取り、すべての文字を小文字に変更した文字列を返します。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1

次の例では、true が返されます。

"test@google.com" = strings.to_lower($e.network.email.to)

strings.to_upper

以下でサポートされています。
strings.to_upper(string_val)

説明

元の文字列をすべて大文字の英字で返します。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1

次の例では、指定された引数を大文字で返します。

strings.to_upper("example") = "EXAMPLE"

strings.trim

以下でサポートされています。
strings.trim(string_to_trim, cutset)

説明

指定された文字列の先頭と末尾の空白を削除します。また、入力文字列から不要な文字（cutset 引数で指定）を削除します。

パラメータのデータ型

STRING、STRING

戻り値の型

STRING

コードサンプル

ユースケースの例を次に示します。

例 1

次の例では、同じ文字列が入力文字列とカットセットとして渡されるため、空の文字列が返されます。

strings.trim("str", "str") // ""
例 2

次の例では、カットセットとして空の文字列が渡されます。カットセットで削除する文字が指定されていないため、元の文字列 str が返されます。

strings.trim("str", "") = "str"
例 3

次の例では、入力文字列がすでに空で、削除する文字がないため、関数は空の文字列を返します。

strings.trim("", "str") = ""
例 4

次の例では、trim 関数が次のものを削除するため、関数は str を返します。

  • 「a aastraa aa 」の末尾に空白文字が含まれている
  • cutset で指定された文字（スペース、a）
strings.trim("a aastraa aa ", " a") = "str"

strings.url_decode

以下でサポートされています。
strings.url_decode(url_string)

説明

URL 文字列が指定されたら、エスケープ文字をデコードし、エンコードされた UTF-8 文字を処理します。デコードに失敗した場合は空の文字列を返します。

パラメータのデータ型

STRING

戻り値の型

STRING

コードサンプル

例 1

この例では、成功するテストケースを示します。

strings.url_decode("three%20nine%20four") = "three nine four"
例 2

この例では、空の文字列のケースを示します。

strings.url_decode("") // ""
例 3

この例では、アルファベット以外の文字の処理を示します。

strings.url_decode("%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B") // "上海+中國"
例 4

この例では、URL デコードのサンプルを示します。

strings.url_decode("http://www.google.com%3Fparam1%3D%22+1+%3E+2+%22%26param2%3D2%3B") // 'http://www.google.com?param1="+1+>+2+"&param2=2;'

timestamp.as_unix_seconds

以下でサポートされています。
timestamp.as_unix_seconds(timestamp [, time_zone])

説明

この関数は、指定されたタイムスタンプ文字列の Unix エポックからの経過秒数を表す整数を返します。

  • timestamp は、有効なエポック タイムスタンプを表す文字列です。形式は %F %T にする必要があります。
  • time_zone は省略可能で、タイムゾーンを表す文字列です。省略した場合、デフォルトは GMT です。文字列リテラルを使用してタイムゾーンを指定できます。以下のオプションがあります。

以下に、有効な time_zone 指定子の例を示します。これらは、時間抽出関数に 2 番目の引数として渡すことができます。

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

パラメータのデータ型

STRING、STRING

戻り値の型

INT

コードサンプル

例 1

有効なエポック タイムスタンプ

timestamp.as_unix_seconds("2024-02-22 10:43:00") = 1708598580
例 2

America/New_York タイムゾーンの有効なエポック タイムスタンプ

timestamp.as_unix_seconds("2024-02-22 10:43:00", "America/New_York") = 1708616580

timestamp.current_seconds

以下でサポートされています。
timestamp.current_seconds()

説明

現在の時刻を Unix 秒数で表す整数を返します。これは検出のタイムスタンプとほぼ同じで、ルールが実行されるタイミングに基づきます。 この関数は、関数 timestamp.now() と同義です。

パラメータのデータ型

NONE

戻り値の型

INT

コードサンプル

例 1

次の例では、証明書が 24 時間を超えて期限切れの状態になっている場合に true が返されます。現在の Unix 秒を減算して、不等価演算子を使用して比較することで、時間差を計算します。

86400 < timestamp.current_seconds() - $e.network.tls.certificate.not_after

timestamp.get_date

以下でサポートされています。
timestamp.get_date(unix_seconds [, time_zone])

説明

この関数は、タイムスタンプの日を表す YYYY-MM-DD 形式の文字列を返します。

  • unix_seconds は、$e.metadata.event_timestamp.seconds などの Unix エポックからの経過秒数を表す整数か、その値を含むプレースホルダです。
  • time_zone は省略可能で、time_zone を表す文字列です。省略した場合、デフォルトは「GMT」です。文字列リテラルを使用してタイムゾーンを指定できます。次のオプションがあります。
    • TZ データベース名（「America/Los_Angeles」など）。詳しくは、このページの「TZ データベース名」列をご覧ください。
    • (+|-)H[H][:M[M]] 形式の UTC からのタイムゾーン オフセット（例: 「-08:00」）。

以下に、有効な time_zone 指定子の例を示します。これらは、時間抽出関数に 2 番目の引数として渡すことができます。

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

パラメータのデータ型

INT、STRING

戻り値の型

STRING

コードサンプル

例 1

この例では、time_zone 引数が省略されているため、デフォルトの「GMT」になります。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts) = "2024-02-19"
例 2

この例では、文字列リテラルを使用して time_zone を定義します。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts, "America/Los_Angeles") = "2024-02-20"

timestamp.get_minute

以下でサポートされています。
timestamp.get_minute(unix_seconds [, time_zone])

説明

この関数は、分を表す [0, 59] の範囲の整数を返します。

  • unix_seconds は、$e.metadata.event_timestamp.seconds などの Unix エポックからの経過秒数を表す整数か、その値を含むプレースホルダです。
  • time_zone は省略可能で、タイムゾーンを表す文字列です。省略した場合、デフォルトは「GMT」です。文字列リテラルを使用してタイムゾーンを指定できます。次のオプションがあります。
    • TZ データベース名（「America/Los_Angeles」など）。詳しくは、このページの「TZ データベース名」列をご覧ください。
    • (+|-)H[H][:M[M]] 形式の UTC からのタイムゾーン オフセット（例: 「-08:00」）。

以下に、有効な time_zone 指定子の例を示します。これらは、時間抽出関数に 2 番目の引数として渡すことができます。

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

パラメータのデータ型

INT、STRING

戻り値の型

INT

コードサンプル

例 1

この例では、time_zone 引数が省略されているため、デフォルトの「GMT」になります。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15
例 2

この例では、文字列リテラルを使用して time_zone を定義します。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_hour

以下でサポートされています。
timestamp.get_hour(unix_seconds [, time_zone])

説明

この関数は、時刻を表す [0, 23] の範囲の整数を返します。

  • unix_seconds は、$e.metadata.event_timestamp.seconds などの Unix エポックからの経過秒数を表す整数か、その値を含むプレースホルダです。
  • time_zone は省略可能で、タイムゾーンを表す文字列です。省略した場合、デフォルトは「GMT」です。文字列リテラルを使用してタイムゾーンを指定できます。次のオプションがあります。
    • TZ データベース名（「America/Los_Angeles」など）。詳しくは、このページの「TZ データベース名」列をご覧ください。
    • (+|-)H[H][:M[M]] 形式の UTC からのタイムゾーン オフセット（例: 「-08:00」）。

以下に、有効な time_zone 指定子の例を示します。これらは、時間抽出関数に 2 番目の引数として渡すことができます。

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

パラメータのデータ型

INT、STRING

戻り値の型

INT

コードサンプル

例 1

この例では、time_zone 引数が省略されているため、デフォルトの「GMT」になります。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15
例 2

この例では、文字列リテラルを使用して time_zone を定義します。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_day_of_week

以下でサポートされています。
timestamp.get_day_of_week(unix_seconds [, time_zone])

説明

この関数は、日曜日から始まる曜日を表す [1, 7] の範囲の整数を返します。たとえば、1 = 日曜日、2 = 月曜日です。

  • unix_seconds は、$e.metadata.event_timestamp.seconds などの Unix エポックからの経過秒数を表す整数か、その値を含むプレースホルダです。
  • time_zone は省略可能で、time_zone を表す文字列です。省略した場合、デフォルトは「GMT」です。文字列リテラルを使用してタイムゾーンを指定できます。次のオプションがあります。
    • TZ データベース名（「America/Los_Angeles」など）。詳しくは、このページの「TZ データベース名」列をご覧ください。
    • (+|-)H[H][:M[M]] 形式の UTC からのタイムゾーン オフセット（例: 「-08:00」）。

以下に、有効な time_zone 指定子の例を示します。これらは、時間抽出関数に 2 番目の引数として渡すことができます。

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

パラメータのデータ型

INT、STRING

戻り値の型

INT

コードサンプル

例 1

この例では、time_zone 引数が省略されているため、デフォルトの「GMT」になります。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6
例 2

この例では、文字列リテラルを使用して time_zone を定義します。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts, "America/Los_Angeles") = 6

timestamp.get_timestamp

以下でサポートされています。
timestamp.get_timestamp(unix_seconds, optional timestamp_format/time_granularity, optional timezone)

説明

この関数は、タイムスタンプの日を表す YYYY-MM-DD 形式の文字列を返します。

  • unix_seconds は、$e.metadata.event_timestamp.seconds などの Unix エポックからの経過秒数を表す整数か、その値を含むプレースホルダです。
  • timestamp_format は省略可能で、タイムスタンプの形式を表す文字列です。省略した場合、デフォルトは %F %T です。形式は、日時形式文字列または次の時間粒度のいずれかを使用して指定できます。SECOND、MINUTE、HOUR、DATE、WEEK、MONTH、YEAR。その他の形式設定オプションについては、日付と時刻の部分の形式設定要素をご覧ください。
  • time_zone は省略可能で、タイムゾーンを表す文字列です。省略した場合、デフォルトは GMT です。文字列リテラルを使用してタイムゾーンを指定できます。以下のオプションがあります。

以下に、有効な time_zone 指定子の例を示します。これらは、時間抽出関数に 2 番目の引数として渡すことができます。

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

パラメータのデータ型

INT、STRING、STRING

戻り値の型

STRING

コードサンプル

例 1

この例では、time_zone 引数が省略されているため、デフォルトの GMT になります。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts) = "2024-02-22 10:43:51"
例 2

この例では、文字列リテラルを使用して time_zone を定義します。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%F %T", "America/Los_Angeles") = "2024-02-22 10:43:51"
例 3

この例では、文字列リテラルを使用して timestamp_format を定義します。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%Y-%m", "GMT") = "2024-02"
例 4

この例では、UNIX タイムスタンプを秒単位の文字列としてフォーマットします。

timestamp.get_timestamp(1708598631, "SECOND", "GMT") = "2024-02-22 10:43:51"
例 5

この例では、分単位で Unix タイムスタンプを文字列としてフォーマットします。

timestamp.get_timestamp(1708598631, "MINUTE", "GMT") = "2024-02-22 10:43"
例 6

この例では、Unix タイムスタンプを時間単位の文字列としてフォーマットします。

timestamp.get_timestamp(1708598631, "HOUR", "GMT") = "2024-02-22 10"
例 7

この例では、UNIX タイムスタンプを日単位の文字列としてフォーマットします。

timestamp.get_timestamp(1708598631, "DATE", "GMT") = "2024-02-22"
例 8

この例では、UNIX タイムスタンプを週単位の文字列としてフォーマットします。

timestamp.get_timestamp(1708598631, "WEEK", "GMT") = "2024-02-18"
例 9

この例では、Unix タイムスタンプを月単位の文字列としてフォーマットします。

timestamp.get_timestamp(1708598631, "MONTH", "GMT") = "2024-02"
例 10

この例では、UNIX タイムスタンプを年単位の文字列としてフォーマットします。

timestamp.get_timestamp(1708598631, "YEAR", "GMT") = "2024"

timestamp.get_week

以下でサポートされています。
timestamp.get_week(unix_seconds [, time_zone])

説明

この関数は、1 年の中の週を表す [0, 53] の範囲の整数を返します。週は日曜日から始まります。年の最初の日曜日より前の日付は 0 週目です。

  • unix_seconds は、$e.metadata.event_timestamp.seconds などの Unix エポックからの経過秒数を表す整数か、その値を含むプレースホルダです。
  • time_zone は省略可能で、タイムゾーンを表す文字列です。省略した場合、デフォルトは「GMT」です。文字列リテラルを使用してタイムゾーンを指定できます。次のオプションがあります。
    • TZ データベース名（「America/Los_Angeles」など）。詳しくは、このページの「TZ データベース名」列をご覧ください。
    • (+|-)H[H][:M[M]] 形式の UTC からのタイムゾーン オフセット（例: 「-08:00」）。

以下に、有効な time_zone 指定子の例を示します。これらは、時間抽出関数に 2 番目の引数として渡すことができます。

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

パラメータのデータ型

INT、STRING

戻り値の型

INT

コードサンプル

例 1

この例では、time_zone 引数が省略されているため、デフォルトの「GMT」になります。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0
例 2

この例では、文字列リテラルを使用して time_zone を定義します。

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts, "America/Los_Angeles") = 0

timestamp.now

以下でサポートされています。
timestamp.now()

説明

1970-01-01 00:00:00 UTC 以降の秒数を返します。これは Unix エポック時間とも呼ばれます。

戻り値の型

INT

コードサンプル

例 1

次の例では、2024 年 5 月 22 日 18:16:59 に実行されたコードのタイムスタンプを返します。

timestamp.now() = 1716401819 // Unix epoch time in seconds for May 22, 2024 at 18:16:59

window.avg

以下でサポートされています。
window.avg(numeric_values [, should_ignore_zero_values])

説明

入力値（整数または浮動小数点数）の平均値を返します。省略可能な 2 番目の引数を true に設定すると、ゼロ値は無視されます。

パラメータのデータ型

INT|FLOAT

戻り値の型

FLOAT

コードサンプル

例 1

この例では、整数の平均を示します。

// This rule sets the outcome $size_mode to the average
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 2.5 if the event file size values in the match window are 1, 2, 3 and 4
例 2

この例では、浮動小数点数の平均を示します。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 1.75 if the event file size values in the match window are 1.1 and 2.4
例 3

負の入力の平均

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0.6 if the event file size values in the match window are -1.1, 1.1, 0.0 and 2.4
例 4

0 は 0 を返す

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0 if the event file size values in the match window is 0
例 5

0 値を無視する

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size, true) // yields 394 if the event file size values in the match window are 0, 0, 0 and 394

window.first

以下でサポートされています。
window.first(values_to_sort_by, values_to_return)

説明

この集計関数は、一致ウィンドウ内で最も相関性の高い int 値を持つイベントから派生した文字列値を返します。たとえば、一致ウィンドウ内でタイムスタンプが最も低いイベント（最も早いイベント）からユーザー ID を取得するといったユースケースがあります。

パラメータのデータ型

INT、STRING

戻り値の型

STRING

コードサンプル

一致ウィンドウ内で相関関係のある整数値が最も低いイベントから派生した文字列値を取得します。

// This rule sets the outcome $first_event to the lowest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $first_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v1 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.last

以下でサポートされています。
window.last(values_to_sort_by, values_to_return)

説明

この集計関数は、一致ウィンドウで最も相関性の高い整数値を持つイベントから派生した文字列値を返します。たとえば、一致ウィンドウ内でタイムスタンプが最も低い（タイムスタンプが最も高い）イベントからユーザー ID を取得するといったユースケースがあります。

パラメータのデータ型

INT、STRING

戻り値の型

STRING

コードサンプル

一致ウィンドウ内で相関関係が最も高い整数値を持つイベントから派生した文字列値を取得します。

// This rule sets the outcome $last_event to the highest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $last_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v3 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.median

以下でサポートされています。
window.median(numeric_values, should_ignore_zero_values)

説明

入力値の中央値を返します。中央値が 2 つある場合、1 つだけが非決定論的に選択され、戻り値として返されます。

パラメータのデータ型

INT|FLOAT、BOOL

戻り値の型

FLOAT

コードサンプル

例 1

この例では、入力値がゼロでない場合に中央値を返します。

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 2 if the file sizes in the match window are [1, 2, 3]
  condition:
      $e
}
例 2

この例では、無視すべきでないゼロ値が入力に含まれている場合に中央値を返します。

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}
例 3

この例では、無視する必要があるゼロ値が入力に含まれている場合に中央値を返します。

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size, true) // returns 2 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}
例 4

この例では、入力に無視すべきゼロ値がすべて含まれている場合に中央値を返します。

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 0 if the file sizes in the match window are [0,0]
  condition:
      $e
}
例 5

この例では、中央値が複数ある場合、1 つの中央値のみが返されることを示します。

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [1, 2, 3, 4]
  condition:
      $e
}

window.mode

以下でサポートされています。
window.mode(values)

説明

入力値の最頻値を返します。モード値の候補が複数ある場合、それらの値のうちの 1 つが非決定論的に選択され、戻り値として返されます。

パラメータのデータ型

INT|FLOAT|STRING

戻り値の型

STRING

コードサンプル

例 1

一致ウィンドウ内の値のモードを取得します。

// This rule sets the outcome $size_mode to the most frequently occurring
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.mode($e.file.size) // yields 1.6 if the event file size values in the match window are 1.6, 2, and 1.6

window.range

以下でサポートされています。
window.range(numeric_values, optional should_ignore_zero_values)

説明

入力値の範囲（最小値と最大値を含む）を返します。各値には整数または浮動小数点を使用できます。省略可能な 2 番目の引数を true に設定すると、ゼロ値は無視されます。

パラメータのデータ型

INT|FLOAT、BOOL

戻り値の型

ARRAY_FLOATS

コードサンプル

次のコードサンプルは、window.range 関数の使用方法の例を示しています。

例: 最小整数と最大整数

この例では、整数の最小値と最大値を示します。

window.range([1, 2, 3, 4], false) = [1.000000, 4.000000]
例: 最小値と最大値の浮動小数点数

この例では、浮動小数点数の最小値と最大値を示します。

window.range([1.100000, 39.400000, 2.400000], false) = [1.100000, 39.400000]
例: 負の整数の最小値と最大値

この例では、負の整数の最小値と最大値を示します。

window.range([-1.100000, 1.100000, 0.000000, 2.400000], false) = [-1.100000, 2.400000]
例: 0 値を無視する

この例は、2 番目のパラメータを設定するときに 0 の値が無視される方法を示しています。

window.range([0, 0, 0, 394, 1], true) = [1.000000, 394.000000]

window.stddev

以下でサポートされています。
window.stddev(numeric_values)

説明

一致ウィンドウ内の入力値の標準偏差を返します。

パラメータのデータ型

INT|FLOAT

戻り値の型

FLOAT

コードサンプル

例 1

この例では、一致ウィンドウ内の整数の標準偏差を返します。

// This rule creates a detection when the file size stddev in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.0 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 2
例 2

この例では、一致ウィンドウ内の浮動小数点数の標準偏差を返します。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.488686 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 2
例 3

この例では、一致ウィンドウ内の負の数値を含む標準偏差を返します。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 48.644972 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 2
例 4

この例では、一致ウィンドウ内のすべての値が同じ場合に、ゼロの標準偏差を返します。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 2
例 5

この例では、正と負の数値を含む一致ウィンドウの標準偏差を返します。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

window.variance

以下でサポートされています。
window.variance(values)

説明

この関数は、入力値の指定された分散を返します。

パラメータのデータ型

INT|FLOAT

戻り値の型

FLOAT

コードサンプル

例 1

この例では、すべての整数の分散を返します。

// This rule creates a detection when the file size variance in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 16 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 10
例 2

この例では、すべての浮動小数点数の分散を返します。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 20.148300 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 10
例 3

この例では、負の数値の分散を返します。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 2366.333333 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 10
例 4

この例では、小さな分散値が返されます。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [0.000000, 0.000000, 0.000100].
condition:
  $e and #p1 > 10
例 5

この例では、分散がゼロになります。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 10
例 6

この例では、正の数値と負の数値の分散を返します。

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。