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 数据。

类 TIPCommon.base.action.base_action.Action

类 TIPCommon.base.action.base_action.Action(name: str)

基础：ABC、Generic[ApiClient]

操作基类为自动化开发提供统一的基础架构，包括属性管理和常规执行流程。

参数

参数
name 操作脚本的标识符。

属性

以下属性用于管理操作的内部状态，并提供对 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 客户端。

attachments（附件）

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 结果，以便在问题墙上显示并用于下游 playbook 逻辑。

property links: list[Link]

返回一个 Link 对象列表，表示相应支持请求结果的外部参考网址。默认情况下，此列表中的所有链接都会发送到相应问题的结果。

logger

property logger: NewLineLogger

返回用于脚本特定日志记录的 NewLineLogger 实例。

降价

property markdowns: list[Markdown]

返回一个 Markdown 对象列表，表示格式化文本数据洞见。默认情况下，此列表中的所有 Markdown 都会发送到问题结果。

name

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

run(**kwargs)

触发操作执行逻辑的标准方法。

soar_action

property soar_action: SiemplifyAction

返回用于直接平台交互的底层 SDK SiemplifyAction 对象。

类 TIPCommon.base.action.base_enrich_action.EnrichAction

类 TIPCommon.base.action.base_enrich_action.EnrichAction(name: str)

基类：Action

EnrichAction 是一种专门的基类，专为使用外部数据更新实体属性的操作而设计。

参数

需要提供以下参数才能初始化丰富化操作并将其注册到平台中。

参数
name 丰富操作脚本的唯一标识符。

属性

以下属性用于管理实体迭代期间使用的数据，并定义操作的输出结果中包含的内容。

属性
enrichment_data

dict

每次实体迭代中当前实体的丰富数据。在每次迭代结束时，实体的 additional_properties 属性都会更新为 self.enrichment_data，这意味着每次都会使用新值设置此值。
entity_results

Any

相应对象的 JSON 输出中包含的实体结果。
global_context

dict

一个字典，用于在丰富操作执行的不同阶段存储和共享上下文数据。

抽象方法

必须在子类中实现以下抽象方法，以定义操作的特定实体类型和丰富逻辑。

抽象方法
_get_entity_types() 获取操作所针对的实体类型。
_perform_enrich_action() 对实体执行主要丰富逻辑。

私有方法

这些内部方法用于处理丰富逻辑的编排，不应修改。

私有方法
_perform_action()

此方法将其他抽象方法与更多开箱即用的丰富逻辑相结合，并将其传递给父类以在 start() 方法中使用。

“数据模型”模块

此模块为跨集成对象、枚举和常量提供结构化定义。

class TIPCommon.base.action.data_models.ActionParamType

类 TIPCommon.base.action.data_models.ActionParamType(value)

基类：Enum

ActionParamType 用于定义操作脚本参数支持的界面数据类型。

常量

常量值
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)

代码库：对象

此模型表示要上传到支持服务请求墙的脚本结果附件。

参数

初始化附件对象需要以下参数，这些参数用于定义附件的元数据以及要上传到支持请求的二进制数据。

参数
filename 要在诉讼结果中创建的文件的名称。
file_contents 表示文件内容的原始二进制数据。
title 附件在平台界面中显示的显示标题；默认值为 '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)

代码库：对象

此类表示与支持请求关联的不可变附件。

属性

以下属性表示已与平台内的支持请求相关联的附件的特定元数据。

属性
attachment_id

int

附件的唯一平台分配标识符。
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)

代码库：对象

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

平台为相应评论分配的唯一整数标识符。
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

与评论相关的提醒的具体标识符，例如 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)

代码库：对象

CaseInsight 表示显示在支持请求墙上的不可变结构化发现结果或提醒摘要。

属性

以下属性用于管理平台内向分析师呈现的数据洞见的分类方式。

属性
title

str

在案例墙上显示的分析洞见的标题。
triggered_by

str

生成数据洞见的集成或用户的名称。
content

str

详细的消息正文或数据洞见发现结果。
severity

InsightSeverity

数据分析的紧急程度。

