以前の SIEM API から Chronicle API に移行する

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

このドキュメントは、以前の SIEM API（Backstory API と Ingestion API）のいずれかを呼び出すアプリケーションの管理に役立ちます。このドキュメントでは、プログラムによるアクセスを設定し、レガシー SIEM API エンドポイントから最新の Chronicle API エンドポイントへの参照を更新する手順について説明します。

移行プロセスの概要については、埋め込み動画をご覧ください。

Chronicle API サーフェスには、開発プロセスを効率化し、 Google Cloud API 標準に準拠して信頼性、セキュリティ、パフォーマンスを向上させ、Cloud Audit Logs、Cloud Monitoring、Cloud Identity、Identity and Access Management（IAM）との統合を強化するために設計されたいくつかの改善が導入されています。また、以前の API の制限事項や複雑さの多くにも対応しています。

変更内容

以前の Backstory API と Ingestion API のエンドポイントに対するすべてのプログラム リクエストは、最新の Chronicle API に移行する必要があります。組織で、これらの以前のエンドポイントを呼び出すカスタム統合、自動化スクリプト、サードパーティ ツールを使用している場合は、2027 年 7 月 20 日までに、最新のエンドポイントと認証フローを使用するようにワークロードを更新する必要があります。また、組織で Google Security Operations SOAR を使用している場合は、Chronicle API を使用するように SOAR の統合とコネクタ（Google Chronicle 統合など）を更新する必要があります。詳細については、SOAR 統合を移行するをご覧ください。

変更されない点

Google Security Operations ユーザー インターフェース（UI）で直接実行されるアクションは、すでに最新の Chronicle API を呼び出しています。組織が UI を介してのみ Google SecOps とやり取りしている場合、またはインテグレーションがすでに Chronicle API エンドポイントを呼び出している場合は、ご対応は不要です。

主な変更点と機能強化

次の表に、以前の SIEM API と Chronicle API の主な違いを示します。

機能領域 以前の SIEM API Chronicle API 詳細
認証情報の管理 Google の担当者が関与する手動プロセス サービス アカウント、認証情報、IAM 権限のセルフサービス管理 セルフサービスの認証情報と IAM の管理により、オンボーディングが簡素化され、手動のサポート リクエストへの依存がなくなります。
コンプライアンス標準 限定的なサポート データ所在地管理、VPC Service Controls、アクセスの透明性、CMEK、FedRAMP の組み込みサポート 最新の組み込みインフラストラクチャ制御は、業界のコンプライアンスと規制の基準を満たしています。
ロギングと監査 以前の監査ストリーム Google Cloud プロジェクトに統合された Cloud Audit Logs 直接統合により、一元化された監査証跡とモニタリングが提供されます。
認証 API トークンとサービス アカウントの認証情報 Google Cloud API とサービスの認証で説明されているように、Workload Identity やサービス アカウントなどの最新の認証方法をサポートする OAuth 2.0 これらの最新の認証方法は、セキュリティを強化し、認証情報のフローを標準化します。
データモデルと API 設計 フラットな独自の構造 リソース指向の設計、RESTful アーキテクチャ、AIP に準拠した標準化された命名 この最新のデザインにより、データの整合性が向上し、API がより直感的になり、オブジェクト操作が簡素化されます。
エンドポイントの命名 一貫性がない RESTful で標準化されている 命名規則を統一しておくと、API がより直感的になり、統合が容易になります。
エコシステム 非常に限定的 MCP、Terraform、クライアント ライブラリ、SDK との統合 最新のクラウド ツールと自動化フレームワークとの幅広い互換性。
パートナー承認 パートナー トークンまたは API キーがお客様のコード全体で直接使用されている テナント リソースのプロジェクト間 IAM 委任、パートナー スコープの TenantService メソッド TenantService メソッドはパートナー プロジェクトで実行されます。他のすべてのテナント API では、テナント プロジェクトでテナントによって付与されたプロジェクト間の IAM 委任が必要です。

パートナー承認

マルチテナント パートナー ワークフローの場合、Chronicle API の認可はリソースの所有権に依存します。リソースをホストするプロジェクトによって、パートナーが必要とする認証情報と IAM 権限が決まります。テナント オペレーションをテナント委任認証情報にスコープ設定することは、パートナーがテナントから明示的な権限が付与されていない限り、テナント データにアクセス、取得、変更できないようにするというコア セキュリティ原則に沿ったものです。次の表は、以前の Backstory API と Chronicle API のパートナー認証を比較したものです。

