本頁面由 Cloud Translation API 翻譯而成。

為 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 運算式。

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

建立副檔名為 yaml 的文字檔案。
在文字檔案中建立 resource_selector 屬性，並指定自訂模組要掃描的一到五種資源類型。自訂模組定義中，資源類型只能指定一次。例如：
```
resource_selector:
 resource_types:
 ‐ cloudkms.googleapis.com/CryptoKey
```
您指定的資源類型必須受到 Security Command Center 支援。如需支援的資源類型清單，請參閱「支援的資源類型」。
建立 predicate 屬性，並指定一或多個 CEL 運算式，檢查要掃描的資源類型屬性。您在 CEL 運算式中參照的任何屬性，都必須存在於 resource_selector 下指定的每個資源類型Google Cloud API 定義中。如要觸發發現結果，運算式必須解析為 TRUE。舉例來說，在下列運算式中，只有大於 2592000s 的 rotationPeriod 值會觸發發現項目。
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
如需編寫 CEL 運算式的相關說明，請參閱下列資源：
- 支援的資源類型。按一下各項資源，即可查看可在 CEL 運算式中使用的屬性。
- 編寫 CEL 運算式。
- 在自訂模組中參照資源和政策屬性。
建立 description 屬性，說明自訂模組偵測到的安全漏洞或錯誤設定。這項說明會顯示在每個發現例項中，協助調查人員瞭解偵測到的問題。文字必須加上引號。例如：
```
description: "The rotation period of
 the identified cryptokey resource exceeds 30 days, the
 maximum rotation period that our security guidelines allow."
```
建立 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 控制台建立或更新自訂模組，則不需要逸出字元。
建立 severity 屬性，並指定這個模組建立的發現項目預設嚴重程度。severity 屬性的常用值為 LOW、MEDIUM、HIGH 和 CRITICAL。例如，假設使用者要求系統將文字從英文翻譯成法文
```
severity: MEDIUM
```
您可以選擇建立 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"
```
將檔案儲存到 gcloud CLI 可存取的位置。
使用下列指令將定義上傳至安全狀態分析：
```
 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 運算式。您可以在Google Cloud 控制台和 YAML 自訂模組定義中使用這兩者。

資源類型	說明	CEL 運算式
具有 IAM 政策的任何資源	檢查 IAM 政策，找出網域外部的成員	`!policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com')))`
`cloudkms.googleapis.com/CryptoKey`	檢查 Cloud KMS 金鑰輪替週期	`has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')`
透過單一政策管理多個資源類型	根據資源類型，檢查資源名稱是否以 `dev` 或 `devAccess` 開頭	`(resource.type == 'compute.googleapis.com/Disk' && resource.name.startsWith('projects/PROJECT_ID/regions/ REGION/disks/devAccess')) \|\| (resource.type == 'compute.googleapis.com/Instance ' && resource.name.startsWith('projects/PROJECT_ID/zones/REGION/instances/dev-'))`
`compute.googleapis.com/Network`	虛擬私有雲對等互連規則，用於比對網路對等互連	`resource.selfLink.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default') \|\| resource.peerings.exists(p, p.network.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/shared$'))`
`cloudfunctions.googleapis.com/CloudFunction`	僅允許 Cloud Run 函式的內部輸入流量	`has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY')`
`compute.googleapis.com/Instance`	資源名稱符合模式	`resource.name.matches('^gcp-vm-(linux\|windows)-v\\d+$')`
`serviceusage.googleapis.com/Service`	僅允許啟用儲存空間相關 API	`resource.state == 'ENABLED' && !( resource.name.matches('storage-api.googleapis.com') \|\| resource.name.matches('bigquery-json.googleapis.com') \|\| resource.name.matches('bigquery.googleapis.com') \|\| resource.name.matches('sql-component.googleapis.com') \|\| resource.name.matches('spanner.googleapis.com'))`
`sqladmin.googleapis.com/Instance`	系統只會允許許可清單中的公開 IP	`(resource.instanceType == 'CLOUD_SQL_INSTANCE' && resource.backendType == 'SECOND_GEN' && resource.settings.ipConfiguration.ipv4Enabled ) && !(resource.ipAddresses.all(ip, ip.type != 'PRIMARY' \|\| ip.ipAddress.matches('IP_ADDRESS'))))`
`dataproc.googleapis.com/Cluster`	檢查 Dataproc 叢集中的專案 ID 是否包含「testing」或「development」子字串	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

自訂發現項目屬性的 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 的自訂模組。