创建自定义连接器

支持的平台：

通过本文档，您可以了解 SOAR SDK 如何为 Content Hub 中可能未提供的第三方工具构建自定义集成。连接器用于从数据源（通常但不一定）注入具有某种提醒队列的数据。通过连接器与 Google SecOps 应用的交互，在平台中创建案例、提醒和事件。连接器会注入基本事件数据，将这些数据分配给提醒，然后将提醒发送到 Google SecOps 应用及其数据处理流水线。

如需创建自定义连接器，请按照以下大致步骤操作：

  1. 创建一个 Manager 类，其中包含第三方工具的 API 逻辑。
  2. 使用 IDE 构建连接器。

创建管理器

创建连接器的第一步是构建一个 Manager 类，其中包含您要集成的技术所需的所有 API 逻辑。例如，Google SecOps 中的 Netskope 集成包含一个预构建的管理器。此管理器包含与 Netskope API 交互所需的所有逻辑，可用作您自己实现的模型。

创建连接器

在 IDE 中，按照构建自定义集成中的说明创建新的连接器。IDE 将生成一个通用模板，其中包含描述连接器脚本的基本结构和要求的代码注释。

虽然连接器逻辑可能有所不同，但该过程通常包括以下核心步骤：

  1. 使用第三方工具的 API 检索提醒、检测结果或事件。对于 Netskope，此操作由 get_alerts() 方法处理。为确保提醒不会重复，请按时间戳发送查询，并在每次运行后更新查询。
  2. 使用 AlertInfo（以前称为 CaseInfo）类构建提醒，并分配所有必填字段
  3. 检索并展平关联的事件数据，以防止出现嵌套列表和字典问题，然后将展平的事件附加到提醒。
  4. 按时间对提醒进行排序，并存储最新的时间戳以用于下一个查询。

导入和 SDK

每个连接器都必须执行以下操作：

  • 从 SiemplifyConnectors 导入 SiemplifyConnectorExecution 类。此类通常在连接器的 main() 函数中实例化。当此对象使用 return_package() 方法将提醒列表传递给 Google SecOps 应用时，脚本即会结束。
  • 从 SiemplifyConnectorsDataModel 导入 AlertInfo 类。实例化此类会创建提醒对象。在此示例中，它被重命名为 SiemplifyAlertInfo，以避免与源系统的内置提醒对象 (Netskope) 混淆，此重命名是可选的。

SiemplifyUtils 模块提供了用于日志记录、处理数据格式、时间转换等操作的常用方法。我们建议您导入 output_handler、dict_to_flat 和 unix_now，因为它们对于核心功能（包括时间处理）至关重要。

大多数连接器还会导入集成功能的 Manager 类。某些集成包含多个 Manager。您还可以根据自己的使用场景导入其他标准 Python 库。

常量变量

最好声明一些常量变量，以供日后使用。

custconnector2
图 1：常量变量

用于创建 Google SecOps 提醒的脚本示例

如前所述，通过实例化 AlertInfo 类的对象来创建提醒。在此示例中，它被重命名为 SiemplifyAlertInfo()，以避免与源系统混淆。alert_info 对象包含多个必需属性，必须定义这些属性，应用才能正确处理提醒。 build_alert_info 函数接收 Netskope 提醒（以原始 JSON 格式，从 API 接收）和 Siemplify 对象作为输入。然后，它会解析 Netskope 提醒，并将相关值分配给 `alert_info` 字段。

此函数还使用了之前定义的常量。在 alert_info 对象上设置的所有属性都会成为 Google SecOps 应用内提醒对象的一部分。

第 35 行（如图 2 所示）突出了此流程的一个重要部分：使用 dict_to_flat 方法将提醒扁平化，然后将其附加到 events 属性。

custconnector3
图 2：用于创建提醒的脚本示例
 

一个提醒可以包含多个事件，在这种情况下，您必须包含相应逻辑来妥善处理每个事件。在此示例中，每个提醒仅包含一个事件，因此默认实现就足够了。

dict_to_flat 方法用于展平原始 JSON 结构。这有助于避免嵌套列表和字典出现问题。扁平化键值对是原始键值对的略微修改版本。

