風險分析規則的指標函式

本文將說明風險分析新版 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)

指標

在每個期間內，每項觀察都有多項相關聯的指標。您必須選取其中一個指標，才能在整個期間內匯總資料。支援五種 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 為 int)。
• 命名空間 (選用)：您只能將命名空間用於在維度中指定的實體。舉例來說，如果您使用 principal.asset.hostname filter，也可以使用 principal.namespace filter。如果您未加入命名空間篩選器，系統會將所有命名空間的資料匯總在一起。您可以使用預設值做為命名空間篩選器。

窗口計算

Google 安全作業團隊會使用每日或每小時的指標時間範圍來計算指標。

每日時段

所有每日時間窗格 (例如 30d) 都會以相同方式決定。Google Security Operations 會使用最新的資料指標資料，且該資料不與規則時間範圍重疊。每日指標的計算作業最多可能需要 6 小時才能完成，且必須等到當天結束 (以世界標準時間為準) 才會開始。前一天的指標資料會在每天世界標準時間 6 點或之前提供。

舉例來說，如果規則會針對 2023-10-31 04:00 到 2023-10-31 07:00 (含) 的事件資料執行，系統可能會產生 2023-10-31 的每日指標，因此指標計算會使用 2023-10-01 到 2023-10-30 (含) 的資料。不過，如果規則會在 2023-10-31 1:00 UTC 至 2023-10-31 3:00 UTC 期間處理事件資料，則 2023-10-30 的每日指標可能不會產生，因此指標計算會使用 2023-09-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 不會預先計算這項指標，而是在執行規則時計算。這項操作是透過在已計算的指標中，匯總現有維度來完成。舉例來說，您可以針對 target.user.userid 和 principal.ip_geo_artifact.location.country_or_region 維度，在後者維度上執行計數唯一匯總，從而從預先計算的 auth_attempts_total 指標中衍生出 daily total count of distinct countries that a user attempted to authenticate 指標。

以下範例規則會計算不重複指標：

$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 還要求事件至少包含一個 ALLOW 的 SecurityResult.Action。

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.dns.id 中具有值的 UDM 事件，預先計算歷史值。

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.http.method 中具有值的 UDM 事件，預先計算歷史值。

metrics.http_queries_success 還需要 network。http.response_code 小於 400。

metrics.http_queries_fail 只會考量含有 network 的事件。http.response_code 大於或等於 400。

網路位元組數

metrics.network_bytes_inbound 會針對 network.received_bytes 的 received_bytes 值為非零值的 UDM 事件，預先計算歷史值，並將該欄位設為 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 專家尋求解答。