将 SOAR 端点迁移到 Chronicle API

支持的平台：

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

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

旧版 SOAR API 和 API 密钥将一直可用到 2026 年 9 月 30 日，之后将不再正常运行。

前提条件

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

主要变化和增强功能

下表重点介绍了旧版 API 和新版 API 表面之间的主要区别：

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

弃用时间表

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

迁移步骤

本部分概述了将应用成功迁移到 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

  • 美国：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 进行身份验证页面。

将服务账号或工作负载身份映射到 SOAR 参数

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

如需映射服务账号，请执行以下操作：

  1. 前往 SOAR 设置 > 高级 > 群组映射。

  2. 点击 添加 添加。

  3. 在添加角色对话框中，在 IAM 角色 / IdP 群组字段中输入服务账号的完整电子邮件地址或 Workload Identity 主账号字符串。

  4. 选择合适的 SOC 角色和环境。

  5. 点击 Add（添加）。

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

更新 API 逻辑

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

测试您的集成

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

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

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