Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

開發剖析器擴充功能

支援的國家/地區：

Google SecOps SIEM

本文說明如何建立剖析器擴充功能，從原始記錄資料中擷取欄位，並將這些欄位對應至 Google Security Operations 平台中的目標 UDM (Unified Data Model) 欄位。

這份文件概述剖析器擴充功能的建立程序：

建立剖析器擴充功能。
必要條件和限制。
找出原始記錄資料中的來源欄位。
選取適當的目的地 UDM 欄位。
選擇適當的剖析器擴充功能定義方法：

定義剖析器擴充功能包括設計剖析邏輯，以篩選原始記錄檔資料、轉換資料，並將資料對應至目標 UDM 欄位。Google SecOps 提供兩種建立剖析器擴充功能的做法：
- 使用無程式碼 (對應資料欄位) 方法建立剖析器擴充功能。
- 使用程式碼片段方法建立剖析器擴充功能。
各種記錄檔格式和情境的剖析器擴充功能建立範例。舉例來說，您可以使用 JSON 建立無程式碼範例，並使用程式碼片段處理複雜邏輯或非 JSON 格式 (CSV、XML、Syslog)。

建立剖析器擴充功能

剖析器擴充功能可彈性擴充現有預設 (和自訂) 剖析器的功能。剖析器擴充功能提供彈性的方式，可擴充現有預設 (或自訂) 剖析器的功能，不必取代這些剖析器。您可以透過擴充功能新增剖析邏輯、擷取及轉換欄位，以及更新或移除 UDM 欄位對應，自訂剖析器管道。

剖析器擴充功能與自訂剖析器不同。您可以為沒有預設剖析器的記錄類型建立自訂剖析器，或選擇不接收剖析器更新。

剖析器擷取和正規化程序

Google SecOps 會收到原始記錄資料，也就是原始記錄。預設 (和自訂) 剖析器會擷取核心記錄欄位，並將其正規化為 UDM 記錄中的結構化 UDM 欄位。這只代表原始記錄資料的子集。您可以定義剖析器擴充功能，擷取預設剖析器未處理的記錄值。啟用後，剖析器擴充功能就會成為 Google SecOps 資料擷取和正規化程序的一部分。

擷取和正規化工作流程

定義新的剖析器擴充功能

預設剖析器包含預先定義的對應指令集，可指定如何擷取、轉換及正規化核心安全性值。您可以透過無程式碼 (「對應資料欄位」) 或程式碼片段方法，定義對應指示來建立新的剖析器擴充功能：

無程式碼方法

無程式碼方法最適合從原生 JSON、XML 或 CSV 格式的原始記錄中，簡單擷取資料。您可以指定原始記錄來源欄位，並對應相應的目的地 UDM 欄位。

舉例來說，如要使用簡單的等式比較，擷取最多 10 個欄位的 JSON 記錄資料。
程式碼片段方法

使用程式碼片段方法，您可以定義指令，從原始記錄中擷取及轉換值，並將這些值指派給 UDM 欄位。程式碼片段會使用與預設 (或自訂) 剖析器相同的 Logstash 類似語法。

所有支援的記錄格式都適用這種做法。最適合以下情境：
- 複雜的資料擷取作業或複雜的邏輯。
- 需要 Grok 型剖析器的非結構化資料。
- 非 JSON 格式，例如 CSV 和 XML。
程式碼片段會使用函式，從原始記錄資料中擷取特定資料。例如 Grok、JSON、KV 和 XML。

在大多數情況下，最好使用預設 (或自訂) 剖析器中使用的資料對應方法。

將新擷取的值併入 UDM 欄位

啟用後，剖析器擴充功能會根據預先定義的合併原則，將新擷取的值合併至相應 UDM 記錄中指定的 UDM 欄位。例如：

覆寫現有值：擷取的值會覆寫目標 UDM 欄位中的現有值。

但重複欄位是例外狀況，您可以設定剖析器擴充功能，在將資料寫入 UDM 記錄中的重複欄位時，附加新值。
剖析器擴充功能優先：剖析器擴充功能中的資料對應指示，優先於該記錄類型預設 (或自訂) 剖析器中的指示。如果對應指令發生衝突，剖析器擴充功能會覆寫預設值設定的值。

舉例來說，如果預設剖析器將原始記錄檔欄位對應至 event.metadata.description UDM 欄位，而剖析器擴充功能將不同的原始記錄檔欄位對應至同一個 UDM 欄位，則剖析器擴充功能會覆寫預設剖析器設定的值。

重複欄位選取器

無論是「對應資料欄位」(免程式碼) 還是「編寫程式碼片段」方法，您都可以控制剖析器擴充功能如何將值儲存至重複欄位 (支援值陣列的欄位，例如 principal.ip)。在「擴充功能」(擴充功能定義) 面板中，使用「重複欄位」欄位，其中提供「附加值」和「取代值」選項。

附加與取代行為

某些 UDM 欄位會儲存值陣列，例如 principal.ip 欄位。「重複欄位」選取器可讓您控管剖析器擴充功能如何將新擷取的資料儲存在重複欄位中：

附加值：

剖析器擴充功能會將新擷取的值附加至 UDM 欄位中現有值的陣列。
取代值：

剖析器擴充功能會將 UDM 欄位中的現有值陣列，替換為新擷取的值。

只有當重複欄位位於階層最低層級時，剖析器擴充功能才能將資料對應至重複欄位。例如：

由於重複的 ip 欄位位於階層的最低層級，且 principal 不是重複欄位，因此系統支援將值對應至 udm.principal.ip。
系統不支援將值對應至 udm.intermediary.hostname，因為 intermediary 是重複欄位，且不在階層的最低層級。

下表提供範例，說明「重複欄位」選取器設定如何影響產生的 UDM 記錄。

