Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

贡献社区响应集成

支持范围：

Google SecOps SOAR

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

响应集成元数据

名称

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

显示名称应包含空格，例如 Vertex AI，而不是 VertexAI。

集成标识符

集成标识符是集成的唯一标识符。集成创建后，此值便无法更改。该标识符的值应与 Name 相同，但去掉了空格。

该标识符在平台上的大多数位置都可用。

说明

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

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

避免在说明中添加网址。

徽标

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

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

回答 > 集成设置
自动化 > Playbook > Playbook 设计器
案例 > 提醒 > 提醒 Playbook 视图

以下是符合我们样式指南的 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}
如果向操作添加了预定义 widget：{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)。

操作

名称

操作的名称应指向正在执行的活动，例如获取案例详情、列出实体事件或执行搜索。

如果操作主要用于处理实体，则最好在名称中添加 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.

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

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 结果是操作最重要的输出。在 playbook 执行期间，可以访问 JSON 结果中提供的所有数据。验证是否正在将有效的 JSON 对象推送到输出。

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

构建 JSON 结果时，请确保在执行期间不会有任何键是唯一的。例如，以下 JSON 对象表示一个不佳的结构，因为它在 playbook 中无法使用：


{
   "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 示例。

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

操作输出（实体丰富）

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

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

操作输出（输出消息）

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

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

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

输出消息的一些示例：

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.

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

"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：指定连接器首次迭代的开始时间。例如，如果最长回溯小时数设置为 1，则连接器将从一小时前开始拉取数据。
验证 SSL：验证与 API/实例的连接。

本体映射

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

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

动态列表

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

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

作业

名称

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

{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：指定作业首次迭代的开始时间。
验证 SSL：验证与 API/实例的连接。