Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用安全狀態分析自訂模組

本頁面說明如何使用 Google Cloud 控制台或 Google Cloud CLI，建立、查看、更新及刪除「安全狀態分析」的自訂模組。

如需更多簡介資訊，請參閱「Security Health Analytics 自訂模組總覽」。

事前準備

您必須先完成下列前置作業，才能使用自訂模組：

必須啟用安全狀態分析。如要瞭解如何啟用「安全狀態分析」，請參閱「啟用或停用內建服務」。
您的使用者帳戶必須具備一或多個 Identity and Access Management (IAM) 角色，且這些角色包含必要權限。詳情請參閱「必要的 IAM 權限」。
如果您打算自行編寫自訂模組，並使用 gcloud 指令上傳至 Security Command Center，則需要 Google Cloud CLI。如要瞭解如何安裝 gcloud CLI，請參閱「安裝 gcloud CLI」。
如果尚未啟用 Security Command Center API，請先啟用，才能使用安全狀態分析的自訂模組。您可以在 Google Cloud 控制台的 API 程式庫頁面啟用 Security Command Center API。
如要瞭解安全狀態分析的用量限制，請參閱「自訂模組配額」。

必要 IAM 權限

如要使用自訂模組，您必須具備下列 Identity and Access Management (IAM) 權限：

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

如要進一步瞭解 IAM 權限和角色，以及如何授予這些權限和角色，請參閱「使用 Google Cloud 控制台授予 IAM 角色」。

建立自訂模組

本節說明如何使用Google Cloud 控制台、gcloud CLI 或 Terraform 建立自訂模組。

如要在建立過程中測試自訂模組，您必須在 YAML 檔案中準備測試資源定義。如需操作說明，請參閱「在 YAML 檔案中建立測試資源」。

如要建立自訂模組，請從下列分頁中選取要使用的方法：

Google Cloud 控制台

如要在 Google Cloud 控制台建立自訂模組，請完成下列步驟：

前往Google Cloud 控制台的 Security Command Center「Settings」(設定) 頁面。

前往設定頁面
如果出現提示，請選取要建立自訂模組的組織、資料夾或專案。
在「安全狀態分析」資訊卡中，按一下「Manage Settings」(管理設定)。
按一下「模組」分頁標籤。
按一下「建立模組」。「Create module for Security Health Analytics」(建立安全狀態分析模組) 頁面隨即開啟。
在「Configure module」(設定模組) 面板中，定義顯示名稱、要掃描的資源和偵測邏輯：
1. 在「Module name」欄位中指定模組名稱。名稱長度必須介於 1 至 128 個半形字元之間，開頭必須為小寫英文字母，而且只能使用英數字元或底線。這個名稱會成為偵測工具產生的發現項目類別。模組建立後即無法變更名稱。
2. 在「Add resource type」(新增資源類型) 下方，指定一到五個要掃描的資源類型。您無法多次指定資源類型。
  
  如需支援的資源類型清單，請參閱「支援的資源類型」。
3. 在「Expression editor」(運算式編輯器) 中，編寫 CEL 運算式，對上一步指定的資源一或多項屬性執行布林值檢查。運算式必須解析為 TRUE，才會觸發發現項目。舉例來說，如果 CryptoKey 資源已定義輪替週期，且輪替週期超過 2,592,000 秒 (30 天)，下列運算式就會觸發發現項目：
```
has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
```
  如要瞭解詳情，請參考下列資源：
4. 點選「下一步」。「Define finding details」(定義發現項目詳細資料) 面板隨即開啟。
在「Define finding details」(定義發現項目詳細資料) 面板中，說明自訂模組偵測到的問題，包括嚴重程度、問題內容、修正方式，以及要納入發現項目的任何資料 (做為自訂來源屬性)：
1. 在「Severity」(嚴重性) 欄位中，指定問題的嚴重性。您可以指定 Low、Medium、High 或 Critical。Medium 是預設值。
  
  如要瞭解嚴重性等級，請參閱「發現項目的嚴重性分類」。
2. 在「Finding description」(發現項目說明) 欄位中，說明自訂模組偵測到的問題。這項說明會顯示在每個發現項目例項中，協助資安團隊瞭解及解決偵測到的問題。
3. 在「Finding next steps」(發現項目後續步驟) 欄位中，說明安全團隊可採取的步驟，以修正或處理偵測到的問題。
  
  每個發現項目例項都會顯示步驟。請列出資安團隊可採取的具體步驟，盡快解決問題。
