風險分析規則的指標函式

本文將說明新版 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

舉例來說，下列規則會顯示特定使用者 (Alice) 在過去 30 天內，某一天驗證失敗次數最多：

$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) 聯結。
• 命名空間 (選用)：您只能將命名空間用於在維度中指定的實體。舉例來說，如果您使用 principal.asset.hostname filter，也可以使用 principal.namespace filter。如果未加入命名空間篩選器，系統會匯總所有命名空間的資料。您可以將預設值做為命名空間篩選器。

視窗計算

Google Security Operations 會使用每日或每小時指標時間範圍計算指標。

每日時段

所有每日時間範圍 (例如 30d) 的判斷方式都相同。 Google Security Operations 會使用最新產生的可用指標資料，這些資料不會與規則時間範圍重疊。計算每日指標最多可能需要 6 小時，且必須等到世界標準時間當日結束後才會開始。前一天的指標資料會在每天世界標準時間 6:00 左右提供。

舉例來說，如果規則是針對 2023 年 10 月 31 日世界標準時間 4:00 至 7:00 的事件資料執行，系統可能已產生 2023 年 10 月 31 日的每日指標，因此指標計算會使用 2023 年 10 月 1 日至 2023 年 10 月 30 日 (含) 的資料。如果是對 2023 年 10 月 31 日世界標準時間 1:00 至 3:00 的事件資料執行規則，系統可能尚未產生 2023 年 10 月 30 日的每日指標，因此指標計算會使用 2023 年 9 月 30 日至 2023 年 10 月 29 日 (含) 的資料。

每小時 today 視窗

每小時指標的計算時間範圍與每日指標不同。today 的每小時指標時間範圍並非固定大小，不像每日指標的 30d 時間範圍。每小時指標時間範圍 today 會盡可能填入每日時間範圍結束和規則時間範圍開始之間的資料。

舉例來說，如果規則是針對 2023 年 10 月 31 日 4:00:00 (世界標準時間) 至 2023 年 10 月 31 日 7:00:00 (世界標準時間) 的事件資料執行，則每日指標計算會使用 2023 年 10 月 1 日至 2023 年 10 月 30 日 (含) 的資料，每小時指標視窗則會使用 2023 年 10 月 31 日 00:00:00 (世界標準時間) 至 2023 年 10 月 31 日 4:00:00 (世界標準時間) 的資料。

計算不重複指標

有一種特殊指標 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 衍生而來，方法是對後者維度執行不重複計數匯總。

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

$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預先計算 UDM 事件的歷史值，這些事件是由 Carbon Black、CrowdStrike Falcon、Microsoft Graph API 警報或 Microsoft Sentinel 產生警報。

驗證嘗試

metrics.auth_attempts_total會預先計算 UDM 事件的歷來值，並使用 USER_LOGIN event type。

metrics.auth_attempts_success 進一步要求事件至少要有一個 SecurityResult.Action ALLOW。

metrics.auth_attempts_fail 則要求所有 SecurityResult.Actions 皆未 ALLOW。

DNS 輸出位元組

metrics.dns_bytes_outbound 會預先計算 UDM 事件的歷史值，其中 network.sent_bytes 大於 0，且目標通訊埠為 53/udp、53/tcp 或 3000/tcp。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預先計算 UDM 事件的歷來值，並使用 PROCESS_LAUNCH event type。

metrics.file_executions_success 進一步要求事件至少要有一個 SecurityResult.Action ALLOW。

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 值不為零的 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 會預先計算 UDM 事件的歷來值，並使用 RESOURCE_CREATION event type 或 USER_RESOURCE_CREATION event type。

如需對等事件類型的清單，請參閱「中繼資料事件類型」

metrics.resource_creation_success 進一步要求事件至少要有一個 SecurityResult.Action ALLOW。

刪除資源

metrics.resource_deletion_success 預先計算 UDM 事件的歷史值，並使用 RESOURCE_DELETION event type，且事件必須至少有一個 SecurityResult.Actions ALLOW。

資源讀取

metrics.resource_read_success 預先計算 UDM 事件的歷史值，並使用 RESOURCE_READ event type，且事件必須至少有一個 SecurityResult.Action ALLOW。

metrics.resource_read_fail 則要求所有 SecurityResult.Actions 都不得為 ALLOW。

限制

使用指標建立 YARA-L 規則時，請注意下列限制：

• 您無法將指標與預設值 (字串為 ""，整數為 0) 聯結。
• 預設值：
  • 如果沒有與事件相應的指標資料，指標函數傳回的值為 0。
  • 如果偵測到的事件沒有指標資料，使用 min 匯總函式可能會傳回 0。
  • 如要檢查事件是否有資料，您可以使用相同篩選條件，對該事件套用指標num_metric_periods匯總。
• 指標函式只能用於結果部分。
• 由於指標函式只會用於結果部分，因此必須像規則中含有相符部分的任何其他值一樣匯總。

還有其他問題嗎？向社群成員和 Google SecOps 專業人員尋求答案。