此页面由 Cloud Translation API 翻译。

响应集成社区贡献指南

支持的平台：

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 连接。即使您的集成没有其他操作，也必须执行此操作。每当用户在集成配置中按 Test 按钮时，系统都应显示准确的连接状态。

版本说明

发布说明的一般结构应遵循以下格式：

{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.
如果预定义 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；例如，“获取支持请求详情”“列出实体事件”或“执行搜索”。

如果操作主要用于处理实体，则最好在名称中添加 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 结果是操作最重要的输出。在 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 示例。

在剧本构建过程中，平台会在表达式构建器中使用 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}。应具有以下参数：

要提取的提醒数量上限：用于指定在 1 次连接器迭代期间应处理多少个 {object}。
向后最大 {小时数/天数}：决定连接器首次迭代的开始时间。例如，如果将最长回溯小时数设置为 1，连接器将开始提取 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}。

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

最长回溯时间（小时/天）：决定作业首次迭代的开始时间。
验证 SSL：验证与 API/实例的连接。