TIPCommon.base

TIPCommon.base 模組是 Google SecOps 整合開發作業的基礎技術參考資料，可提供動作、背景工作和跨平台資料正規化的核心邏輯。

動作資料剖析

本節包含實用函式，可將原始 API 回應中的案件資料剖析為結構化物件，以用於自動化工作。

TIPCommon.base.action.action_parser.parse_case_attachment

TIPCommon.base.action.action_parser.parse_case_attachment(attachment: MutableMapping[str, Any]) → CaseAttachment

這項公用程式會將 API 回應中的原始 JSON 附件資料，轉換為結構化 CaseAttachment 物件。

參數

參數
attachment 從 API 回應擷取的附件原始 JSON 資料。

TIPCommon.base.action.action_parser.parse_case_comment

TIPCommon.base.action.action_parser.parse_case_comment(comment: MutableMapping[str, Any]) → CaseComment

這項函式會將原始 JSON 註解資料剖析為 CaseComment 物件，方便存取註解中繼資料。

參數

參數
comment 從 API 回應擷取的留言原始 JSON 資料。

class TIPCommon.base.action.base_action.Action

類別 TIPCommon.base.action.base_action.Action(name: str)

底座：ABC、Generic[ApiClient]

Action 基礎類別提供統一的自動化開發基礎架構，包括屬性管理和一般執行流程。

參數

參數
name 動作指令碼的 ID。

屬性

下列屬性可管理動作的內部狀態，並提供 SDK 資源和整合用戶端的存取權。

屬性
_soar_action

SiemplifyAction

SiemplifyAction SDK 物件。
_api_client

Apiable

整合作業的 API 用戶端。
_name

str

使用這項動作的指令碼名稱。
_action_start_time

int

動作開始時間 (以 Unix 為單位)。
_logger

SiemplifyLogger

用於記錄動作的記錄器物件。
_params

Container

這項動作的參數容器。
global_context

dict

視需要儲存內容的字典。
_entity_types

list[EntityTypesEnum]

動作支援的實體類型。
_entities_to_update

list[Entity]

動作結束時要更新的實體。
json_results

JSON

動作的 JSON 結果。
_attachments

list[Attachment]

要新增的案件結果附件。
_contents

list[Content]

要新增的案件結果內容。
_data_tables

list[DataTable]

要新增的案件結果資料表。
_html_reports

list[HTMLReport]

要新增的案件結果 HTML 報表。

list[Link]

要新增的案件結果連結。
_markdowns

list[Markdown]

要新增的案件結果 Markdown。
_entity_insights

list[EntityInsight]

要新增的案件實體洞察資料。
_case_insights

list[CaseInsight]

要新增的案件洞察資料。
_execution_state

ExecutionState

動作的最終執行狀態指標。
_result_value

bool

動作最終結果值。
_output_message

str

動作成功時的輸出訊息。
_error_output_message

str

動作失敗時的輸出訊息。

方法

用於管理動作指令碼生命週期和輸出格式的標準方法。

- run() 執行動作。
- _get_adjusted_json_results() 將 JSON 結果調整為特定結構。

抽象方法

開發人員必須覆寫這些方法，才能定義自訂動作的專屬邏輯。

抽象方法
_validate_params() 驗證這項動作的參數。
_init_api_clients() 初始化動作的 API 用戶端。
_perform_action() 執行動作的主要邏輯。

其他方法

這些選用方法會在動作執行生命週期的特定階段觸發，用於處理快訊或清除資源。

  • _get_entity_types()
  • _finalize_action_on_success()
  • _finalize_action_on_failure()
  • _on_entity_failure()
  • _handle_timeout()
  • _extract_action_parameters()
  • _finalize()

SDK 包裝函式

這些方法可輕鬆存取基礎 SDK，讓動作與案件、快訊和平台設定互動。

  • _add_attachment_to_current_case()
  • _get_current_case_attachments()
  • _add_comment_to_case()
  • _get_current_case_comments()
  • _assign_case_to_user()
  • _add_tag_to_case()
  • _attach_playbook_to_current_alert()
  • _get_similar_cases_to_current_case()
  • _get_alerts_ticket_ids_from_cases_closed_since_timestamp()
  • _change_current_case_stage()
  • _change_current_case_priority()
  • _close_current_case()
  • _close_alert()
  • _escalate_case()
  • _mark_case_as_important()
  • _raise_incident()
  • _add_entity_to_case()
  • _update_alerts_additional_data()
  • _get_current_integration_configuration()
  • _any_alert_entities_in_custom_list()
  • _add_alert_entities_to_custom_list()
  • _remove_alert_entities_from_custom_list()

導入範例

以下範例說明如何透過從 Action 基礎類別繼承，實作自訂動作。

from TIPCommon.base.actions.action_base import Action
from TIPCommon.validation import ParameterValidator

SOME_ACTION_SCRIPT_NAME = 'Some Integration - Some Action'