選取重複欄位	記錄檔範例	剖析器擴充功能設定	生成的結果
附加值	`{"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"1.1.1.1, 2.2.2.2"}}}`	先決條件欄位：`protoPayload.requestMetadata.callerIp` 先決條件值：`" "` 先決條件運算子：`NOT_EQUALS` 原始資料欄位：`protoPayload.requestMetadata.callerIp` 目的地欄位：`event.idm.read_only_udm.principal.ip`	`metadata:{event_timestamp:{}.....}principal:{Ip:"1.1.1.1, 2.2.2.2"} } }`
附加值	`{"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"2.2.2.2, 3.3.3.3", "name":"Akamai Ltd"}}}`	先決條件 1：先決條件欄位：`protoPayload.requestMetadata.callerIp` 先決條件值：`" "` 先決條件運算子：`NOT_EQUALS` 原始資料欄位：`protoPayload.requestMetadata.callerIp` 目的地欄位：`event.idm.read_only_udm.principal.ip` 前提條件 2：原始資料欄位：`protoPayload.requestMetadata.name` 目的地欄位：`event.idm.read_only_udm.metadata.product_name`	套用擴充功能前，預先建構的剖析器產生的事件。 `metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}` 套用擴充功能後的輸出內容。 `timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} .... product_name: "Akamai Ltd"}principal:{ip:"1.1.1.1, 2.2.2.2, 3.3.3.3"}}}`
替換值	`{"protoPayload":{"@type":"type..AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"2.2.2.2"}}}`	先決條件欄位：`protoPayload.authenticationInfo.principalEmail` 先決條件值：`" "` 先決條件運算子：`NOT_EQUALS` 原始資料欄位：`protoPayload.authenticationInfo.principalEmail` 目的地欄位：`event.idm.read_only_udm.principal.ip`	套用擴充功能前，預先建構的剖析器產生的 UDM 事件。 `timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}` 套用擴充功能後的 UDM 輸出內容 `timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ....} principal:{ip:"2.2.2.2"}}}`

限制

每個記錄類型只能有一個剖析器擴充功能：每個記錄類型只能建立一個剖析器擴充功能。
只能使用一種資料對應指示方法：您可以採用無程式碼或程式碼片段方法建立剖析器擴充功能，但不能同時使用這兩種方法。
用於驗證的記錄樣本：驗證 UDM 剖析器擴充功能時，需要過去 30 天內的記錄樣本。詳情請參閱「確認記錄類型有可用的剖析器」。
基本剖析器錯誤：剖析器擴充功能無法識別或修正基本剖析器錯誤。
重複欄位處理：您只能在特定擴充功能中使用單一方法 (附加或取代)。替換整個重複物件時請務必小心，以免資料意外遺失。
Additional.fields會解讀為一組鍵/值組合，而非重複欄位：因此，只要將剖析器和擴充功能的 UDM 對應及輸出內容各自的鍵/值新增至集合，即可順暢地合併兩者。
消除歧義的事件：剖析器擴充功能無法處理單一記錄中有多個不重複事件的記錄，例如 Google 雲端硬碟陣列。
XML 和無程式碼：XML 不支援無程式碼模式。請改用程式碼片段方法。
剖析器語法與 YARA-L 偵測規則：擷取剖析器和剖析器擴充功能會在擷取時使用 Logstash Grok 和設定語法搭配篩選器 (例如 grok、mutate、json、date 和 base64)，將原始記錄剖析為統合式資料模型 (UDM)。剖析器無法使用 YARA-L 語法、結果區塊或產生器函式 (例如 yield)。YARA-L 2.0 嚴格來說是偵測引擎查詢語言，會在標準化 UDM 事件的下游進行評估，用於發出威脅快訊，無法剖析原始記錄、變更 UDM 欄位或捨棄傳入的記錄流量。
預設只會轉送應用程式：根據預設，剖析器擴充功能只會套用至啟用後新擷取的記錄。如有重大業務需求，需要使用更新後的對應重新剖析歷來記錄，可以透過 Google Cloud 支援服務要求執行後端記錄重播工作。詳情請參閱「重新剖析歷來資料 (記錄重播)」。
剖析器邏輯無法存取擷取標籤：剖析器擴充功能無法讀取擷取標籤 (metadata.ingestion_labels)，將值對應至 UDM 欄位，因為剖析器會在沙箱執行環境中執行，只能查看原始記錄主體。
使用無程式碼方法時的保留關鍵字：如果記錄檔包含下列任何保留關鍵字，請使用程式碼片段方法，而非無程式碼方法：
- collectionTimestamp
- createTimestamp
- enableCbnForLoop
- event
- filename
- message
- namespace
- output
- onErrorCount
- timestamp
- timezone
移除現有對應關係：您只能使用程式碼片段方法，移除現有的 UDM 欄位對應關係。
無法使用擴充功能移除主機名稱 UDM 欄位的對應關係：您無法使用擴充功能取消設定 (移除) 主機名稱 UDM 欄位 (例如 principal.hostname) 的對應關係。

剖析器概念

下列文件說明重要的剖析器概念：

必要條件

建立剖析器擴充功能的必要條件：

記錄類型必須有運作中的預設 (或自訂) 剖析器。
Google SecOps 必須能夠使用預設 (或自訂) 剖析器，擷取及正規化原始記錄。
請確認目標記錄類型的主動預設 (或自訂) 剖析器，在過去 30 天內已擷取原始記錄資料。這項資料應包含您打算擷取或用於篩選記錄的欄位樣本。這項資訊將用於驗證新的資料對應指示。

開始使用

建立剖析器擴充功能前，請先完成下列工作：

確認必要條件：

確認記錄類型有運作中的剖析器。如果尚未建立剖析器，請建立自訂剖析器。
找出要從原始記錄中擷取的欄位：

找出要從原始記錄中擷取的欄位。
選取適當的 UDM 欄位：

