将自定义模块与 Security Health Analytics 搭配使用

仅限高级层级：此功能仅适用于 Security Command Center 高级层级。

本页面介绍了如何使用 Google Cloud 控制台或 Google Cloud CLI 创建、查看、更新和删除 Security Health Analytics 的自定义模块。

如需更多介绍性信息，请参阅 Security Health Analytics 自定义模块概览。

准备工作

您需要先满足以下前提条件，然后才能使用自定义模块：

• 您需要使用 Security Command Center 的高级层级。更多信息 有关 Security Command Center 层级的信息，请参阅 Security Command Center 激活概览。
• 必须启用 Security Health Analytics。如需了解如何启用 Security Health Analytics，请参阅启用或停用内置服务。
• 您的用户账号必须获得一个或多个可提供所需权限的 Identity and Access Management (IAM) 角色。如需了解详情，请参阅所需的 IAM 权限。
• 如果您打算编写自己的自定义模块并使用 gcloud 命令将其上传到 Security Command Center，则需要使用 Google Cloud CLI。如需详细了解如何安装 gcloud CLI，请参阅安装 gcloud CLI。
• 如果 Security Command Center API 尚未启用，则需要先启用它，然后才能使用 Security Health Analytics 的自定义模块。您可以在 Google Cloud 控制台中的 API 库页面上启用 Security Command Center API。
• 如需了解 Security Health Analytics 的用量限额，请参阅自定义模块配额。

必需的 IAM 权限

如需使用自定义模块，您需要拥有以下 Identity and Access Management (IAM) 权限：

权限	角色
securitycenter.securityhealthanalyticscustommodules.create securitycenter.securityhealthanalyticscustommodules.update securitycenter.securityhealthanalyticscustommodules.delete	roles/securitycenter.settingsEditor roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.get securitycenter.securityhealthanalyticscustommodules.list	roles/securitycenter.settingsViewer roles/securitycenter.adminViewer roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.test	roles/securitycenter.securityHealthAnalyticsCustomModulesTester roles/securitycenter.adminViewer roles/securitycenter.adminEditor roles/securitycenter.admin

如需详细了解 IAM 权限和角色 如何授予这些权限，请参阅 使用 Google Cloud 控制台授予 IAM 角色。

创建自定义模块

本部分介绍了如何使用 Google Cloud 控制台或 gcloud CLI 创建自定义模块。

如需在创建过程中测试自定义模块，您需要在 YAML 文件中准备测试资源定义。如需查看相关说明，请参阅在 YAML 文件中创建测试资源。

要创建自定义模块，请选择您要使用的方法： 以下标签页：

Google Cloud 控制台

如需在 Google Cloud 控制台中创建自定义模块，请完成以下步骤：

1. 转到 Google Cloud 控制台中的 Security Command Center 设置页面。

   转至“设置”

2. 如果出现提示，请选择需要在其中创建自定义模块的组织、文件夹或项目。

3. 在 Security Health Analytics 卡片上，点击管理设置。

4. 点击模块标签页。

5. 点击 Create module。 系统会打开 Create module for Security Health Analytics（创建 Security Health Analytics 的模块）页面。

6. 在配置模块面板上，定义显示名称、要扫描的资源以及检测逻辑：

   1. 在模块名称字段中，指定模块的名称。该名称必须介于 1 到 128 个字符之间，以小写字母开头，并且只能包含字母数字字符或下划线。此名称将成为检测器生成的发现结果的类别。模块创建后，您将无法更改其名称。

   2. 在添加资源类型下，指定要扫描的资源类型（一到五个）。您不能多次指定资源类型。

      如需查看支持的资源类型列表，请参阅支持的资源类型。

   3. 在表达式编辑器中，编写 CEL 表达式，以对您在上一步中指定的资源的一个或多个属性运行布尔值检查。如需触发发现结果，表达式必须解析为 TRUE。 例如，如果 CryptoKey 资源定义了轮替周期且轮替周期超过 2,592,000 秒（30 天），则以下表达式会触发发现结果：

      has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
      

      详情请参阅以下内容：

      • 编写 CEL 表达式
      • 在自定义模块中引用资源和政策属性
      • 标准 CEL 定义列表

   4. 点击下一步。系统会打开定义发现结果详情面板。