4. 選用：在「Custom finding properties」(自訂發現項目屬性) 欄位中，最多可指定 10 個名稱/值組合，定義要與每個發現項目執行個體一併傳回的自訂來源屬性。這項資訊會以發現項目 JSON 中的來源屬性形式傳回，並顯示在Google Cloud 控制台發現項目詳細資料的「Source properties」(來源屬性) 分頁中。以鍵/值組合的形式指定文字或屬性值：
  - 在「Property name」(屬性名稱) 欄位中，指定自訂來源屬性的名稱。名稱必須符合下列規則：
    - 名稱開頭須為小寫英文字母。
    - 名稱只能使用英數字元或底線。
    - 名稱長度必須介於 1 至 128 個字元之間。
    - 每個名稱在其他來源資源中不得重複。
  - 在「Property value」(屬性值) 欄位中，指定下列其中一個值，長度不得超過 1024 個字元：
    - 以引號括住的文字字串。引號也計入 1024 個字元的限制。例如： "This string provides additional useful information."
    - 掃描中資源的任何屬性。舉例來說，如果您要檢查 CryptoKey 資源，可以指定 resource.rotationPeriod。系統會傳回 rotationPeriod 屬性的值。
5. 點選「下一步」。「Enable module」(啟用模組) 面板隨即開啟。
選用：使用「Enable module」(啟用模組) 面板的下拉式選單，指定是否要在建立時啟用或停用自訂模組。根據預設，自訂模組建立後會自動啟用。如果指定「Disable」(停用)，日後可以在「安全狀態分析」設定頁面的「Modules」(模組) 分頁啟用模組。
點選「下一步」。「Test module」(測試模組) 面板隨即開啟。
選用：建議您先測試自訂模組，再建立模組。

如要測試自訂模組，請按照下列步驟操作：
1. 建立 YAML 檔案，其中包含自訂模組檢查資源的測試資源定義。
  
  如要瞭解如何建立測試資料檔案，請參閱「在 YAML 檔案中建立測試資源」。
2. 在「Upload the YAML file」(上傳 YAML 檔案) 下方，按一下「Browse」(瀏覽)，上傳含有測試資源定義的 YAML 檔案。檔案上傳後，測試會自動啟動。
3. 在「測試結果預覽」下方查看結果。
  - 如果 YAML 檔案有語法或其他錯誤，瀏覽器頁面底部附近會顯示浮動錯誤訊息。
  - 如果測試成功，系統會傳回下列資訊：
    - 自訂模組的顯示名稱。
    - 您在測試資料檔案的 resource 屬性中指定的任意名稱。
    - 已建立或將建立自訂模組的組織、資料夾或專案。
測試結果不會儲存或寫入 Security Command Center。

詳情請參閱「測試自訂模組」。
點選「建立」。系統會將您導回「Modules」(模組) 頁面，您應該會看到建立的模組，狀態為「Enabled」(已啟用)。

新的自訂模組不會立即用於 Security Health Analytics 掃描。詳情請參閱「偵測延遲時間」。

gcloud CLI

如要使用 gcloud 指令建立自訂模組，您必須先在 YAML 檔案中編寫自訂模組的定義，其中包含偵測邏輯和輸出屬性的 CEL 運算式。

定義完成後，請使用 gcloud CLI 指令將定義上傳至 Security Command Center。

按照「編寫安全狀態分析自訂模組」中的操作說明，在 YAML 檔案中編寫自訂模組定義。
將 YAML 檔案儲存至 gcloud CLI 執行個體可存取的位置。
將自訂定義上傳至 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 檔案的路徑和檔案名稱，其中包含自訂模組的定義。

Terraform

為組織建立自訂模組：