選取適當的對應 UDM 欄位，以對應擷取的原始記錄欄位。
選擇剖析器擴充功能定義方法：

選擇其中一種擴充方法 (資料對應方法) 來建立剖析器擴充功能。

確認先決條件

請確認您要擴充的記錄類型有運作中的剖析器，如以下章節所述：

確認記錄類型有運作中的剖析器

請確定您要擴充的記錄類型有有效的預設 (或自訂) 剖析器。

在下列清單中搜尋記錄類型：

支援的記錄檔類型 (使用預設剖析器)。
- 如果記錄類型有預設剖析器，請確認剖析器已啟用。
- 如果記錄類型沒有預設剖析器，請確認記錄類型有自訂剖析器。
支援的記錄類型 (沒有預設剖析器)。
- 如果記錄類型沒有預設剖析器，請確認記錄類型有自訂剖析器。

確認記錄類型有自訂剖析器

如要確保記錄類型有自訂剖析器，請按照下列步驟操作：

在導覽列中，依序選取「SIEM 設定」 >「剖析器」。
在「剖析器」表格中，搜尋要擴充的記錄檔類型。
- 如果該記錄類型尚未有預設或自訂剖析器，請按一下「新增剖析器」 (或「建立剖析器」)，然後按照「根據對應指示建立自訂剖析器」一文中的步驟操作。
- 如果該記錄類型已有自訂剖析器，請確認剖析器已啟用。

確認剖析器已啟用記錄類型

如要檢查剖析器是否適用於記錄類型，請按照下列步驟操作：

在導覽列中，依序選取「SIEM 設定」 >「剖析器」。
在「剖析器」表格中，搜尋要擴充的記錄檔類型。

如果記錄類型的剖析器未啟用，請啟用：
- 如要瞭解預設剖析器，請參閱「管理預建剖析器更新」。
- 如需自訂剖析器，請參閱「設定自訂剖析器」。

找出要從原始記錄檔擷取的欄位

分析要擷取資料的原始記錄，找出預設 (或自訂) 剖析器未擷取的欄位。請注意預設 (或自訂) 剖析器如何擷取原始記錄欄位，並將其對應至相應的 UDM 欄位。

如要找出要從原始記錄中擷取的特定欄位，可以使用搜尋工具找出這些欄位：

如要存取搜尋工具，請依序前往「調查」>「SIEM 搜尋」。在搜尋查詢前方輸入 raw=。詳情請參閱「搜尋原始記錄」。
如要使用舊版搜尋工具，請按一下「SIEM 搜尋」頁面頂端的「前往舊版搜尋」。詳情請參閱「舊版方法：使用原始記錄搜尋提示」。

如要進一步瞭解如何搜尋原始記錄，請參閱：

選取適當的 UDM 欄位

現在您已找出要擷取的特定目標欄位，可以將這些欄位對應至相應的目的地 UDM 欄位。在原始記錄來源欄位和目的地 UDM 欄位之間建立明確的對應關係。您可以將資料對應至任何支援標準資料類型或重複欄位的 UDM 欄位。

選擇正確的 UDM 欄位

下列資源可協助簡化程序：

熟悉主要的 UDM 概念
瞭解現有剖析器使用的資料對應
使用 UDM 查詢工具，找出與來源欄位相符的潛在 UDM 欄位。
剖析器資料對應的重要 UDM 欄位指南，包含 UDM 結構定義最常用欄位的摘要和說明。
「統合式資料模型欄位清單」包含所有 UDM 欄位及其說明。清單中的「repeated」標籤會標示重複欄位。
避免錯誤的重要 UDM 注意事項

熟悉主要的 UDM 概念

邏輯物件：事件和實體

UDM 結構定義會說明儲存資料的所有可用屬性。每筆 UDM 記錄都會說明事件或實體。資料會儲存在不同欄位，視記錄描述的是事件還是實體而定。
- UDM 事件物件會儲存環境中發生的動作相關資料。原始事件記錄檔會說明裝置記錄的動作，例如防火牆或網頁 Proxy。
- UDM 實體物件會儲存與 UDM 事件相關的參與者或實體資料，例如您環境中的資產、使用者或資源。
UDM 事件結構
UDM 實體結構

UDM 名詞：名詞代表 UDM 事件中的參與者或實體。舉例來說，名詞可以是「執行」事件中所述活動的裝置或使用者。名詞也可以是事件所描述活動的目標裝置或使用者。

UDM 名詞	說明
`principal`	負責啟動事件所述動作的實體。
`target`	動作的對象或目標實體。在防火牆連線中，接收連線的機器就是目標。
`src`	主體對來源實體執行的動作。舉例來說，如果使用者將檔案從一部電腦複製到另一部電腦，檔案和原始電腦就會以 src 表示。
`intermediary`	在事件中擔任中介角色的任何實體，例如 Proxy 伺服器。這類擴充功能可能會影響動作，例如封鎖或變更要求。
`observer`	負責監控及回報事件，但不會直接與流量互動的實體。例如網路入侵偵測系統，或是安全資訊與事件管理系統。
`about`	事件中涉及的其他實體，不屬於上述類別。例如電子郵件附件，或程序啟動期間載入的 DLL。

在實務上，最常使用的主體和目標名詞物件是：此外，請注意上述說明為名詞的建議用法。實際用量可能會因預設或自訂基礎剖析器的實作方式而異。

瞭解現有剖析器使用的資料對應

建議您先瞭解預設 (或自訂) 剖析器使用的現有資料對應，也就是原始記錄來源欄位與目的地 UDM 欄位之間的對應。

如要查看原始記錄來源欄位與現有預設 (或自訂) 剖析器所用目的地 UDM 欄位之間的資料對應，請按照下列步驟操作：