7. 在定义发现结果详情面板上，描述自定义模块检测到的问题，包括其严重程度、问题是什么、如何解决问题，以及您要在发现结果中添加作为自定义来源属性的任何数据：

   1. 在严重程度字段中，指定问题的严重程度。您可以指定 Low、Medium、High 或 Critical。默认值为 Medium。

      如需了解严重级别，请参阅发现结果的严重程度分类。

   2. 在发现结果说明字段中，说明自定义模块检测到的问题。此说明出现在每项发现结果中 帮助安全团队了解并解决 检测到的问题。

   3. 在发现结果后续步骤字段中，说明安全团队可以执行来修复或解决检测到的问题的步骤。

      这些步骤会随每个发现结果实例一起显示。其中包括安全团队可以执行以尽快解决问题的具体步骤。

   4. 可选：在 Custom finding properties（自定义发现结果属性）字段中，最多指定 10 个名称-值对，以定义随每个发现结果实例一起返回的自定义来源属性。该信息会作为发现结果 JSON 中的来源属性返回，并显示在 Google Cloud 控制台的发现结果详情中的来源属性标签页上。以键值对形式指定文本或属性值：

      • 在属性名称字段中，为自定义来源属性指定名称。该名称必须符合以下规则：
        • 名称必须以小写字母开头。
        • 名称只能包含字母数字字符或下划线。
        • 名称的长度必须介于 1 到 128 个字符之间。
        • 每个名称在其他来源媒体资源中必须是唯一的。
      • 在属性值字段中，指定以下值之一（不超过 1024 个字符）：
        • 用英文引号括起来的文本字符串。英文引号包含在 1024 个字符的限制内。例如："This string provides additional useful information."
        • 正在扫描的资源的任何属性。例如，如果您要检查 CryptoKey 资源， 您可以指定 resource.rotationPeriod。 rotationPeriod 属性。

   5. 点击下一步。系统会打开启用模块面板。

8. 可选：使用启用模块面板的下拉菜单指定自定义模块在创建后处于启用状态还是停用状态。默认情况下，自定义模块在创建后处于启用状态。如果您指定了停用，则稍后可以在 Security Health Analytics 设置页面的模块标签页中启用模块。

9. 点击下一步。系统会打开测试模块面板。

10. 可选：在创建自定义模块之前，我们建议您先对其进行测试。

    如需测试自定义模块，请按照以下步骤操作：

    1. 创建一个 YAML 文件，其中包含自定义模块检查的资源的测试资源定义。

       如需了解如何创建测试数据文件，请参阅在 YAML 文件中创建测试资源。

    2. 在上传 YAML 文件下，点击浏览以上传 YAML 包含测试资源定义的文件上传该文件后，测试会自动开始。

    3. 在测试结果预览下，查看结果。

       • 如果 YAML 文件中存在语法或其他错误，则浏览器页面底部附近会显示浮动错误消息。

       • 如果测试成功，则测试会返回以下信息：

         • 自定义模块的显示名称。
         • 您在 resource 属性中指定的任意名称 测试数据文件中
         • 在其中已创建或将创建自定义模块的组织、文件夹或项目。

    测试结果不会存储或写入到 Security Command Center。

    如需了解详情，请参阅测试自定义模块。

11. 点击创建。您会返回到模块页面，并且应该会看到自己创建的模块，其状态为已启用。

新自定义模块并非立即可供以下人员使用： 扫描中的 Security Health Analytics。如需了解详情，请参阅检查延迟时间。

gcloud CLI

如需使用 gcloud 命令创建自定义模块，您首先需要执行以下操作： 将自定义模块的定义编码到 YAML 文件中，该文件包含 用于检测逻辑和输出属性的 CEL 表达式。

