YARA-L 2.0 語言語法

本節說明 YARA-L 語法的主要元素。另請參閱 YARA-L 2.0 語言總覽。

註解

使用斜線符號 (// comment) 指定註解，或使用正斜線字元 (/* comment */) 設定多行註解 (如同在 C 中一樣)。

常數

支援整數、字串、浮點數和規則運算式常數。如果是字串常數，請使用雙引號。規則運算式使用 /regex/ 表示規則運算式常數。

數量

# 字元在條件區段中是特殊字元。如果這個值是在任何事件或預留位置變數名稱之前使用，則代表符合所有 events 條件條件的不重複事件或值數量。

注意： $var 相當於 #var > 0

IP 子網路搜尋

您可以使用 YARA-L，使用 net.ip_in_range_cidr() 陳述式搜尋子網路中所有 IP 位址的 UDM 事件。並同時支援 IPv4 和 IPv6。

如要搜尋特定 IP 位址範圍，請指定 IP UDM 欄位和無類別跨網域路由 (CIDR) 範圍。YARA-L 可處理單個和重複的 IP 位址欄位。

IPv4 範例：

net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

IPv6 範例：

net.ip_in_range_cidr($e.network.dhcp.yiaddr, "2001:db8::/32")

如需使用 net.ip_in_range_cidr() 陳述式的範例規則，請參閱範例規則：IP 位址範圍中的單一事件

運算子

您可以在 YARA-L 中使用以下運算子：

運算子	說明
=	等號
!=	不等於
<	小於
<=	小於或等於
>	大於
>=	大於或等於

字串報價

您可以使用下列任何半形字元來括住 YARA-L 2.0 中的字串。不過，視您使用的文字而定，引用文字的解讀方式會有所不同。

1. 雙引號 (")：用於一般字串。必須包含逸出字元。 例如：「hello\tworld」\\t 會被解讀為分頁

2. 左引號 (\)—用來解譯所有字元。 例如：「hello\tworld」\t 並未解讀為分頁標籤

規則運算式需要在字串內包含反斜線 (\) 字元。不過，如果使用雙引號，您就必須使用反斜線字元逸出反斜線字元，否則可能會混淆。

例如，下列規則運算式相等：

• re.regex($e.network.email.from, `.*altostrat\.com`)
• re.regex($e.network.email.from, ".*altostrat\\.com")

我們建議您使用規則運算式中的規則運算式字元，方便使用者閱讀。

變數

在 YARA-L 2.0 中，所有變數都會以 $<variable name> 表示。

您可以定義下列的變數類型：

• 事件變數：以正規化格式 (UDM) 表示的事件群組。在 events 區段中指定事件變數的條件。您可以使用變數之後的事件欄位來識別事件變數。事件欄位是以 .<field name> 的鏈結表示 (例如 $e.field1.field2)。事件欄位鏈一律從頂層 UDM 開始。

• 比對變數：在「相符」部分中宣告。由於相符變數會針對每個不重複的配對變數 (以及每個時段) 傳回一個相符變數，因此系統會將相符變數對查詢進行分組。當規則找到相符項目時，就會傳回比對變數值。在 events 區段中指定各個相符變數的意義。

• 預留位置變數：在 events 區段中宣告及定義。預留位置變數與比對變數類似。不過，您可以在 condition 區段中使用預留位置變數來指定比對條件。

使用比對變數和預留位置變數，透過遞迴彙整條件宣告事件欄位之間的關係 (詳情請參閱事件區段語法)。

事件區段語法

在 events 區段中，列出述詞以指定述詞：

• 每個相符或預留位置變數的意義
• 單一事件變數的篩選條件
• 兩個事件變數的彙整條件。

注意： 每個預留位置「必須」對應到某個事件欄位。舉例來說，如果您只在規則的同一行中參照下列預留位置，由於 $var 並未繫結至事件變數，因此無法編譯：$e.field != $var

變數宣告

適用於變數宣告，請使用以下語法：

• EVENT_FIELD = VAR
• VAR = EVENT_FIELD

兩者相同，如以下範例所示：

• $e.source.hostname = $hostname
• $userid = $e.principal.user.userid

這個宣告表示此變數代表事件變數指定的欄位。當事件欄位是陣列欄位時，比對變數可以代表陣列中的任何值。 也可以將多個事件欄位指派給單一相符項目或預留位置變數。這是暫時性彙整條件。

例如：

• $e1.source.ip = $ip
• $e2.target.ip = $ip

等於：

• $e1.source.ip = $ip
• $e1.source.ip = $e2.target.ip

事件變數篩選條件

如需單一事件變數的篩選條件，請使用下列語法：

• [EVENT_FIELD] [OP] [CONST]
• [CONST] [OP] [EVENT_FIELD]

雖然兩者相等，但我們建議您使用前 ([EVENT_FIELD] [OP] [CONST]) 來閱讀。

例如：

• $e.source.hostname = "host1234"
• $e.source.port < 1024
• 1024 < $e.source.port

這個述詞會做為事件變數的篩選器，也就是說，由事件變數所代表的事件群組應符合該事件。

事件變數的彙整條件

如要代表兩個事件變數的加入條件，請使用下列語法：

[EVENT_FIELD] [OP] [EVENT_FIELD]

例如：

• $e1.source.hostname = $e2.target.hostname
• $e1.metadata.timestamp < $e2.metadata.timestamp

這個述詞會結合兩個事件變數與條件。

以下是無效述詞的範例：

• $e.source.hostname != $hostname //comparison over match/placeholder var
• $hostname != "host1234" //comparison over match/placeholder var
• $var1 //variable itself does not mean anything

邏輯運算子

您可以在 events 區段中使用邏輯 and 和邏輯 or 運算子，如以下範例所示：

• $e.metadata.event_type = "NETWORK_DNS" or $e.metadata.event_type = "NETWORK_DHCP"
• ($e.metadata.event_type = "NETWORK_DNS" and $e.principal.ip = "192.0.2.12") or ($e.metadata.event_type = "NETWORK_DHCP" and $e.principal.mac = "AB:CD:01:10:EF:22")
• not $e.metadata.event_type = "NETWORK_DNS"

根據預設，優先順序從最高到最低為 not、and 和 or。

舉例來說，系統會將 "a or b and c" 評估為 "a or (b and c)"。如有需要，可以使用括號變更優先順序。

相符區段語法

在「相符」部分中，列出群組事件的相符變數，再檢查配對條件。每次比對時，這些欄位都會傳回這些欄位。

• 在 events 區段中指定各個相符變數的意義。
• 指定要在 over 關鍵字之後與事件建立關聯的時間範圍。系統會忽略時間範圍以外的事件。
• 請使用以下語法指定時間範圍：<number><s/m/h/d> 其中「s/m/h/d」分別代表秒、分鐘、小時和天。
• 您最少可以指定 1 分鐘。
• 您可以指定的時間上限為 48 小時。

以下是有效的 match 範例：

$var1, $var2 over 5m

當系統找到相符的規則時，這個陳述式會傳回 $var1 和 $var2 (已在 events 區段中定義)。指定的時間為 5 分鐘。超過 5 分鐘的事件不會建立關聯，因此不受規則忽略。

以下是有效的 match 範例：

$user over 1h

如果規則找到相符項目，這個陳述式會傳回 $user。您指定的時間範圍為 1 小時。超過一小時的活動均不連結。系統不會將此規則視為偵測。

以下是有效的 match 範例：

$source_ip, $target_ip, $hostname over 30s

當規則找到相符項目時，這個陳述式會傳回 $source_ip、$target_ip 和 $hostname。您指定的時間範圍為 30 秒。長度超過 30 秒的事件不會建立關聯。系統不會將此規則視為偵測。

以下範例說明無效 match：

• var1, var2 over 5m // invalid variable name
• $user 1h // missing keyword

條件區段語法

在 condition 區段中，指定針對 events 區段定義的事件和變數的比對條件。此處列出比對述詞，以關鍵字 and 或 or 結合。

以下條件屬於邊界條件。而且會強制有關聯的事件變數存在，這表示該事件至少必須出現一次事件。

• $var // equivalent to #var > 0
• #var > n // where n is >= 0
• #var >= m // where m > 0

下列條件無法繫結。它們允許相關聯的事件變數不存在，這代表在偵測中找不到任何事件事件。這可讓非存在的規則不具功用，而可用來搜尋缺少變數，而不提供變數。

• !$var // equivalent to #var = 0
• #var < n // where n is > 0
• #var <= m // where m >= 0

在以下範例中，變數 (事件變數或預留位置變數) 中的特殊字元 # 代表該變數的不重複事件或價值：

$e and #port > 50 or #event1 > 2 or #event2 > 1 or #event3 > 0

如果 $event1 有多個不同事件，且 $event2 與兩個不同事件不同，則以下不存在不存在的範例也會評估為 true：

#event1 > 2 and !$event2

注意： 請勿在 condition 區段中使用 match 變數。這是將語意錯誤分組的事件，因為以 match 變數值來分組。當 event 變數本身為述詞時，代表至少有一個這類事件存在的條件。

注意： 請勿在指派給 match 變數的所有 event 變數上指定未繫結條件。這是語義上的錯誤，因為系統傳回的 match 變數值必須至少有一個來含有該值。

以下是無效述詞的範例：

• $e, #port > 50 // incorrect keyword usage
• $e or #port < 50 // or keyword not supported with non-bounding conditions

規則運算式

您可以使用下列任一語法來定義 YARA-L 2.0 中的規則運算式：

• 使用 YARA 語法：與事件相關。 以下是這個語法的一般表示法：$e.field = /regex/
• 使用 YARA-L 語法：做為下列參數的函式：
  • 要套用規則運算式的欄位。
  • 指定為字串的規則運算式。您可以在字串後使用 nocase 修飾符來指示搜尋作業應忽略大小寫。 以下是這個語法的一般表示法：re.regex($e.field, `regex`)

注意： 不論哪一種方式，如果字串包含的運算式與提供的規則運算式相符，子字串就會成為 True。在規則運算式的開頭或結尾加上 .*。

如要比對完全相符的字串或與前置字元或後置字串，請在規則運算式中加入 ^ (開頭) 和 $ (結尾) 錨點字元。

舉例來說，/^full$/ 會完全比對 "full"，而 /full/ 可以與 "fullest"、"lawfull" 和 "joyfully" 達成比對。

原始字串

您可以使用 YARA-L 2.0 搜尋企業事件資料中的原始字串。

若要搜尋原始字串，請用引號括住字串 (`)，不要使用雙引號 (")。

倒引號指出字串內容將解讀為文字 (無法剖析字元)。