在導覽列中，依序選取「SIEM 設定」 >「剖析器」。
在「剖析器」表格中，搜尋要擴充的記錄檔類型。
前往該資料列，然後依序點選「選單」 >「查看」。

在「預先建構」 (或「自訂」) 分頁中，「剖析器程式碼」部分會顯示原始記錄來源欄位與現有預設 (或自訂) 剖析器中使用的目的地 UDM 欄位之間的資料對應。

使用 UDM 查詢工具

使用 UDM 查詢工具，找出與原始記錄來源欄位相符的 UDM 欄位。

Google SecOps 提供 UDM 查詢工具，可協助您快速找出目的地 UDM 欄位。如要存取 UDM 查詢工具，請依序前往「調查」>「SIEM 搜尋」。

如要瞭解如何使用 UDM 查詢工具，請參閱下列主題：

UDM 查詢工具範例

舉例來說，如果原始記錄中有一個名為「packets」的來源欄位，請使用 UDM 查詢工具，找出名稱中含有「packets」的潛在目的地 UDM 欄位：

依序前往「調查」>「SIEM 搜尋」。
在「SIEM Search」(SIEM 搜尋) 頁面中，按一下「UDM Lookup」(UDM 查詢)。

系統隨即會開啟「UDM Lookup」對話方塊。搜尋工具會依欄位名稱或欄位值比對 UDM 欄位：
- 依欄位名稱查詢 - 比對您輸入的文字字串與含有該文字的欄位名稱。
- 依欄位值查詢：比對您輸入的值與儲存的記錄資料中包含該值的欄位。
在「UDM 查詢」對話方塊的「查詢 UDM 欄位/值」欄位中輸入「packets」，然後選取「UDM 欄位」。

搜尋功能會顯示潛在的 UDM 欄位清單，這些欄位的 UDM 欄位名稱包含「封包」一詞。
逐一點選各列，即可查看每個 UDM 欄位的說明。

避免發生錯誤的重要 UDM 注意事項

名稱相似的欄位：UDM 的階層式結構可能會導致欄位名稱相似。請參閱預設剖析器，瞭解相關指引。詳情請參閱「瞭解現有剖析器使用的資料對應」。
任意欄位對應：使用 additional 物件，對應無法直接對應至 UDM 欄位的資料。詳情請參閱「將任意欄位對應至 UDM」。
重複欄位：在程式碼片段中使用重複欄位時，請務必謹慎。取代整個物件可能會覆寫原始資料。使用無程式碼方法可進一步控管重複欄位。詳情請參閱「重複欄位選取器」。
UDM 事件類型適用的必要 UDM 欄位：將 UDM metadata.event_type 欄位指派給 UDM 記錄時，每個 event_type 都需要 UDM 記錄中存在一組不同的相關欄位。詳情請參閱「進一步瞭解如何指派 UDM metadata.event_type 欄位」。
基本剖析器問題：剖析器擴充功能無法修正基本剖析器的錯誤。基礎剖析器是建立 UDM 記錄的預設 (或自訂) 剖析器。請考慮加強剖析器擴充功能、修改基本剖析器或預先篩選記錄等選項。

將任意欄位對應至 UDM

如果找不到合適的標準 UDM 欄位來儲存資料，請使用 additional 物件將資料儲存為自訂鍵/值組合。即使 UDM 記錄沒有相符的 UDM 欄位，您還是能將重要資訊儲存在 UDM 記錄中。

選擇剖析器擴充功能定義方法

選擇剖析器擴充功能定義方法前，請先完成下列章節：

建立剖析器擴充功能
開始使用

接下來，請開啟「Parser Extension」頁面，然後選取要用來定義剖析器擴充功能的擴充功能方法：

開啟剖析器擴充功能頁面

您可以在「剖析器擴充功能」頁面定義新的剖析器擴充功能。

您可以透過下列方式開啟「剖析器擴充功能」頁面：從「設定」選單、從「原始記錄搜尋」，或從舊版「原始記錄搜尋」：

從「設定」選單開啟

如要從「設定」選單開啟「剖析器擴充功能」頁面，請按照下列步驟操作：

在導覽列中，依序選取「SIEM 設定」 >「剖析器」。

「剖析器」表格會依記錄檔類型顯示預設剖析器清單。
找到要擴充的記錄類型，依序點選「選單」圖示 >「擴充剖析器」>「建立擴充功能」。

「剖析器擴充功能」頁面隨即開啟。

從「原始記錄檔搜尋」開啟

如要從「原始記錄搜尋」開啟「剖析器擴充功能」頁面，請按照下列步驟操作：

依序前往「調查」>「SIEM 搜尋」。
在搜尋欄位中，將前置字元 raw = 新增至搜尋引數，並將搜尋字詞放在引號內。例如：raw = "example.com"。
按一下「執行搜尋」。結果會顯示在「原始記錄」面板中。
在「原始記錄」面板中，按一下記錄 (資料列)。系統會顯示「事件檢視器」面板。
在「Event Viewer」面板中，按一下「Raw Log」分頁標籤。系統會顯示原始記錄。
依序點選「管理剖析器」>「擴充剖析器」>「建立擴充功能」 (或依序選取「建立擴充功能」>「下一步」)。

「剖析器擴充功能」頁面隨即開啟。

從舊版「原始記錄檔搜尋」開啟

如要從舊版「原始記錄檔搜尋」開啟「剖析器擴充功能」頁面，請按照下列步驟操作：

使用舊版「原始記錄搜尋」，搜尋與要剖析的記錄類似的記錄。
從「時間軸」面板選取事件 (或按一下原始記錄圖示)，即可開啟原始記錄。
依序點選「管理剖析器」>「擴充剖析器」>「建立擴充功能」 (或依序選取「建立擴充功能」>「下一步」)。

「剖析器擴充功能」頁面隨即開啟。

剖析器擴充功能頁面

頁面會顯示「原始記錄」和「擴充功能」 (擴充功能定義) 面板：