完成定义后，您可以使用 gcloud CLI 命令将定义上传到 Security Command Center。

1. 按照对 Security Health Analytics 的自定义模块进行编码中的说明，在 YAML 文件中对自定义模块定义进行编码。
2. 将 YAML 文件保存到您的 gcloud CLI 实例可访问的位置。

3. 将自定义设置上传到 Security Command Center：

   gcloud scc custom-modules sha create \
       PARENT_FLAG=PARENT_ID \
       --display-name="MODULE_DISPLAY_NAME" \
       --enablement-state="ENABLEMENT_STATE" \
       --custom-config-from-file=MODULE_FILE_NAME.yaml
   

   请替换以下内容：

   • PARENT_FLAG：创建自定义模块所在的级别，可以是 --organization、--folder 或 --project。
   • PARENT_ID：您要在其中创建自定义模块的组织、文件夹或项目的 ID。
   • ENABLEMENT_STATE：enabled 或 disabled。
   • MODULE_DISPLAY_NAME：发现结果类别 您想在自定义模块返回发现结果时显示的名称。 该名称必须介于 1 到 128 个字符之间，以小写字母开头，并且只能包含字母数字字符或下划线。
   • MODULE_FILE_NAME：包含自定义模块定义的 YAML 文件的路径和文件名。

检查延迟时间

创建或更新自定义模块的定义后，新的或更新后的自定义模块最多可能要延迟几个小时才能用于扫描。

创建或修改自定义模块不会触发扫描。 自定义模块可供使用后，直到首次进行批量扫描或对目标资源的配置的更改触发实时扫描时，Security Health Analytics 才会开始使用该自定义模块。

如需详细了解 Security Health Analytics 扫描类型，请参阅 Security Health Analytics 扫描类型。

更新自定义模块

您可以更新 Security Health Analytics 自定义 模块。

自定义模块的以下属性无法更改：

• 显示名称。
• 自定义模块 ID。
• 自定义模块的完整资源名称。

更新自定义模块时，该自定义模块发出的所有发现结果 不会同时更新。如果对模块的更改使发出的发现结果发生更改，则只有在下一次 Security Health Analytics 批量或实时扫描后，发现结果才会反映这些更改。

如需修改自定义模块，您可以使用 Google Cloud 控制台 或 gcloud CLI。如需查看相关说明，请点击以下标签页之一。

Google Cloud 控制台

如需在 Google Cloud 控制台中更新现有自定义模块，请按照以下步骤操作：

1. 转到 Google Cloud 控制台中的 Security Command Center 设置页面。

   转至“设置”

2. 在项目选择器中，选择最初在其中创建自定义模块的组织、文件夹或项目。您无法在任何其他位置修改自定义模块。

3. 在 Security Health Analytics 卡片上，点击管理设置。

4. 选择模块标签页。系统会显示所有 Security Health Analytics 检测模块。

5. 使用模块列表顶部的过滤条件字段或通过滚动找到您需要修改的自定义模块。

6. 在自定义模块所在行右侧，点击操作菜单图标 。

7. 在操作菜单中，点击修改图标 ()。系统会打开查看模块页面，并显示配置模块标签页。

8. 在查看模块上修改每个标签页的自定义模块字段 页面。

9. 可选：在保存更新之前，我们建议您先对其进行测试。

   如需测试自定义模块，请按照以下步骤操作：

   1. 创建一个 YAML 文件，其中包含自定义模块检查的资源的测试资源定义。

      如需了解如何创建测试数据文件，请参阅在 YAML 文件中创建测试资源。

   2. 在上传 YAML 文件下，点击浏览以上传 YAML 包含测试资源定义的文件上传该文件后，测试会自动开始。

   3. 在测试结果预览下，查看结果。

      • 如果 YAML 文件中存在语法或其他错误，则浏览器页面底部附近会显示浮动错误消息。

      • 如果测试成功，则测试会返回以下信息：

        • 自定义模块的显示名称。
        • 您在 resource 属性中指定的任意名称 测试数据文件中
        • 在其中已创建或将创建自定义模块的组织、文件夹或项目。

   测试结果不会存储或写入到 Security Command Center。

   如需了解详情，请参阅测试自定义模块。