可能的值如下：

  • info
  • warning
  • error
    		•
    insight_type

    InsightType

    对数据分析进行分类。

    可能的值如下：

  • general
  • entity
    		•
    entity_identifier

    str | None

    如果分析洞见侧重于实体，则为实体的具体标识符。
    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“事件”
    INVESTIGATION“调查”
    RESEARCH“研究”
    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“基础架构问题”
    IRRELEVANT_TCP_UDP_PORT“无关的 TCP/UDP 端口”
    MISCONFIGURED_SYSTEM“系统配置错误”
    OTHER“其他”
    SIMILAR_CASE_IS_ALREADY_UNDER_INVESTIGATION “类似支持请求已在调查中”
    SYSTEM_APPLICATION_MALFUNCTION “系统/应用故障”
    SYSTEM_CLOCKED_THE_ATTACK“系统已阻止攻击”
    UNFORESEEN_EFFECTS_OF_CHANGE“变更的意外影响”
    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“未知”
    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')

    代码库：对象

    Content 表示由脚本生成并添加到案例墙上的不可变文本结果。

    属性

    以下属性用于定义在平台上的诉讼结果中显示的基于文本或 Markdown 的内容。

    属性
    title

    str | None

    内容块在脚本结果界面中显示的显示标题。
    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')

    代码库：对象

    DataTable 表示以 CSV 格式设置的字符串列表，这些字符串在支持请求结果中呈现为结构化表格。

    属性

    以下属性用于定义操作结果集中表格数据的结构和显示方式。

    属性
    title

    str | None

    平台界面中显示在数据表格上方的标题。
    data_table

    list[str]

    一个字符串列表，其中每个元素表示一个 CSV 格式的行，用于构建表格。

    class 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)

    代码库：对象

    EntityInsight 用于创建与实体关联的特定发现，通常显示在实体的详情视图中。

    属性

    以下属性用于定义实体与集成脚本生成的发现之间的关系。

    属性
    entity

    Entity

    正在通过新发现结果进行丰富化的实体对象。
    message

    str

    实体的核心观测结果、发现或描述性消息。
    triggered_by

    str | None

    发现相应结果的集成的名称。
    original_requesting_user

    str | None

    最初发起请求的用户的唯一标识符。

    class TIPCommon.base.action.data_models.EntityTypesEnum

    类 TIPCommon.base.action.data_models.EntityTypesEnum(value)

    基类：Enum

    EntityTypesEnum 为 Google SecOps 识别的所有实体类型提供常量。

    常量

    以下常量定义了平台支持的标准化实体类型，用于丰富数据和执行自动化任务。

    常量 值
    ADDRESS'ADDRESS'
    ALERT'ALERT'
    APPLICATION“申请”
    CHILD_HASH'CHILDHASH'
    CHILD_PROCESS'CHILDPROCESS'
    CLUSTER'CLUSTER'
    CONTAINER'CONTAINER'
    CREDIT_CARD'CREDITCARD'
    CVE'CVE'
    CVE_ID'CVEID'
    DATABASE'DATABASE'
    DEPLOYMENT'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“Destination网址”
    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])

    代码库：对象

    FullDetailsConfigurationParameter 封装了一个常规集成配置参数及其从 API 检索到的完整元数据。

    属性

    以下属性用于管理参数元数据、标识和配置限制。

    table> 属性 full_dict

    dict[str, Any]

    从 API 响应中收到的原始字典。

    id

    int | None

    平台为参数分配的唯一标识符。

    integration_identifier

    str

    与相应参数关联的集成的标识符，例如 VirusTotalV3。

    creation_time

    int

    参数的创建时间戳（以 Unix 毫秒为单位）。

    modification_time

    int

    表示参数上次修改时间的时间戳（以 Unix 毫秒为单位）。

    is_mandatory

    bool

    定义参数是否是集成正常运行所必需的。

    description

    str | None

    参数用途的详细说明。

    name

    str

    参数的内部标识符名称。

    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, ...)

    代码库：对象

    HTMLReport 表示要添加到测试结果中的基于 HTML 的自定义可视化图表。

    属性

    属性
    title

    str | None

    案例墙上报告的显示标题。
    report_name

    str

    报告的内部标识符或文件名。
    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')

    代码库：对象

    链接表示要显示在案例墙上的外部网址结果（以超链接的形式）。

    属性

    属性

    str | None

    超链接的显示文本。

    str

    链接的目标网址。

    class TIPCommon.base.action.data_models.Markdown

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

    代码库：对象

    Markdown 提供了一种结构化方式，可使用 Markdown 语法返回富文本格式的内容。

    属性

    属性
    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])

    代码库：对象

    ScriptParameter 表示操作脚本的单个输入参数，用于管理其值、默认状态以及在剧本或手动操作中的可见性。

    属性

    以下属性用于管理各个脚本形参的元数据、值优先级和数据限制。

    属性
    full_dict

    dict[str, Any]

    从 API 响应中收到的原始字典。
    id

    int | None

    平台为参数分配的唯一标识符。
    creation_time

    int

    参数的创建时间戳（以 Unix 毫秒为单位）。
    modification_time

    int

    表示参数上次修改时间的时间戳（以 Unix 毫秒为单位）。
    custom_action_id

    int | None

    与相应参数关联的自定义操作的标识符。
    is_mandatory

    bool

    指示是否必须提供相应参数，操作脚本才能执行。
    default_value

    Any

    参数的默认值。

    在 playbook 执行中，此值的优先级高于 value。
    description

    str | None

    参数用途的详细说明。
    name

    str | None

    参数的内部标识符名称。
    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)

    代码库：对象

    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='')

    代码库：对象

    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>)

    代码库：对象

    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='')

    代码库：对象

    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 对象。

    “接口”模块

    此模块定义了基础脚本组件的标准抽象合约。

    类 TIPCommon.base.interfaces.apiable.Apiable

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

    代码库：ABC、Generic[ApiParams]

    Apiable 是封装 API 通信逻辑的类的抽象基本接口，可确保外部服务交互具有一致的结构。

    类 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 属性进行身份验证。

    在会话对象初始化后，使用此方法与会话关联的服务建立身份验证。

    类 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 的消息，包括异常堆栈轨迹。

    类 TIPCommon.base.interfaces.session.Session

    类 TIPCommon.base.interfaces.session.Session

    基类：ABC、Generic[_R]

    会话接口提供了一致的蓝图，用于使用各种 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 请求的核心请求调度程序。

    “作业”模块

    这为在平台内按预定时间表执行的后台处理脚本提供了框架。

    类 TIPCommon.base.job.base_job.Job

    类 TIPCommon.base.job.base_job.Job(name: str)

    基类：ABC、Generic[ApiClient]

    Job 是一个抽象基类，专为执行独立后台操作（例如数据同步或健康检查）的预定任务而设计。

    参数

    以下参数是初始化作业并将其注册到平台中所需的参数。

    参数
    name 用于注册和标识作业脚本的唯一标识符。

    属性

    以下属性可用于访问作业的执行上下文、配置和集成服务客户端。

    属性
    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 客户端。

    类 TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple

    类 TIPCommon.base.job.base_job_refresh_token.SuccessFailureTuple(success_list, failure_list)

    基数：元组

    SuccessFailureTuple 是一种专门的命名元组，用于将批处理批量作业操作的结果分为成功和失败。

    属性

    属性
    success_list

    list

    一个列表，其中包含已成功处理的标识符或对象。
    failure_list

    list

    包含处理失败的标识符或对象的列表。

    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])

    代码库：对象

    JobParameter 表示作业脚本的单个配置参数，用于管理其元数据和值状态。

    属性

    属性
    full_dict

    dict[str, Any]

    在作业初始化期间从 API 收到的原始字典。
    id

    int | None

    作业参数的唯一平台分配标识符。
    is_mandatory

    bool

    指示是否必须提供相应参数才能运行作业。
    name

    str | None

    参数的内部标识符名称。
    type

    ActionParamType

    形参的数据类型分类。
    value

    Any

    参数的默认值；此值通常在自动化作业执行中具有优先权。

    需要更多帮助？获得社区成员和 Google SecOps 专业人士的解答。