比對區段語法

支援的國家/地區：

Google SecOps SIEM

在 YARA-L 2.0 中，match 部分提供多事件關聯的機制。這項功能會連結特定時間範圍內的常見屬性 (例如使用者、IP 位址或檔案雜湊)，定義將事件歸類為單一偵測結果的邏輯。

您可以在下列情況使用 match 區段：

在規則中連結兩個以上不同的事件。
在「搜尋」和「資訊主頁」中匯總資料，例如計算特定時間範圍內的登入失敗次數。

定義關聯條件

您可以指定下列項目，定義這項關聯性的條件：

分組欄位 (鍵)：事件 (定義於 events 區段) 必須具有相同值的變數 (例如 $user 或 $ip)，才能觸發比對。
時間限制：事件必須在時間範圍內發生，才能滿足規則或匯總條件。在「規則」中，這會定義偵測時間範圍；在「搜尋」和「資訊主頁」中，這會定義彙整或關聯時間範圍。

比較功能需求

下表詳細比較了規則與搜尋和資訊主頁。

功能	規則規定	支援搜尋和資訊主頁
變數類型	必須使用 `events` 區段中定義的預留位置。	支援預留位置和直接 UDM 欄位。
時間範圍	定義偵測邊界。	定義匯總或關聯性 bucket。
語法	`over <number><m/h/d>` (例如 `10m`、`2h`、`1d`)	`over <number><m/h/d>`
限制	最小值：`1m` / 最大值：`48h`	最小值：`1m` / 最大值：`48h`

支援的視窗類型

YARA-L 2.0 會使用不同的視窗行為，判斷時間的劃分方式和事件的分組方式。您可以在「match」部分，使用下列任一支援的視窗，依指定的時間精細度將事件欄位和預留位置分組。

支援的視窗類型	語法	說明	常見用途
躍點	`$key over <duration>`	時間間隔重疊 (預設行為)。	多個事件的一般關聯性。
翻滾	`$key by <duration> tumbling`	固定大小、不重疊且連續的時間間隔。	以最多 1 小時為單位量化活動 (例如 `$user by 30m`)。
滑動	`$key over <duration> [before\|after] $pivot`	以特定「樞紐」事件為基準的時間間隔。	嚴格排序 (例如 `File Download after Login`)。

語法範例：

match:
  $user, $source_ip over 5m  // Groups events by user and IP within a 5-minute window

跳躍式時間區間

跳躍視窗是多事件規則的預設行為。這項功能會建立重疊的時間間隔，確保不會錯過視窗邊界附近的事件。

語法：$key over <duration> (例如 $user over 30m)
用途：最適合用於偵測，確保無論時間間隔的開始或結束時間為何，都能偵測到特定情境。
支援：支援在搜尋和資訊主頁中匯總 (例如 count)。

根據預設，含有 match 區段的 YARA-L 查詢會使用跳躍視窗，在一段時間內關聯多個事件。查詢的執行時間範圍會劃分為一組固定的重疊跳躍視窗。雖然這些時間範圍的長度是在 match 區段中指定，但重疊間隔和時間範圍對齊方式是由系統定義，使用者無法設定。然後，系統會在每個預先決定的時間範圍內，將事件相互關聯。

範例：重疊的躍點視窗，用於持續進行關聯性分析

以下範例顯示在 [1:00, 2:00] 時間範圍內執行的查詢，其中包含 match 區段 $user over 30m，可能產生的重疊躍點視窗組合為 [1:00, 1:30]、[1:03, 1:33] 和 [1:06, 1:36]。

rule hop_window_brute_force_example {
meta:
  description = "Detects multiple failed logins within a shifting 30-minute window."
  severity = "Medium"

events:
  $login.metadata.event_type = "USER_LOGIN"
  $login.extensions.auth.auth_status = "FAILURE"
  $login.principal.user.userid = $user

match:
  // This creates the overlapping windows (e.g., 1:00-1:30, 1:03-1:33)
  $user over 30m

condition:
  // This will trigger if 10 or more failures fall into any single 30m hop
  #login >= 10
}

範例：使用躍點視窗進行多事件關聯

以下範例代表大多數多事件規則的預設值。並擷取同一段時間內發生的事件。