10. 点击页面底部的保存。 您的更改会应用于自定义模块。

gcloud CLI

如需使用 gcloud CLI 更新自定义模块，请先修改自定义模块的 YAML 定义，然后使用 gcloud 命令在 Security Health Analytics 中更新自定义模块。

1. 修改自定义模块定义。有关如何编写代码的信息 自定义模块定义，请参见 为 Security Health Analytics 编码自定义模块。

2. 将修改后的 YAML 文件保存到 gcloud CLI 可访问的位置。

3. 通过发出以下命令在 Security Health Analytics 中更新自定义模块：

   gcloud scc custom-modules sha update MODULE_ID \
      PARENT_FLAG=PARENT_ID \
      --enablement-state="ENABLED" \
      --custom-config-from-file=MODULE_FILE_NAME.yaml
   

   请替换以下内容：

   • MODULE_ID：ID 或完整资源名称 自定义模块
   • PARENT_FLAG：创建自定义模块所在的级别，可以是 --organization、--folder 或 --project。
   • PARENT_ID：创建自定义模块的组织、文件夹或项目的 ID。
   • MODULE_FILE_NAME： 包含自定义模块定义的 YAML 文件。

查看自定义模块

选择一个标签页，了解如何查看自定义模块定义。

Google Cloud 控制台

如需在 Google Cloud 控制台中查看自定义模块，请按照以下步骤操作：

1. 进入 Security Command Center 设置中的 Security Health Analytics 页面。

   转至“设置”

2. 点击模块标签页。 系统会打开模块面板。

3. 如有必要，请使用模块列表顶部的过滤条件字段找到您需要修改的自定义模块。

4. 要查看自定义模块定义的详细信息，请点击操作 菜单图标 ，位于右侧 。

5. 在操作菜单中，点击修改图标 。系统会打开查看模块页面，并显示配置模块标签页。

6. 点击浏览查看模块页上的各个标签，查看所有 字段。

gcloud CLI

如需查看自定义模块的详细信息，请输入以下命令：

gcloud scc custom-modules sha get MODULE_ID \
      PARENT_FLAG=PARENT_ID

请替换以下内容：

• MODULE_ID：ID 或完整资源名称 自定义模块
• PARENT_FLAG：创建自定义模块所在的级别，可以是 --organization、--folder 或 --project。
• PARENT_ID：创建自定义模块的组织、文件夹或项目的 ID。

列出自定义模块

选择一个标签页，了解如何显示自定义模块列表。

Google Cloud 控制台

1. 进入 Security Command Center 设置中的 Security Health Analytics 页面。

   转至“设置”

2. 点击模块标签页。 系统会打开模块面板。

3. 点击要显示的模块列表顶部的过滤条件字段 过滤器类型列表

4. 选择类型，然后输入 Custom。该模块列表会更新，仅显示自定义模块。

gcloud CLI

要查看自定义模块列表，请输入 以下命令：

gcloud scc custom-modules sha list \
    PARENT_FLAG=PARENT_ID

请替换以下内容：

• PARENT_FLAG：创建自定义模块所在的级别，可以是 --organization、--folder 或 --project。
• PARENT_ID：组织、文件夹、 或在其中创建自定义模块的项目中

删除自定义模块

您可以将自定义模块从在其中创建该模块的组织、文件夹或项目或者父级组织或文件夹中删除。您无法从继承自定义模块的文件夹或项目中删除该模块。

注意：已删除的模块无法恢复。

如需了解如何删除自定义模块，请选择以下某个标签页。

Google Cloud 控制台

1. 转到 Google Cloud 控制台中的 Security Command Center 设置页面。

   转至“设置”

2. 如果系统提示，请选择您的组织、文件夹或项目。

3. 在 Security Health Analytics 卡片上，点击管理设置。

4. 选择模块标签页。系统会显示所有 Security Health Analytics 检测模块。

