開發自訂轉換器

支援的服務：

Google SecOps SOAR

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

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

擴充功能套件

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

擴充功能套件的最佳做法

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

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

建立擴充功能套件

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

1. 依序前往「自動化」>「IDE」。
2. 按一下「add 建立新項目」。
3. 從下拉式選單中選取「擴充功能套件」。
4. 為擴充功能套件提供不重複的名稱。
注意：名稱建立後即無法變更。
5. 按一下「儲存」。

上傳依附元件

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

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

1. 在 IDE 中開啟「Extension Pack settings」。
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. 建立參數：
   • 每個自訂轉換器函式都包含預設的輸入參數。這個參數代表輸入資料，也就是函式套用的預留位置。您無法刪除這個參數。
   • 此外，您也可以新增要在函式中使用的選用參數。
8. 說明文件 (選用)：定義運算式建立工具的產品內說明文件：
   • 預期輸入：說明函式預期為這個轉換器接收的資料類型 (例如「字串」或「字串清單」)。
   • 預期輸出內容：說明函式預期為這個轉換器傳回的資料類型 (例如「布林值」)。
   • 使用範例：提供叫用函式的範例 (例如 if_empty("new_value"))。

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

逾時

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

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

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

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

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

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

非 JSON 預留位置：

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

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

錯誤處理機制

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

自訂邏輯運算子

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

建立自訂邏輯運算子

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

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 分鐘。

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

在應對手冊中使用

自訂邏輯運算子會顯示在「Playbook Conditions」(Playbook 條件)、「Previous Action Conditions」(先前動作條件) 和「Entity Selection」(實體選取) 的運算子選單中。

除了標準運算子 (例如「等於」或「包含」) 之外，您也可以選取自訂邏輯運算子。

錯誤處理機制

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

限制

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

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