開發自訂轉換器

支援的國家/地區：

Google SecOps SOAR

注意： 這項功能適用《Google Security Operations 服務專屬條款》的《正式發布前產品條款》。正式發布前的功能只提供部分支援，對正式發布前的功能所做的變更可能與其他正式發布前的版本不相容。詳情請參閱《Google SecOps 技術支援服務指南》和《Google SecOps 服務專屬條款》。
如果您的環境中未顯示這項功能，請參閱「管理預覽功能」一文，或與系統管理員聯絡。

您可以在 IDE 中直接建立以 Python 為基礎的自訂轉換函式和邏輯運算子，並在應對手冊中使用這些函式和運算子，因應複雜且多樣化的用途。

擴充功能套件

擴充功能套件是一種特殊整合類型，可做為自訂轉換函式和邏輯運算子的容器。與標準整合不同，擴充功能套件不需要執行個體設定，可以直接從 IDE 建立。

擴充套件包的最佳做法

• 整合：建立一個主要擴充功能套件，並在其中新增多個轉換函式或邏輯運算子。
• 區隔：如果需要一組可能與主套件衝突的不同 Python 程式庫 (依附元件)，請建立新的擴充套件。

重要事項：如要在 IDE 中建立擴充功能套件，必須具備「所有環境」權限。

建立擴充功能套件

如要建立新的擴充功能套件，請按照下列步驟操作：

1. 前往「回應」>「IDE」。
2. 按一下「add 建立新項目」。
3. 從下拉式選單中選取「Extension Pack」。
4. 為擴充功能套件提供專屬名稱。
注意：名稱建立後即無法變更。
5. 按一下 [儲存]。

上傳依附元件

與標準整合功能一樣，擴充套件會在虛擬環境中執行，您可以在其中管理 Python 程式庫。

如要管理媒體庫，請按照下列步驟操作：

1. 在 IDE 中開啟「擴充功能套件設定」。
2. 從 PyPi 新增必要的 Python 程式庫，或從電腦上傳。

這個擴充功能套件中的所有轉換器和邏輯運算子，都能使用這些依附元件。

匯入與匯出

您可以直接在 IDE 介面中手動匯入及匯出擴充功能套件。

注意：如果客戶尚未完成第 2 階段的遷移作業，可能無法匯入及匯出資料。詳情請參閱 SOAR 遷移總覽。

自訂轉換函式

自訂轉換器是使用者定義的 Python 函式，可擴充運算式建立工具中的預建函式。您可以在 IDE 中直接建立這些函式，用於擷取及操控資料，並與現有的內建函式搭配使用。

建立自訂轉換器

如要定義新的自訂轉換器，請按照下列步驟操作：

1. 在 IDE 中找出目標擴充功能套件。
2. 選取目標擴充功能套件，在套件下方新增項目。
3. 選取「Custom Transformation Function」(自訂轉換函式)。
4. 為其命名。
注意：名稱建立後即無法變更。
5. 選用：新增說明。當您將滑鼠游標懸停在運算式建構工具中的自訂轉換器上時，就會顯示這項資訊。
6. 使用 Python 定義指令碼邏輯。您可以從提供的預設範本開始。
   • 如預先定義的範本所示，指令碼必須包含 main 函式。
   • 指令碼必須使用 SDK end 函式，將結果傳回給運算式建構工具。
   • 自訂轉換器的輸入內容可以是不同類型 (例如字串或清單)。請務必在 main 函式中將其轉換為預期類型。
   • 在轉換器的 IDE 中，您只能使用 SDK 方法的子集：
     • transformer.extract_param("ParamName")：擷取輸入值。
     • transformer.LOGGER：寫入記錄以進行偵錯。
     • transformer.end(result)：傳回轉換後的值。
7. 建立參數：
   • 每個自訂轉換器函式都包含預設的 Input 參數。這個參數代表輸入資料，也就是函式套用的預留位置。您無法刪除這項參數。
   • 此外，您也可以新增要在函式中使用的選用參數。
8. 說明文件 (選用)：定義運算式建構工具的產品內說明文件：
   • 預期輸入：說明函式預期為這個轉換器接收的資料類型 (例如「字串」或「字串清單」)。
   • 預期輸出內容：說明函式預期會為這個轉換器傳回的資料類型 (例如「布林值」)。
   • 使用範例：提供叫用函式的範例 (例如 if_empty("new_value"))。

