本頁面由 Cloud Translation API 翻譯而成。

函式

支援的國家/地區：

Google SecOps SIEM

本節說明可在規則、搜尋和資訊主頁查詢中使用的 YARA-L 2.0 函式。

另請參閱適用於資訊主頁的 YARA-L 2.0 函式，以及使用 YARA-L 2.0 搜尋時的統計資料和匯總。

這些函式可用於 YARA-L 查詢的下列部分：

「events」專區。
BOOL_CLAUSE 結果部分的條件。

arrays.concat

支援的國家/地區：

規則搜尋

arrays.concat(string_array, string_array)

說明

複製原始字串陣列中的元素，然後傳回新的字串陣列。

參數資料類型

ARRAY_STRINGS，ARRAY_STRINGS

傳回類型

ARRAY_STRINGS

程式碼範例

範例 1

以下範例會串連兩個不同的字串陣列。

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

範例 2

以下範例會使用空字串串連陣列。

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

範例 3

以下範例會串連空陣列。

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

arrays.index_to_float

支援的國家/地區：

規則搜尋

arrays.index_to_float(array, index)

說明

傳回陣列中指定索引位置的元素。該索引處的元素會以浮點數形式傳回。

索引是整數值，代表陣列中元素的位置。根據預設，陣列的第一個元素索引為 0，最後一個元素的索引為 n-1，其中 n 是陣列的大小。負數索引可存取陣列元素，相對於陣列結尾。舉例來說，索引 -1 是指陣列中的最後一個元素，索引 -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)

說明

傳回陣列中指定索引的值 (整數)。

參數資料類型

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 的浮點數陣列擷取元素。

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

範例 5

這個函式會從索引 0 的整數陣列擷取元素。

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 則是指陣列中的倒數第二個元素。

參數資料類型

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

這個範例會使用分隔符號，將陣列與非空值元素聯結。

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

範例 2

這個範例會將陣列與空值元素和分隔符號聯結。

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

範例 3

這個範例會將陣列與非空值元素聯結，且不含分隔符號。

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)

說明

傳回陣列中的最大元素，如果陣列為空白，則傳回零。

參數資料類型

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])

說明

傳回陣列中的最小元素，如果陣列空白，則傳回零。如果將第二個選用引數設為 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

這個範例使用含有兩個元素的字串陣列。

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

範例 2

這個範例使用包含 3 個元素的 int 陣列。

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="

轉換失敗 (預設為選填字串)

如果提供的位元組值無效，函式會預設為 "invalid bytes"。

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

cast.as_bool

支援的國家/地區：

規則搜尋

cast.as_bool(string_or_int)

說明

函式會將 int 或字串值轉換為布林值。如果函式呼叫的值無法轉換，就會傳回 FALSE。只會針對整數 1 和不區分大小寫的字串「true」傳回 TRUE。

參數資料類型

INT|STRING

傳回類型

BOOL

程式碼範例

範例 1

這個範例說明如何轉換非布林值字串

cast.as_bool("123") = false

範例 2

Truthy 整數 (1)

cast.as_bool(1) = true

範例 3

Truthy 字串

cast.as_bool("true") = true

範例 4

大寫的真值字串

cast.as_bool("TRUE") = true

範例 5

負整數

cast.as_bool(0-1) = false

範例 6

False 整數 (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"

轉換失敗 (預設為選填字串)

如果提供的值無效，函式預設會使用字串「"casting error"」。

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

指紋

支援的國家/地區：

規則

hash.fingerprint2011(byteOrString)

說明

這個函式會計算輸入位元組序列或字串的 fingerprint2011 雜湊值。這個函式會傳回 INT 範圍內的無符號 [2, 0xFFFFFFFFFFFFFFFF] 值。

參數資料類型

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 Epoch 時間起算的秒數) 相差超過 5 分鐘，這個範例就會傳回 True，無論事件發生在指定時間之前或之後都一樣。對 math.abs 的呼叫不得取決於多個變數或預留位置。舉例來說，您無法將下列範例中硬式編碼的時間值 1643687343 替換為 $e2.metadata.event_timestamp.seconds。

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

math.ceil

支援的國家/地區：

規則搜尋

math.ceil(number)

說明

傳回大於或等於指定數字的最小整數 (無條件進位)。如果輸入為空值或太大而無法放入 int64，則會傳回 0。

參數資料類型

FLOAT

傳回類型