请查看图 2 中的以下逻辑：

  • 使用 uuid 库为 display_id 分配一个随机生成的值。Netskope 提醒不提供 UUID 字段，但如果有，则可以使用该字段。
  • ticket_id 设置为与 display_id 匹配。 这两个字段在系统中的每个提醒中都必须是唯一的。通过生成随机 UUID 来确保唯一性。
  • name 是提醒名称，将显示在 GUI 中。
  • rule_generator 是指在源系统中生成提醒的规则。此字段可能不会始终出现在原始数据中。如果缺少该值，您可以分配任何字符串值，但不能留空。
  • start_time 和 end_time 表示相应提醒的时间戳。在此示例中，Netskope 提醒提供了一个 Unix 纪元时间戳，必须将其乘以 1000 才能转换为毫秒。这是 Google SecOps 的预期格式。如果来源使用其他格式，您必须进行转换。如需了解有用的时间转换方法，请参阅 SiemplifyUtils.py 模块。
  • priority：Google SecOps 应用会根据每个支持请求的提醒优先级为其分配优先级。 Google SecOps API 使用以下方案将数值映射到视觉标签，其中整数值在连接器中传递：{"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100}，其中整数值是在连接器中传递的值。例如，传递 `100` 会在 GUI 中将相应提醒标记为严重。在此连接器中，一个额外的辅助函数使用 `SEVERITY_MAP` 常量将 Netskope 的严重程度值映射到此优先级范围。不过，由于 Netskope 的严重程度字段不一致，因此映射需要额外的逻辑来评估多个字段。
  • device_vendor 和 device_product 的值来自脚本中之前定义的常量。
  • 在 Google SecOps 中使用多个环境时，environment 至关重要。在这种情况下，它来自 siemplify 对象，并与平台中为连接器选择的环境保持一致。
  • 在第 37 行（图 3）中，连接器通过添加一个新键 product_name（值为“Netskope”）来修改基本事件字典。这是必需的，因为原始数据不包含可用于在平台本体中进行映射和建模的一致产品字段。
    custconnector4
    图 3：修改基本事件

运行连接器的脚本示例

main 函数包含连接器的核心执行逻辑：

  • output_handler 修饰器用于调试目的，本文档不作介绍。
  • main 函数包含一个可选参数 is_test_run，其默认值为 False。顾名思义，此参数用于确定连接器应在生产环境中接收提醒，还是应在应用的连接器测试标签页中以测试模式运行。

查看每行脚本的核心执行逻辑明细：

custconnector4
图 3：修改基本事件
  • 第 56 行和第 57 行初始化了两个在执行期间使用的空列表。
  • 在第 58 行中，SiemplifyConnectorExecution 类实例化了 siemplify 对象。此对象用于管理连接器的大部分运行时行为。
  • 在第 61 行中，创建了 Connector Allowlist 的实例。虽然此连接器中未使用该参数，但它在其他连接器中很常用，本指南中不作讨论。
  • 在第 67-69 行中，为连接器参数（例如身份验证凭证或配置设置）定义了变量。
  • 在第 71 行中，它实例化了 NetskopeManager 对象并传入相关参数，以实现成功的身份验证。此示例中未显示处理身份验证的内部 Manager 逻辑。
  • 在第 73 行中，它会从之前连接器执行期间创建的本地文件中检索时间戳。此时间戳用于避免重复处理相同的提醒。
  • 在第 74 行和第 75 行中，它会处理连接器首次运行且时间戳尚未设置的情况（例如，当时间戳默认为“0”时）。由于 Netskope 需要 Unix 纪元时间，并且不接受“0”作为有效开始时间，因此会使用“unix_now”函数检索当前时间（以毫秒为单位）。此值除以 `1,000` 即可转换为 Unix 纪元秒数。然后，将得到的开始时间和结束时间传递给 Manager 中的 `get_alerts` 方法。虽然许多 API 只接受开始时间，但 Netskope API 要求基于时间的提醒查询同时提供开始时间和结束时间。
  • 在第 77 行中，它从 Netskope 检索提醒列表。如果连接器在测试模式下运行，则系统只会选择列表中的最后一个提醒（第 79-80 行）。

溢出逻辑

然后，连接器会遍历检索到的提醒，并使用之前定义的 build_alert_info 函数根据每个提醒构建一个提醒。它会将每个提醒附加到之前初始化的 all_alerts 列表中。连接器逻辑的下一部分处理溢出。
溢出是一种阈值机制，可防止在短时间内接收过多的提醒，尤其是在提醒共享相同的环境、产品和规则生成器时。虽然不是强制性的，但我们建议您根据最佳实践实现溢出逻辑，以防止性能下降。

查看图 4 中每个脚本行的溢出逻辑细分：

  • 在第 104-105 行中，如果 alert 未被归类为溢出，则会将其附加到要注入的提醒列表中。

    • custconnector5
    图 4：溢出机制。

结束连接器执行

如果连接器未在测试模式下运行，则必须更新时间戳以反映检索到的最新提醒。这样可确保在下一个执行周期内不会重新提取相同的提醒。all_alerts 列表按时间戳排序，因此即使是溢出的提醒也会有助于确定最新时间戳。

请查看图 5 中按脚本行划分的连接器执行逻辑细分：

  • 在第 126 行，未溢出的提醒列表会提交到应用，然后应用会在 GUI 中创建并显示这些提醒。
  • 在第 128-131 行中，它们用于确定连接器是否在测试模式下运行。系统会根据应用传递的系统参数（例如，在测试标签页上点击运行连接器一次时）来做出此判断。
    custconnector6
    图 5：结束连接器执行

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