resource "google_scc_management_organization_security_health_analytics_custom_module" "example" {
  organization = "123456789"
  display_name = "basic_custom_module"
  location = "global"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

為資料夾建立自訂模組：

resource "google_folder" "folder" {
  parent       = "organizations/123456789"
  display_name = "folder-name"
  deletion_protection = false
}

resource "google_scc_management_folder_security_health_analytics_custom_module" "example" {
  folder = google_folder.folder.folder_id
  location = "global"
  display_name = "basic_custom_module"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

為專案建立自訂模組：

resource "google_scc_management_project_security_health_analytics_custom_module" "example" {
  location = "global"
  display_name = "basic_custom_module"
  enablement_state = "ENABLED"
  custom_config {
    predicate {
      expression = "resource.rotationPeriod > duration(\"2592000s\")"
    }
    resource_selector {
      resource_types = [
        "cloudkms.googleapis.com/CryptoKey",
      ]
    }
    description = "The rotation period of the identified cryptokey resource exceeds 30 days."
    recommendation = "Set the rotation period to at most 30 days."
    severity = "MEDIUM"
  }
}

偵測延遲時間

建立或更新自訂模組的定義後，可能需要等待幾小時，才能在掃描中使用新的或更新後的自訂模組。

建立或修改自訂模組不會觸發掃描。自訂模組可供使用後，安全狀態分析不會立即開始使用，而是等到第一次批次掃描，或目標資源設定變更觸發即時掃描時，才會開始使用。

如要進一步瞭解安全狀態分析掃描類型，請參閱「安全狀態分析掃描類型」。

更新自訂模組

您可以更新安全狀態分析自訂模組的大部分屬性。

自訂模組的下列屬性無法變更：

顯示名稱。
自訂模組 ID。
自訂模組的完整資源名稱。

更新自訂模組時，自訂模組先前產生的發現項目不會同時更新。如果模組變更導致產生的發現項目有所變更，則只有在下次安全狀態分析批次或即時掃描後，發現項目才會反映變更。

如要修改自訂模組，可以使用 Google Cloud 控制台或 gcloud CLI。按一下下列其中一個分頁標籤，查看操作說明。

Google Cloud 控制台

如要在 Google Cloud 控制台更新現有的自訂模組，請按照下列步驟操作：

前往Google Cloud 控制台的 Security Command Center「Settings」(設定) 頁面。

前往設定頁面
在專案選取器中，選取原先建立自訂模組的組織、資料夾或專案。您無法在其他地方編輯自訂模組。
在「安全狀態分析」資訊卡中，按一下「Manage Settings」(管理設定)。
選取「模組」分頁標籤。系統會顯示所有安全狀態分析偵測模組。
使用模組清單頂端的篩選器欄位，或捲動畫面找出要修改的自訂模組。
在自訂模組列的右側，按一下「Action menu」(動作選單) 圖示。
在「Action menu」(動作選單) 中，按一下「Edit」(編輯) 圖示 ()。「View module」(查看模組) 頁面隨即開啟，並顯示「Configure module」(設定模組) 分頁。
視需要編輯「View module」(查看模組) 頁面上每個分頁的自訂模組欄位。
選用：建議您先測試更新，再儲存。

如要測試自訂模組，請按照下列步驟操作：
1. 建立 YAML 檔案，其中包含自訂模組檢查資源的測試資源定義。
  
  如要瞭解如何建立測試資料檔案，請參閱「在 YAML 檔案中建立測試資源」。
2. 在「Upload the YAML file」(上傳 YAML 檔案) 下方，按一下「Browse」(瀏覽)，上傳含有測試資源定義的 YAML 檔案。檔案上傳後，測試會自動啟動。
3. 在「測試結果預覽」下方查看結果。
  - 如果 YAML 檔案有語法或其他錯誤，瀏覽器頁面底部附近會顯示浮動錯誤訊息。
  - 如果測試成功，系統會傳回下列資訊：
    - 自訂模組的顯示名稱。
    - 您在測試資料檔案的 resource 屬性中指定的任意名稱。
    - 已建立或將建立自訂模組的組織、資料夾或專案。
測試結果不會儲存或寫入 Security Command Center。

詳情請參閱「測試自訂模組」。
按一下頁面底部的「儲存」。變更會套用至自訂模組。

gcloud CLI

如要使用 gcloud CLI 更新自訂模組，請先編輯自訂模組的 YAML 定義，然後使用 gcloud 指令，在安全狀態分析中更新自訂模組。

編輯自訂模組定義。如要瞭解如何編寫自訂模組定義，請參閱「編寫安全狀態分析自訂模組」。
將編輯後的 YAML 檔案儲存至 gcloud CLI 可存取的位置。
發出下列指令，更新安全狀態分析中的自訂模組：
```
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 控制台查看自訂模組，請按照下列步驟操作：

前往 Security Command Center 設定的「Security Health Analytics」(安全狀態分析) 頁面。

前往設定頁面
按一下「模組」分頁標籤。「Modules」(模組) 面板隨即開啟。
如有需要，請使用模組清單頂端的篩選器欄位，找出要修改的自訂模組。
如要查看自訂模組定義的詳細資料，請按一下自訂模組列右側的「Action menu」(動作選單) 圖示。
在「動作選單」中，按一下「編輯」圖示。「View module」(查看模組) 頁面隨即開啟，並顯示「Configure module」(設定模組) 分頁。
按一下「View module」(查看模組) 頁面上的分頁標籤，查看自訂模組定義的所有欄位。

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 控制台

前往 Security Command Center 設定的「Security Health Analytics」(安全狀態分析) 頁面。

前往設定頁面
按一下「模組」分頁標籤。「Modules」(模組) 面板隨即開啟。
按一下模組清單頂端的篩選器欄位，即可顯示篩選器類型清單。
選取「類型」，然後輸入 Custom。模組清單會更新，只顯示自訂模組。

gcloud CLI

如要查看自訂模組清單，請輸入下列指令：

gcloud scc custom-modules sha list \
    PARENT_FLAG=PARENT_ID

更改下列內容：

PARENT_FLAG：建立自訂模組的層級，可以是 --organization、--folder 或 --project。
PARENT_ID：建立自訂模組的組織、資料夾或專案 ID。

刪除自訂模組

您可以從建立自訂模組的組織、資料夾或專案，或上層組織或資料夾中刪除自訂模組。您無法從繼承自訂模組的資料夾或專案中刪除該模組。

如要瞭解如何刪除自訂模組，請選取下列其中一個分頁標籤。

Google Cloud 控制台

前往Google Cloud 控制台的 Security Command Center「Settings」(設定) 頁面。

前往設定頁面
系統顯示提示時，請選取組織、資料夾或專案。
在「安全狀態分析」資訊卡中，按一下「Manage Settings」(管理設定)。
選取「模組」分頁標籤。系統會顯示所有安全狀態分析偵測模組。
使用模組清單頂端的篩選器欄位，或捲動畫面找出要修改的自訂模組。
在自訂模組列的右側，按一下「Action menu」(動作選單) 圖示。
在「動作」選單中，按一下「刪除」。「Delete custom module」(刪除自訂模組) 對話方塊隨即開啟。
在對話方塊中，按一下「刪除」。

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。

在下次批次掃描中，安全狀態分析會將已刪除自訂模組的發現項目標示為無效。

查看結果

您可以在Google Cloud 控制台或 Security Command Center API 中，查看自訂模組產生的發現項目。

控制台

前往 Google Cloud 控制台的 Security Command Center「發現項目」頁面。

前往「發現項目」
選取 Google Cloud 專案或組織。
在「快速篩選器」部分的「來源顯示名稱」子區段中，選取「Security Health Analytics Custom」。發現項目查詢結果會更新，只顯示這個來源的發現項目。
如要查看特定發現項目的詳細資料，請按一下「Category」(類別) 欄中的發現項目名稱。系統會開啟發現項目的詳細資料面板，並顯示「摘要」分頁。
在「摘要」分頁中，查看發現項目的詳細資料，包括偵測到的內容、受影響的資源，以及可採取的修復步驟 (如有)。
選用：如要查看發現項目的完整 JSON 定義，請按一下「JSON」分頁標籤。

gcloud CLI

如要查看發現項目，請按照下列步驟操作：

開啟終端機視窗。

如要取得安全狀態分析的來源 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

如要列出自訂模組產生的所有發現項目，請執行下列指令：
```
gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID
```

如要列出特定自訂模組的發現項目，請執行下列指令：

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

後續步驟

您可以管理自訂模組產生的發現項目，就像管理 Security Command Center 中的所有發現項目一樣。如需操作說明，請參閱下列資訊：

使用安全狀態分析自訂模組 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要 IAM 權限

建立自訂模組

Google Cloud 控制台

gcloud CLI

Terraform

偵測延遲時間

更新自訂模組

Google Cloud 控制台

gcloud CLI

查看自訂模組

Google Cloud 控制台

gcloud CLI

列出自訂模組

Google Cloud 控制台

gcloud CLI

刪除自訂模組

Google Cloud 控制台

gcloud CLI

查看結果

控制台

gcloud CLI

後續步驟

使用安全狀態分析自訂模組