INT

程式碼範例

本節包含使用 math.ceil 的範例。

範例 1

這個範例會傳回整數的上限。

math.ceil(2.000000) = 2

範例 2

這個範例會傳回負數的上限。

math.ceil(0-1.200000) = -1

範例 3

這個範例會傳回 0，因為數字太大，無法以 64 位元整數表示。

math.ceil(184467440737095516160.0) = 0

math.floor

支援的國家/地區：

規則搜尋

math.floor(float_val)

說明

傳回不大於所提供值的最大整數值 (向下捨入)。如果輸入為空值或過大而無法納入 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))

說明

傳回兩個地理位置 (座標) 之間的距離，單位為公尺。如果座標無效，則傳回 -1。

參數資料類型

FLOAT、FLOAT、FLOAT、FLOAT

傳回類型

FLOAT

程式碼範例

範例 1

以下範例會傳回距離，前提是所有參數都是有效的座標：

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

範例 2

以下範例會傳回距離，因為其中一個參數是截斷的座標：

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

範例 3

以下範例會在其中一個參數是無效座標時傳回 -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

這個範例包含一個負數倍精確度值、一個零 INT64 值和一個正數 INT64 值。

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

範例 3

這個範例包含一個負數 double、一個零 INT64 和一個負數 INT64 值。

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

範例 4

這個範例包含兩個負數倍精確度浮點數和一個零 INT64 值。

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

範例 5

這個範例包含一個負數雙精度值和兩個相同的值。

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)

說明

傳回第一個引數的第二個引數次方。如果發生溢位，就會傳回 0。

參數資料類型

