构建自定义集成

支持的平台：

Google SecOps SOAR

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

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

在 IDE 中创建自定义集成

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

使用情形：构建自定义 Armis 集成

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

1. 在主菜单中，依次前往响应 > IDE。
2. 点击 Create New Item（创建新项），然后选择 Integration（集成）。
3. 输入名称，然后点击创建。

该集成现在会显示在列表中，并带有 设置 设置选项，表示这是一个自定义集成。

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

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

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

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

[tool.uv.sources]
# The key (e.g., compressed-rtf) must match the dependency name
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 文档。

创建自定义管理器

管理器是第三方工具 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) 要验证的响应
       :param error_msg: (str) 要显示的错误消息
       """
       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 Secret：用于向服务验证应用身份的机密密钥。
• 验证 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 和 Content Hub 中。
2. 点击导入。集成会同时显示在 IDE 和内容中心中。
3. 系统会生成一个包含定义、脚本和配置的 ZIP 文件。系统不会自动包含 Managers 文件夹。
• 如需导出集成，请执行以下操作：
• 点击导出下载软件包。

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