风险分析规则的指标函数

本文档介绍了风险分析的新 YARA-L 语法功能的主要元素。如需详细了解 YARA-L，请参阅 YARA-L 2.0 语言语法。

YARA-L 指标函数

Google Security Operations 支持多种指标函数，这些函数可以汇总大量历史数据。

指标函数只能在结果部分中使用。所有示例函数调用都假定在多事件规则中使用。

使用指标函数的所有规则都会自动归类为多事件规则，即使这些规则没有匹配部分，并且只使用一个事件变量也是如此。这意味着它们将计入多事件规则配额。

指标函数参数

指标函数可用于执行实体行为分析的规则。

例如，以下规则会显示特定 IP 地址在过去一个月内每天发送的最大字节数。具体 IP 地址由占位符变量表示，在本例中为 $ip。如需详细了解占位变量，请参阅变量声明。

$max_bytes_per_day = max(metrics.network_bytes_outbound(
    period:1d, window:30d,
    metric:value_sum,
    agg:max,
    principal.asset.ip:$ip
))

由于这些函数中使用的实参数量较多，因此它们使用具名形参，这些形参可按任意顺序指定。具体参数如下所示：

时段

将各个日志事件合并为一个观测结果的时长。仅允许使用 1h 和 1d 这两个值。

窗口

将各个观测结果聚合为一个值（例如平均值和最大值）的时长。window 的允许值取决于相应指标的周期。有效的映射如下：

period:1h:window:today

period:1d:window:30d

例如，以下规则会告知您，在过去 30 天内，特定用户（Alice）在给定日期内尝试身份验证失败的最大次数：

$user = "alice"
$max_fail = max(metrics.auth_attempts_fail(
    period:1d, window:30d,
        metric:event_count_sum,
        agg:max,
        target.user.userid:$user
))

对于 first-seen 类型的检测，可以使用小时级指标和天级指标的组合。例如，以下规则会告知您用户是否是首次登录相应应用：

events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.security_result.action = "ALLOW"
    $userid = $e.target.user.userid
    $app = $e.target.application
match:
    // find events from now - 4h ago, which is the recommended look-back period
    $userid, $app over 4h
outcome:
    // check hourly analytics until daily analytics are available
    $first_seen_today = max(metrics.auth_attempts_success(
        period:1h, window:today, metric:first_seen, agg:max,
        target.user.userid:$userid, target.application:$app))
    $first_seen_monthly = max(metrics.auth_attempts_success(
        period:1d, window:30d, metric:first_seen, agg:max,
        target.user.userid:$userid, target.application:$app))
condition:
    $e and ($first_seen_today = 0) and ($first_seen_monthly = 0)

指标

在每个周期内，每个观测结果都有许多与之相关的指标。 必须选择其中一个指标才能聚合整个窗口期内的数据。支持 5 种 metric 类型：

event_count_sum - 每个时间段内不重复的日志事件数。

first_seen - 每个时间段内匹配的日志事件的首次发现时间戳。

last_seen - 每个时间段内匹配的日志事件的上次查看时间戳。

value_sum - 表示相应时间段内所有日志事件的总字节数。此值只能用于名称中包含 bytes 的指标函数。

num_unique_filter_values - Google SecOps 未预先计算但可在规则执行期间计算的指标。如需了解详情和要求，请参阅统计唯一指标。

Agg

应用于相应指标的聚合。聚合应用于整个窗口期（例如，过去 30 天内的最高每日值）。允许的值包括：

avg - 每个周期的平均值。这是统计平均值，不包括零值。

max - 每个时间段的最大值。

min - 每个周期的最小值。

num_metric_periods - 时间窗口内具有非零指标值的周期数。

stddev - 每个周期的价值的标准差。这是不包含零值的统计标准差。

sum - 每个时间段内各个值的总和，涵盖整个窗口。

例如，以下规则会告知您特定用户（Alice）在过去 30 天内任意一天的平均身份验证失败次数：

$user = "alice"
$avg_fail = max(metrics.auth_attempts_fail(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:avg,
        target.user.userid:$user
))

以下规则可用于了解特定用户在过去 30 天内成功通过身份验证的次数：

$total_success = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:sum,
        target.user.userid:$user
))

以下规则会告知您特定用户在过去 30 天内是否至少成功登录过一次：

$days_success = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:num_metric_periods,
        target.user.userid:$user
))

以下规则可用于确定特定用户首次或最后一次成功登录的时间：