class SomeAction(Action):

 def _validate_params(self) -> None:
 validator = ParameterValidator(self.soar_action)
 ... # validation logic

 def _perform_action(self, entity: Entity) -> None:
 try:
 self.logger.info('Querying Api client')
 data = self.api_client.do_something(
 param=self.params.query,
 entity=entity.original_identifier
 )

 ... # Some logic to process the data

 except SomeCustomException as err:
 self.error_output_message = (
 "Action wasn't able to successfully do its thing."

 )
 raise err from err


def main() -> None:
 SomeAction(SEARCH_GRAPHS_SCRIPT_NAME).run()


if __name__ == '__main__':
 main()

屬性

下列屬性提供動作中繼資料、結果和 SDK 物件的唯讀或管理存取權。

action_start_time

property action_start_time: int

傳回 int，代表動作的開始時間 (採用 Unix 格式)。

api_client

property api_client: ApiClient | Collection[ApiClient] | Type[Tuple[ApiClient, ...]] | None

傳回 Apiable 物件，代表為整合設定的 API 用戶端。

附件

property attachments: list[Attachment]

傳回 Attachment 物件清單，代表與這項動作相關聯的案件結果附件。根據預設，這份清單中的所有附件都會傳送至案件結果。

case_insights

property case_insights: list[CaseInsight]

傳回 CaseInsight 物件清單，代表與這項動作相關聯的高層級發現。根據預設，這份清單中的所有案件洞察資料都會傳送至案件結果。

錄

property contents: list[Content]

傳回 Content 物件清單，代表案件的文字結果。根據預設，這份清單中的所有內容都會傳送至案件結果。

data_tables

property data_tables: list[DataTable]

傳回 DataTable 物件清單，代表案件的表格資料洞察。根據預設，這份清單中的所有資料表都會傳送至案件結果。

entities_to_update

property entities_to_update: list[DomainEntityInfo]

動作完成後，傳回要在平台中更新的 Entity 物件清單。

entity_insights

property entity_insights: list[EntityInsight]

傳回 EntityInsight 物件的清單，代表與特定實體相關的發現項目。根據預設，這份清單中的所有實體洞察資料都會傳送至案件結果。

entity_types

property entity_types: list[EntityTypesEnum]

傳回 EntityTypesEnum 物件的清單，代表動作設計要處理的實體類型。如果動作在實體上執行，系統只會處理這個清單中顯示的類型。

error_output_message

property error_output_message: str

取得或設定平台在執行失敗時顯示的訊息。 預設值為 Action ACTION_NAME failed。

execution_state

property execution_state: ExecutionState

傳回代表最終處理狀態指標的 ExecutionState 物件。可能的狀態包括：

  • ExecutionState.COMPLETED = 0
  • ExecutionState.IN_PROGRESS = 1
  • ExecutionState.FAILED = 2
  • ExecutionState.TIMED_OUT = 3

global_context

global_context: dict

這個字典用於在動作執行期間儲存及擷取內容資訊。

html_reports

property html_reports: list[HTMLReport]

傳回 HTMLReport 物件清單，代表案件結果的視覺化報表。根據預設，這份清單中的所有 HTML 報表都會傳送至案件結果。

is_first_run

property is_first_run: bool

如果是首次執行動作，則傳回 true，否則傳回 false。

json_results

property json_results: Dict[str, Any] | List[Dict[str, Any]]

傳回格式化的 JSON 結果，以便在案件牆上顯示，並用於下游劇本邏輯。

property links: list[Link]

傳回 Link 物件的清單，代表案件結果的外部參照網址。根據預設，這份清單中的所有連結都會傳送至案件結果。

記錄器

property logger: NewLineLogger

傳回用於指令碼專屬記錄的 NewLineLogger 執行個體。

markdowns

property markdowns: list[Markdown]

傳回代表格式化文字洞察的 Markdown 物件清單。根據預設，這份清單中的所有 Markdown 都會傳送至案件結果。

名稱

property name: str

傳回動作指令碼的字串名稱。

output_message

property output_message: str

取得或設定平台中顯示的訊息，總結成功的動作執行。

params

property params: Container

傳回 Container 物件，說明動作的輸入參數，每個參數都會顯示為 snake_case 屬性。

result_value

property result_value: bool

取得或設定傳回給平台的成功指標。

  • True：動作成功。
  • False：動作失敗。

執行

run(**kwargs)

觸發動作執行邏輯的標準方法。

soar_action

property soar_action: SiemplifyAction

傳回用於直接平台互動的基礎 SDK SiemplifyAction 物件。

class TIPCommon.base.action.base_enrich_action.EnrichAction

類別 TIPCommon.base.action.base_enrich_action.EnrichAction(name: str)

基礎：動作

EnrichAction 是專門的基礎類別，適用於使用外部資料更新實體屬性的動作。

參數

您必須提供下列參數，才能初始化擴充動作並在平台中註冊。

參數
name 擴充動作指令碼的專屬 ID。

屬性

下列屬性可管理實體疊代期間使用的資料，並定義動作輸出結果中包含的內容。

屬性
enrichment_data

dict

每個實體疊代中，目前實體的擴充資料。在每次疊代結束時，實體的 additional_properties 屬性會以 self.enrichment_data 更新，也就是說，每次都會以新值設定這個值。
entity_results

Any

