以前の 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 SecOps ユーザー インターフェース（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 との統合 最新のクラウド ツールと自動化フレームワークとの幅広い互換性。

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

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

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

始める前に

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

  • 最新の SIEM インフラストラクチャにデプロイする: 最新の SIEM インフラストラクチャを活用して、インスタンスが Google Cloud プロジェクトにデプロイされていることを確認します。詳細な手順については、SIEM 移行の概要をご覧ください。
  • Chronicle API を有効にする: Google Cloud コンソールで、プロジェクトに移動して Chronicle API（chronicle.googleapis.com）を有効にします。詳細については、 Google Cloud プロジェクトで 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 を呼び出すスクリプトまたは統合を特定します。これらの統合は、コードベース、自動化スクリプト、サードパーティ製ツールを確認することで特定できます。

認証と権限付与の設定

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

  1. 認証方法を選択します。リストに表示されているいずれかの方法を使用して、ワークロードが Chronicle API に対して認証を行う方法を選択します。Workload Identity 連携を使用すると、有効期間の長いサービス アカウント キーの管理と保存が不要になるため、セキュリティが強化されます。高度な認証シナリオ（サービス アカウントの権限借用など）については、Chronicle API に対する認証をご覧ください。

  2. IAM 権限を付与する: 認証に使用される ID（サービス アカウントまたは外部 ID プリンシパル）に必要な IAM 権限を付与します。必要なアクセスレベルに応じて、必要な IAM ロールを ID に割り当てます。詳細については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。事前定義ロールには次のものがあります。

    最小権限の原則に従い、カスタムまたは事前定義の IAM ロールを活用して、自動化に必要な権限のみを付与することをおすすめします。

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

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

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

    • 従来のコンテンツの背景情報の範囲: 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 Security Operations 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 のプロフェッショナルから回答を得ることができます。