「原始記錄」面板：

系統會顯示所選記錄類型的原始記錄資料範例。如果您是從「原始記錄搜尋」開啟頁面，範例資料就是搜尋結果。您可以使用 「View as」(顯示為) 選單 (Raw、JSON、CSV、XML 或 Hex/ASCII) 和「Wrap Text」(換行) 核取方塊，設定範例格式。
1. 確認顯示的原始記錄資料樣本可代表剖析器擴充功能將處理的記錄。
2. 按一下「預覽 UDM 輸出內容」 (或「顯示 UDM 輸出內容」)，即可查看範例原始記錄資料的 UDM 輸出內容。
「擴充功能」(擴充功能定義) 面板：

您可以透過兩種對應指令方法定義剖析器擴充功能：對應資料欄位 (免程式碼) 或編寫程式碼片段 (或編寫程式碼片段)。您無法在同一個剖析器擴充功能中同時使用這兩種方法。

視您選擇的方法而定，您可以指定要從傳入的原始記錄檔中擷取的來源記錄檔資料欄位，並將這些欄位對應至相應的 UDM 欄位，也可以編寫程式碼片段來執行這些工作及其他作業。

選取擴充功能做法

在「剖析器擴充功能」頁面，「擴充功能」面板的「擴充功能方法」欄位中，選取下列其中一種方法來建立剖析器擴充功能：

對應資料欄位 (免程式碼) 方法：

您可以使用這種方法指定原始記錄中的欄位，並將這些欄位對應至目的地 UDM 欄位。

這個方法適用於下列原始記錄格式：
- 原生 JSON、原生 XML 或 CSV。
- Syslog 標頭加上原生 JSON、原生 XML 或 CSV。您可以為下列格式的原始記錄建立資料欄位類型對應說明：JSON、XML、CSV、SYSLOG + JSON、SYSLOG + XML 和 SYSLOG + CSV。
請參閱下一個步驟的「建立無程式碼 (地圖資料欄位) 指示」。
編寫程式碼片段 (或編寫程式碼片段) 方法：

這種方法可讓您使用類似 Logstash 的語法指定指令，從原始記錄中擷取及轉換值，並將這些值指派給 UDM 記錄中的 UDM 欄位。
- 程式碼片段使用的語法和區段，與預設 (或自訂) 剖析器相同。詳情請參閱「剖析器語法」。
- 這種做法適用於該記錄類型支援的所有資料格式。
請參閱下一個步驟：建立程式碼片段操作說明。

建立無程式碼 (地圖資料欄位) 指示

無程式碼做法 (也稱為「對應資料欄位」方法) 可讓您指定原始記錄欄位的路徑，並將這些欄位對應至相應的目標 UDM 欄位。

使用免程式碼方法建立剖析器擴充功能前，請先完成下列章節：

建立剖析器擴充功能
開始使用
選取擴充方法，然後選取「對應資料欄位」選項。

定義剖析器擴充功能的後續步驟如下：

設定重複欄位選取器
為每個欄位定義資料對應指令
提交並啟用剖析器擴充功能

為每個欄位定義資料對應指令

為要從原始記錄中擷取的每個欄位定義資料對應指令。指令應指定原始記錄中的來源欄位路徑，並將其對應至目的地 UDM 欄位。

如果「原始記錄」面板中顯示的原始記錄樣本包含 Syslog 標頭，系統就會顯示「Syslog」和「目標」欄位。(部分記錄格式不含 Syslog 標頭，例如原生 JSON、原生 XML 或 CSV)。

Google SecOps 需要「Syslog」和「Target」欄位，預先處理 Syslog 標頭，並擷取記錄的結構化部分。
1. 定義下列欄位：
  - Syslog：這是使用者定義的模式，可預先處理原始記錄，並將 Syslog 標頭與結構化部分分開。
    
    使用 Grok 和規則運算式指定擷取模式，識別 Syslog 標頭和原始記錄訊息。詳情請參閱「定義 Syslog 擷取器欄位」。
  - 目標：Syslog 欄位中的變數名稱，用於儲存記錄的結構化部分。
    
    在擷取模式中指定變數名稱，儲存記錄的結構化部分。
  以下分別是「Syslog」和「目標」欄位的擷取模式和變數名稱範例。
2. 在「Syslog」和「Target」欄位中輸入值後，按一下「Validate」按鈕。
  
  驗證程序會檢查語法和剖析錯誤，然後傳回下列任一項目：
  - 成功：系統會顯示資料對應欄位。定義剖析器擴充功能的其餘部分。
  - 失敗：系統會顯示錯誤訊息。請先修正錯誤情況再繼續。
(選用) 定義先決條件指令。

前置條件指令會將靜態值與原始記錄中的欄位比對，找出剖析器擴充功能要處理的原始記錄子集。如果傳入的原始記錄符合前提條件，剖析器擴充功能就會套用對應指令。如果值不相符，剖析器擴充功能就不會套用對應指令。

填寫下列欄位：
- 先決條件欄位 (或 CSV 的先決條件資料欄)：原始記錄中的欄位 ID，內含要比較的數值。如果記錄資料格式為 JSON 或 XML，請輸入欄位的完整路徑；如果資料格式為 CSV，請輸入資料欄位置。
- 先決條件運算子：選取「等於」或「不等於」。
- 先決條件值：與原始記錄中的先決條件欄位進行比較的靜態值。
如需前置條件指令的另一個範例，請參閱「無程式碼 - 使用前置條件值擷取欄位」。
將原始記錄資料欄位對應至目的地 UDM 欄位：
- 原始資料欄位 (或 CSV 的原始資料欄)：如果記錄資料格式為 JSON (例如：jsonPayload.connection.dest_ip) 或 XML (例如：/Event/Reason-Code)，請輸入欄位的完整路徑；如果資料格式為 CSV，請輸入欄位位置 (注意：索引位置從 1 開始)。
- 目的地欄位：輸入用來儲存值的完整 UDM 欄位名稱，例如 udm.metadata.collected_timestamp.seconds。
重要事項： 如果原始記錄採用 JSON 格式，記錄值的資料類型必須與對應目的地 UDM 欄位的資料類型一致。舉例來說，如果記錄檔將 packets sent 記錄為字串 ("packets_sent":"16")，而您嘗試將此字串對應至具有 uint64 資料類型的 network.sent_bytes UDM 欄位，指令就會失敗。這項規定不適用於 CSV 和 XML 格式的記錄。
如要繼續新增更多欄位，請按一下「新增」，然後輸入下一個欄位的所有對應指示詳細資料。

