贡献社区响应集成

支持平台：

Google SecOps SOAR

本文档概述了通过社区 贡献向 Google SecOps 提交响应 集成的准则。所有提交的集成都会经过 Google SecOps 官方团队的审核流程，重点是本文档中突出显示的 要求。

响应集成元数据

名称

名称 应与集成将要集成的产品名称相对应，并且不应包含任何特殊字符。

显示名称 应使用空格书写；例如， Vertex AI 而不是 VertexAI。

集成标识符

集成标识符 是 集成的唯一标识符。集成创建后，此值无法更改。 标识符应与 Name 的值相同，但要移除 空格。

该标识符在平台的大部分位置都可用。

说明

说明 应提供集成所创建产品的概览，且不得超过 500 个字符。它必须包含以下信息：

This integration is owned by the "{vendor name}". Support Contact: {email}.

避免在说明中放置网址。

徽标

每个集成都应提供一个 SVG 图标。此图标应 适应平台内的各种主题。图标应仅从平台继承主题 。

您应在以下页面上验证徽标：

• 响应 > 集成设置
• 响应 > 剧本 > 剧本设计器
• 案例 > 提醒 > 提醒剧本视图

以下是 SVG 徽标的示例，旨在与我们的样式指南相匹配：

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>
        

请务必先对 SVG 进行编码，然后再将其添加到集成定义 文件，如内容中心的其他集成中所述。

文档链接

作为集成的一部分，您可以添加一个链接，将用户指向 文档。此文档预计将托管在您的端。

用户可以从配置实例 对话框的参数 部分访问文档链接。

配置参数

所有集成都应包含配置参数（API 根目录 + 身份验证 参数），除非底层 API 不需要任何身份验证 并且 API 根目录可以硬编码。对于需要身份验证的所有集成，都应有一个 Verify SSL 参数。

所有参数都应有说明。说明应帮助 用户从平台内配置集成。避免在参数说明中放置网址。

Ping 操作

Ping 操作 是一种特殊操作，平台使用它 来验证 API 连接。即使您的 集成没有任何其他操作，此操作也是必需的。每当用户在集成配置中按下 测试 按钮时，都应显示 准确的连接状态。

版本说明

版本说明的一般结构应遵循以下 格式：

• {integration item} - {update}
• 例如：Get Case Details - Added ability to fetch information about affected IOCs

根据具体情况，特定 场景有独特的版本说明：

• 如果是新集成：New Integration Added - {integration name}
• 如果添加了新操作：New Action Added - {action name}
• 如果添加了新连接器：New Connector Added - {connector name}
• 如果添加了新作业：New Job Added - {job name}
• 如果将预定义微件添加到操作：{action name} - Added Predefined Widget.
• 如果预定义微件已更新：{action name} - Updated Predefined Widget.
• 对于影响所有集成项的更改：Integration - {Update}
• 对于影响所有操作的更改：Integration's Actions - {Update}
• 对于影响所有连接器的更改：Integration's Connectors - {Update}
• 对于影响所有作业的更改：Integration's Jobs - {Update}

如果版本包含回归性更改，则需要在版本说明中 您需要指定 REGRESSIVE!。例如， Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

版本说明位于集成详情 侧边 抽屉式导航栏中，当您点击集成中的详情 按钮时，该抽屉式导航栏会显示出来。

版本控制

每次集成更新后，都应将 集成版本更新 +1。版本应以整数表示。不允许使用 11.1.3 或 11.1 等次要版本。

标记

您可以选择性地向集成添加标记。避免创建新的 标记类型；使用平台中已有的标记。如果您 没有看到适合您的标记，请咨询审核团队。

一般注意事项

• 提交前测试每个集成内容。
• 检查所有集成内容是否存在潜在漏洞和 易受攻击的依赖项。
• 在开发期间始终使用最新支持的 Python 版本 (Python 3.11)。

操作

名称

操作的名称 应指向正在执行的 activity；例如，Get Case Details 、List Entity Events 或 Execute Search 。

如果操作主要用于处理实体，则 最好在名称中添加Entity；例如， Enrich Entities。

操作名称应以 2-3 个字词表达。

说明

操作的说明 应向用户突出显示执行操作的结果。

如果操作使用实体，则需要附加有关支持的实体类型的信息。 例如：

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

如果操作在 Async 模式下运行，则需要在说明中提供以下 备注：

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

尽量将说明限制在 500 个字符以内。

操作参数

操作配置参数应具有直观的名称。 避免使用特殊字符，并尽量将操作参数名称限制在 2-4 个字词以内。

参数的说明应向用户解释该参数对操作执行的 影响。如果参数支持 预先确定的支持值数量，则在说明中提供以下部分： Possible Values: {value 1}, {value 2}

操作输出（脚本结果）

脚本结果应表示操作的简单结果。在 大多数情况下，它应仅指向一个名为 is_success 的变量，该变量可以取值 true 或 false。

