构建自定义集成

支持：

Google SecOps SOAR

本文档介绍了如何在集成式开发 环境 (IDE) 中创建自定义集成，并使用与商业集成相同的结构。您可以在各种环境的内容中心内查找和配置自定义集成。然后，您可以在 Playbook、手动操作和远程代理中使用它们。与其他 IDE 项类似，系统还支持导入和导出功能。

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

在 IDE 中创建自定义集成

您可以为 Armis 产品构建自定义集成，并创建管理器以及 Ping 操作。此过程假定您了解 Python 和面向对象的编程。

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

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

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

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

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

注意：脚本依赖项是自定义 集成所需的 Python 库。依赖项可以作为 .WHL、 .TAR、.GZ 或 .PY 文件上传。每个 集成都在自己的虚拟环境中运行，让您可以使用 特定的库版本，而无需考虑底层 系统上安装的内容。例如，如需使用不同版本的 requests 库， 请从 PyPI 或 GitHub 等可信来源下载该库，并将其添加为 脚本依赖项。
对于需要预编译二进制轮（例如带有 C 扩展程序的软件包）的依赖项，SOAR 平台使用针对 manylinux_2_17_x86_64 架构构建的标准 cpython。选择 .WHL 文件时，请验证它是否与此标记兼容。
如果库未安装在虚拟环境中，集成 会回退到系统安装的版本。

如果您使用的是需要嵌套子依赖项的自定义或专有 .WHL 文件 （例如 TIPCommon），则必须先为整个依赖项树 手动上传各个轮文件 （例如：anyio、certifi、httpx、 idna 或 sniffio），然后才能保存。未能解析 嵌套依赖项会导致通用的 errorCode: 2000 失败。如需查看所需平台库的完整列表，请参阅 有关检索 TIPCommon 的社区指南。

如果依赖项软件包没有适用于 manylinux_2_17_x86_64 架构的预编译轮 (.WHL) 文件，或者您需要特定的源代码版本，则可以提供指向 源代码的直接网址（例如 .tar.gz 文件）。平台的 依赖项解析器 uv 支持在 pyproject.toml 文件中的 [tool.uv.sources] 表中定义这些源代码网址。例如：

[project]
# ... other project fields ...

[tool.uv.sources]
compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" }
dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }

如需详细了解如何使用 uv 定义不同类型的依赖项，请参阅有关 管理依赖项 的 uv 文档。

推荐的工作流：使用 mp CLI 进行高级依赖项管理

对于需要复杂或多层外部库（如 TIPCommon）的集成，Google 建议完全绕过手动 IDE 上传 ，并使用 Marketplace CLI (mp) 工具在本地开发它们。此工具使用 uv 软件包管理器自动跟踪和打包嵌套依赖项。

前提条件

• 在本地开发机器上安装 Python 3.11 或更高版本。
• 安装 uv Python 软件包管理器（请参阅 uv 安装指南）。

初始设置

1. 将官方内容中心代码库 克隆到本地环境。
2. 使用 uv 安装 mp 工具：

   uv tool install mp --from git+https://github.com/chronicle/content-hub.git#subdirectory=packages/mp

3. 使用实例 根网址和旧版 API 密钥登录 Google SecOps 环境：

   mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}

   注意： CLI 工具需要旧版 SOAR 实例网址和 API 密钥格式进行身份验证。
4. 配置本地根代码库路径：

   mp config --root-path /path/to/cloned/content-hub

5. 在以下位置的代码库布局中为专有集成创建自定义子目录： content-hub/content/response_integrations/custom/

向集成添加 TIPCommon 或复杂依赖项

如果您在 IDE 中创建的集成需要 TIPCommon 或其他多层库，请使用以下本地 工作流安全地管理其依赖项：

1. 在克隆的代码库中，前往自定义集成目录：

   cd content-hub/content/response_integrations/custom/

2. 从 Google SecOps 实例中拉取现有集成结构：

   mp pull --type integration --name "{INTEGRATION_NAME}"

3. 将目录更改为新拉取的集成文件夹：

   cd {INTEGRATION_NAME}

4. 使用 uv 注入所需的 TIPCommon 轮文件 软件包。这会自动跟踪嵌套的子依赖项 轮并将其下载到本地环境软件包配置中：

   uv pip install /path/to/wheels/TIPCommon-your-version-py3-none-any.whl

5. 将完全编译的集成及其新跟踪的依赖项 树推回到 Google SecOps 实例：

   mp push --type integration --name "{INTEGRATION_NAME}"

验证安装

如需确认依赖项已成功打包，且未遇到 an errorCode: 2000 循环，请执行以下操作：

• 在 IDE 中打开自定义集成。
• 添加测试行以从软件包导入模块，例如：from TIPCommon.extraction import extract_action_param
• 点击测试/播放 按钮以调试执行。如果脚本 编译干净，且未抛出 ModuleNotFoundError，则 嵌套依赖项会正确解析。

创建自定义管理器

管理器是第三方工具 API 的封装容器。虽然不是强制性的，但我们建议将它们用于与外部工具交互的集成。管理器不应从 SDK 导入。创建后，将它们导入连接器、操作和作业。

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

1. 在 IDE 中，点击 创建新项 ，然后选择 管理器。
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 内容中心配置和 Ping 操作

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

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

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

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

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

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

实现 Ping 操作

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

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

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

启用集成

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

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

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

查看自定义集成

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

在 IDE 中导出和导入

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

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

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