$first_seen = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:first_seen,
        agg:min,
        target.user.userid:$user
))
$last_seen = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:last_seen,
        agg:max,
        target.user.userid:$user
))

以下规则可用于了解用户在过去 30 天内任意一天发送的最大字节数：

$max_daily_bytes = max(metrics.network_bytes_outbound(
        period:1d, window:30d,
        metric:value_sum,
        agg:max,
        target.user.userid:$user
))

过滤

过滤条件允许在聚合之前按预先计算的指标中的值过滤指标（请参阅指标中的值）。过滤条件可以是任何有效的事件表达式（事件部分中的单行），但不得包含任何事件字段或占位符。此条件中只能包含指标类型的变量。

以下规则仅包含 value_sum > 10 AND event_count_sum > 2 的指标：

$max_bytes_per_day = max(metrics.network_bytes_outbound(
    period:1d, window:30d,
    metric:value_sum,
    agg:max,
    principal.asset.ip:$ip
    filter:value_sum > 10 AND event_count_sum > 2
))

有效的过滤条件示例

filter:value_sum > 10 AND event_count_sum != 5
filter:event_count_sum = 100 OR event_count_sum > 1000
filter:timestamp.get_day_of_week(first_seen) = 3

无效的过滤条件示例

// No placeholders in filter expressions.
filter:value_sum > $ph

// No event fields in filter expressions.
filter:event_count_sum + $e.field > 10

// No event fields in filter expressions.
filter:timestamp.subtract(first_seen, $e.metadata.timestamp)

UDM 字段

指标按 1 个、2 个或 3 个 UDM 字段进行过滤，具体取决于相应函数。如需了解详情，请参阅函数。

以下类型的 UDM 字段用于指标函数：

• 维度 -（必需）此文档中列出了不同的组合。您无法联接具有默认值（字符串为 ""，整数为 0）的指标。
• 命名空间 -（可选）您只能为在维度中指定的实体使用命名空间。例如，如果您使用 principal.asset.hostname filter，也可以使用 principal.namespace filter。如果不添加命名空间过滤条件，系统会将所有命名空间中的数据汇总在一起。您可以使用默认值作为命名空间过滤条件。

窗口计算

Google Security Operations 使用每日或每小时指标窗口来计算指标。

每日窗口期

所有每日窗口（例如 30d）都以相同的方式确定。 Google Security Operations 使用生成的最新可用指标数据，这些数据与规则时间范围不重叠。每日指标的计算最多可能需要 6 小时才能完成，并且只有在世界协调时间 (UTC) 的一天结束时才会开始。前一天的指标数据将在每天 6:00（世界协调时间）之前或当天 6:00 提供。

例如，对于在 2023 年 10 月 31 日 4:00 UTC 至 2023 年 10 月 31 日 7:00 UTC 期间运行的规则，2023 年 10 月 31 日的每日指标可能已生成，因此指标计算将使用 2023 年 10 月 1 日至 2023 年 10 月 30 日（含）的数据。而对于在 2023 年 10 月 31 日 1:00 UTC 至 2023 年 10 月 31 日 3:00 UTC 期间运行的规则，2023 年 10 月 30 日的每日指标可能尚未生成，因此指标计算将使用 2023 年 9 月 30 日至 2023 年 10 月 29 日（含）的数据。

每小时 today 时段

小时级指标的时间窗口与日级指标的时间窗口的计算方式不同。每小时指标的 today 小时指标窗口大小不是固定的，不像每日指标的 30d 天指标窗口那样。每小时指标窗口 today 会在每日窗口结束时间与规则时间窗口开始时间之间尽可能多地填充数据。

例如，对于从 2023-10-31 4:00:00 UTC 到 2023-10-31 7:00:00 UTC 运行的规则，每日指标计算将使用 2023-10-01 到 2023-10-30（含）的数据，而每小时指标窗口将使用 2023-10-31 00:00:00 UTC 到 2023-10-31 4:00:00 UTC 的数据。

统计唯一身份用户指标

有一种特殊类型的指标 num_unique_filter_values 不会由 Google SecOps 预先计算，而是在规则执行期间计算。为此，您需要对预先计算的指标中的现有维度进行汇总。例如，daily total count of distinct countries that a user attempted to authenticate 中的指标可以通过对维度 target.user.userid 和 principal.ip_geo_artifact.location.country_or_region 上预先计算的 auth_attempts_total 指标执行 count_distinct 聚合（针对后一个维度）来得出。

以下示例规则用于统计唯一指标：