如需對應欄位的其他範例，請參閱「無程式碼 - 擷取欄位」。

提交並啟用剖析器擴充功能

為要從原始記錄中擷取的所有欄位定義資料對應指示後，請提交並啟用剖析器擴充功能。

按一下「提交」，儲存並驗證對應指示。

Google SecOps 會驗證對應指示：

如果驗證程序成功，狀態會變更為「有效」，且對應指令會開始處理傳入的記錄資料。

如果驗證程序失敗，狀態會變更為「失敗」，且「原始記錄」欄位會顯示錯誤。

以下是驗證錯誤的範例：

  ERROR: generic::unknown: pipeline.ParseLogEntry failed: LOG_PARSING_CBN_ERROR:
  "generic::invalid_argument: pipeline failed: filter mutate (7) failed: copy failure:
  copy source field \"jsonPayload.dest_instance.region\" must not be empty
  (try using replace to provide the value before calling copy)

  "LOG: {"insertId":"14suym9fw9f63r","jsonPayload":{"bytes_sent":"492",
  "connection":{"dest_ip":"10.12.12.33","dest_port":32768,"protocol":6,
  "src_ip":"10.142.0.238","src_port":22},"end_time":"2023-02-13T22:38:30.490546349Z",
  "packets_sent":"15","reporter":"SRC","src_instance":{"project_id":"example-labs",
  "region":"us-east1","vm_name":"example-us-east1","zone":"us-east1-b"},
  "src_vpc":{"project_id":"example-labs","subnetwork_name":"default",
  "vpc_name":"default"},"start_time":"2023-02-13T22:38:29.024032655Z"},
  "logName":"projects/example-labs/logs/compute.googleapis.com%2Fvpc_flows",
  "receiveTimestamp":"2023-02-13T22:38:37.443315735Z","resource":{"labels":
  {"location":"us-east1-b","project_id":"example-labs",
    "subnetwork_id":"00000000000000000000","subnetwork_name":"default"},
    "type":"gce_subnetwork"},"timestamp":"2023-02-13T22:38:37.443315735Z"}

剖析器擴充功能的生命週期狀態

剖析器擴充功能有下列生命週期狀態：

DRAFT：尚未提交的新建剖析器擴充功能。
VALIDATING：Google SecOps 會根據現有的原始記錄驗證對應指令，確保欄位剖析作業不會發生錯誤。
LIVE：剖析器擴充功能通過驗證，現已投入生產。這項服務會從傳入的原始記錄中擷取資料，並轉換為 UDM 記錄。
FAILED：剖析器擴充功能驗證失敗。

進一步瞭解 Syslog 擷取器欄位

您可以定義 Grok、規則運算式，以及規則運算式模式中的具名權杖，將 Syslog 標頭與結構化記錄分開，並儲存輸出內容。

定義 Syslog 擷取器欄位

「Syslog」和「Target」欄位中的值會共同定義剖析器擴充功能如何將 Syslog 標頭與原始記錄的結構化部分分開。在「Syslog」Syslog欄位中，您可以使用 Grok 和規則運算式語法組合定義運算式。運算式包含變數名稱，可識別原始記錄的結構化部分。在「目標」欄位中，指定該變數名稱。

以下範例說明這些欄位如何搭配運作。

以下是原始記錄的範例：

