创建自定义连接器

支持的平台：

Google SecOps SOAR

注意：本文档假设您具备 Python 和面向对象编程方面的工作知识。

本文档介绍了 SOAR SDK 如何为可能未在内容中心提供的第三方工具构建自定义集成。连接器用于从数据源（通常但不总是具有某种类型的提醒队列）注入数据。通过连接器与 Google SecOps 应用的互动，可在平台中创建支持请求、提醒和事件。连接器会注入基本事件数据，将这些数据分配给提醒，然后将提醒发送到 Google SecOps 应用及其数据处理流水线。

注意：详细了解 TIP Common 库。

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

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

创建经理

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

创建连接器

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

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

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

注意：一个提醒可以包含多个事件。例如，SIEM 平台会将多个事件关联到一个警报（例如 Trellix ESM）或违规事件（例如 QRadar）。相比之下，端点检测工具通常会针对每个提醒生成一个事件。连接器逻辑应反映数据源的结构。

导入和 SDK

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

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

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

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

注意：旧版连接器可以使用 SiemplifyConnectors 中的 CaseInfo。此类与 AlertInfo 相同，反映的是已弃用的命名惯例。

常量变量

最好声明几个常量变量以供日后使用。

图 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 属性。

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

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

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

查看图 2 中的以下逻辑：

• display_id 使用 uuid 库分配一个随机生成的值。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` 会在界面中将相应提醒标记为严重。在此连接器中，一个额外的辅助函数使用 `SEVERITY_MAP` 常量将 Netskope 的严重程度值映射到此优先级范围。不过，由于 Netskope 的严重程度字段不一致，因此映射需要额外的逻辑来评估多个字段。
• device_vendor 和 device_product 的值来自脚本中之前定义的常量。
• 在 Google SecOps 中使用多个环境时，environment 至关重要。在这种情况下，它来自 siemplify 对象，并与平台中为连接器选择的环境保持一致。
• 在第 37 行（图 3）中，连接器通过添加一个新键 product_name（值为“Netskope”）来修改基本事件字典。这是必需的，因为原始数据不包含可用于在平台本体中进行映射和建模的一致产品字段。

  

  图 3：修改基本事件

运行连接器的脚本示例

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

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

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

图 3：修改基本事件

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

溢出逻辑

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

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

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



图 4：溢出机制。

结束连接器执行

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

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

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

  

  图 5：结束连接器执行

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