為 Security Health Analytics 編寫自訂模組

本頁說明如何使用一般運算語言 (CEL) 和 YAML，編寫自訂模組定義。

使用 Google Cloud CLI 將自訂模組定義上傳至 Security Health Analytics。

在 YAML 檔案中，自訂模組定義包含一組結構化屬性，可用於定義安全性狀態分析自訂模組的下列元素：

• 要掃描的資源。
• 要使用的偵測邏輯。
• 提供給安全團隊的資訊，方便他們快速瞭解、分類及解決偵測到的問題。

如要瞭解構成 YAML 定義的必要和選用屬性，請參閱「編碼步驟」。

避免建立多餘的偵測器

如要控管尋找音量，請避免建立及執行含有多餘功能的模組。

舉例來說，如果您建立自訂模組，檢查加密金鑰是否超過 30 天未輪替，請考慮停用內建的 Security Health Analytics 偵測器 KMS_KEY_NOT_ROTATED，因為該偵測器會使用 90 天的值進行檢查，因此會多餘。

如要進一步瞭解如何停用偵測器，請參閱「啟用及停用偵測器」。

編碼步驟

您可將 Security Health Analytics 的自訂模組定義編碼為一系列 YAML 屬性，其中部分屬性包含 CEL 運算式。

如要編寫自訂定義模組，請按照下列步驟操作：

1. 建立副檔名為 yaml 的文字檔案。

2. 在文字檔案中建立 resource_selector 屬性，並指定自訂模組要掃描的一到五種資源類型。自訂模組定義中，資源類型只能指定一次。例如：

   resource_selector:
    resource_types:
    ‐ cloudkms.googleapis.com/CryptoKey

   您指定的資源類型必須受到 Security Command Center 支援。如需支援的資源類型清單，請參閱「支援的資源類型」。

3. 建立 predicate 屬性，並指定一或多個 CEL 運算式，檢查要掃描的資源類型屬性。您在 CEL 運算式中參照的任何屬性，都必須存在於 resource_selector 下指定的每個資源類型Google Cloud API 定義中。如要觸發發現結果，運算式必須解析為 TRUE。舉例來說，在下列運算式中，只有大於 2592000s 的 rotationPeriod 值會觸發發現項目。

   predicate:
    expression: resource.rotationPeriod > duration("2592000s")

   如需編寫 CEL 運算式的相關說明，請參閱下列資源：

   • 支援的資源類型。 按一下各項資源，即可查看可在 CEL 運算式中使用的屬性。
   • 編寫 CEL 運算式。
   • 在自訂模組中參照資源和政策屬性。

4. 建立 description 屬性，說明自訂模組偵測到的安全漏洞或錯誤設定。這項說明會顯示在每個發現例項中，協助調查人員瞭解偵測到的問題。文字必須加上引號。 例如：

   description: "The rotation period of
    the identified cryptokey resource exceeds 30 days, the
    maximum rotation period that our security guidelines allow."

5. 建立 recommendation 屬性，說明如何修正偵測到的問題。gcloud CLI 需要在特定字元 (例如引號) 前加上逸出字元。以下範例顯示如何使用反斜線逸出每組引號：

   recommendation: "To fix this issue go to
     https://console.cloud.google.com/security/kms. Click the key-ring that
     contains the key. Click the key. Click \"Edit rotation period\". Then
     set the rotation period to at most 30 days."
   

   如果您使用Google Cloud 控制台建立或更新自訂模組，則不需要逸出字元。

6. 建立 severity 屬性，並指定這個模組建立的發現項目預設嚴重程度。severity 屬性的常用值為 LOW、MEDIUM、HIGH 和 CRITICAL。例如，假設使用者要求系統 將文字從英文翻譯成法文

   severity: MEDIUM

7. 您可以選擇建立 custom_output 屬性，並指定要隨每項發現事項傳回的其他資訊。以一或多個名稱/值組合的形式，指定要傳回的資訊。您可以傳回掃描資源的屬性值或字串常值。屬性必須指定為 resource.PROPERTY_NAME。字串常值必須加上引號。以下範例顯示 custom_output 定義，會傳回屬性值 (掃描的 CryptoKey 資源中 rotationPeriod 的值) 和文字字串 "Excessive rotation period for CryptoKey"：

    custom_output:
      properties:
        - name: duration
          value_expression:
            expression: resource.rotationPeriod
        - name: note
          value_expression:
            expression: "Excessive rotation period for CryptoKey"
   

8. 將檔案儲存到 gcloud CLI 可存取的位置。

