开发自定义转换器

支持范围：

Google SecOps SOAR

注意：此功能受 Google Security Operations 服务专用条款的非正式版产品条款约束。我们对正式发布前功能的支持可能有限，并且对正式发布前功能的更改与其他正式发布前版本可能不兼容。如需了解详情，请参阅 Google SecOps 技术支持服务准则和 Google SecOps 服务专用条款。
如果您的环境中未显示此功能，请参阅管理预览版功能或与系统管理员联系。

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

扩展包

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

扩展程序包的最佳实践

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

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

创建扩展包

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

1. 前往自动化 > IDE。
2. 点击 add 创建新项。
3. 从下拉菜单中选择扩展程序包。
4. 为扩展程序包提供一个唯一的名称。
注意：名称一经创建便无法更改。
5. 点击保存。

上传依赖项

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

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

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

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

导入和导出

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

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

自定义转换器

自定义转换器是用户定义的 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. 创建参数：
   • 每个自定义转换器函数都包含一个默认的输入参数。此参数表示输入数据，即函数应用于的占位符。您无法删除此参数。
   • 此外，您还可以添加要在函数中使用的可选参数。
8. 文档（可选）：为表达式构建器定义产品内文档：
   • 预期输入：描述函数预期为此转换器接收的数据类型（例如，“字符串”或“字符串列表”）。
   • 预期输出：描述函数预期为此转换器返回的数据类型（例如，“布尔值”）。
   • 用法示例：提供如何调用函数的示例（例如 if_empty("new_value")）。

您可以直接在 IDE 中测试自定义转换函数逻辑，然后再将其用于 playbook。这样，您就可以验证 Python 脚本是否正确处理各种输入类型和参数，并返回预期结果。

超时

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

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

在表达式构建器中使用自定义转换器

保存后，自定义转换器会与内置函数一起显示在表达式构建器的函数列表中。它们采用以下格式：ExtensionPackName.TransformerName。将鼠标悬停在函数上，即可显示根据参数说明生成的文档。

支持所有占位符（JSON 和非 JSON）

表达式构建器支持 Playbook Designer 中公开的所有占位符，包括非 JSON 结果。

对于非 JSON 占位符：

• 您可以手动将示例数据输入到表达式构建器中，以针对各种输入类型（字符串、列表 [逗号分隔值] 和 JSON）测试逻辑。
• 使用输入类型进行测试并不能保证占位符在运行时会返回该特定类型。
• 大多数占位符都会解析为字符串，但某些特定类型会根据其数量解析为字符串或列表（例如 entity.identifier）。对于这些类型，建议始终将输入视为列表。

注意：抽样数据是临时性的，在您关闭表达式构建器或保存表达式后不会保存。如果您再次打开构建器，则必须重新输入示例数据。

错误处理

如果自定义转换函数在执行期间遇到错误，则使用该转换器的 playbook 操作会失败。Python 脚本生成的具体错误消息会显示在 playbook 运行视图中的屏幕上，以便您直接排查逻辑问题。

自定义逻辑运算符

自定义逻辑运算符可让您定义自己的布尔逻辑来比较值。

创建自定义逻辑运算符

如需定义新的逻辑运算符，请按以下步骤操作：

1. 在 IDE 中，找到目标扩展程序包。
2. 选择自定义逻辑运算符。
3. 请为其命名。
注意：名称一经创建便无法更改。
4. 可选：在 Playbook Designer 中为逻辑运算符菜单添加说明。
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 条件、上一个操作条件和实体选择中的运算符菜单内。

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

错误处理

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

限制

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

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