5. 使用模块列表顶部的过滤条件字段或通过滚动找到您需要修改的自定义模块。

6. 在自定义模块所在行右侧，点击操作菜单图标 。

7. 在操作菜单中，点击删除。系统会打开 Delete custom module（删除自定义模块）对话框。

8. 在该对话框中，点击删除。

gcloud CLI

如需删除自定义模块，请输入以下命令：

gcloud scc custom-modules sha delete MODULE_ID \
    PARENT_FLAG=PARENT_ID

请替换以下内容：

• MODULE_ID：ID 或完整资源名称 自定义模块
• PARENT_FLAG：创建自定义模块所在的级别，可以是 --organization、--folder 或 --project。
• PARENT_ID：创建自定义模块的组织、文件夹或项目的 ID。

已删除的自定义模块的发现结果将在下一次批量扫描时被 Security Health Analytics 标记为无效。

审核发现结果

您可以在 Google Cloud 控制台、Security Operations 控制台（适用于企业版客户）或 Security Command Center API 中查看自定义模块生成的发现结果。

控制台

Google Cloud 控制台

1. 在 Google Cloud 控制台中，前往 Security Command Center 的发现结果页面。

   前往“发现结果”页面

2. 选择您的 Google Cloud 项目或组织。
3. 在快速过滤条件部分的来源显示名称子部分中，选择 Security Health Analytics Custom。发现结果查询结果会更新，以仅显示 来自此来源的发现结果。
4. 如需查看特定发现结果的详细信息，请点击类别下的发现结果名称。系统会打开发现结果的详细信息面板，并显示摘要标签页。
5. 在摘要标签页上，查看发现结果的详细信息，包括有关检测到的内容、受影响的资源的信息，以及您可以采取的发现结果修复步骤（如果有）。
6. 可选：如需查看发现结果的完整 JSON 定义，请点击 JSON 标签页。

Security Operations 控制台

仅限企业版：此功能仅适用于 Security Command Center 企业版。

1. 在 Security Operations 控制台中，转到发现结果页面。

   https://CUSTOMER_SUBDOMAIN.backstory.chronicle.security/posture/findings
   

   将 CUSTOMER_SUBDOMAIN 替换为您的客户专用标识符。

2. 在 Aggregations 部分中，点击以展开 Source Display Name 小节。
3. 选择 Security Health Analytics Custom。发现结果的查询结果会更新为仅显示此来源的发现结果。
4. 如需查看特定发现结果的详细信息，请点击类别下的发现结果名称。系统会打开发现结果的详细信息面板，并显示摘要标签页。
5. 在摘要标签页上，查看发现结果的详细信息，包括有关检测到的内容、受影响的资源的信息，以及您可以采取的发现结果修复步骤（如果有）。
6. 可选：如需查看发现结果的完整 JSON 定义，请点击 JSON 标签页。

gcloud CLI

如需查看发现结果，请执行以下操作：

1. 打开一个终端窗口。

2. 如需获取 Security Health Analytics 的来源 ID，请运行 以下命令：

   gcloud scc sources describe organizations/ORGANIZATION_ID \
   --source-display-name='Security Health Analytics Custom'
   

   显示的输出应类似于以下内容：在本示例中， SOURCE_ID 是由服务器分配的 ID，用于确保安全性 来源。

   description: ...
   displayName: Security Health Analytics Custom
   name: organizations/ORGANIZATION_ID/sources/SOURCE_ID
   

3. 如需列出自定义模块生成的所有发现结果，请运行以下命令：

   gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID
   

4. 如需列出某个特定自定义模块的发现结果，请运行以下命令：

   gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID --filter="category=\"MODULE_NAME\""
   

后续步骤

您可以像管理 Security Command Center 中的所有发现结果一样管理自定义模块生成的发现结果。如需查看相关说明，请参阅以下信息：

• 在 Google Cloud 控制台中处理发现结果
• 使用安全标记
• 设置发现结果通知
• 导出 Security Command Center 数据