自定义转换函数和逻辑运算符

支持的平台：

Google SecOps SOAR

注意： 此功能受《Google Security Operations 服务专用条款》的正式发布前产品条款的约束。我们对正式发布前功能的支持可能有限，并且对正式发布前功能的更改与其他正式发布前版本可能不兼容。如需了解详情，请参阅 Google SecOps 技术支持服务准则和 Google SecOps 服务专用条款。

您可以在 IDE 中直接创建基于 Python 的自定义转换函数和逻辑运算符，并在 playbook 中使用它们来应对复杂多样的使用情形。

扩展包

扩展包是一种专门的集成类型，旨在充当自定义转换函数和逻辑运算符的容器。与标准集成不同，扩展包不需要实例配置，可以直接从 IDE 创建。

扩展包的最佳实践

• 整合：创建一个主扩展包，并向其中添加多个转换函数或逻辑运算符。
• 分离：如果您需要一组可能与主扩展包冲突的其他 Python 库（依赖项），请创建一个新的扩展包。

重要提示：在 IDE 中创建扩展包需要所有环境权限。

创建扩展包

如需创建新的扩展包，请按以下步骤操作：

1. 前往响应 > IDE。
2. 点击添加图标 新建内容。
3. 从下拉菜单中选择扩展包。
4. 为扩展包提供一个唯一的名称。
注意：名称一经创建便无法更改。
5. 点击保存。

上传依赖项

与标准集成一样，扩展包在虚拟环境中运行，您可以在其中管理 Python 库。

如需管理您的媒体库，请按以下步骤操作：

1. 在 IDE 中打开 Extension Pack 设置。
2. 从 PyPi 添加所需的 Python 库，或从计算机上传这些库。

这些依赖项可供此特定扩展包中包含的所有转换器和逻辑运算符使用。

导入和导出

您可以在 IDE 界面中直接手动导入和导出扩展包。

注意：对于尚未完成第 2 阶段迁移的客户，可能无法使用导入和导出功能。如需了解详情，请参阅 SOAR 迁移概览。

自定义 Transformer

自定义转换器是用户定义的 Python 函数，用于扩展表达式构建器中的预建函数。您可以在 IDE 中直接创建它们，以提取和处理数据，并且它们可以与现有的内置函数一起使用。

创建自定义转换器

如需定义新的自定义转换器，请按照以下步骤操作：

1. 在 IDE 中，找到目标扩展程序包。
2. 选择目标扩展包，以便在该包下添加新项。
3. 选择自定义转换函数。
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 中直接测试自定义转换函数逻辑，然后再在 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）结果。

参数

自定义逻辑运算符接受两个参数：左侧（必需且不可修改）和右侧（可选；可由用户停用）。

• 示例 1： if [left side] not in [right side]。
• 示例 2： if [left side] is greater than 80（无右侧）。

超时

• 默认超时时间：1 分钟。
• 最长超时时间：3 分钟。

注意：由于平台会等待函数完成，因此您必须尽可能缩短执行时间。最佳做法是专注于直接数据转换，避免查询外部来源或执行繁重的处理。

在 playbook 中使用

自定义逻辑运算符会显示在剧本条件、上一个操作条件和实体选择中的运算符菜单中。

自定义逻辑运算符可与标准运算符（例如“等于”或“包含”）一起选择。

错误处理

如果自定义逻辑运算符函数在执行期间遇到错误，使用该运算符的 playbook 条件或步骤将失败。Python 脚本返回的错误消息会显示在 playbook 运行视图中，以帮助进行问题排查。

限制

• 触发器或 Webhook 中不支持自定义转换函数和逻辑运算符。

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