$outcome_variable = max(metrics.auth_attempts_total(
    period: 1d,
    window: 30d,
    // This metric type indicates any filter with a wildcard value should be
    // aggregated over each day to produce a new metric on-the-fly.
    metric: num_unique_filter_values,
    agg: max,
    target.user.userid: $userid,
    // Filter whose value should be counted over each day to produce the
    // num_unique_filter_values metric.
    principal.ip_geo_artifact.location.country_or_region: *
))

此功能具有以下限制：

• 计算唯一指标数量时，只能按 1 个过滤维度进行汇总。使用通配符令牌 * 作为过滤条件值即可表示这一点。

函数

本部分包含有关 Google Security Operations 支持的特定指标函数的文档。

提醒事件

metrics.alert_event_name_count 会预先计算由 Carbon Black、CrowdStrike Falcon、Microsoft Graph API 警报或 Microsoft Sentinel 生成了警报的 UDM 事件的历史值。

身份验证尝试次数

metrics.auth_attempts_total 预先计算具有 USER_LOGIN event type 的 UDM 事件的历史值。

metrics.auth_attempts_success 还要求事件至少有一个 SecurityResult.Action 的 ALLOW。

metrics.auth_attempts_fail 要求所有 SecurityResult.Actions 都不是 ALLOW。

DNS 出站字节数

metrics.dns_bytes_outbound 会预先计算 network.sent_bytes 大于 0 且目标端口为 53/udp、53/tcp 或 3000/tcp 的 UDM 事件的历史值。network.sent_bytes 可作为 value_sum 使用。

DNS 查询

metrics.dns_queries_total 会预先计算 network 中有值的 UDM 事件的历史值。dns.id。

metrics.dns_queries_success 还要求 network。dns.response_code 为 0 (NoError)。

metrics.dns_queries_fail 仅考虑具有 network 的事件。dns.response_code 大于 0。

文件执行

metrics.file_executions_total 预先计算具有 PROCESS_LAUNCH event type 的 UDM 事件的历史值。

metrics.file_executions_success 还要求相应事件至少有一个 ALLOW 的 SecurityResult.Action。

metrics.file_executions_fail 则要求所有 SecurityResult.Actions 都不是 ALLOW。

HTTP 查询

metrics.http_queries_total 会预先计算 network 中有值的 UDM 事件的历史值。http.method。

metrics.http_queries_success 进一步要求 network。http.response_code 小于 400。

metrics.http_queries_fail 仅考虑具有 network 的事件。http.response_code 大于或等于 400。

网络字节数

metrics.network_bytes_inbound 会预先计算 network 值不为零的 UDM 事件的历史值。received_bytes，并将该字段作为 value_sum 提供。

metrics.network_bytes_outbound 要求 network.sent_bytes 具有非零值，并使该字段可作为 value_sum 使用。

metrics.network_bytes_total 会考虑 network.received_bytes 或 network.sent_bytes（或两者）的值不为零的事件，并将这两个字段的总和作为 value_sum 提供。

资源创建

metrics.resource_creation_total 会预先计算 RESOURCE_CREATION event type 或 USER_RESOURCE_CREATION event type 的 UDM 事件的历史值。

如需查看等效事件类型的列表，请参阅元数据事件类型

metrics.resource_creation_success 进一步要求事件至少有一个 ALLOW 的 SecurityResult.Action。

资源删除

metrics.resource_deletion_success 预先计算具有 RESOURCE_DELETION event type 的 UDM 事件的历史值，并进一步要求事件至少具有一个 ALLOW 的 SecurityResult.Actions。

资源读取

metrics.resource_read_success 预先计算具有 RESOURCE_READ event type 的 UDM 事件的历史值，并进一步要求事件至少具有一个 ALLOW 的 SecurityResult.Action。

而 metrics.resource_read_fail 要求所有 SecurityResult.Actions 都不能为 ALLOW。

限制

使用指标创建 YARA-L 规则时，请注意以下限制：

• 您无法联接具有默认值（字符串为 ""，整数为 0）的指标。
• 默认值：
  • 如果没有与事件对应的指标数据，则指标函数返回的值为 0。
  • 如果检测到的事件中没有指标数据，使用 min 对函数进行聚合可能会返回 0。
  • 如需检查某个事件是否有数据，您可以对该事件使用相同的过滤条件，并应用 num_metric_periods 汇总。
• 指标函数只能在结果部分中使用。
• 由于指标函数仅在结果部分中使用，因此必须像匹配部分中的任何其他值一样进行聚合。

需要更多帮助？从社区成员和 Google SecOps 专业人士那里获得解答。