9. 使用下列指令將定義上傳至安全狀態分析：

    gcloud scc custom-modules sha create \
        --organization=organizations/ORGANIZATION_ID \
        --display-name="MODULE_DISPLAY_NAME" \
        --enablement-state="ENABLED" \
        --custom-config-from-file=DEFINITION_FILE_NAME.yaml
   

   替換下列值：

   • ORGANIZATION_ID，或是將 --organization 標記替換為 --folders 或 --project，並指定父項資料夾或專案的 ID。
   • MODULE_DISPLAY_NAME，並提供名稱，以便在自訂模組傳回發現項目時，顯示為發現項目類別。名稱長度必須介於 1 至 128 個字元之間，只能使用英數字元或底線，而且開頭須為小寫英文字母。
   • DEFINITION_FILE_NAME，並將其替換為包含自訂模組定義的 YAML 檔案路徑和檔案名稱。

   如要進一步瞭解如何使用安全狀態分析自訂模組，請參閱「使用安全狀態分析自訂模組」。

掃描新自訂模組的延遲時間

建立自訂模組不會觸發新的掃描作業。

在發生下列任一情況前，Security Health Analytics 不會開始使用新的自訂模組：

• 建立自訂模組後的第一批掃描作業。視您在批次掃描排程中建立自訂模組的時間而定，安全性狀態分析最多可能需要 24 小時，才會開始使用自訂模組。
• 目標資源發生變更時，系統會觸發即時掃描。

自訂模組定義範例

以下範例顯示已完成的自訂模組定義，如果 cloudkms.googleapis.com/CryptoKey 資源的 rotationPeriod 屬性值大於 2,592,000 秒 (30 天)，就會觸發發現項目。這個範例會在 custom_output 區段中傳回兩個選用值：resource.rotationPeriod 的值和附註 (以文字字串形式)。

請注意範例中的下列元素：

• 如要查看可檢查的資產或資源類型，請參閱 resource_selector 部分下方的resource_types。
• 模組對資源執行的檢查 (即偵測邏輯) 定義於 expression 後方的 predicate 區段。
• 在 custom_output 區段中，定義了兩個自訂來源屬性：duration 和 violation。
• description 屬性會說明偵測到的問題。
• recommendation 屬性會指定如何修正偵測到的問題。由於引號會出現在指引中，因此每個引號前面都必須加上反斜線逸出字元。

severity: HIGH
description: "Regular key rotation helps provide protection against
compromised keys, and limits the number of encrypted messages available
to cryptanalysis for a specific key version."
recommendation: "To fix this issue go to
https://console.cloud.google.com/security/kms. Click the key-ring that
contains the key. Click the key. Click \"Edit rotation period\". Then
set the rotation period to at most 30 days."
resource_selector:
  resource_types:
  - cloudkms.googleapis.com/CryptoKey
predicate:
  expression: resource.rotationPeriod > duration("2592000s")
custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.rotationPeriod
    - name: violation
      value_expression:
        expression:
          "Excessive rotation period for CryptoKey"

在自訂模組中參照資源和政策屬性

無論您使用哪種方法建立自訂模組 (使用Google Cloud 控制台或自行編寫定義)，都必須能夠查閱可在自訂模組中評估的屬性。您也需要瞭解如何在自訂模組定義中參照這些屬性。

尋找資源或政策的屬性

Google Cloud 資源的屬性是在資源的 API 定義中定義。如要查看這項定義，請按一下「支援的資源類型」中的資源名稱。

如要瞭解政策的屬性，請參閱 IAM API 參考資料說明文件。如要瞭解政策的屬性，請參閱政策。

在自訂模組定義中參照資源屬性

建立自訂模組時，掃描資源屬性的所有直接參照都必須以 resource 開頭，後面接上任何父項屬性，最後是目標屬性。屬性之間以半形句號分隔，使用 JSON 樣式的點標記法。

以下是資源屬性的範例，以及如何擷取這些屬性：

• resourceName：在 Cloud Asset Inventory 中儲存資源的完整名稱，例如 //cloudresourcemanager.googleapis.com/projects/296605646631。
• resource.rotationPeriod：其中 rotationPeriod 是 resource 的屬性。
• resource.metadata.name：其中 name 是 metadata 的子屬性，而 metadata 是 resource 的子屬性。

參考 IAM 政策屬性

您可以參照資源的 IAM 政策屬性，建立評估資源 IAM 政策的 CEL 運算式。可用的屬性只有繫結和繫結中的角色。

參考 IAM 政策屬性時，policy 是頂層屬性。

以下是 IAM 政策屬性的範例，以及如何擷取這些屬性：