rule hop_window_example {
meta:
  description = "Detect a user with a failed login followed by a success within 30m"

events:
  $e1.metadata.event_type = "USER_LOGIN"
  $e1.extensions.auth.auth_status = "FAILURE"
  $e1.principal.user.userid = $user

  $e2.metadata.event_type = "USER_LOGIN"
  $e2.extensions.auth.auth_status = "SUCCESS"
  $e2.principal.user.userid = $user

match:
  $user over 30m  // This is a hop window

condition:
  $e1 and $e2
}

範例：跳躍視窗比較

如要找出暴力破解嘗試，10m 視窗會將所有 USER_LOGIN失敗情形歸類為一組。接著，condition 會評估該特定 10 分鐘值區內的計數 (#e) 是否超過門檻。

rule failed_logins
{
meta:
  author = "Security Team"
  description = "Detects multiple failed user logins within 10-minute windows."
  severity = "HIGH"

events:
  $e.metadata.event_type = "USER_LOGIN"
  $e.security_result.action = "FAIL"
  $user = $e.target.user.userid

match:
  $user over 10m

condition:
  #e >= 5
}

「match」部分會找出在 10 分鐘 (10m) 間隔內，於新位置登入失敗的使用者：

match:
  $user over 10m

滾動式時間區間

滾動式時間區間會將資料串流劃分為固定大小、不重疊且連續的時間間隔。每個資料事件只會指派給一個時間區間。這與滑動或跳躍式時間區間不同，後者可能會有重疊的時間間隔。

語法：使用 by 運算子 ($key by <duration>)，例如 $user by 30m。
適用情況：最適合用於報表和建立資訊主頁，方便您計算不同區塊中的事件 (例如 "How many alerts per hour?")。
搜尋和資訊主頁：常用於建立不含重複事件的乾淨長條圖。

範例：使用滾動視窗進行固定間隔計數

以下範例顯示 30 分鐘的滾動式時間區間，其中 1:00:00 到 1:29:59 之間發生的事件會一起處理。接著，系統會分開處理下一組事件 (從 1:30:00 到 1:59:59)。

rule tumbling_window_threshold_example {
meta:
  description = "Detect more than 50 failed logins from a single IP within a fixed 1-hour block."
  severity = "Medium"

events:
  $login.metadata.event_type = "USER_LOGIN"
  $login.extensions.auth.auth_status = "FAILURE"
  $login.principal.ip = $ip

match:
// This creates distinct, 1-hour blocks (e.g., 1:00-1:59, 2:00-2:59)
  $ip by 1h

condition:
  #login > 50
}

滑動視窗

如要搜尋以嚴格相對順序發生的事件 (例如 e1 最多在 e2 發生後兩分鐘內發生)，請使用滑動時間區間。與固定時間區間不同，滑動時間區間會使用以下語法，在每次發生指定 $pivot_event 時觸發：

after：時間範圍從樞紐事件的時間戳記開始，並向前延伸。
before：時間範圍以樞紐事件的時間戳記為結尾，並向後延伸。

在查詢的 match 部分中，指定滑動視窗，如下所示：

<match-var-1>, <match-var-2>, ... over <duration> [before|after] <pivot-event-var>

語法：$key over <duration> before|after $<pivot_event>
分組鍵：用於連結事件的常見欄位 (例如 $user、$ip)。
時間長度：與樞紐事件的時間差 (例如 5m、1h)。
用途：
- 嚴格排序：偵測需要依序執行的攻擊鏈 (例如，先建立使用者，再提升權限)。
- 相對時間：找出在「觸發」事件特定偏移時間內發生的事件 (例如 Process Start 事件後 30 秒內發生的 Network Connection)。
- 缺席偵測：找出在開始事件後，必要「清除」或「心跳」事件未發生時 (例如沒有對應 End 事件的 Database Backup Start)。

有效的滑動視窗範例

以下範例顯示有效的滑動視窗：

$var1, $var2 over 5m after $e1 $user over 1h before $e2 $host, $ip over 1h before $e2

範例：使用滑動視窗進行前瞻性關聯 (`after`)

以下範例說明如何偵測事件序列，其中第二個事件必須在主要「觸發」或樞紐事件發生後的特定時間範圍內發生。這有助於偵測快速的橫向移動或自動後續動作。

rule sliding_window_after_example {
meta:
  description = "Detect a network connection occurring within 1 minute after a suspicious process launch."
  severity = "High"

events:
  $proc.metadata.event_type = "PROCESS_LAUNCH"
  $proc.principal.hostname = $host

  $net.metadata.event_type = "NETWORK_HTTP"
  $net.principal.hostname = $host

match:
  // $proc is the pivot; the 1-minute window starts at the $proc timestamp
  $host over 1m after $proc

condition:
  $proc and $net
}

範例：使用滑動視窗進行回溯相關性分析 (`before`)

使用 "before" 滑動視窗，調查特定快訊發生前的活動。這項功能通常用於根本原因分析，找出重大偵測事件發生前的立即情況。

rule sliding_window_before_example {
meta:
  description = "Identify file modifications occurring in the 5 minutes before a ransomware alert."
  severity = "Critical"

events:
  $file.metadata.event_type = "FILE_MODIFICATION"
  $file.principal.hostname = $host

  $alert.metadata.event_type = "ANTIVIRUS_DETECTION"
  $alert.metadata.product_name = "Premium_AV"
  $alert.principal.hostname = $host

match:
  // $alert is the pivot; the 5-minute window ends at the $alert timestamp
  $host over 5m before $alert

condition:
  $file and $alert
}

成效和最佳做法

滑動視窗需要比標準 (跳躍) 視窗更多的處理能力，因為系統會針對每個樞紐事件的發生次數計算滑動視窗，因此可能會導致效能變慢。

請遵守下列規則，確保規則、搜尋和資訊主頁發揮最佳成效：

優先處理跳躍視窗：除非偵測邏輯需要特定事件序列 (先訂購 A，再訂購 B)，否則請使用預設跳躍視窗。只有在事件順序至關重要或您要搜尋遺失的事件時，才使用滑動視窗。
使用時間戳記篩選條件來評估成效：如果您只需要確認某個事件是否發生在另一個事件之後，通常在 events 或 condition 區段中比較時間戳記，會比使用滑動時間區間更有效率，例如：

$e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds

多事件設計：避免對單一事件查詢使用滑動視窗。滑動視窗是專為多個事件的關聯性而設計。單一事件邏輯適用下列規範：
- 使用多個事件變數，並更新 condition 部分。
- 如果不需要關聯性，請完全移除 match 區段。
- 視需要新增時間戳記篩選器，而非使用滑動時間範圍，例如：
  $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds

瞭解時間界線

「match」部分會根據分組鍵將事件劃分為不同群組。指定的時間長度會定義每個群組的時間界線：

納入：只有在時間範圍內的事件，才會傳遞至該特定相符項目的 condition 評估。
排除：系統會忽略視窗外的事件，避免不相關的事件觸發誤判。

「`match`」部分中的零值

Google SecOps 會隱含地篩除 match 區段中使用的所有預留位置的零值 (字串為 ""、數字為 0、布林值為 false，列舉型別則為位置 0 中的值)。

範例：篩除零值

以下範例說明如何查詢並篩除零值。

rule ZeroValuePlaceholderExample {

events:
  // Because $host is used in the match section, the query behaves
  // as if the following predicate was added to the events section:
  // $host != ""
  $host = $e.principal.hostname

  // Because $otherPlaceholder was not used in the match,
  // there is no implicit filtering of zero values for $otherPlaceholder.
  $otherPlaceholder = $e.principal.ip

match:
  $host over 5m

condition:
  $e
}

不過，如果預留位置已指派給函式，查詢不會在 match 區段中，隱含地篩除預留位置的零值。

如要停用零值的隱含篩選，請使用選項區段中的 allow_zero_values 選項。「allow_zero_values」選項僅適用於規則。

範例：允許零值

以下範例說明查詢不會隱含篩除 match 區段中使用的預留位置零值：

rule AllowZeroValuesExample {

events:
  // Because allow_zero_values is set to true, there is no implicit filtering
  // of zero values for $host.
  $host = $e.principal.hostname

  // Because $otherPlaceholder was not used in the match,
  // there is no implicit filtering of zero values for $otherPlaceholder.
  $otherPlaceholder = $e.principal.ip

match:
  $host over 5m

condition:
  $e

options:
  allow_zero_values = true
}

後續步驟

如要繼續使用 YARA-L 邏輯，或深入瞭解進階查詢函式，請參閱下列資源：

語法和邏輯

參考資料和範例

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