API メソッド リソース スコープ 承認
以前の Backstory API /v1/partner/customer/* 個のエンドポイント パートナーのすべての顧客コード パートナーは、独自のパートナー トークンまたは API キーを使用してこれらのエンドポイントを直接呼び出します。
Chronicle API: TenantService CreateTenant、ListTenants、UpdateTenant パートナーのインスタンス: projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/* パートナーは、パートナー プロジェクトで chronicle.googleapis.com/tenants.* 権限を持つ独自のサービス アカウントまたは認証情報を使用して、これらのメソッドを直接呼び出します。
Chronicle API: InstanceService や ForwarderService などの他のサービス GetInstance、UpdateInstance、GenerateForwarderFiles、その他のテナント スコープのメソッド テナントのインスタンス: projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/... パートナーの認証情報だけでは、テナント データにアクセスしたり、テナント データを変更したりすることはできません。テナント管理者は、テナントの Google Cloud プロジェクトで、パートナーのサービス アカウントまたは Workload Identity 連携プリンシパルに roles/chronicle.admin、roles/chronicle.viewer、カスタムロールなどの IAM ロールを付与する必要があります。

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

以前の SIEM API は 2027 年 7 月 20 日にシャットダウンされる予定です。サービスの中断を避けるため、この日付より前に移行を完了することをおすすめします。

  • 2026 年 10 月 26 日以降、新しいインスタンスから以前の API（Backstory API と Ingestion API）を呼び出すことができなくなります。
  • 2027 年 7 月 20 日までに、既存のすべてのインスタンスを Chronicle API に移行する必要があります。以前の API は使用できなくなります。

始める前に

Chronicle API に移行する前に、次のことを確認してください。

  • 最新の SIEM インフラストラクチャにデプロイする: インスタンスが、最新の SIEM インフラストラクチャを使用して、お客様または MSSP パートナーの Google Cloud プロジェクトにデプロイされていることを確認します。詳細な手順については、SIEM 移行の概要をご覧ください。
  • Chronicle API を有効にする: Google Cloud コンソールで、インスタンスをホストするプロジェクトに移動し、Chronicle API（chronicle.googleapis.com）を有効にします。詳細については、 Google Cloud プロジェクトで API を有効にするをご覧ください。
  • SOAR 統合を特定する: 環境で Google SecOps SOAR を Google Security Operations SIEM に接続している場合は、既存のコネクタを確認します。詳細については、SOAR 統合を移行するをご覧ください。

SOAR 統合を移行する

組織で Google SecOps SOAR を Google SecOps SIEM に接続している場合は、Chronicle API を使用するように SOAR インテグレーションとコネクタ（Google Chronicle インテグレーションなど）を移行する必要があります。

Google Chronicle の統合とコネクタをアップグレードして Chronicle API を使用するための詳細な手順（環境の Chronicle API ルートの特定や認証情報の構成など）については、Backstory API から Chronicle API への移行をご覧ください。

Chronicle API に移行する

次の手順に沿って、カスタム スクリプトと統合を従来の API から Chronicle API に移行します。

  1. API の使用状況の監査: 以前のエンドポイントを呼び出す環境内のすべてのカスタム スクリプトとインテグレーションを特定します。
  2. 認証と認可を設定する: Chronicle API へのリクエストを認証して認可するように環境を構成します。
  3. エンドポイントをマッピングして URL を更新する: 以前のエンドポイントを最新のリージョン エンドポイントに置き換えます。
  4. API ロジックを更新する: 最新の API のデータモデルに合わせて、リクエスト ペイロードとレスポンス処理を調整します。
  5. 統合をテストする: 本番環境にデプロイする前に、ステージング環境で変更を検証します。

Audit API の使用状況を確認する

環境を監査して、backstory.googleapis.com または malachiteingestion-pa.googleapis.com を呼び出すカスタム スクリプトまたは統合を特定します。これらの統合を特定するには、コードベース、自動化スクリプト、サードパーティ製ツールを確認します。組織で Google SecOps SOAR も使用している場合は、SOAR インテグレーションを移行するをご覧ください。

認証と権限付与の設定

Chronicle API へのリクエストを認証して認可するように環境を構成します。

  1. 認証方法を選択します。リストに表示されているいずれかの方法を使用して、ワークロードが Chronicle API に対して認証を行う方法を選択します。Workload Identity 連携を使用すると、有効期間の長いサービス アカウント キーの管理と保存が不要になるため、セキュリティが強化されます。高度な認証シナリオ（サービス アカウントの権限借用など）については、Chronicle API に対する認証をご覧ください。
  2. IAM 権限を付与する: 認証に使用される ID（サービス アカウントまたは外部 ID プリンシパル）に必要な IAM 権限を付与します。レガシー呼び出しを置き換える最新のエンドポイントに必要な特定の IAM 権限については、SIEM API エンドポイント マッピングをご覧ください。
    • カスタムロール（推奨）: 必要な権限を持つカスタム IAM ロールを作成し、サービス アカウントまたは外部 ID プリンシパルにカスタムロールを付与します。
    • 事前定義ロール: サービス アカウントまたは外部 ID プリンシパルに Google SecOps 事前定義ロールを付与します。これにより、特定の自動化に必要なアクセス権よりも多くのアクセス権が付与される可能性があります。
    • マルチテナント パートナー委任: TenantService の外部（GetInstance、UpdateInstance、GenerateForwarderFiles など）でテナント リソースを管理する MSSP またはパートナーの場合、テナント管理者は、テナントの Google Cloud プロジェクトで必要な IAM ロールをサービス アカウントまたは Workload Identity 連携プリンシパルに明示的に付与する必要があります。

  3. 認証情報の環境変数を設定する: GOOGLE_APPLICATION_CREDENTIALS 環境変数を設定して、アプリケーションのデフォルト認証情報（ADC）で認証情報を使用するようにランタイム環境を構成します。この変数は、ダウンロードしたサービス アカウント キーの JSON ファイルまたは Workload Identity 連携の認証情報構成ファイルのいずれかを指す必要があります。Google Cloud クライアント ライブラリは、リクエストを認証するためにこの変数を自動的に検出します。

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"

  4. OAuth スコープを更新する: 以前の統合スクリプトでトークン生成用の OAuth スコープが明示的にリクエストされている場合は、スコープ文字列を更新します。以前のスコープでは、最新の API サーフェスへのアクセス権が付与されません。

    • 以前の Backstory のスコープ: https://www.googleapis.com/auth/chronicle-backstory
    • Chronicle スコープ: https://www.googleapis.com/auth/chronicle（またはより広範な https://www.googleapis.com/auth/cloud-platform スコープ）。

エンドポイントをマッピングして URL を更新する

Chronicle API サーフェスを理解し、以前の呼び出しをマッピングして、アプリケーションのサービス エンドポイントを更新します。

リファレンス ドキュメントを確認する

Chronicle API の包括的なドキュメントをよく理解します。

エンドポイントを Chronicle API にマッピングする

アプリケーションが行う以前の API 呼び出しごとに、対応する最新のエンドポイントを特定します。同様に、スキーマの変更や追加のフィールドを考慮して、既存のデータモデルを最新の構造にマッピングします。すべての SIEM エンドポイントの詳細については、SIEM API エンドポイント マッピングをご覧ください。ワークフローが SOAR エンドポイントともやり取りする場合は、SOAR API エンドポイント マッピング テーブルをご覧ください。

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

API 呼び出しのベース URL を更新して、正しいリージョン サービス エンドポイントを指すようにします。Chronicle API はリージョン サービスであるため、Google SecOps インスタンスのロケーションと一致するリージョン サービス エンドポイントを呼び出す必要があります。

すべての最新のエンドポイントは一貫した接頭辞を使用するため、最終的なエンドポイント アドレスを予測できます。次の例は、最新のエンドポイント 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 SecOps SIEM のお客様 ID。

リージョン アドレス:

  • africa-south1: https://africa-south1-chronicle.googleapis.com または https://chronicle.africa-south1.rep.googleapis.com
  • asia-northeast1: https://asia-northeast1-chronicle.googleapis.com または https://chronicle.asia-northeast1.rep.googleapis.com
  • asia-south1: https://asia-south1-chronicle.googleapis.com または https://chronicle.asia-south1.rep.googleapis.com
  • asia-southeast1: https://asia-southeast1-chronicle.googleapis.com または https://chronicle.asia-southeast1.rep.googleapis.com
  • asia-southeast2: https://asia-southeast2-chronicle.googleapis.com または https://chronicle.asia-southeast2.rep.googleapis.com
  • australia-southeast1: https://australia-southeast1-chronicle.googleapis.com または https://chronicle.australia-southeast1.rep.googleapis.com
  • europe-west12: https://europe-west12-chronicle.googleapis.com または https://chronicle.europe-west12.rep.googleapis.com
  • europe-west2: https://europe-west2-chronicle.googleapis.com または https://chronicle.europe-west2.rep.googleapis.com
  • europe-west3: https://europe-west3-chronicle.googleapis.com または https://chronicle.europe-west3.rep.googleapis.com
  • europe-west6: https://europe-west6-chronicle.googleapis.com または https://chronicle.europe-west6.rep.googleapis.com
  • europe-west9: https://europe-west9-chronicle.googleapis.com または https://chronicle.europe-west9.rep.googleapis.com
  • me-central1: https://me-central1-chronicle.googleapis.com または https://chronicle.me-central1.rep.googleapis.com
  • me-central2: https://me-central2-chronicle.googleapis.com または https://chronicle.me-central2.rep.googleapis.com
  • me-west1: https://me-west1-chronicle.googleapis.com または https://chronicle.me-west1.rep.googleapis.com
  • northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com または https://chronicle.northamerica-northeast2.rep.googleapis.com
  • southamerica-east1: https://southamerica-east1-chronicle.googleapis.com または https://chronicle.southamerica-east1.rep.googleapis.com
  • 米国（us）: https://us-chronicle.googleapis.com または https://chronicle.us.rep.googleapis.com
  • ヨーロッパ（eu）: https://eu-chronicle.googleapis.com または https://chronicle.eu.rep.googleapis.com

サポートされているすべてのエンドポイントの包括的なリストについては、Chronicle API の サービス エンドポイントのドキュメントの公式リファレンスをご覧ください。

たとえば、us ロケーションのインスタンスのすべての検出ルールを一覧表示するには、次のリクエストを送信します。

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

同様に、リージョン エンドポイント（rep）エイリアスを使用してケースなどの SOAR リソースをクエリするには、次のリクエストを送信します。

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

API ロジックを更新する

Chronicle API REST リファレンスを確認して、アプリケーションのフィールド名とデータ構造の変更を特定して実装します。一部の以前のエンドポイントは類似している可能性がありますが、最新のデータモデルとエンドポイント構造に合わせて統合を更新する必要があります。

Google Cloud クライアント ライブラリを使用する

統合を簡素化して、認証、トークンの更新、転送の詳細を自動的に処理します。これには、公式の Google Cloud クライアント ライブラリを使用することをおすすめします。Chronicle API は、Python、Go、Java、Node.js、C# など、8 つのプログラミング言語でサポートされています。インストールと使用方法の詳細については、クライアント ライブラリと SDK をご覧ください。

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

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

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

トラブルシューティング

このセクションでは、移行中に発生する可能性のある一般的なエラーの解決方法について説明します。

HTTP 403 Forbidden または PERMISSION_DENIED

API 呼び出しが HTTP 403 Forbidden エラーまたは PERMISSION_DENIED エラーを返す場合は、次のことを確認してください。

  • 認証方法とプリンシパル: 正しい認証情報を使用していることを確認します。
    • Workload Identity 連携を使用している場合は、外部 ID プリンシパルが、プロジェクトの IAM ロールにバインドされているプリンシパルと一致していることを確認します。
    • サービス アカウントを使用している場合は、正しいサービス アカウントが使用されており、無効になっていないことを確認します。最新の Chronicle API エンドポイントには、レガシー サービス アカウント（メールアドレスに bk または malachite-cx が含まれていることが多い）を使用しないでください。
  • IAM ロール: サービス アカウントまたは外部 ID プリンシパルに、 Google Cloud プロジェクトで必要な事前定義またはカスタムの IAM ロール（Chronicle API Viewer や Chronicle API Editor など）が付与されていることを確認します。きめ細かいエンドポイント権限については、SIEM API エンドポイント マッピングをご覧ください。

HTTP 401 Unauthorized または UNAUTHENTICATED

API 呼び出しが HTTP 401 Unauthorized または UNAUTHENTICATED で失敗した場合は、次の点を確認してください。

  • OAuth スコープ: カスタム スクリプトが最新のスコープ https://www.googleapis.com/auth/chronicle（またはより広範な https://www.googleapis.com/auth/cloud-platform スコープ）をリクエストしていることを確認します。以前のスコープ（https://www.googleapis.com/auth/chronicle-backstory）では、最新の Chronicle API へのアクセス権は付与されません。
  • 環境変数: GOOGLE_APPLICATION_CREDENTIALS 環境変数が設定され、ランタイム環境内の正しい JSON キーファイルまたは Workload Identity 連携構成ファイルを指していることを確認します。

HTTP 404 Not Found または地域不一致

API 呼び出しが HTTP 404 Not Found を返すか、接続に失敗した場合は、リージョン エンドポイントを確認します。

  • リージョン エンドポイント: Chronicle API はリージョン サービスです。Google SecOps インスタンスのリージョンと一致するエンドポイント（フランクフルトのインスタンスの場合は https://europe-west3-chronicle.googleapis.com など）を呼び出していることを確認します。別のリージョンにリクエストを送信すると、エラーが発生します。リージョン アドレスの完全なリストについては、サービス エンドポイントを更新するか、公式のサービス エンドポイント リファレンスをご覧ください。

次のステップ

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