底數：INT|FLOAT 指數：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.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-L 語法 - 與事件相關。以下是這個語法的一般表示法：
```
$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)

說明

使用引數中提供的規則運算式模式，從字串擷取資料。

這個函式會採用兩個引數：

stringText：要搜尋的原始字串。
regex：表示要搜尋模式的規則運算式。

規則運算式可包含 0 或 1 個括號中的擷取群組。如果規則運算式包含 0 個擷取群組，函式會傳回第一個相符的完整子字串。如果規則運算式包含 1 個擷取群組，函式會傳回擷取群組的第一個相符子字串。定義兩個以上的擷取群組會傳回編譯器錯誤。

參數資料類型

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。以下範例包含一個擷取群組。

"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)

說明

執行規則運算式取代作業。

這個函式需要三個引數：

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")

sample_rate

支援的國家/地區：

規則

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 編碼字串做為引數。如果 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

下列範例會使用兩個以上的引數呼叫 coalesce 函式。這項條件會比較事件 $e 中的第一個非空值 IP 位址，與參照清單 ip_watchlist 中的值。在此呼叫中合併引數的順序，與規則條件中列舉引數的順序相同：

$e.principal.ip 會最先受到評估。
$e.src.ip。
$e.target.ip。
如果先前的 ip 欄位未設定，則最後會傳回「No IP」字串做為預設值。

strings.coalesce($e.principal.ip, $e.src.ip, $e.target.ip, "No IP") in %ip_watchlist

範例 3

下列範例會嘗試從事件 principal.hostname 和事件 $e2 合併 $e1。由於引數是不同的事件變數，因此會傳回編譯器錯誤。

// 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」)。此外，如果浮點數的小數位數超過 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

這個範例會傳回 true，因為字串含有子字串「is」。

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

範例 2

這個範例會傳回 false，因為字串沒有子字串「that」。

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

strings.count_substrings

支援的國家/地區：

規則搜尋

strings.count_substrings(string_to_search_in, substring_to_count)

說明

如果提供字串和子字串，則會傳回 int64，表示子字串在字串中不重疊的出現次數。

參數資料類型

STRING，STRING

傳回類型

INT

程式碼範例

本節包含的範例會計算子字串在指定字串中出現的次數。

範例 1

這個範例使用非空值字串和非空值的單一子字串字元。

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

範例 2

本範例使用非空值字串和非空值子字串 (長度超過一個字元)。

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

範例 3

這個範例使用非空值字串和空白子字串。

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

範例 4

這個範例使用空白字串和長度超過一個字元的非空值子字串。

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

範例 5

這個範例使用空字串和空子字串。

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

範例 6

本範例使用非空字串和非空子字串，且子字串長度超過一個字元，出現次數也超過一次。

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

範例 7

這個範例使用非空值字串和非空值子字串，且子字串長度超過一個字元，出現次數也超過一次。這項功能會醒目顯示重疊子字串出現次數的限制

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

strings.ends_with

支援的國家/地區：

規則搜尋

strings.ends_with(value, suffix)

說明

函式會採用兩個字串 (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

隨機字串，而非網址

strings.extract_domain("1234") = ""

範例 3

多個反斜線

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

範例 4

妥善處理非字母字元

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

範例 5

處理 URI

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

範例 6

實際網址前有多個字元

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

範例 7

URI 中的特殊字元 #

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

範例 8

網址中的特殊字元 #

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

隨機字串，而非網址

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

實際網址前有多個字元

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

範例 7

URI 中的特殊字元 #

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

範例 8

網址中的特殊字元 #

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

轉換失敗 (預設為空白位元組)

如果提供的值無效，函式預設為空白位元組。

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

strings.from_hex

支援的國家/地區：

規則搜尋

strings.from_hex(hex_string)

說明

傳回與指定十六進位字串相關聯的位元組。

參數資料類型

STRING

傳回類型

BYTES

程式碼範例

取得與特定十六進位字串相關聯的位元組。

範例 1

這個範例顯示非十六進位字元的轉換。

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

範例 2

這個範例顯示輸入內容為空字串。

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

範例 3

這個範例顯示十六進位字串轉換。

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

這個範例使用相同的第一個和第二個引數。

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

範例 2

這個範例使用空字串做為第二個引數。

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

範例 3

這個範例使用空字串做為第一個引數，並使用字串做為第二個引數。

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

範例 4

這個範例使用含有空格的字串，以及做為第二個引數的字串。

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

以下範例會將相同字串做為第一個和第二個引數傳遞。

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

範例 2

以下範例會將空字串做為第二個引數傳遞。

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

範例 3

以下範例會將空字串做為第一個引數傳遞，並將非空字串做為第二個引數傳遞。

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

範例 4

以下範例會將含有空白字元的字串做為第一個引數傳遞，並將非空白字串做為第二個引數傳遞。

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

在下列範例中，相同的字串會做為輸入字串和 cutset 傳遞，因此會產生空字串。

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

範例 2

在下列範例中，系統會將空字串當做 cutset 傳遞，因此會產生原始字串 str，因為 cutset 中未指定要移除的字元。

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

範例 3

在下列範例中，函式會產生空字串，因為輸入字串已為空白，且沒有要移除的字元。

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

範例 4

在下列範例中，函式會產生 str，因為 trim 函式會移除下列項目：

「a aastraa aa 」中的尾端空白字元
cutset 中指定的字元 (空格、a)

strings.trim("a aastraa aa ", " a") = "str"

strings.url_decode

支援的國家/地區：

規則搜尋

strings.url_decode(url_string)

說明

提供網址字串後，解碼逸出字元並處理已編碼的 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

這個範例顯示網址解碼範例。

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。您可以使用字串常值指定時區。可用的選項如下：
- TZ 資料庫名稱，例如 America/Los_Angeles。詳情請參閱 Wikipedia 的 tz 資料庫時區清單。
- 與世界標準時間的時區偏移量，格式為 (+|-)H[H][:M[M]]，例如「-08:00」。

以下是有效的 time_zone 規範符示例，您可以將這些規範符做為第二個引數傳遞至時間擷取函式：

"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

有效的 Unix 時間戳記，時區為 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 是代表 Unix 紀元後經過秒數的整數，例如 $e.metadata.event_timestamp.seconds，或是包含該值的預留位置。
time_zone 為選用項目，代表時區的字串。如果省略，預設值為「GMT」。您可以使用字串常值指定時區。選項包括：
- 時區資料庫名稱，例如「America/Los_Angeles」。詳情請參閱這個頁面的「時區資料庫名稱」欄
- 與世界標準時間的時區偏移量，格式為 (+|-)H[H][:M[M]]，例如「-08:00」。

以下是有效的時區指定符示例，您可以將這些指定符做為第二個引數傳遞至時間擷取函式：

"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 是代表 Unix 紀元後經過秒數的整數，例如 $e.metadata.event_timestamp.seconds，或是包含該值的預留位置。
time_zone 為選用項目，代表時區的字串。如果省略，預設值為「GMT」。您可以使用字串常值指定時區。選項包括：
- 時區資料庫名稱，例如「America/Los_Angeles」。詳情請參閱這個頁面的「時區資料庫名稱」欄
- 與世界標準時間的時區偏移量，格式為 (+|-)H[H][:M[M]]，例如「-08:00」。

以下是有效的 time_zone 規範符示例，您可以將這些規範符做為第二個引數傳遞至時間擷取函式：

"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 是代表 Unix 紀元後經過秒數的整數，例如 $e.metadata.event_timestamp.seconds，或是包含該值的預留位置。
time_zone 為選用項目，代表時區的字串。如果省略，預設值為「GMT」。您可以使用字串常值指定時區。選項包括：
- 時區資料庫名稱，例如「America/Los_Angeles」。詳情請參閱這個頁面的「時區資料庫名稱」欄
- 與世界標準時間的時區偏移量，格式為 (+|-)H[H][:M[M]]，例如「-08:00」。

以下是有效的 time_zone 規範符示例，您可以將這些規範符做為第二個引數傳遞至時間擷取函式：

"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 是代表 Unix 紀元後經過秒數的整數，例如 $e.metadata.event_timestamp.seconds，或是包含該值的預留位置。
time_zone 為選用項目，代表時區的字串。如果省略，預設值為「GMT」。您可以使用字串常值指定時區。選項包括：
- 時區資料庫名稱，例如「America/Los_Angeles」。詳情請參閱這個頁面的「時區資料庫名稱」欄
- 與世界標準時間的時區偏移量，格式為 (+|-)H[H][:M[M]]，例如「-08:00」。

以下是有效的時區指定符示例，您可以將這些指定符做為第二個引數傳遞至時間擷取函式：

"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 是代表 Unix 紀元後經過秒數的整數，例如 $e.metadata.event_timestamp.seconds，或是包含該值的預留位置。
timestamp_format 為選用項目，是代表時間戳記格式的字串。如未填寫此欄位，則預設值為 %F %T。您可以透過日期時間格式字串或下列任一時間精細度指定格式：SECOND、MINUTE、HOUR、DATE、WEEK、MONTH 或 YEAR。如需更多格式設定選項，請參閱日期和時間部分的格式元素
time_zone 為選用項目，代表時區的字串。如果省略，預設值為 GMT。您可以使用字串常值指定時區。可用的選項如下：
- IANA 時區 (TZ) 資料庫名稱，例如 America/Los_Angeles。詳情請參閱 Wikipedia 上的 tz 資料庫時區清單。
- 與世界標準時間的時區偏移量，格式為 (+|-)H[H][:M[M]]，例如「-08:00」。

以下是有效的 time_zone 規範符示例，您可以將這些規範符做為第二個引數傳遞至時間擷取函式：

"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])

說明

這個函式會傳回 [0, 53] 範圍內的整數，代表一年中的週數。一週以星期日開始。一年中第一個星期日之前的日期為第 0 週。

unix_seconds 是代表 Unix 紀元後經過秒數的整數，例如 $e.metadata.event_timestamp.seconds，或是包含該值的預留位置。
time_zone 為選用項目，代表時區的字串。如果省略，預設值為「GMT」。您可以使用字串常值指定時區。選項包括：
- 時區資料庫名稱，例如「America/Los_Angeles」。詳情請參閱這個頁面的「時區資料庫名稱」欄
- 與世界標準時間的時區偏移量，格式為 (+|-)H[H][:M[M]]，例如「-08:00」。

以下是有效的 time_zone 規範符示例，您可以將這些規範符做為第二個引數傳遞至時間擷取函式：

"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 Epoch 時間。

傳回類型

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])

說明

傳回輸入值的平均值 (可以是整數或浮點數)。將選用的第二個引數設為 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 returns 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)

說明

這項匯總函式會傳回字串值，該值衍生自相符時間範圍內相關整數值最低的事件。舉例來說，您可以在比對時間範圍內，從時間戳記最低的事件 (最早的事件) 取得使用者 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

這個範例顯示，如果有多個中位數，系統只會傳回一個中位數。

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)

說明

傳回輸入值的眾數。如果有多個可能的模式值，系統只會非決定性地選擇其中一個值做為傳回值。

參數資料類型

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)

說明

傳回找到的輸入值範圍 (包括最小值和最大值)。每個值可以是整數或浮點數。將選填的第二個引數設為 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 值

這個範例說明設定第二個參數時，系統如何忽略 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 專業人員尋求答案。