构建自定义集成

支持：

Google SecOps SOAR

本文档介绍了为 Google SecOps 构建自定义集成的流程。目前的最佳实践是使用您首选的 IDE 在本地开发集成，并通过 GitHub 使用现代 GitOps 工作流管理集成。对于旧版环境或快速原型，您也可以直接在内置 SOAR IDE 中构建集成。

注意：如需了解构建和提交自定义集成的标准化开发框架、质量保证指南和最佳实践，请参阅自定义集成指南。

本地 IDE 和 GitHub 工作流（推荐）

建议的工作流是在本地开发集成并通过 GitHub 进行管理。此方法符合现代 GitOps 实践，可实现更好的版本控制、协作和自动化依赖项管理。

如需了解详细的技术步骤、安装指南以及使用 Marketplace CLI 工具和 uv 软件包管理器的现代命令，请参阅官方 Chronicle Content Hub GitHub 代码库。

概念性工作流概览

如需在本地开发自定义集成，建议您遵循此 GitOps 生命周期。如需了解这些命令的确切最新语法，请参阅 GitHub 上的官方 MP CLI 文档。

1. 创建分支并克隆：将官方 content-hub 代码库克隆到本地开发机器。
2. 安装工具：安装 mp CLI 工具和 uv Python 软件包管理器。
3. 进行身份验证：使用实例网址和 API 密钥，通过 MP CLI 登录 Google SecOps 环境。
4. 本地开发：使用您首选的 IDE（例如 VS Code 或 PyCharm）编写集成代码，并利用本地调试和测试工具。
5. 管理依赖项：使用 uv 在本地 pyproject.toml 文件中声明和管理依赖项（例如 TIPCommon）。
6. 同步：使用 mp pull 和 mp push 命令将本地代码与 Google SecOps 实例同步，以便进行测试和部署。

替代方案：在内置 IDE 中创建自定义集成

如果您要维护旧版集成、快速测试脚本，或在本地开发受限的环境中工作，可以使用内置 IDE。

应用场景：构建自定义 Armis 集成

如需在 IDE 中创建自定义集成，请按以下步骤操作：

1. 在主菜单中，依次前往响应 > IDE。
2. 点击 创建新内容，然后选择集成。
3. 输入名称，然后点击创建。

现在，该集成会与 设置 设置选项一起列出，表示它是自定义集成。

点击 settings 设置以显示集成设置，您可以在其中定义图标、说明、Python 依赖项和集成参数。

注意：脚本依赖项是自定义集成所需的 Python 库。依赖项可以作为 .WHL、.TAR、.GZ 或 .PY 文件上传。每个集成都在自己的虚拟环境中运行，因此无论底层系统上安装了什么，您都可以使用特定的库版本。

如果您使用的是需要嵌套子依赖项的自定义或专有 .WHL 文件（例如 TIPCommon），则必须在保存之前人工上传整个依赖项树的各个 wheel 文件。未能解析嵌套依赖项会导致一般 errorCode: 2000 失败。如需进行高级依赖项跟踪，请考虑使用本地 IDE 和 GitHub 工作流。

创建自定义管理器

管理器是第三方工具 API 的封装容器。虽然并非强制要求，但我们建议在与外部工具交互的集成中使用这些变量。管理员不应从 SDK 导入。创建后，将其导入连接器、操作和作业。

如需创建自定义管理员，请按以下步骤操作：

1. 在 IDE 中，点击 Create New Item（创建新项），然后选择 Manager（管理器）。
2. 选择 Armis 集成，然后输入管理员名称。
   
3. 修改并运行以下脚本：

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token = api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) The response to validate
       :param error_msg: (str) The error message to display
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

注意：基本操作不需要管理器。不过，我们建议您在对用于数据解析和转换的小型操作进行分组时创建一个。

参数、Google SecOps Content Hub 配置和 Ping 操作

集成设置中定义的参数会显示在 Google SecOps Content Hub 配置中。这些参数包括：

• API 根：您要连接到的服务的基础网址。
• API 密钥：用于向服务验证应用身份的机密密钥。
• 验证 SSL 复选框：如果启用，则会验证与 Armis 服务器连接的 SSL 证书是否有效。
• 远程运行复选框：此设置用于确定代码或任务是在远程服务器上执行，还是在本地执行。启用此选项后，系统会将必要的指令和数据发送到专用服务器进行处理。

如需更新参数，请按以下步骤操作：

1. 请输入正确的凭据。
2. 依次点击保存 > 测试。

注意：更新凭据后，请务必点击保存。所有第三方集成都必须实现 Ping 操作。测试按钮会运行此操作来验证连接性。

如果缺少 Ping 操作，测试按钮会失败并显示红色 X。

实现 Ping 操作

Ping 操作的逻辑类似于成功的身份验证。

如需实现 Ping 操作，请执行以下操作：

1. 在 IDE 中，在 Armis 集成中创建一个名为 Ping 的新操作。
2. 使用 ArmisManager auth 方法验证身份验证。

启用集成

如需启用集成，请按以下步骤操作：

1. 在响应 > IDE 中，将启用/停用切换开关切换到开启位置。
2. 点击保存。绿色切换开关表示成功。Content Hub 中的凭据会传递给 ArmisManager。如果 auth 完成且没有错误，测试按钮会显示一个绿色对勾标记。

使用 extract_configuration_param 方法从集成配置中导入参数。或者，使用 extract_action_param 在操作本身中定义参数。不过，Ping 操作应始终使用配置参数，因为这些参数会由 Content Hub 进行测试。

查看自定义集成

前往内容中心，搜索您创建的自定义集成。 如果您在初始配置期间未创建映像，系统会为其分配默认自定义映像。请注意，Content Hub 更新不会覆盖或删除任何自定义集成。

在 IDE 中导出和导入

在这种情况下，请执行下列其中一项操作：

• 如需导入集成，请执行以下操作：
1. 上传具有正确文件夹结构的 ZIP 文件；集成会显示在 IDE 和 Content Hub 中。
2. 点击导入。该集成会同时显示在 IDE 和 Content Hub 中。
3. 系统会生成一个 ZIP 文件，其中包含定义、脚本和配置。Managers 文件夹不会自动包含在内。
• 如需导出集成，请执行以下操作：
• 点击导出以下载软件包。

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