Chronicle API に移行する

以下でサポートされています。

このドキュメントは、インテグレーション、カスタム スクリプト、カスタム アクションを使用して SOAR API をプログラムで呼び出す場合に適用されます。このドキュメントでは、Chronicle API の一部として、プログラマティック API リファレンスを新しい SOAR API エンドポイントに更新する手順と考慮事項について説明します。

Chronicle API サーフェスには、開発プロセスを効率化するために設計されたいくつかの改善が導入されています。また、古い API に存在する制限や複雑さにも対処しています。

従来の SOAR API と API キーは 2027 年 3 月 31 日まで利用可能ですが、それ以降は機能しなくなります。

前提条件

SOAR API の移行を行う前に、次のことを行う必要があります。

主な変更点と機能強化

次の表に、古い API サーフェスと新しい API サーフェスの主な違いを示します。

機能領域 古い API 新しい API 詳細
認証 API トークン OAuth 2.0 新しい認証方法により、セキュリティが強化され、プロセスが標準化されます。
データモデル フラットな構造 リソース指向の設計 この新しい設計により、データの整合性が向上し、オブジェクトの操作が簡素化されます。
エンドポイントの命名 一貫性がない RESTful で標準化されている 一貫した命名により、API がより直感的になり、統合が容易になります。

サポート終了スケジュール

SOAR の古い API サーフェスは、2027 年 3 月 31 日に完全に非推奨になる予定です。サービスの中断を避けるため、この日付より前に移行を完了することをおすすめします。

移行手順

このセクションでは、アプリケーションを Chronicle API に正常に移行する手順について説明します。

ドキュメントを確認する

Chronicle API リファレンス ガイドなど、新しい API の包括的なドキュメントをよく理解してください。

エンドポイントを新しい API サーフェスにマッピングする

アプリケーションが行う古い API 呼び出しごとに、対応する新しいエンドポイントを特定します。同様に、古いデータモデルを新しいデータモデルにマッピングし、構造の変更や新しいフィールドを考慮します。詳細については、API エンドポイント マッピング テーブルをご覧ください。

省略可: ステージング統合を作成する

カスタム統合または商用統合のコンポーネントを編集する場合は、まず変更をステージング統合に push することをおすすめします。このプロセスにより、本番環境の自動化フローに影響を与えることなくテストできます。SOAR API を使用するカスタムビルド アプリケーションを移行する場合は、次のステップに進みます。統合ステージングの詳細については、ステージング モードで統合をテストするをご覧ください。

サービス エンドポイントと URL を更新する

サービス エンドポイントは、API サービスのネットワーク アドレスを指定するベース URL です。1 つのサービスに複数のサービス エンドポイントを設定できます。Chronicle はリージョン サービスであり、リージョン エンドポイントのみをサポートしています。

新しいエンドポイントはすべて一貫した接頭辞を使用するため、最終的なエンドポイント アドレスを予測できます。次の例は、新しいエンドポイント URL 構造を示しています。

[api_version]/projects/[project_id]/locations/[location]/instances[instance_id]/...

この構造により、エンドポイントの最終アドレスは次のようになります。

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

ここで

  • service_endpoint: リージョン サービス アドレス
  • api_version: クエリする API バージョン。v1alpha、v1beta、v1 のいずれかです。
  • project_id: プロジェクト ID（IAM 権限に定義したプロジェクトと同じ）
  • location: プロジェクトのロケーション（リージョン）。リージョン エンドポイントと同じ
  • instance_id: Google Security Operations SIEM のお客様 ID。

リージョン アドレス:

  • africa-south1: https://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1: https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12: https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2: https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3: https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6: https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9: https://chronicle.europe-west9.rep.googleapis.com

  • me-central1: https://chronicle.me-central1.rep.googleapis.com

  • me-central2: https://chronicle.me-central2.rep.googleapis.com

  • me-west1: https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

  • us: https://chronicle.us.rep.googleapis.com

  • eu: https://chronicle.eu.rep.googleapis.com

たとえば、米国のプロジェクトのすべてのケースのリストを取得するには、次のようにします。

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

認証方法を更新する

新しい API は、認証に Google Cloud IAM を使用します。この新しい認証フローを実装するには、アプリケーションまたはレスポンス統合を更新する必要があります。スクリプトを実行するユーザーに、アクセスしようとしているエンドポイントに対する適切な権限があることを確認します。この新しいフローを実装するには、レスポンスの統合またはアプリケーションを更新する必要があります。スクリプトを実行するユーザーが、対象のエンドポイントに必要な権限を持っていることを確認します。詳しい手順については、Chronicle API ページに対する認証をご覧ください。

サービス アカウントまたは Workload Identity を SOAR パラメータにマッピングする

サービス アカウントまたは Workload Identity 連携を使用して Chronicle API に対する認証を行う場合は、プラットフォーム内で認証を行い、Google SecOps と正常に通信できるようにする必要があります。このマッピングは、サービス アカウントまたは Workload Identity に SOC のロールと環境への必要なアクセス権を付与するために必要です。

Google SecOps へのサービス アカウント アクセスまたは Workload Identity 連携アクセスを付与するには、ID をプラットフォームのアクセス制御パラメータにマッピングする必要があります。このマッピングは、自動タスクや API オペレーションの実行に必要な SOC ロールと環境へのアクセス権を ID に付与するために必要なステップです。

  1. [設定] > [アクセス管理] > [グループ マッピング] に移動します。
  2. [追加] 追加 をクリックします。

  3. [マッピングを追加] ダイアログのフィールドに値を入力して、ID をプラットフォームのアクセス制御パラメータにマッピングします。

    1. [IdP / ユーザー グループ] フィールドに、次のいずれかを入力します。
      • Cloud Identity を使用して ID が設定されている場合は、サービス アカウントの完全なメールアドレス。
      • Workload Identity プリンシパル文字列（Workforce Identity 連携を使用して ID が設定されている場合）。

    2. 次のアクセス制御フィールドを構成します。

      フィールド 説明
      権限グループ 権限グループを選択して、ID がアクセスできるモジュールとサブモジュールを定義します。
      SOC ロール SOC ロールを選択して、ID のロール（Tier 1 など）を定義します。
      環境 ID がアクセスできる環境または環境グループ（[すべての環境] など）を選択します。
      グループ メンバー 必要に応じて、必要なユーザーのメールアドレスを入力します。メールアドレスを追加するごとに Enter キーを押します。
      制限される操作 制限付きアクションを選択して、モジュール内の特定の操作を制限します。

  4. [追加] をクリックします。

ユーザーとサービス アカウントのマッピングの詳細については、サードパーティ ID を使用してプラットフォームでユーザーをマッピングするまたは Cloud Identity を使用してプラットフォームでユーザーをマッピングするをご覧ください。

API ロジックを更新する

API リファレンスに記載されている新しいデータモデルとエンドポイント構造を分析します。すべてのメソッドが大幅に変更されたわけではなく、既存のコードの一部は再利用できます。主な目的は、新しいリファレンス ドキュメントを確認し、特定のユースケースごとに、アプリケーションのロジック内のフィールド名とデータ構造に必要な変更を特定して実装することです。

インテグレーションをテストする

更新したアプリケーションを本番環境にデプロイする前に、ステージング統合でテストします。

  1. テスト計画を作成する: 移行されたすべての機能をカバーするテストケースを定義します。
  2. テストを実行する: 自動テストと手動テストを実行して、精度と有効性を確認します。
  3. パフォーマンスをモニタリングする: 新しい API を使用してアプリケーションのパフォーマンスを評価します。

さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。