重复字段
在统一数据模型 (UDM) 中,某些字段被标记为重复,这表示它们是值列表或其他类型的消息。本文档介绍了如何针对重复的 UDM 字段使用表达式、占位符、数组索引和重复消息。
布尔表达式和重复字段
经过修改和未经修改的布尔表达式可以作用于重复字段。
请考虑以下事件:
event_original {
principal {
// ip is a repeated field
ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]
hostname: "host"
}
}
修改后的表达式
在重复字段的表达式中使用 any 和 all 修饰符。
any- 如果重复字段的任何元素满足条件,则整个事件都满足条件。例如:event_original满足any $e.principal.ip = "192.0.2.1"event_original失败any $e.repeated_field.field_a = "9.9.9.9"
all- 如果重复字段的所有元素都满足条件,则整个事件都满足条件。例如:event_original满足net.ip_in_range_cidr(all $e.principal.ip, "192.0.2.0/8")event_original失败all $e.principal.ip = "192.0.2.2"
使用 any 或 all 编写条件时,请注意,使用 not 对条件求反可能与使用求反运算符的含义不同。
例如:
not all $e.principal.ip = "192.168.12.16"会检查是否并非所有 IP 地址都与192.168.12.16匹配,这意味着查询会检查是否至少有一个 IP 地址与192.168.12.16不匹配all $e.principal.ip != "192.168.12.16"会检查是否所有 IP 地址都与192.168.12.16不匹配,这意味着查询会检查是否没有 IP 地址与192.168.12.16匹配
限制:
any和all运算符仅与重复字段(而非标量字段)兼容。any和all不能用于联接两个重复字段。例如,any $e1.principal.ip = $e2.principal.ip无效。- 引用列表表达式不支持
any和all运算符。
未经修改的表达式
例如,假设有一个事件,其中 security_result 字段是重复字段:
security_result[0].threat_id = "threat_a"
security_result[1].threat_id = "threat_b"
security_result[1].rule_name = "rule_b"
security_result[2].threat_id = "threat_c"
未经修改的搜索查询(例如 $e.security_result.rule_name = "")会返回此事件,因为如果任何元素满足条件,则默认重复字段行为会评估为 true。该查询与索引 0 和索引 2 匹配,其中 rule_name 字段不存在(空字符串)。
同样,该事件也与 $e.security_result.rule_name != "" 查询匹配,因为在索引 1 处满足了条件。
如需检查所有 security_result 元素中是否都不存在 rule_name 字段,请使用 all 运算符:all $e.security_result.rule_name = ""。此查询与示例事件不匹配。
对于未修改的表达式,重复字段中的每个元素都是单独处理的。如果事件的重复字段包含 n 个元素,则查询会应用于事件的 n 个副本,其中每个副本都包含重复字段的一个元素。这些副本是临时性的,不会存储。
对于上述 event_original 示例数据集,规则会应用于以下副本:
| 活动文案 | principal.ip | principal.hostname |
|---|---|---|
| event_copy_1 | "192.0.2.1" | "host" |
| event_copy_2 | "192.0.2.2" | "host" |
| event_copy_3 | "192.0.2.3" | "host" |
如果任何事件副本满足重复字段上的所有未修改条件,则事件整体满足所有条件。因此,如果您对重复字段设置了多个条件,则单个事件副本必须满足所有条件。以下查询示例使用前面的示例数据集来演示此行为。
示例:未修改的表达式
针对 event_original 示例数据集运行时,以下规则会返回一个匹配项,因为 event_copy_1 满足所有事件谓词:
rule repeated_field_1 {
meta:
events:
net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/8") // Checks if IP address matches 192.x.x.x
$e.principal.ip = "192.0.2.1"
condition:
$e
}
针对 event_original 示例数据集运行时,以下规则不会返回匹配项,因为 $e.principal.ip 中没有满足所有事件谓词的事件副本。
rule repeated_field_2 {
meta:
events:
$e.principal.ip = "192.0.2.1"
$e.principal.ip = "192.0.2.2"
condition:
$e
}
重复字段上的修改后表达式与重复字段上的未修改表达式兼容,因为每个事件副本的元素列表都相同。请参考以下规则:
rule repeated_field_3 {
meta:
events:
any $e.principal.ip = "192.0.2.1"
$e.principal.ip = "192.0.2.3"
condition:
$e
}
该规则会应用于以下副本:
| 活动文案 | principal.ip | any $e.principal.ip |
|---|---|---|
| event_copy_1 | "192.0.2.1" | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
| event_copy_2 | "192.0.2.2" | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
| event_copy_3 | "192.0.2.3" | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
在这种情况下,所有副本都满足 any $e.principal.ip = "192.0.2.1",但只有 event_copy_3 满足 $e.principal.ip = "192.0.2.3"。因此,整个事件都会匹配。
这些表达式类型还可以这样理解:
- 使用
any或all的重复字段上的表达式会针对event_original中的列表执行操作。 - 不使用
any或all的重复字段表达式会对单个event_copy_n事件执行操作。
占位符和重复字段
重复字段可与占位符分配搭配使用。与重复字段上未修改的表达式类似,系统会为每个元素创建事件的副本。同样以 event_copy 为例,对于每个事件副本,占位符会采用 event_copy_n 的重复字段值,其中 n 是事件副本编号。如果在匹配部分中使用占位符,可能会导致多个匹配项。
示例:重复字段占位符
以下示例会生成一个匹配项。对于 `event_copy_1`,`$ip` 占位符等于 `192.0.2.1`,这满足规则中的谓词。匹配项的事件样本包含一个元素 `event_original`。
// Generates 1 match.
rule repeated_field_placeholder1 {
meta:
events:
$ip = $e.principal.ip
$ip = "192.0.2.1"
$host = $e.principal.hostname
match:
$host over 5m
condition:
$e
}
以下示例会生成三个匹配项。对于每个不同的 event_copy_n 副本,$ip 占位符等于不同的值。分组是在 $ip 上完成的,因为它位于匹配部分。因此,您会得到三个匹配项,其中每个匹配项的 $ip 匹配变量都有不同的值。每个匹配项都具有相同的事件样本:单个元素 event_original。
// Generates 3 matches.
rule repeated_field_placeholder2 {
meta:
events:
$ip = $e.principal.ip
net.ip_in_range_cidr($ip, "192.0.2.0/8") // Checks if IP matches 192.x.x.x
match:
$ip over 5m
condition:
$e
}
使用分配给重复字段的占位符的结果
占位符会分配给每个重复字段的每个元素,而不是整个列表。在 outcome 部分中使用时,系统只会使用满足前面部分条件的元素来计算结果。
请参考以下规则:
rule outcome_repeated_field_placeholder {
meta:
events:
$ip = $e.principal.ip
$ip = "192.0.2.1" or $ip = "192.0.2.2"
$host = $e.principal.hostname
match:
$host over 5m
outcome:
$o = array_distinct($ip)
condition:
$e
}
此规则有四个执行阶段。第一阶段是事件复制:
| 活动文案 | $ip | $host | $e |
|---|---|---|---|
| event_copy_1 | "192.0.2.1" | "host" | event_id |
| event_copy_2 | "192.0.2.2" | "host" | event_id |
| event_copy_3 | "192.0.2.3" | "host" | event_id |
然后,事件部分会过滤掉不符合过滤条件的行:
| 活动文案 | $ip | $host | $e |
|---|---|---|---|
| event_copy_1 | "192.0.2.1" | "host" | event_id |
| event_copy_2 | "192.0.2.2" | "host" | event_id |
event_copy_3 已被滤除,因为 "192.0.2.3" 不满足 $ip = "192.0.2.1" or $ip = "192.0.2.2"。
然后,match 部分将按匹配变量进行分组依据,outcome 部分将对每个组执行汇总:
| $host | $o | $e |
|---|---|---|
| "host" | ["192.0.2.1", "192.0.2.2"] | event_id |
$o = array_distinct($ip) 是使用上一阶段(而非事件复制阶段)的$ip计算得出的。
最后,condition 部分将过滤每个组。由于此规则仅检查 $e 是否存在,因此前面的行将产生一个检测结果。
$o 并不包含 $e.principal.ip 中的所有元素,因为并非所有元素都满足事件部分中的所有条件。不过,e.principal.ip 的所有元素都会出现在事件示例中,因为事件示例使用的是 event_original。
数组索引
您可以对重复字段执行数组索引。如需访问第 n 个重复字段元素,请使用标准列表语法(元素从 0 开始编制索引)。越界元素会返回默认值。
$e.principal.ip[0] = "192.168.12.16"$e.principal.ip[999] = ""如果元素少于 1, 000 个,则计算结果为true。
限制:
- 索引必须是非负整数字面量。例如,
$e.principal.ip[-1]无效。 - 类型为
int的值(例如,设置为int的占位符)不计入在内。 - 数组索引不能与
any或all结合使用。例如,any $e.intermediary.ip[0]无效。 - 数组索引不能与映射语法结合使用。例如,
$e.additional.fields[0]["key"]无效。 - 如果字段路径包含多个重复字段,则所有重复字段都必须使用数组索引。例如,
$e.intermediary.ip[0]无效,因为intermediary和ip都是重复字段,但只有ip有索引。
重复消息
当 message 字段重复时,会产生一个意外效果,即降低匹配的可能性。以下示例对此进行了说明。
请考虑以下事件:
event_repeated_message {
// about is a repeated message field.
about {
// ip is a repeated string field.
ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]
hostname: "alice"
}
about {
hostname: "bob"
}
}
如针对重复字段上未修改的表达式所述,系统会为重复字段的每个元素创建事件的临时副本。请参考以下规则:
rule repeated_message_1 {
meta:
events:
$e.about.ip = "192.0.2.1"
$e.about.hostname = "bob"
condition:
$e
}
该规则会应用于以下副本:
| 活动文案 | about.ip | about.hostname |
|---|---|---|
| event_copy_1 | "192.0.2.1" | "alice" |
| event_copy_2 | "192.0.2.2" | "alice" |
| event_copy_3 | "192.0.2.3" | "alice" |
| event_copy_4 | "" | "bob" |
该事件与规则不匹配,因为不存在满足所有表达式的事件副本。
重复消息和数组索引
在重复消息字段上使用数组索引和未修改的表达式时,可能会出现另一种意外行为。请参考以下使用数组索引的示例规则:
rule repeated_message_2 {
meta:
events:
$e.about.ip = "192.0.2.1"
$e.about[1].hostname = "bob"
condition:
$e
}
该规则会应用于以下副本:
| 活动文案 | about.ip | about[1].hostname |
|---|---|---|
| event_copy_1 | "192.0.2.1" | "bob" |
| event_copy_2 | "192.0.2.2" | "bob" |
| event_copy_3 | "192.0.2.3" | "bob" |
| event_copy_4 | "" | "bob" |
由于 event_copy_1 满足 repeated_message_2 中的所有表达式,因此该事件与规则匹配。
这可能会导致意外行为,因为规则 repeated_message_1 缺少数组索引,未产生匹配项,而规则 repeated_message_2 使用了数组索引,产生了匹配项。