這個物件的 JSON 輸出內容中包含的實體結果。
global_context

dict

這個字典用於在擴充動作執行的不同階段中，儲存及共用內容資料。

抽象方法

子類別必須實作下列抽象方法，才能定義動作的特定實體型別和擴充邏輯。

抽象方法
_get_entity_types() 取得動作執行的實體類型。
_perform_enrich_action() 對實體執行主要擴充邏輯。

私有方法

這些內部方法會處理擴充邏輯的協調作業，不應修改。

私有方法
_perform_action()

這個方法會將其他抽象方法與更多 OOTB 擴充邏輯合併，並傳遞至父項類別，以便在 start() 方法中使用。

「資料模型」模組

這個模組提供跨整合物件、列舉和常數的結構化定義。

class TIPCommon.base.action.data_models.ActionParamType

類別 TIPCommon.base.action.data_models.ActionParamType(value)

基底：Enum

ActionParamType 定義動作指令碼參數支援的 UI 資料類型。

常數

常數值
BOOLEAN1
CASE_PRIORITIES7
CLOSE_CASE_REASONS5
CLOSE_ROOT_CAUSE6
CODE20
CONTENT11
DDL15
EMAIL_CONTENT10
ENTITY_TYPE13
MULTI_VALUES14
NULL-1
PASSWORD12
PLAYBOOK_NAME2
STAGE4
STRING0
USER3

class TIPCommon.base.action.data_models.Attachment

類別 TIPCommon.base.action.data_models.Attachment(filename: str, file_contents: bytes, title: str = 'Script Result Attachment', additional_data: dict | None = None)

基底：object

這個模型代表要上傳至案件牆的指令碼結果附件。

參數

初始化附件物件時，必須提供下列參數，定義附件的中繼資料，以及要上傳至案件的二進位資料。

參數
filename 要在案件結果中建立的檔案名稱。
file_contents 代表檔案內容的原始二進位資料。
title 附件在平台 UI 中顯示的標題；預設為 'Script Result Attachment'。

屬性

下列屬性會定義動作指令碼產生的檔案附件中繼資料和二進位內容。

屬性
title

str | None

平台介面中顯示的附件標題。
filename

str

要建立的檔案名稱。
file_contents

bytes

附件檔案的原始二進位內容。
additional_data

dict | None

字典，內含與附件相關聯的補充資料。

class TIPCommon.base.action.data_models.CaseAttachment

類別 TIPCommon.base.action.data_models.CaseAttachment(attachment_id: int, attachment_type: str, description: str, is_favorite: bool)

基底：object

這個類別代表與案件相關聯的不可變更附件。

屬性

下列屬性代表已與平台案件建立關聯的附件特定中繼資料。

屬性
attachment_id

int

附件的專屬平台指派 ID。
attachment_type

str

附件的分類或 MIME 類型 (例如 txt、csv 或 json)。
description

str

使用者定義或系統產生的附件內容說明。
is_favorite

bool

指出附件是否已標示為最愛，方便在案件牆上快速存取。

class TIPCommon.base.action.data_models.CaseComment

類別 TIPCommon.base.action.data_models.CaseComment(comment: str, creator_user_id: str, comment_id: int, comment_type: int, case_id: int, is_favorite: bool, modification_time_unix_time_in_ms: int, creation_time_unix_time_in_ms: int, alert_identifier: str, creator_full_name: str | None = None, is_deleted: bool | None = None, last_editor: str | None = None, last_editor_full_name: str | None = None, modification_time_unix_time_in_ms_for_client: int | None = None, comment_for_client: str | None = None)

基底：object

CaseComment 代表與案件或快訊相關聯的不可變更留言記錄，會擷取建立者詳細資料和稽核時間戳記。

屬性

下列屬性定義案件留言的內容和管理中繼資料。

屬性
comment

str

留言的主要文字內容。
comment_for_client

str | None

可選用的註解版本，專為客戶瀏覽而設計。
modification_time_unix_time_in_ms_for_client

int

comment_for_client 的修改時間戳記，以 Unix 毫秒為單位。
last_editor

str

最後編輯者的 ID，例如 77bdb7a4-8484-481d-9482-2449e33f9518。
last_editor_full_name

str

最後編輯留言的使用者全名，例如 admin admin。
is_deleted

bool

指出留言是否已標示為刪除。
creator_user_id

str

建立者使用者 ID，例如 77bdb7a4-8484-481d-9482-2449e33f9518。
creator_full_name

str

建立者的完整顯示名稱，例如 System。
comment_id

int

平台指派給留言的專屬整數 ID。
comment_type

int

留言的類型分類。
case_id

int

與這則留言相關聯的案件 ID。
is_favorite

bool

指出留言是否已置頂為「我的收藏」。
modification_time_unix_time_in_ms

int

留言的上次修改時間 (以 Unix 毫秒為單位)，例如 1686040471269。
creation_time_unix_time_in_ms

int

留言的建立時間，以 Unix 毫秒為單位，例如 1686040471269。
alert_identifier

str

與留言相關的快訊專屬 ID，例如 SUSPICIOUS PHISHING EMAIL_83765943-9437-4771-96F6-BD0FB291384E。