您可以在 IDE 中直接測試自訂轉換函式邏輯，再將其用於劇本。這可讓您確認 Python 指令碼是否能正確處理各種輸入類型和參數，並傳回預期結果。

逾時

• 預設逾時時間：1 分鐘。
• 逾時時間上限：3 分鐘。

注意：由於平台會等待函式完成，您必須盡量縮短執行時間。著重於直接轉換資料，避免大量處理或查詢外部來源。

在運算式建立工具中使用自訂轉換器

儲存後，自訂轉換器會與內建函式一起顯示在運算式建構工具的函式清單中。格式如下：ExtensionPackName.TransformerName。將滑鼠游標懸停在函式上，即可查看根據參數說明產生的說明文件。

支援所有預留位置 (JSON 和非 JSON)

運算式建構工具支援 Playbook 設計工具中公開的所有預留位置，包括非 JSON 結果。

非 JSON 預留位置：

• 您可以在運算式產生器中手動輸入範例資料，針對各種輸入類型 (字串、清單 (以半形逗號分隔的值) 和 JSON) 測試邏輯。
• 使用輸入類型進行測試，不保證預留位置會在執行階段傳回該特定類型。
• 大多數預留位置都會解析為字串，但特定類型會根據數量解析為字串或清單 (例如 entity.identifier)。建議一律將這些預留位置的輸入內容視為清單。

注意：樣本資料為暫時性資料，在您關閉運算式建立工具或儲存運算式後，系統不會儲存這些資料。如果再次開啟建構工具，則必須重新輸入樣本資料。

錯誤處理機制

如果自訂轉換函式在執行期間發生錯誤，使用該轉換器的劇本動作就會失敗。Python 指令碼產生的特定錯誤訊息會顯示在自動化腳本執行檢視畫面中，方便您直接排解邏輯問題。

自訂邏輯運算子

自訂邏輯運算子可讓您自行定義布林邏輯，用於比較值。

建立自訂邏輯運算子

如要定義新的邏輯運算子，請按照下列步驟操作：

1. 在 IDE 中，找出目標擴充功能套件。
2. 選取「自訂邏輯運算子」。
3. 輸入名稱。
注意：名稱建立後即無法變更。
4. 選用：在 Playbook 設計工具中，為邏輯運算子選單新增說明。
5. 使用 Python 定義指令碼邏輯。您可以從提供的預先定義範本著手。
   • 指令碼必須包含 main 函式。
   • 指令碼必須使用 SDK end 函式，將布林值結果傳回條件。
   • 您只能在 IDE 中使用 SDK 方法的子集，用於邏輯運算子：
   • logical_operator.extract_param("ParamName")：用於擷取輸入值。
   • logical_operator.LOGGER：用於寫入偵錯記錄。
   • logical_operator.end(result)：結果為布林值 (true 或 false)。

您可以直接在 IDE 中測試自訂邏輯運算子邏輯。您可以輸入引數的測試值，並驗證函式是否根據定義的條件，傳回正確的布林值 (True 或 False) 結果。

參數

自訂邏輯運算子接受兩個參數：「Left Side」 (必填且不可編輯) 和「Right Side」 (選填；使用者可停用)。

• 範例 1： if [left side] not in [right side]。
• 範例 2： if [left side] is greater than 80 (沒有右側)。

逾時

• 預設逾時時間：1 分鐘。
• 逾時時間上限：3 分鐘。

注意：由於平台會等待函式執行完畢，因此您必須盡量縮短執行時間。最佳做法是專注於直接資料轉換，避免查詢外部來源或執行大量處理作業。

在應對手冊中使用

自訂邏輯運算子會顯示在「應對手冊條件」、「先前動作條件」和「實體選取」的運算子選單中。

自訂邏輯運算子可與標準運算子 (例如「等於」或「包含」) 一起選取。

錯誤處理機制

如果自訂邏輯運算子函式在執行期間發生錯誤，使用該運算子的教戰手冊條件或步驟就會失敗。Python 指令碼傳回的錯誤訊息會顯示在劇本執行檢視畫面中，協助排解問題。

限制

• 觸發條件或Webhook 不支援自訂轉換函式和邏輯運算子。

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