Security Health Analytics でのカスタム モジュールの使用

このページでは、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 の有効化については、組み込みサービスを有効または無効にするをご覧ください。
  • ユーザー アカウントには、必要な権限を含む 1 つ以上の Identity and Access Management（IAM）ロールを付与する必要があります。詳細については、必要な IAM 権限をご覧ください。
  • 独自のカスタム モジュールを作成して、gcloud コマンドで Security Command Center にアップロードする場合は、Google Cloud CLI が必要です。gcloud CLI のインストールについては、gcloud CLI のインストールをご覧ください。
  • Security Command Center API がまだ有効になっていない場合は、Security Health Analytics でカスタム モジュールを使用する前に、API を有効にする必要があります。Security Command Center API は、Google Cloud コンソールの [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. [ モジュールを作成する] をクリックします。[Security Health Analytics のモジュールを作成する] ページが開きます。

  6. [モジュールを構成する] パネルで、表示名、スキャンするリソースと検出ロジックを定義します。

    1. [モジュール名] フィールドにモジュールの名前を指定します。名前は 1～128 文字で、先頭は英小文字にします。それ以降は、英数字とアンダースコアのみを使用してください。この名前は、この検出器が生成する検出結果の検出結果カテゴリになります。モジュールの作成後は、名前を変更できません。

    2. [リソースタイプを追加する] で、スキャンするリソースタイプを 1 ～ 5 個指定します。リソースタイプは複数回指定できません。

      サポートされているリソースタイプの一覧については、サポートされているリソースタイプをご覧ください。

    3. 式エディタで、最後のステップで指定したリソースの 1 つ以上のプロパティに対してブール値チェックを実行する CEL 式を作成します。検出結果をトリガーするには、式を TRUE に解決する必要があります。たとえば、CryptoKey リソースにローテーション期間が定義されていて、ローテーション期間が 2,592,000 秒（30 日）より長い場合、次の式は検出結果をトリガーします。

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

      詳しくは以下をご覧ください。

    4. [次へ] をクリックします。[検出結果の詳細を定義する] パネルが開きます。

  7. [検出結果の詳細を定義する] パネルで、重大度、問題が何か、問題を修正する方法、カスタムソース プロパティとして検出結果に含めるあらゆるデータなど、カスタム モジュールが検出する問題について記述します。

    1. [重大度] フィールドに、問題の重大度を指定します。Low、Medium、High、または Critical を指定できます。デフォルトは Medium です。

      重大度レベルについては、検出結果の重大度の分類をご覧ください。

    2. [検出結果の説明] フィールドに、カスタム モジュールが検出する問題を説明します。この説明は、セキュリティ チームが検出された問題を理解し、対処できるように、検出結果のインスタンスごとに表示されます。

    3. [次の手順の確認] フィールドに、セキュリティ チームが検出された問題を修正またはそれ以外の方法で対処できる手順を入力します。

      この手順は検出結果インスタンスごとに表示されます。セキュリティ チームが問題を可能な限り迅速に解決できるように、具体的な手順を記述します。

    4. 省略可: [カスタム検出プロパティ] フィールドには、最大 10 個の名前と値のペアを指定して、検出結果のインスタンスごとに返されるカスタムソース プロパティを定義します。情報は、検出結果の JSON でソース プロパティとして返され、Google Cloud コンソールの検出結果の詳細の [ソース プロパティ] タブに表示されます。テキストまたはプロパティの値を Key-Value ペアとして指定します。

      • [プロパティ名] フィールドに、カスタム ソース プロパティの名前を指定します。名前は次のルールに準拠している必要があります。
        • 名前の先頭は小文字にします。
        • 名前には英数字とアンダースコアのみを使用します。
        • 名前の長さは 1 ～ 128 文字にする必要があります。
        • 各名前は、他のソース プロパティの中で一意である必要があります。
      • [プロパティ値] フィールドで、次のいずれかの値を 1,024 文字以下で指定します。
        • 引用符で囲まれたテキスト文字列。引用符は 1,024 文字の上限に含まれます。例: "This string provides additional useful information."
        • スキャンされるリソースの任意のプロパティ。たとえば、CryptoKey リソースを確認する場合は、resource.rotationPeriod を指定できます。rotationPeriod プロパティの値が返されます。

    5. [Next] をクリックします。[モジュールを有効化する] パネルが開きます。

  8. 省略可: [モジュールを有効化する] パネルのプルダウン メニューを使用して、カスタム モジュールを作成時に有効にするか無効にするかを指定します。デフォルトでは、カスタム モジュールは作成時に有効になります。[無効] を指定した場合、後で Security Health Analytics の設定ページの [モジュール] タブでモジュールを有効にできます。

  9. [Next] をクリックします。[モジュールのテスト] パネルが開きます。

  10. （省略可）カスタム モジュールを作成する前に、テストすることをおすすめします。

    カスタム モジュールをテストするには、次の手順に従います。

    1. カスタム モジュールがチェックするリソースのテストリソース定義を含む YAML ファイルを作成します。

      テストデータ ファイルを作成する方法については、YAML ファイルにテストリソースを作成するをご覧ください。

    2. [YAML ファイルをアップロードする] で [参照] をクリックし、テストリソース定義を含む YAML ファイルをアップロードします。ファイルがアップロードされると、テストが自動的に開始されます。

    3. [テスト結果のプレビュー] で結果を確認します。

      • YAML ファイルに構文またはその他のエラーがある場合は、ブラウザページの一番下の近くにフローティング エラー メッセージが表示されます。

      • テストが成功すると、次の情報が返されます。

        • カスタム モジュールの表示名。
        • テストデータ ファイルの resource プロパティに指定した任意の名前。
        • カスタム モジュールが作成された（または作成される予定の）組織、フォルダ、またはプロジェクト。

    テスト結果は保存されず、Security Command Center にも書き込まれません。

    詳細については、カスタム モジュールのテストをご覧ください。

  11. [作成] をクリックします。[モジュール] ページに戻り、ステータスが [有効] となった作成したモジュールが表示されます。

新しいカスタム モジュールは、Security Health Analytics のスキャンですぐに使用することはできません。詳細については、検出レイテンシをご覧ください。

gcloud CLI

gcloud コマンドを使用してカスタム モジュールを作成するには、まず、検出ロジックと出力プロパティの CEL 式を含む YAML ファイルに、カスタム モジュールの定義をコーディングする必要があります。

定義が完了したら、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: カスタム モジュールが作成された組織、フォルダ、またはプロジェクトの ID。

カスタム モジュールを削除する

カスタム モジュールは、作成元の組織、フォルダ、プロジェクト、あるいは親の組織、フォルダから削除できます。それを継承したフォルダまたはプロジェクトからカスタム モジュールを削除できません。

カスタム モジュールを削除する方法については、次のいずれかのタブを選択してください。

Google Cloud コンソール

  1. Google Cloud コンソールで Security Command Center の [設定] ページに移動します。

    [設定] に移動

  2. プロンプトが表示されたら、組織、フォルダ、またはプロジェクトを選択します。

  3. [Security Health Analytics] カードで、[設定を管理] をクリックします。

  4. [モジュール] タブを選択します。Security Health Analytics のすべての検出モジュールが表示されます。

  5. モジュールのリストの上部にあるフィルタ フィールドを使用するかスクロールして、変更が必要なカスタム モジュールを見つけます。

  6. カスタム モジュールの行の右側にある操作メニュー アイコン をクリックします。

  7. 操作メニューで [削除] をクリックします。[カスタム モジュールを削除する] ダイアログが開きます。

  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 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 のすべての検出結果と同様に、カスタム モジュールによって生成された検出結果を管理できます。手順については、以下をご覧ください。