class TIPCommon.base.action.data_models.CaseInsight

類別 TIPCommon.base.action.data_models.CaseInsight(triggered_by: str, title: str, content: str, severity: InsightSeverity, insight_type: InsightType, entity_identifier: str = '', additional_data: Any | None = None, additional_data_type: Any | None = None, additional_data_title: str | None = None)

基底：object

CaseInsight 代表顯示在案件牆上的不可變動結構化發現或快訊摘要。

屬性

下列屬性可管理平台內洞察資料的分類和呈現方式。

屬性
title

str

案件總覽頁面顯示的洞察資料標題。
triggered_by

str

產生洞察資料的整合服務或使用者名稱。
content

str

洞察資料的詳細訊息內文或發現項目。
severity

InsightSeverity

洞察資訊的緊急程度。

可能的值如下：

  • info
  • warning
  • error
    		•
    insight_type

    InsightType

    深入分析資訊的類別。

    可能的值如下：

  • general
  • entity
    		•
    entity_identifier

    str | None

    如果洞察資訊以實體為中心，則為實體的特定 ID。
    additional_data

    Any | None

    與洞察資料相關的補充資料。
    additional_data_type

    Any | None

    「additional_data」屬性的資料類型分類。
    additional_data_title

    str | None

    增補資料區塊的顯示標題。

    class TIPCommon.base.action.data_models.CasePriority

    類別 TIPCommon.base.action.data_models.CasePriority(value)

    基底：Enum

    CasePriority 會定義指派給平台內案件的整數型嚴重程度等級。

    常數

    常數 值
    CRITICAL100
    HIGH80
    INFORMATIONAL0
    LOW40
    MEDIUM60

    class TIPCommon.base.action.data_models.CaseStage

    類別 TIPCommon.base.action.data_models.CaseStage(value)

    基底：Enum

    CaseStage 會指定案件在生命週期內可轉換的作業階段。

    常數

    常數 值
    ASSESSMENT「評估」
    IMPROVEMENT「改善」
    INCIDENT'Incident'
    INVESTIGATION「調查」
    RESEARCH「研究」
    TRIAGE'Triage'

    class TIPCommon.base.action.data_models.CloseCaseOrAlertInconclusiveRootCauses

    類別 TIPCommon.base.action.data_models.CloseCaseOrAlertInconclusiveRootCauses(value)

    基底：Enum

    CloseCaseOrAlertInconclusiveRootCauses 提供根本原因選項，適用於無法做出明確判定的情況。

    常數

    常數 值
    NO_CLEAR_CONCLUSION「沒有明確結論」

    class TIPCommon.base.action.data_models.CloseCaseOrAlertMaintenanceRootCauses

    類別 TIPCommon.base.action.data_models.CloseCaseOrAlertMaintenanceRootCauses(value)

    基底：Enum

    CloseCaseOrAlertMaintenanceRootCauses 定義與排定測試、系統維護或規則開發相關的根本原因。

    常數

    常數 值
    LAB_TEST「實驗室檢驗」
    OTHER其他
    RULE_UNDER_CONSTRUCTION「規則建構中」

    class TIPCommon.base.action.data_models.CloseCaseOrAlertMaliciousRootCauses

    類別 TIPCommon.base.action.data_models.CloseCaseOrAlertMaliciousRootCauses(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

    基底：Enum

    CloseCaseOrAlertMaliciousRootCauses 提供特定類別，用於確認威脅、基礎架構問題或系統故障。

    常數

    常數 值
    EXTERNAL_ATTACK「外部攻擊」
    INFRASTRUCTURE_ISSUE'Infrastructure issue'
    IRRELEVANT_TCP_UDP_PORT'Irrelevant TCP/UDP port'
    MISCONFIGURED_SYSTEM「系統設定錯誤」
    OTHER其他
    SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION 「類似案件已在調查中」
    SYSTEM_APPLICATION_MALFUNCTION 「系統/應用程式故障」
    SYSTEM_CLOCKED_THE_ATTACK「系統已封鎖攻擊」
    UNFORESEEN_EFFECTS_OF_CHANGE「變更的不可預期影響」
    UNKNOWN「Unknown」(不明)

    class TIPCommon.base.action.data_models.CloseCaseOrAlertNotMaliciousRootCauses

    類別 TIPCommon.base.action.data_models.CloseCaseOrAlertNotMaliciousRootCauses(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

    基底：Enum

    CloseCaseOrAlertNotMaliciousRootCauses 會定義良性活動、合法動作或不會造成威脅的錯誤類別。

    常數

    常數 值
    EMPLOYEE_ERROR「員工錯誤」
    HUMAN_ERROR「人為錯誤」
    LAB_TEST「實驗室檢驗」
    LEGIT_ACTION「Legit action」(合法動作)
    MISCONFIGURED_SYSTEM「系統設定錯誤」
    NONE「無」
    NORMAL_BEHAVIOR「正常行為」
    OTHER其他
    PENETRATION_TEST「滲透測試」
    RULE_UNDER_CONSTRUCTION「規則建構中」
    SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION 「類似案件已在調查中」
    UNKNOWN「Unknown」(不明)
    USER_MISTAKE「使用者錯誤」

    class TIPCommon.base.action.data_models.CloseCaseOrAlertReasons

    類別 TIPCommon.base.action.data_models.CloseCaseOrAlertReasons(value)

    基底：Enum

    CloseCaseOrAlertReasons 提供標準化的高階類別，說明案件或快訊關閉的原因。

    常數

    常數 值
    MALICIOUS0
    NOT_MALICIOUS1
    MAINTENANCE2
    INCONCLUSIVE3

    class TIPCommon.base.action.data_models.Content

    類別 TIPCommon.base.action.data_models.Content(content: str, title: str = 'Script Result Content')

    基底：object

    內容：代表腳本產生的不可變更文字結果，可新增至案件牆。

    屬性

    下列屬性定義了平台案件結果中顯示的文字或 Markdown 內容。

    屬性
    title

    str | None

    顯示在指令碼結果 UI 中的內容區塊顯示標題。
    content

    str

    核心訊息內容，可以提供原始文字字串，或以 Markdown 格式設定。

    class TIPCommon.base.action.data_models.DataTable

    類別 TIPCommon.base.action.data_models.DataTable(data_table: list[str], title: str = 'Script Result Data Table')

    基底：object

    DataTable 代表以 CSV 格式呈現的字串清單，在案件結果中會顯示為結構化表格。

    屬性

    下列屬性會定義動作結果集內表格資料的結構和顯示方式。

    屬性
    title

    str | None

    平台介面中資料表上方顯示的標題。
    data_table

    list[str]

    字串清單，每個元素代表以 CSV 格式設定的資料列， 建構表格。

    類別 TIPCommon.base.action.data_models.EntityInsight

    類別 TIPCommon.base.action.data_models.EntityInsight(entity: DomainEntityInfo, message: str, triggered_by: str | None = None, original_requesting_user: str | None = None)

    基底：object

    EntityInsight 用於建立與實體相關的特定發現，通常會顯示在實體的詳細資料檢視畫面中。

    屬性

    下列屬性定義實體與整合指令碼產生的結果之間的關係。

    屬性
    entity

    Entity

    要以新發現內容豐富化的實體物件。
    message

    str

    實體的核心觀察結果、發現或描述性訊息。
    triggered_by

    str | None

    識別發現項目的整合項目名稱。
    original_requesting_user

    str | None

    最初發出要求的使用者專屬 ID。

    class TIPCommon.base.action.data_models.EntityTypesEnum

    類別 TIPCommon.base.action.data_models.EntityTypesEnum(value)

    基底：Enum

    EntityTypesEnum 提供 Google SecOps 辨識的所有實體類型常數。

    常數

    下列常數定義平台支援的標準化實體類型，可用於擴充和自動化作業。

    常數 值
    ADDRESS'ADDRESS'
    ALERT'ALERT'
    APPLICATION'APPLICATION'
    CHILD_HASH'CHILDHASH'
    CHILD_PROCESS'CHILDPROCESS'
    CLUSTER'CLUSTER'
    CONTAINER'CONTAINER'
    CREDIT_CARD'CREDITCARD'
    CVE'CVE'
    CVE_ID'CVEID'
    DATABASE'DATABASE'
    DEPLOYMENT「部署」
    DESTINATION_DOMAIN'DESTINATIONDOMAIN'
    DOMAIN'DOMAIN'
    EMAIL_MESSAGE'EMAILSUBJECT'
    EVENT'EVENT'
    FILE_HASH'FILEHASH'
    FILE_NAME'FILENAME'
    GENERIC'GENERICENTITY'
    HOST_NAME'HOSTNAME'
    IP_SET'IPSET'
    MAC_ADDRESS'MacAddress'
    PARENT_HASH'PARENTHASH'
    PARENT_PROCESS'PARENTPROCESS'
    PHONE_NUMBER'PHONENUMBER'
    POD'POD'
    PROCESS'PROCESS'
    SERVICE'SERVICE'
    SOURCE_DOMAIN'SOURCEDOMAIN'
    THREAT_ACTOR'THREATACTOR'
    THREAT_CAMPAIGN'THREATCAMPAIGN'
    THREAT_SIGNATURE'THREATSIGNATURE'
    URL'DestinationURL'
    USB'USB'
    USER'USERUNIQNAME'

    class TIPCommon.base.action.data_models.ExecutionState

    類別 TIPCommon.base.action.data_models.ExecutionState(value)

    基底：Enum

    ExecutionState 代表傳回給平台的最終狀態指標，用於判斷動作是否成功。

    常數

    常數 值
    COMPLETED0
    IN_PROGRESS1
    FAILED2
    TIMED_OUT3

    class TIPCommon.base.action.data_models.FullDetailsConfigurationParameter

    類別 TIPCommon.base.action.data_models.FullDetailsConfigurationParameter(input_dict: dict[str, Any])

    基底：object

    FullDetailsConfigurationParameter 會封裝一般整合設定參數，以及從 API 擷取的完整中繼資料。

    屬性

    下列屬性會管理參數中繼資料、識別資訊和設定限制。

    table> 屬性 full_dict

    dict[str, Any]

    從 API 回應收到的原始字典。

    id

    int | None

    平台指派給參數的專屬 ID。

    integration_identifier

    str

    與這個參數相關聯的整合 ID，例如 VirusTotalV3。

    creation_time

    int

    參數的建立時間戳記，以 Unix 毫秒為單位。

    modification_time

    int

    時間戳記，指出參數上次修改時間 (以 Unix 毫秒為單位)。

    is_mandatory

    bool

    定義整合功能是否需要參數。

    description

    str | None

    參數用途的詳細說明。

    name

    str

    參數的內部 ID 名稱。

    display_name

    str

    平台介面中顯示的參數名稱，方便使用者辨識。

    value

    Any

    指派給參數的預設值。

    type

    IntegrationParamType

    參數的資料類型分類。

    optional_values

    list

    為下拉式選單 (DDL) 參數類型提供的選用值清單。

    class TIPCommon.base.action.data_models.HTMLReport

    類別 TIPCommon.base.action.data_models.HTMLReport(report_name: str, report_contents: str, ...)

    基底：object

    HTMLReport 代表要新增至案件結果的自訂 HTML 型視覺化內容。

    屬性

    屬性
    title

    str | None

    案件總覽頁面上的報表顯示標題。
    report_name

    str

    報表的內部 ID 或檔案名稱。
    report_contents

    str

    定義報表內容的原始 HTML 字串。

    class TIPCommon.base.action.data_models.IntegrationParamType

    類別 TIPCommon.base.action.data_models.IntegrationParamType(value)

    基底：Enum

    IntegrationParamType 會指定整合設定支援的資料類型。

    常數

    常數 值
    NULL-1
    BOOLEAN0
    INTEGER1
    STRING2
    PASSWORD3
    IP4
    EMAIL8

    類別 TIPCommon.base.action.data_models.Link(link: str, title: str = 'Script Result Link')

    基底：object

    連結代表外部網址結果，會顯示為案件牆上的超連結。

    屬性

    屬性

    str | None

    超連結的顯示文字。

    str

    連結的目標網址。

    class TIPCommon.base.action.data_models.Markdown

    類別 TIPCommon.base.action.data_models.Markdown(markdown_name: str, markdown_content: str, ...)

    基底：object

    Markdown 提供結構化方式，可使用 Markdown 語法傳回 RTF 格式內容。

    屬性

    屬性
    title

    str | None

    Markdown 區塊的顯示標題。
    markdown_content

    str

    以 Markdown 語法格式化的內容。
    markdown_name

    str

    指派給這項 Markdown 結果的專屬名稱。

    class TIPCommon.base.action.data_models.ScriptParameter

    類別 TIPCommon.base.action.data_models.ScriptParameter(input_dict: dict[str, Any])

    基底：object

    ScriptParameter 代表動作指令碼的單一輸入參數，可管理其值、預設狀態，以及在劇本或手動動作中的顯示狀態。

    屬性

    下列屬性可管理個別指令碼參數的中繼資料、值優先順序和資料限制。

    屬性
    full_dict

    dict[str, Any]

    從 API 回應收到的原始字典。
    id

    int | None

    平台指派給參數的專屬 ID。
    creation_time

    int

    參數的建立時間戳記，以 Unix 毫秒為單位。
    modification_time

    int

    時間戳記，指出參數上次修改時間 (以 Unix 毫秒為單位)。
    custom_action_id

    int | None

    與這個參數相關聯的自訂動作 ID。
    is_mandatory

    bool

    指出是否必須提供參數，才能執行動作指令碼。
    default_value

    Any

    參數的預設值。

    在應對手冊執行作業時，系統會優先採用這個值，而非 value。
    description

    str | None

    參數用途的詳細說明。
    name

    str | None

    參數的內部 ID 名稱。
    value

    Any

    參數的目前值。

    在手動執行動作時，這個值的優先順序高於 default_value。
    type

    ActionParamType

    參數的資料類型分類。
    optional_values

    list

    為下拉式選單 (DDL) 參數類型提供的選用值清單。

    指令碼執行結果

    下列類別和函式定義了標準化結構，可將動作和連接器的資料傳回平台。

    class TIPCommon.base.data_models.ActionJsonOutput

    類別 TIPCommon.base.data_models.ActionJsonOutput(title='JsonResult', content='', type=None, is_for_entity=False, json_result=None)

    基底：object

    ActionJsonOutput 代表動作的結構化 JSON 酬載，可進行特定分類和實體層級指定目標。

    屬性

    屬性
    title

    str

    JSON 結果區塊的顯示標題。
    content

    str

    隨附 JSON 資料的文字內容或摘要。
    type

    str | None

    JSON 輸出內容的選用分類類型。
    is_for_entity

    bool

    指出 JSON 結果是否與實體相關聯。
    json_result

    JSON | None

    實際的 JSON 結構化資料酬載。

    class TIPCommon.base.data_models.ActionOutput

    類別 TIPCommon.base.data_models.ActionOutput(output_message, result_value, execution_state, json_output, debug_output='')

    基底：object

    ActionOutput 會封裝動作的完整結果結構，結合人類可解讀的訊息、狀態和結構化 JSON。

    屬性

    屬性
    output_message

    str

    向分析師顯示的主要摘要訊息。
    result_value

    str | bool

    動作的邏輯結果 (例如成功/失敗)。
    execution_state

    ExecutionState

    動作執行的最終生命週期狀態。
    json_output

    ActionJsonOutput | None

    動作的結構化 JSON 結果。
    debug_output

    str

    用於疑難排解的可選診斷資訊。

    class TIPCommon.base.data_models.ConnectorJsonOutput

    類別 TIPCommon.base.data_models.ConnectorJsonOutput(alerts, overflow_alerts=<factory>, log_items=<factory>, log_rows=<factory>, variables=<factory>)

    基底：object

    ConnectorJsonOutput 會定義連接器傳回的結構化資料，包括擷取的快訊、溢位詳細資料和執行記錄。

    屬性

    屬性
    alerts

    list[AlertInfo | CaseInfo]

    成功擷取的快訊或案件物件清單。
    overflow_alerts

    list[OverflowAlertDetails]

    超過擷取限制並以溢位方式處理的快訊清單。
    log_items

    list

    連接器執行期間產生的結構化記錄項目清單。
    variables

    dict

    在連接器執行之間保留的狀態變數字典。

    class TIPCommon.base.data_models.ConnectorOutput

    類別 TIPCommon.base.data_models.ConnectorOutput(json_output, debug_output='')

    基底：object

    ConnectorOutput 代表連接器執行結果的頂層容器，會包裝結構化 JSON 資料和選用的偵錯字串。

    屬性

    屬性
    json_output

    ConnectorJsonOutput | None

    內含擷取和記錄資料的結構化 JSON 結果。
    debug_output

    str

    選用的偵錯字串，用於內部診斷追蹤。

    TIPCommon.base.data_models.alert_info_from_json

    TIPCommon.base.data_models.alert_info_from_json(json_) → AlertInfo

    剖析屬性字典，建立 AlertInfo 物件。這通常用於在資料轉換或測試期間重建快訊物件。

    傳回

    根據提供的 JSON 字典中定義的屬性，傳回完全初始化的 AlertInfo 物件。

    介面模組

    這個模組會定義基礎指令碼元件的標準抽象合約。

    class TIPCommon.base.interfaces.apiable.Apiable

    類別 TIPCommon.base.interfaces.apiable.Apiable(authenticated_session: AuthenticatedSession, configuration: ApiParams)

    基底：ABC、Generic[ApiParams]

    Apiable 是類別的抽象基礎介面，可封裝 API 通訊邏輯，確保外部服務互動結構一致。

    class TIPCommon.base.interfaces.authable.Authable

    類別 TIPCommon.base.interfaces.authable.Authable

    基底：ABC、Generic[AuthParams]

    Authable 是類別的抽象基本介面，可管理驗證工作流程，並提供標準化藍圖，用於與外部服務建立安全連線。

    抽象方法

    子類別必須實作下列抽象方法，才能定義目標服務所需的特定驗證邏輯。

    抽象方法
    authenticate_session()

    authenticate_session(params: AuthParams) → None

    使用提供的 params (例如 dataclass、TypedDict 或 namedtuple) 驗證 self.session 屬性。

    工作階段物件初始化後，請使用這個方法與工作階段相關聯的服務建立驗證。

    class TIPCommon.base.interfaces.logger.Logger

    類別 TIPCommon.base.interfaces.logger.Logger

    基地：ABC

    記錄器介面，確保市集指令碼提供標準化診斷輸出內容。

    抽象方法

    您必須實作下列方法，才能處理各種記錄嚴重程度和例外狀況回報。

    抽象方法
    debug()

    debug(msg: str, *args, **kwargs) → None

    記錄嚴重性等級為 DEBUG 的訊息。
    info()

    info(msg: str, *args, **kwargs) → None

    記錄嚴重性等級為 INFO 的訊息。
    warn()

    warn(warning_msg: str, *args, **kwargs) → None

    記錄嚴重性等級為 WARNING 的訊息。
    error()

    error(error_msg: str, *args, **kwargs) → None

    記錄嚴重性等級為 ERROR 的訊息。
    exception()

    exception(ex: Exception, *args, **kwargs) → None

    記錄嚴重性等級為 ERROR 的訊息，包括例外狀況堆疊追蹤。

    class TIPCommon.base.interfaces.session.Session

    類別 TIPCommon.base.interfaces.session.Session

    底座：ABC、Generic[_R]

    Session 介面提供一致的藍圖，可使用各種 HTTP 程式庫管理 API 工作階段。

    屬性

    下列屬性可管理已建立 HTTP 通訊工作階段的設定和安全性設定。

    屬性
    headers

    dict

    這個字典包含要隨工作階段中每個要求傳送的 HTTP 標頭。
    verify

    bool

    布林值，指出工作階段是否應驗證伺服器的 SSL 憑證。

    抽象方法

    下列抽象方法會定義標準 HTTP 動詞和主要要求調度器，子類別必須實作這些方法。

    抽象方法
    get()

    get(url: str, *args, **kwargs) → _R

    使用 HTTP GET 要求從伺服器擷取資源。
    post()

    post(url: str, *args, **kwargs) → _R

    使用 HTTP POST 要求將資料傳送至伺服器，以建立資源。
    put()

    put(url: str, *args, **kwargs) → _R

    使用 HTTP PUT 要求更新或建立伺服器上的資源。
    patch()

    patch(url: str, *args, **kwargs) → _R

    使用 HTTP PATCH 要求對資源套用部分修改。
    delete()

    delete(url: str, *args, **kwargs) → _R

    使用 HTTP DELETE 要求從伺服器移除指定資源。
    request()

    request(method: str, *args, **kwargs) → _R

    用於以指定方法執行 HTTP 要求的核心要求調度器。

    工作模組

    這項功能提供架構，讓您在平台內按照定義的排程執行背景處理指令碼。

    class TIPCommon.base.job.base_job.Job

    類別 TIPCommon.base.job.base_job.Job(name: str)

    基底：ABC、Generic[ApiClient]

    Job 是抽象基礎類別，專為執行獨立背景作業的排定工作而設計，例如資料同步或健康狀態檢查。

    參數

    您必須提供下列參數，才能初始化作業並在平台中註冊。

    參數
    name 用來註冊及識別工作指令碼的專屬 ID。

    屬性

    下列屬性可存取作業的執行環境、設定和整合式服務用戶端。

    屬性
    api_client

    ApiClient | None

    提供已初始化的 API 用戶端或用戶端集合，用於與外部服務互動。
    error_msg

    str

    儲存工作執行期間遇到的任何錯誤訊息，以供診斷報告使用。
    job_start_time

    int

    工作開始執行的 Unix 時間戳記。
    logger

    ScriptLogger

    提供記錄介面，用於在執行期間擷取資訊、警告和錯誤資料。
    name

    str

    工作指令碼的註冊名稱。
    params

    Container

    這個容器會保留提供給工作例項的特定設定參數。
    soar_job

    SiemplifyJob

    代表基礎平台工作執行個體，可存取低階執行掛鉤。

    方法

    下列方法可管理作業的自動調度管理和執行生命週期。

    方法
    start()

    簽名： start(**kwargs) → None

    觸發作業執行邏輯的主要進入點。

    class TIPCommon.base.job.base_job_refresh_token.RefreshTokenRenewalJob

    類別 TIPCommon.base.job.base_job_refresh_token.RefreshTokenRenewalJob(name: str, integration_identifier: str)

    基底：Job、Generic[ApiClient]

    RefreshTokenRenewalJob 提供生命週期方法，可影響權杖維護作業的作業處理程序。子類別不需要覆寫這些方法。

    屬性

    屬性
    api_client

    ApiClient | Collection[ApiClient] | Type[Tuple[ApiClient, ...]] | None

    用於外部服務互動的已初始化 API 用戶端。

    class TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple

    類別 TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple(success_list, failure_list)

    基底：tuple

    SuccessFailureTuple 是專用的具名元組，用於將批次作業的結果分類為成功和失敗。

    屬性

    屬性
    success_list

    list

    內含成功處理的 ID 或物件的清單。
    failure_list

    list

    內含處理失敗的 ID 或物件的清單。

    TIPCommon.base.job.base_job_refresh_token.validate_param_csv_to_multi_value

    TIPCommon.base.job.base_job_refresh_token.validate_param_csv_to_multi_value(param_name, param_csv_value, delimiter=',') → list[str]

    這個函式會驗證以半形逗號分隔 (CSV) 的參數字串，並剖析為不重複元素的清單。這個函式可處理複雜格式，包括單一值、加上引號的字串和混合輸入內容。

    參數

    參數
    param_name

    str

    要驗證的參數名稱或鍵。
    param_csv_value

    str | None

    工作設定中提供的原始 CSV 字串。如果 None 為空，則傳回空白清單。

    發出

    如果輸入字串包含無效的雙引號數量、不相符的引號，或 CSV 中的任何個別值驗證失敗，就會引發 ValueError 例外狀況。

    傳回

    從輸入內容剖析的不重複驗證字串 list[str] 清單。如果系統未識別出有效值，或輸入內容為 None，則會傳回空白清單。

    class TIPCommon.base.job.data_models.JobParameter

    類別 TIPCommon.base.job.data_models.JobParameter(input_dict: MutableMapping[str, Any])

    基底：object

    JobParameter 代表工作指令碼的個別設定參數，可管理其值和中繼資料狀態。

    屬性

    屬性
    full_dict

    dict[str, Any]

    在工作初始化期間，從 API 收到的原始字典。
    id

    int | None

    平台為工作參數指派的專屬 ID。
    is_mandatory

    bool

    指出是否必須提供參數才能執行作業。
    name

    str | None

    參數的內部 ID 名稱。
    type

    ActionParamType

    參數的資料類型分類。
    value

    Any

    參數的預設值；在自動執行工作時，系統通常會優先採用這個值。

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