将自定义模块与 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 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. 选择 Modules 标签页。系统会显示所有 Security Health Analytics 检测模块。

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

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

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

8. 根据需要修改 View module 页面上每个标签页的自定义模块字段。

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：在其中创建自定义模块的组织、文件夹或项目的 ID。

删除自定义模块

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

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

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

Google Cloud 控制台

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

   转至“设置”

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

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

4. 选择 Modules 标签页。系统会显示所有 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 Command Center API 中查看自定义模块生成的发现结果。

Google Cloud 控制台

您可以在 Google Cloud 控制台中查看自定义模块生成的发现结果以及其他 Security Command Center 发现结果。

如需查看发现结果，请按以下步骤操作：

1. 进入 Google Cloud 控制台中的发现结果页面。

   转至“发现结果”

2. 如果出现提示，请选择您的组织。

3. 在快速过滤器面板中，向下滚动到来源显示名称部分，然后点击 Security Health Analytics 自定义。发现结果的查询结果面板会更新，仅显示来自 Security Health Analytics 自定义模块的发现结果。

   如果您没有看到 Security Health Analytics 自定义，则表示没有自定义模块返回任何发现结果。

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 数据