<13>1 2022-09-14T15:03:04+00:00 fieldname fieldname - - - {"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

原始記錄包含下列部分：

系統記錄檔標頭：<13> 2022-09-14T15:03:04+00:00 fieldname fieldname - - -
JSON 格式的事件：{"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

如要將 Syslog 標頭與原始記錄的 JSON 部分分開，請在「Syslog」Syslog欄位中使用下列範例運算式：%{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg}

運算式的這個部分會識別 Syslog 標頭： %{TIMESTAMP\_ISO8601} %{WORD} %{WORD} ([- ]+)?
運算式的這個部分會擷取原始記錄的 JSON 區段： %{GREEDYDATA:msg}

這個範例包含變數名稱 msg。您可以選擇變數名稱。剖析器擴充功能會擷取原始記錄的 JSON 區段，並指派給 msg 變數。

在「目標」欄位中，輸入變數名稱 msg。儲存在 msg 變數中的值，會輸入至您在剖析器擴充功能中建立的資料欄位對應指令。

以原始記錄範例為例，以下區隔會輸入至資料對應指令：

{"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

下圖顯示已填寫的「Syslog」和「Target」欄位：

系統記錄檔擷取器欄位

下表提供更多範例，包括範例記錄、Syslog 擷取模式、Target 變數名稱和結果。

原始記錄範例	Syslog 欄位	目標欄位	結果
`<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}"`	`%{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg}`	msg	`field_mappings { field: "msg" value: "{\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" }`
`<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\"} - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}`	`%{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg1} ([- ]+)?%{GREEDYDATA:msg2}`	msg2	`field_mappings { field: "msg2" value: "{\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" }`
`"<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\"} - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}"`	`%{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:message} ([- ]+)?%{GREEDYDATA:msg2}`	msg2	`Error - message already exists in state and not overwritable.`

進一步瞭解如何指派 UDM `metadata.event_type` 欄位

將 UDM metadata.event_type 欄位指派給 UDM 記錄時，系統會進行驗證，確保 UDM 記錄中包含必要的相關欄位。每個 UDM metadata.event_type 都需要一組不同的相關欄位，舉例來說，沒有 user 的 USER_LOGIN 事件就沒有用。

如果缺少必要的相關欄位，UDM 驗證會傳回錯誤：

  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }

Grok 剖析器會傳回更詳細的錯誤：

  generic::unknown:
  invalid event 0: LOG_PARSING_GENERATED_INVALID_EVENT:
  "generic::invalid_argument: udm validation failed: target field is not set"

如要找出指派 UDM event_type 時的必填欄位，請使用下列資源。採用指南會補充 UDM 使用指南，提供填入特定 UDM metadata.event_type 時所需的最低強制性 UDM 欄位。

Google SecOps 說明文件：UDM 使用指南 - 各事件類型的必要和選用 UDM 欄位
採用指南：深入瞭解 UDM 剖析 - 第 1.1 部分
採用指南：GoStaash 剖析基本概念

舉例來說，開啟文件並搜尋 GROUP_CREATION 事件類型。

您應該會看到下列最低 UDM 欄位，以 UDM 物件的形式呈現：

  {
      "metadata": {
          "event_timestamp": "2023-07-03T13:01:10.957803Z",
          "event_type": "GROUP_CREATION"
      },
      "principal": {
          "user": {
              "userid": "pinguino"
          }
      },
      "target": {
          "group": {
              "group_display_name": "foobar_users"
          }
      }
  }

建立程式碼片段操作說明

使用程式碼片段方法時，您可以運用類似 Logstash 的語法，定義如何從原始記錄中擷取及轉換值，並將這些值指派給 UDM 記錄中的 UDM 欄位。

使用程式碼片段方法建立剖析器擴充功能前，請先完成下列章節：

建立剖析器擴充功能
開始使用
選取擴充功能方法，然後選取「編寫程式碼片段」 (或「編寫程式碼片段」) 選項。

定義剖析器擴充功能的後續步驟如下：

如需提示和最佳做法，請參閱「撰寫程式碼片段指令的提示和最佳做法」。
建立程式碼片段指令
提交程式碼片段指示

撰寫程式碼片段指令的訣竅與最佳做法

如果 Grok 模式不正確、重新命名或取代作業失敗，或是發生語法錯誤，程式碼片段指令可能會失敗。如需提示和最佳做法，請參閱下列文章：

建立程式碼片段指示

程式碼片段操作說明會使用與預設 (或自訂) 剖析器相同的語法和區段：

第 1 節：從原始記錄中擷取資料。
第 2 節。轉換擷取的資料。
第 3 節。為一或多個 UDM 欄位指派值。
第 4 節。將 UDM 事件欄位繫結至 @output 鍵。

如要使用程式碼片段建立剖析器擴充功能，請按照下列步驟操作：

在「剖析器擴充功能」頁面的「CBN 程式碼片段」面板中，輸入程式碼片段來建立剖析器擴充功能。
按一下「驗證」，驗證對應指示。

程式碼片段指令範例

以下範例說明程式碼片段。

以下是原始記錄的範例：

  {
      "insertId": "00000000",
      "jsonPayload": {
          ...section omitted for brevity...
          "packets_sent": "4",
          ...section omitted for brevity...
      },
      "timestamp": "2022-05-03T01:45:00.150614953Z"
  }

以下程式碼片段範例會將 jsonPayload.packets_sent 中的值對應至 network.sent_bytes UDM 欄位：

filter {
  mutate {
    replace => {
      "jsonPayload.packets_sent" => ""
    }
  }
  # Section 1. extract data from the raw JSON log
  json {
    source => "message"
    array_function => "split_columns"
    on_error => "_not_json"
  }
  if [_not_json] {
    drop {
      tag => "TAG_UNSUPPORTED"
    }
  } else {
    # Section 2. transform the extracted data
    if [jsonPayload][packets_sent] not in ["", 0] {
      mutate {
        convert => {
          "jsonPayload.packets_sent" => "uinteger"
        }
        on_error => "_exception1"
      }
      # Section 3. assign the value to a UDM field
      mutate {
        Replace => {
          "event.idm.read_only_udm.network.sent_bytes" => "jsonPayload.packets_sent"
        }
        on_error => "_exception2"
      }
      if ![_exception1] and![_exception2] {
        # Section 4. Bind the UDM fields to the @output key
        mutate {
          merge => {
            "@output" => "event"
          }
        }
      }
    }
  }
}

提交程式碼片段指令

按一下「提交」即可儲存對應指示。
Google SecOps 會驗證對應指示。
- 如果驗證程序成功，狀態會變更為「有效」，且對應指令會開始處理傳入的記錄資料。
- 如果驗證程序失敗，狀態會變更為「失敗」，且「原始記錄」欄位會顯示錯誤。
注意： 驗證剖析器擴充功能時，無法編輯資料對應指示。

管理現有剖析器擴充功能

您可以查看、編輯、刪除及控管現有剖析器擴充功能的存取權。

查看現有的剖析器擴充功能

在導覽列中，依序選取「SIEM 設定」 >「剖析器」。
在剖析器清單中，找出要查看的剖析器 (記錄類型)。如果剖析器有剖析器擴充功能，名稱旁會顯示 EXTENSION (或 EXTN) 文字。
前往該資料列，然後依序點選「選單」 >「擴充剖析器」 >「查看擴充功能」。

系統會顯示「查看自訂/預建剖析器」>「擴充功能」分頁 (或「擴充功能」分頁)，其中會顯示剖析器擴充功能的詳細資料。摘要面板預設會顯示剖析器擴充功能。LIVE

編輯剖析器擴充功能

如「查看現有的剖析器擴充功能」一文所述，開啟「View Custom/Prebuilt Parser」 >「Extension」分頁 (或「Extensions」分頁)。
按一下「編輯擴充功能」 (或「編輯」) 按鈕。

系統隨即會顯示「剖析器擴充功能」頁面。
編輯剖析器擴充功能。
- 如要取消編輯並捨棄變更，請按一下「捨棄草稿」 (或「捨棄擴充功能」)。
- 如要隨時刪除剖析器擴充功能，請按一下「刪除失敗的擴充功能」 (或「刪除擴充功能」)。
- 編輯剖析器擴充功能完成後，按一下「提交」。
  
  系統會執行驗證程序，驗證新設定。
  
  注意： 驗證剖析器擴充功能時，您無法編輯資料對應指示。

刪除剖析器擴充功能

如「查看現有的剖析器擴充功能」一文所述，開啟「View Custom/Prebuilt Parser」 >「Extension」分頁 (或「Extensions」分頁)。
按一下「刪除擴充功能」按鈕。

控管剖析器擴充功能的存取權

根據預設，具備「管理員」角色的使用者可以存取剖析器擴充功能。您可以控管哪些人能查看及管理剖析器擴充功能。如要進一步瞭解如何管理使用者和群組，或指派角色，請參閱「角色式存取控管」。

下表列出 Google SecOps 的新角色。

功能	動作	說明
剖析器	刪除	刪除剖析器擴充功能。
剖析器	編輯	建立及編輯剖析器擴充功能。
剖析器	查看	查看剖析器擴充功能。

使用剖析器擴充功能移除 UDM 欄位對應

您可以使用剖析器擴充功能移除現有的 UDM 欄位對應。

依序點選「SIEM 設定」>「剖析器」。
使用下列任一方法查看「剖析器擴充功能」頁面：
- 如要查看現有擴充功能，請依序點選「選單」圖示 >「擴充剖析器」>「查看擴充功能」。
- 如要建立新的剖析器擴充功能，請依序點選「選單」圖示 >「擴充剖析器」>「建立擴充功能」。
選取「Write Code Snippets」(撰寫程式碼片段) (或「Write code snippet」)，做為擴充方法，加入自訂程式碼片段，移除特定 UDM 欄位的值。

如要為現有擴充功能新增程式碼片段，請在「擴充功能」 (或「擴充功能」) 分頁中，按一下「編輯擴充功能」 (或「編輯」)，然後新增程式碼片段。

如需程式碼片段範例，請參閱「程式碼片段 - 移除現有對應」。
按照「提交程式碼片段指令」中的步驟提交擴充功能。

時區處理和時間戳記格式設定

Google SecOps 會以 RFC 3339 UTC 格式，將時間戳記標準化及序列化至微秒精確度 (YYYY-MM-DDTHH:MM:SS.ffffffZ)。如果來源記錄僅提供秒級精確度，平台會自動在缺少的尾數部分填入尾隨零 (.000000Z)，以維持結構定義一致性。

如果事件時間戳記早於擷取時間 (ingested_timestamp < event_timestamp)，通常是因為來源發出當地實際時間的時間戳記，但沒有 ISO 時區偏移量 (預設為世界標準時間)，或是發生時鐘漂移。如要解決時區差異問題，請使用下列任一方法：

在剖析器擴充功能中調整時間戳記：在程式碼片段剖析器擴充功能中使用 date 篩選器，指定來源時區：

if [raw_log] =~ /EST/ {
  date {
    match => [ "timestamp_str", "MMM dd HH:mm:ss" ]
    timezone => "America/New_York"
    target => "event.metadata.event_timestamp"
  }
}

設定轉送器收集器時區覆寫：依序前往「SIEM Settings」>「Forwarders」，編輯目標收集器，啟用「Override timezone」，然後從「Timezone」選單中選取來源 IANA 時區 (例如 Europe/Paris)，即可在擷取期間自動調整時間戳記。

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

開發剖析器擴充功能

建立剖析器擴充功能

剖析器擷取和正規化程序

定義新的剖析器擴充功能

將新擷取的值併入 UDM 欄位

重複欄位選取器

附加與取代行為

限制

剖析器概念

必要條件

開始使用

確認先決條件

確認記錄類型有運作中的剖析器

確認記錄類型有自訂剖析器

確認剖析器已啟用記錄類型

找出要從原始記錄檔擷取的欄位

選取適當的 UDM 欄位

選擇正確的 UDM 欄位

熟悉主要的 UDM 概念

瞭解現有剖析器使用的資料對應

使用 UDM 查詢工具

UDM 查詢工具範例

避免發生錯誤的重要 UDM 注意事項

將任意欄位對應至 UDM

選擇剖析器擴充功能定義方法

開啟剖析器擴充功能頁面

從「設定」選單開啟

從「原始記錄檔搜尋」開啟

從舊版「原始記錄檔搜尋」開啟

剖析器擴充功能頁面

選取擴充功能做法

建立無程式碼 (地圖資料欄位) 指示

為每個欄位定義資料對應指令

提交並啟用剖析器擴充功能

進一步瞭解 Syslog 擷取器欄位

定義 Syslog 擷取器欄位

進一步瞭解如何指派 UDM metadata.event_type 欄位

建立程式碼片段操作說明

撰寫程式碼片段指令的訣竅與最佳做法

建立程式碼片段指示

程式碼片段指令範例

提交程式碼片段指令

管理現有剖析器擴充功能

查看現有的剖析器擴充功能

編輯剖析器擴充功能

刪除剖析器擴充功能

控管剖析器擴充功能的存取權

使用剖析器擴充功能移除 UDM 欄位對應

時區處理和時間戳記格式設定

進一步瞭解如何指派 UDM `metadata.event_type` 欄位