• policy.bindings，其中 bindings 是 policy 的屬性。
• policy.version，其中 version 是 policy 的屬性。

如需更多範例，請參閱「CEL 運算式範例」。

如要瞭解政策的屬性，請參閱政策。

撰寫 CEL 運算式

建立自訂模組時，您可以使用 CEL 運算式評估掃描資源的屬性。您也可以選擇使用 CEL 運算式定義自訂 name-value 配對，以便在結果中傳回額外資訊。

無論是在 Google Cloud 控制台中建立自訂模組，還是自行在 YAML 檔案中編寫自訂模組定義，您定義的 CEL 運算式都相同。

偵測邏輯的 CEL 運算式

您可以使用 CEL 運算式和標準 CEL 運算子，評估掃描資源的屬性，為自訂模組編寫偵測邏輯。

運算式可以是單一值的簡單檢查，也可以是檢查多個值或條件的複雜複合運算式。無論如何，運算式都必須解析為布林值 true，才能觸發發現結果。

如要在 Google Cloud 控制台中建立自訂模組，請在「設定模組」頁面的「運算式編輯器」中撰寫這些運算式。

如果您在 YAML 檔案中編寫自訂模組，請在 predicate 屬性下方加入這些運算式。

無論您使用 Google Cloud 控制台或 YAML 檔案，評估資源屬性的 CEL 運算式都必須符合下列規則：

• 您在 CEL 運算式中指定的屬性，必須是掃描資源的屬性，如資源類型的 API 定義中所定義。

• 如果自訂模組評估多種資源類型，您在 CEL 運算式中指定的屬性，必須是自訂模組評估的每種資源類型共有的屬性。

  舉例來說，如果您定義名為 invalid_cryptokey 的自訂模組，檢查 cloudkms.googleapis.com/CryptoKey 和 cloudkms.googleapis.com/CryptoKeyVersion 這兩種資源類型，則可編寫下列運算式，因為 CryptoKey 和 CryptoKeyVersion 資源類型都包含 name 屬性：

  predicate:
  resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")

  不過，您無法在 invalid_cryptokey 自訂模組中指定下列運算式，因為運算式評估的 importTime 和 rotationPeriod 屬性並未由兩種資源類型共用：

  predicate:
  resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")

• CEL 運算式中的所有列舉都必須以字串表示。舉例來說，下列是 cloudkms.googleapis.com/CryptoKeyVersion 資源類型的有效運算式：

  resource.state = "PENDING_GENERATION"

• 您在 predicate 屬性中定義的 CEL 運算式結果必須是布林值。只有在結果為 true 時，才會觸發發現項目。

如要進一步瞭解 CEL，請參閱下列文章：

• CEL 規格
• CEL 語言定義

CEL 運算式範例

下表列出一些可用於評估資源屬性的 CEL 運算式。您可以在Google Cloud 控制台和 YAML 自訂模組定義中使用這兩者。

自訂發現項目屬性的 CEL 運算式

您也可以選擇定義最多十項自訂屬性，與自訂模組產生的結果一併傳回，以便在查詢結果中取得額外資訊。

自訂屬性會顯示在 JSON 格式的發現項目來源屬性中，以及Google Cloud console 中發現項目詳細資料的「來源屬性」分頁下方。

自訂屬性會定義為 name-value 配對。

如果您在 Google Cloud 控制台中建立自訂模組，請在「定義發現項目詳細資料」頁面的「自訂發現項目屬性」部分定義 name-value 配對。

如果您在 YAML 檔案中編寫自訂模組，請在 custom_output 屬性下，將 name-value 對列為 properties。

無論您是使用 Google Cloud 控制台或 YAML 檔案，都適用下列規則：

• 指定 name 做為不含引號的文字字串。

• 將 value 指定為下列其中一項：

  • 如要傳回屬性值，請指定下列格式的屬性：

    RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN

  這個例子當中：

  • RESOURCE_TYPE 可以是 resource 或 policy。
  • PROPERTY 包含要傳回值的屬性的一或多個父項屬性。

  • PROPERTY_TO_RETURN 是包含要傳回值的屬性。

  • 如要傳回文字字串，請在字串前後加上半形引號。

以下範例顯示 YAML 檔案中 custom_output 下方正確定義的兩組 name-value 配對：

custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.name
    - name: property_with_text
      value_expression:
        expression: "Note content"

後續步驟

如要測試、提交、查看及更新自訂模組，請參閱下列頁面：

• 如要測試自訂模組，請參閱「測試 Security Health Analytics 自訂模組」。
• 如要上傳、查看及更新自訂模組，請參閱建立及管理 Security Health Analytics 的自訂模組。