此页面由 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 处的 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 表示数组中的倒数第二个元素。

形参数据类型

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

说明

返回数组中的最小元素；如果数组为空，则返回零。如果将第二个可选实参设置为 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

假整数 (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 哈希值。此函数会返回范围为 [2, 0xFFFFFFFFFFFFFFFF] 的无符号 INT 值。

形参数据类型

BTYE，STRING

返回类型

INT

代码示例

id_fingerprint = hash.fingerprint2011("user123")

群组

支持的平台：

搜索

group(field1, field2, field3, ...)

说明

将类型相似的字段分组到占位变量中。

在 UDM 搜索中，分组字段用于搜索多个类似类型的字段。与分组字段类似，组函数可让您选择要分组在一起以触发检测的字段。您可以使用 group 函数来收集有关不同名词类型中特定实体（例如主机名、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

此示例返回负数的上限。

math.ceil(0-1.200000) = -1

示例 3

此示例返回 0，因为该数字对于 64 位整数来说过大，无法计算其上限。

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

说明

返回两个地理位置（坐标）之间的距离（以米为单位）。如果坐标无效，则返回 -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

此示例包含一个负双精度浮点值、一个零 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)（包含 0，不包含 1）内生成 DOUBLE 类型的伪随机值。

返回类型

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

此示例返回负整数实参的平方根。

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 模式中用英文括号括起来的对应组匹配的文本插入到 replacementText 中。使用 \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)

说明

此函数用于根据确定性抽样策略确定是否包含某个事件。此函数返回：

true 表示一部分输入值，相当于 (rateNumerator / rateDenominator)，表示相应事件应纳入样本中。
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 中的第一个非 null 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

以下示例尝试合并事件 $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”）。此外，超过 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

此示例使用非 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)

说明

函数接受两个字符串 (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)

说明

从给定字符串中剪裁前导空格。此函数会移除 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)

说明

从给定字符串中剪裁尾随空格。移除该 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。如需了解详情，请参阅维基百科上的 tz 数据库时区列表。
- 相对于世界协调时间 (UTC) 的时区偏离值，格式为 (+|-)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

有效的纪元时间戳，时区为 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”。您可以使用字符串字面量来指定时区。选项包括：
- TZ 数据库名称，例如“America/Los_Angeles”。如需了解详情，请参阅本页中的“TZ 数据库名称”列
- 相对于世界协调时间 (UTC) 的时区偏离值，格式为 (+|-)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

代码示例

示例 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”。您可以使用字符串字面量来指定时区。选项包括：
- TZ 数据库名称，例如“America/Los_Angeles”。如需了解详情，请参阅本页中的“TZ 数据库名称”列
- 相对于世界协调时间 (UTC) 的时区偏离值，格式为 (+|-)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”。您可以使用字符串字面量来指定时区。选项包括：
- TZ 数据库名称，例如“America/Los_Angeles”。如需了解详情，请参阅本页中的“TZ 数据库名称”列
- 相对于世界协调时间 (UTC) 的时区偏离值，格式为 (+|-)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”。您可以使用字符串字面量来指定时区。选项包括：
- TZ 数据库名称，例如“America/Los_Angeles”。如需了解详情，请参阅本页中的“TZ 数据库名称”列
- 相对于世界协调时间 (UTC) 的时区偏离值，格式为 (+|-)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_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。如需了解详情，请参阅维基百科上的 tz 数据库时区列表。
- 相对于世界协调时间 (UTC) 的时区偏离值，格式为 (+|-)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”。您可以使用字符串字面量来指定时区。选项包括：
- TZ 数据库名称，例如“America/Los_Angeles”。如需了解详情，请参阅本页中的“TZ 数据库名称”列
- 相对于世界协调时间 (UTC) 的时区偏离值，格式为 (+|-)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 纪元时间。

返回类型

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 返回 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