一般来说，如果操作执行完毕并执行了操作，则 is_success 应为 true。

操作输出（JSON 结果）

JSON 结果是操作最重要的输出。在剧本 执行期间，可以访问 JSON 结果中的所有 数据。验证是否将有效的 JSON 对象推送到输出。

JSON 结果的大小上限为 15 MB。

构建 JSON 结果时，请确保没有在执行期间 唯一的键。例如，以下 JSON 对象 表示结构不佳，因为它在剧本中不可用：

{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}
    

请改为按如下方式设置格式：

[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]
   

如果您在操作中使用实体并按 实体返回结果，则最佳实践是按如下方式构建 JSON 结果：

[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]
    

始终考虑如何在 自动化操作 中使用操作的输出。

确保您的操作有 JSON 示例 。

在剧本构建过程中，平台会在表达式构建器中使用 JSON 示例 。准确的 JSON 示例可以显著提升 剧本构建体验。从 JSON 示例中移除所有 PII 信息。

操作输出（实体扩充）

如果操作在实体上执行，则在操作执行期间， 您可以向实体附加其他元数据。该元数据的结构 应遵循以下格式：{integration identifier}_{key}。例如：WebRisk_is_malicious。

您可以在实体详情页面中找到添加的元数据。

操作输出（输出消息）

输出消息应以更具描述性的方式向用户解释操作 执行情况。它应将用户指向 操作执行的结果。

如果某些实体已成功扩充，但其他实体未成功扩充，则 最佳实践是在消息中为每个提供的实体提供状态信息。

如果您认为在操作 执行期间遇到了严重错误，请确保针对这种情况提供详细消息并 使操作失败。当操作失败时，相应的剧本将停止 执行，直到手动解决或跳过该错误为止。

输出消息的一些示例：

• Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
• Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
• None of the provided entities were found in VirusTotal.
• Successfully executed query "{query}" in Google SecOps.

如果操作应失败并停止执行剧本，建议采用以下结构的输出消息：

"Error executing action "{action name}". Reason: {error}'

避免放置错误的完整回溯。相反，请尝试以自然语言将 用户指向实际问题。

连接器

名称

连接器的名称应将用户指向将要提取的数据。一般来说，名称的结构应如下所示：

• {integration display name} - {data that is being ingested} Connector
• 例如：Crowdstrike - Pull Alerts Connector

说明

连接器的说明应向用户突出显示连接器将提取的内容；例如，Pull alerts from Crowdstrike。此外，您还需要提供有关动态列表支持的信息； 例如，Dynamic List works with the display_name parameter.

在这种情况下，最终说明将如下所示：

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

尽量将说明限制在 500 个字符以内。

连接器参数

连接器配置参数应具有直观的名称。 避免使用特殊字符，并尽量将操作参数名称限制在 2-4 个字词以内。

参数的说明应向用户解释该参数对连接器执行的 影响。

如果参数支持预先确定的支持值数量， 则在说明中提供以下部分： Possible Values: {value 1}, {value 2}。应具有以下参数：

• Max Alerts To Fetch：决定在 1 个连接器迭代期间应处理多少个 {object}。
• Max {Hours/Days} Backwards：决定连接器首次迭代的开始时间。例如，如果 Max Hours Backwards 设置为 1，则连接器将开始提取一小时前的数据。
• Verify SSL：验证与 API/实例的连接。

本体映射

对于创建的每个连接器，建议提供本体 映射，以验证共同客户是否获得最佳体验。

本体映射用于自动创建实体（IOC 和 资产）。此外，系统字段（如 开始时间 和结束时间 ）的关键元数据也在其中定义。

动态列表

动态列表 是一项可选功能，可让您为提取构建 高级过滤器。您可以灵活地使用它构建任何自定义 逻辑，同时拥有独特的 UX。最常见的用例是 定义允许名单或屏蔽名单。

如果您要为动态列表构建任何自定义逻辑，请确保 在连接器的说明中提供该逻辑。此外，建议使用 将动态列表用作屏蔽名单 参数，以便 也支持反向逻辑。

作业

名称

作业的名称 应向用户解释此作业正在执行的操作。一般来说，名称的结构应如下所示：

• {integration display name} - {process} Job
• 例如：ServiceNow - Sync Incidents Job

说明

作业的说明应向用户突出显示 作业在迭代期间执行的操作；例如，This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

尽量将说明限制在 500 个字符以内。

作业参数

作业配置参数应具有直观的名称。避免 使用特殊字符，并尽量将操作参数名称限制在 2-4 个字词以内。

参数的说明应向用户解释该参数对作业执行的影响。

如果参数支持预先确定的支持值数量， 则在说明中提供以下部分：

Possible Values: {value 1}, {value 2}。

除了身份验证参数之外，所有作业都应具有以下参数：

• Max {Hours/Days} Backwards：决定作业首次迭代的开始时间。
• Verify SSL：验证与 API/实例的连接。

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