迁移到 Chronicle API

支持范围：

如果您使用集成、自定义脚本或自定义操作以编程方式调用 SOAR API，则本文档适用于您。 本文档概述了相关步骤和注意事项，旨在帮助您将程序化 API 参考文档更新为 Chronicle API 的新 SOAR API 端点。

Chronicle API 接口引入了多项改进，旨在简化您的开发流程。它还解决了旧版 API 中存在的限制和复杂性。

旧版 SOAR API 和 API 密钥将一直可用，直到 2027 年 3 月 31 日，之后将不再有效。

前提条件

在执行 SOAR API 迁移之前，您需要执行以下操作：

主要变化和增强功能

下表重点介绍了新旧 API 接口之间的主要区别：

功能区域 旧版 API 新 API 详细信息
身份验证 API 令牌 OAuth 2.0 新的身份验证方法可提高安全性并使流程标准化。
数据模型 扁平化结构 面向资源的设计 这种新设计提高了数据一致性，并简化了对象操作。
端点命名 不一致 RESTful 且标准化 一致的命名方式使 API 更直观、更易于集成。

弃用时间表

旧版 SOAR API surface 计划于 2027 年 3 月 31 日完全弃用。我们建议您在此日期之前完成迁移，以免服务中断。

迁移步骤

本部分概述了将应用成功迁移到 Chronicle API 的步骤：

查看文档

熟悉新 API 的全面文档，包括 Chronicle API 参考指南。

将端点映射到新的 API Surface

为应用发出的每个旧 API 调用确定对应的新端点。同样，将旧数据模型映射到新数据模型，并考虑任何结构性变化或新字段。如需了解详情，请参阅 API 端点映射表。

可选：创建预演集成

如果您要修改自定义集成或商业集成的组件，我们建议您先将更改推送到预演集成。这样，您就可以在不影响生产自动化流程的情况下进行测试。 如果您要迁移使用 SOAR API 的自定义应用，可以跳到下一步。如需详细了解集成预演，请参阅在预演模式下测试集成。

更新服务端点和网址

服务端点是指定 API 服务的网络地址的基础网址。一项服务可以有多个服务端点。Chronicle 是一项区域级服务，仅支持区域级端点。

所有新端点都使用一致的前缀，从而使最终端点地址可预测。以下示例展示了新的端点网址结构：

[api_version]/projects/[project_id]/locations/[location]/instances[instance_id]/...

此结构使端点的最终地址如下所示：

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

其中：

  • service_endpoint：区域服务地址
  • api_version：要查询的 API 版本。可以是 v1alpha、v1beta 或 v1。
  • project_id：您的项目 ID（与您为 IAM 权限定义的项目相同）
  • location：项目的位置（区域）；与区域端点相同
  • instance_id：您的 Google Security Operations SIEM 客户 ID。

区域级地址：

  • africa-south1：https://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1：https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1：https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1：https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2：https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1：https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12：https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2：https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3：https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6：https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9：https://chronicle.europe-west9.rep.googleapis.com

  • me-central1：https://chronicle.me-central1.rep.googleapis.com

  • me-central2：https://chronicle.me-central2.rep.googleapis.com

  • me-west1：https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2：https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1：https://chronicle.southamerica-east1.rep.googleapis.com

  • us：https://chronicle.us.rep.googleapis.com

  • eu：https://chronicle.eu.rep.googleapis.com

例如，如需获取美国境内某个项目的所有支持请求的列表，请运行以下命令：

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

更新身份验证方法

新 API 使用 Google Cloud IAM 进行身份验证。您需要更新应用或响应集成，以实现这一新的身份验证流程。确保运行脚本的用户对他们尝试访问的端点拥有正确的权限。 如需实现这一新流程，您必须更新响应集成或应用。确保执行脚本的用户拥有目标端点的必要权限。如需了解详细说明，请参阅向 Chronicle API 进行身份验证页面。

将服务账号或 Workload Identity 映射到 SOAR 参数

如果您使用服务账号或工作负载身份联合向 Chronicle API 进行身份验证，则必须在平台内对其进行授权，以确保其能够成功与 Google SecOps 通信。必须进行此映射，才能为服务账号或 Workload Identity 提供对 SOC 角色和环境的必要访问权限。

如需向 Google SecOps 授予服务账号访问权限或工作负载身份联合访问权限，您必须将该身份映射到平台的访问权限控制参数。此映射是强制性步骤，旨在为身份提供必要的访问权限，以便其能够访问执行自动化任务或 API 操作所需的 SOC 角色和环境。

  1. 依次前往设置 > 访问权限管理 > 群组映射。
  2. 点击添加 添加。

  3. 填写添加映射对话框中的字段，将身份映射到平台的访问权限控制参数。

    1. 在 IdP/用户群组字段中，输入以下内容之一：
      • 服务账号的完整邮箱（如果身份是使用 Cloud Identity 设置的）。
      • Workload Identity 主账号字符串（如果身份是使用员工身份联合设置的）。

    2. 配置以下访问权限控制字段：

      字段 说明
      权限组 选择权限组，以定义该身份可以访问哪些模块和子模块。
      SOC 角色 选择 SOC 角色以定义身份的角色（例如第 1 层）。
      环境 选择该身份可以访问的环境或环境组（例如所有环境）。
      群组成员 输入所需的用户邮箱（如适用）。每添加一个邮箱后按 Enter 键。
      受限操作 选择受限操作，以限制模块内的特定操作。

  4. 点击 Add（添加）。

如需详细了解如何映射用户和服务账号，请参阅使用第三方身份在平台中映射用户或使用 Cloud Identity 在平台中映射用户。

更新 API 逻辑

分析 API 参考文档中提供的新数据模型和端点结构。并非所有方法都发生了重大变化，部分现有代码可以重复使用。主要目标是查看新的参考文档，并针对每个具体应用场景，在应用逻辑中识别并实现对字段名称和数据结构的必要更改。

测试您的集成

在部署到生产环境之前，请先在预演集成中测试更新后的应用：

  1. 创建测试计划：定义涵盖所有已迁移功能的测试用例。
  2. 执行测试：运行自动化和手动测试，以确认准确性和有效性。
  3. 监控性能：评估应用在使用新 API 后的性能。

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