未加工のログをセルフマネージド Google Cloud Storage バケットにエクスポートする
Data Export API を使用すると、Google Security Operations から管理対象の Google Cloud Storage バケットにセキュリティ データを一括エクスポートできます。この機能は、重要な長期データの保持をサポートし、履歴フォレンジック分析と厳格なコンプライアンス要件(SOX や GDPR など)をサポートします。
API リファレンスの詳細については、データ エクスポート API(拡張版)をご覧ください。
Data Export API は、ポイントインタイム データ エクスポート用のスケーラブルで信頼性の高いソリューションを提供し、最大 100 TB のリクエストを処理します。
マネージド パイプラインとして、次のようなエンタープライズ グレードの重要な機能を提供します。
- 一時的なエラーの自動再試行
- 包括的なジョブ ステータスのモニタリング
- 各エクスポート ジョブの完全な監査証跡
API は、Google Cloud Storage バケット内の日時でエクスポートされたデータを論理的にパーティショニングします。
この機能を使用すると、大規模なデータ オフロード ワークフローを構築できます。Google SecOps は、エクスポート プロセスの複雑さを管理して、安定性とパフォーマンスを確保します。
主なメリット
Data Export API は、セキュリティ データのライフサイクルを管理するための、復元力と監査性に優れたソリューションを提供します。主なメリットは次のとおりです。
- 信頼性: このサービスは大規模なデータ移転を処理します。システムは、指数バックオフ戦略を使用して、一時的な問題(一時的なネットワークの問題など)が発生したエクスポート ジョブを自動的に再試行し、復元力を高めます。一時的なエラーが原因でエクスポート ジョブが失敗した場合は、自動的に数回再試行されます。すべての再試行後にジョブが永続的に失敗すると、システムはそのステータスを
FINISHED_FAILUREに更新します。そのジョブの API レスポンスには、原因を説明する詳細なエラー メッセージが含まれます。 包括的な監査可能性: 厳格なコンプライアンスとセキュリティ基準を満たすため、システムはエクスポート ジョブに関連するすべてのアクションを不変の監査証跡にキャプチャします。このトレイルには、すべてジョブの作成、開始、成功、失敗、アクションを開始したユーザー、タイムスタンプ、ジョブ パラメータが含まれます。
パフォーマンスとスケールを最適化: API は堅牢なジョブ管理システムを使用します。このシステムには、プラットフォームの安定性を確保し、単一のテナントがリソースを独占しないように、キューイングと優先順位付けが含まれています。
データの完全性とアクセシビリティの向上: システムは、Google Cloud Storage バケット内の論理ディレクトリ構造にデータを自動的に整理します。これにより、過去の分析のために特定の時間枠を特定してクエリを実行できます。
セキュリティ: この API は、顧客管理の暗号鍵(CMEK)(ゼロトラスト セキュリティ)とデータ RBAC(最小権限アクセス)に完全に準拠するように設計されています。エクスポート ジョブは、リクエストをトリガーしたユーザーのデータ公開範囲を継承し、不正なデータ抽出を防ぎます。エクスポート パイプラインは Google Cloud Key Management Service とも完全に統合されており、データは独自の鍵を使用して Google Cloud Storage バケットに保存された状態で暗号化されたままになります。
主な用語と概念
- エクスポート ジョブ: 特定の期間のログデータを Google Cloud Storage バケットにエクスポートする単一の非同期オペレーション。システムは、一意の
dataExportIdを使用して各ジョブを追跡します。 - ジョブのステータス: エクスポート ジョブのライフサイクルにおける現在の状態(
IN_QUEUE、PROCESSING、FINISHED_SUCCESSなど)。 - Google Cloud Storage バケット: ユーザーが所有する Google Cloud Storage バケット。エクスポートされたデータの宛先として機能します。
- ログタイプ: エクスポートできるログの特定のカテゴリ(
NIX_SYSTEM、WINDOWS_DNS、CB_EDRなど)。詳細については、サポートされているすべてのログタイプのリストをご覧ください。
エクスポートされたデータ構造を理解する
ジョブが正常に完了すると、システムは Google Cloud Storage バケットにデータを書き込みます。特定のパーティション分割されたディレクトリ構造を使用して、データアクセスとクエリを簡素化します。
ディレクトリ パスの構造: gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/logdata-SHARD_INDEX.csv
ここで
- GCS_BUCKET_NAME: Google Cloud Storage バケットの名前。
- EXPORT_JOB_NAME: エクスポート ジョブの一意の
dataExportIdUUID(オブジェクトパスにハイフンなし)。 - LOGTYPE: エクスポートされたデータのログタイプの名前(
GCP_DNS、WINDOWS_DNSなど)。 - EVENT_TIME_BUCKET: エクスポートされたログのイベント タイムスタンプの時間バケットを指します。UTC 時間の開始(
YYYY/MM/DD/HH/00/00)に切り捨てられます。たとえば、2025/08/25/01/00/00には、2025 年 8 月 25 日の01:00:00 UTCから01:59:59 UTCまでのイベント タイムスタンプを持つログが含まれます。 - EPOCH_EXECUTION_TIME: エクスポート ジョブの実行が開始された日時を示す 20 桁のゼロ埋め Unix エポック タイムスタンプ(マイクロ秒単位)(例:
00001756083600000000)。 logdata-SHARD_INDEX.csv: 未加工のログを含む 0 インデックスのシャーディングされたファイル(logdata-0.csv、logdata-1.csvなど)を指します。各ファイル シャードの目標サイズは約 100 MB です。
エクスポートされたオブジェクトのパスの例:
gs://my-archive-bucket/b4a3c2d1e8f76a5b4c3d2e1f0a9b8c7d/GCP_DNS/2025/08/25/01/00/00/00001756083600000000/logdata-0.csv
エクスポート完了マニフェスト(exported_paths.txt):
エクスポート ジョブがステータス FINISHED_SUCCESS で終了し、少なくとも 1 つのログファイルが書き込まれると、パイプラインはマニフェスト ファイルも gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/exported_paths.txt に書き込みます(エクスポート フィルタまたは期間に一致するログがない場合、マニフェスト ファイルは書き込まれず、dataExportStatus.exportedGlobPatterns は空になります)。exported_paths.txt の各行には、ジョブによって書き込まれた 1 時間ごとのパーティション ディレクトリの /bigstore/ 接頭辞(/bigstore/GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/*、gs://GCS_BUCKET_NAME/.../* にマッピングされる)を使用した glob パターンが一覧表示されます。ダウンストリームの自動化ジョブや圧縮ジョブは、このマニフェストを読み取ることで、バケット全体を一覧表示することなく、エクスポートされたすべてのパーティションを列挙できます。
パフォーマンスと制限事項
このサービスには、プラットフォームの安定性と公平なリソース割り当てを確保するために、次の特定の上限が設けられています。
- ジョブあたりの最大データ量: 個々のエクスポート ジョブでリクエストできるデータ量は最大 100 TB です。大規模なデータセットの場合は、エクスポートを複数のジョブに分割し、期間を短くすることをおすすめします。
- 同時実行ジョブ: 各お客様テナントは、最大 3 つのエクスポート ジョブを同時に実行またはキューに格納できます。この上限を超える新しいジョブ作成リクエストは、システムによって拒否されます。
- ジョブの完了時間: エクスポートされるデータの量によって、ジョブの完了時間が決まります。1 つのジョブに最長で 18 時間かかることがあります。
- エクスポート形式とデータスコープ: API は、次の制限と機能を備えた一括エクスポートとポイントインタイム エクスポートをサポートしています。
- 未加工ログのみ: エクスポートできるのは未加工ログのみです(UDM ログ、UDM イベント、検出はエクスポートできません)。UDM データをエクスポートする方法については、セルフマネージド BigQuery プロジェクトにエクスポートするをご覧ください。
- ファイル形式とデータ圧縮: API は、
logdata-SHARD_INDEX.csvという名前のファイル内に、圧縮されていない改行区切りの未加工のログ文字列としてデータをエクスポートします(シャードあたり約 100 MB のサイズを目標としています)。CSV ファイル名拡張子にかかわらず、ファイルはカンマ区切りの列としてフォーマットされません。各未加工ログエントリ(未加工 JSON オブジェクト、syslog 行、CEF レコードなど)は、埋め込まれた改行をエスケープせずに、改行文字(\n)が続く逐語的に書き込まれます。そのため、複数行の未加工ログ(XML ペイロードやスタック トレースなど)は、シャード ファイル内の複数の行にまたがることができます。出力ファイル形式は API で変更できません。Apache Parquet などの圧縮されたカラム型形式でアーカイブを保存するには、エクスポート ジョブがFINISHED_SUCCESSに達した後に、ダウンストリームの圧縮ステップを実行します。
前提条件とアーキテクチャ
このセクションでは、データ エクスポート ツール API を使用するためのシステム アーキテクチャと必要な要件の概要を説明し、システム アーキテクチャの詳細について説明します。この情報を使用して、環境が正しく構成されていることを確認します。
データ エクスポート API を使用する前に、次の前提条件の手順を完了して、Google Cloud Storage の宛先を設定し、必要な権限を付与します。
ユーザーに権限を付与します。データ エクスポート API を使用するには、Google SecOps テナントにリンクされている BYOP Google Cloud プロジェクトに次の権限が必要です。
- chronicle.dataExports.fetchServiceAccountForDataExport
- chronicle.dataExports.create
- chronicle.dataExports.cancel
- chronicle.dataExports.get
- chronicle.dataExports.list
これらの権限は、次の IAM 事前定義ロールの一部です。
- Chronicle API 管理者: API を使用してエクスポート ジョブを作成、更新、キャンセル、表示するための完全な権限を付与します。このロールはグローバル アクセスを付与します。
- Chronicle API 閲覧者: API を使用してジョブ構成と履歴を表示するための読み取り専用権限を付与します。
restrictedDataAccessロールがない場合、このロールを持つユーザーはすべてのデータを表示できます(+ 別のロールを追加の手順と条件の追加をご覧ください)。
ユーザーにデータ RBAC スコープを適用する。ユーザーを特定のデータアクセス スコープに制限する手順は次のとおりです。
- 適用するデータ RBAC スコープが、[設定] > [アクセス管理] > [データアクセス] > [スコープ] で作成されていることを確認します。ユーザーに割り当てる各スコープのフルネームをメモします。
データ エクスポート管理用の Identity and Access Management(IAM)カスタムロールを作成します。事前定義ロールでは、過剰なアクセス権が付与される可能性や、特定の権限の組み合わせがない可能性があります。そのため、次の手順に沿って、スコープ内のコンテキストでデータ エクスポートを管理するためにカスタマイズされたカスタムロールを作成します。
- Google Cloud コンソールで、[IAM と管理] > [ロール] に移動します。
- [+ ロールを作成] をクリックします。
- タイトルを入力します(例:
SecOps Scoped Data Export User)。 - ID(例:
secopsScopedDataExportUser)を入力します。 - [+ 権限を追加] をクリックします。
- Chronicle 権限をフィルタし、最初のステップ(API ユーザーに権限を付与する)に記載されている関連する権限を追加します。
- [作成] をクリックします。
ユーザーに IAM ロールを付与する。[IAM] ページで、次の操作を行って、必要なロールをユーザーに割り当てます。
- [IAM と管理]、[IAM] の順にクリックします。
- [+ アクセスを許可] をクリックします。
- [新しいプリンシパル] に、ユーザーのメールアドレスを入力します。
ロールを割り当てる手順は次のとおりです。
- 作成したカスタムロール(
SecOps Scoped Data Export Userなど)を追加します。 - [+ 別のロールを追加] をクリックし、Chronicle API 制限付きデータアクセス(
restrictedDataAccess)ロールを追加します。このロールは、ユーザーをデータスコープの対象としてマークするために重要です。
- 作成したカスタムロール(
Chronicle API Restricted Data Accessロール バインディングに IAM 条件を追加します。ユーザーを特定のデータスコープにリンクする手順は次のとおりです。- [IAM 条件を追加] をクリックします。
- 条件作成ツールまたは条件エディタを使用して、許可されるスコープを定義します。このとき、最初の手順で作成したスコープ名をリソース名として使用します。たとえば、
scope_testという名前のスコープを使用するには、条件resource.name.endsWith("/dataAccessScopes/scope_test")を設定します。
Data Export API でデータ RBAC がどのように実装されているかについては、データ RBAC が Data Export API にどのように適用されるかをご覧ください。
Google Cloud Storage バケットを作成します。 Google Cloudプロジェクトで、Google SecOps テナントと同じリージョンに新しい Google Cloud Storage バケット(エクスポートされたデータの宛先)を作成します。不正アクセスを防ぐために、非公開にします。長期アーカイブの場合は、初期エクスポートの書き込みと検証(またはオプションの下流の Parquet 圧縮)に
STANDARDデフォルト ストレージ クラスを使用するようにバケットを構成し、オブジェクトのライフサイクル管理(SetStorageClassルール)を使用してオブジェクトをCOLDLINEストレージまたはARCHIVEストレージに移行します。詳細については、バケットを作成するをご覧ください。サービス アカウントに権限を付与する。Google SecOps テナントにリンクされている Google SecOps サービス アカウントに、バケットにデータを書き込むために必要な IAM ロールを付与するには、次の操作を行います。
FetchServiceAccountForDataExportAPI エンドポイントを呼び出して、Google SecOps インスタンスの一意のサービス アカウントを特定します。API はサービス アカウントのメールアドレスを返します。リクエストの例:
{ "parent": "projects/myproject/locations/us/instances/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }レスポンスの例:
{ "service_account_email": "service-1234@gcp-sa-chronicle.iam.gserviceaccount.com" }宛先の Google Cloud Storage バケットに対して、Google SecOps サービス アカウント プリンシパルに次の IAM ロールを付与します。これにより、Google SecOps サービスはエクスポートされたデータファイルを Google Cloud Storage バケットに書き込むことができます。
Storage object administrator (roles/storage.objectAdmin)Legacy bucket reader (roles/storage.legacyBucketReader)
詳細については、Google SecOps サービス アカウントへのアクセス権を付与するをご覧ください。
認証を完了します。データ エクスポート API は呼び出しを認証します。この認証を設定するには、次のセクションの手順に沿って操作します。
主なユースケースとコア ワークフロー
Data Export API には、データ エクスポート ジョブを作成し、一括データ エクスポートのライフサイクル全体を管理するための一連のエンドポイントが用意されています。すべての操作は API 呼び出しを使用して行います。
以降のユースケースでは、データ エクスポート ジョブの作成、モニタリング、管理の方法について説明します。
新しいデータ エクスポート ジョブを作成する
システムは、データ エクスポート ジョブの仕様を親リソースの Google SecOps インスタンスに保存します。このインスタンスは、エクスポート ジョブのログデータのソースです。
Google SecOps インスタンスの一意のサービス アカウントを特定する方法については、FetchServiceAccountForDataExports をご覧ください。
新しいエクスポートを開始するには、
POSTリクエストをdataExports.createエンドポイントに送信します。詳細については、CreateDataExportエンドポイントをご覧ください。
データ エクスポート ジョブのステータスをモニタリングする
特定のエクスポート ジョブのデータ エクスポート ジョブの詳細とステータスを表示したり、フィルタを構成して特定のタイプのジョブを表示したりできます。
特定のエクスポート ジョブを表示する方法については、GetDataExport をご覧ください。
フィルタを使用して特定のタイプのデータ エクスポート ジョブを一覧表示する方法については、ListDataExport をご覧ください。
キューに格納されたジョブをキャンセルする
ステータスが IN_QUEUE のジョブはキャンセルできます。
キューに格納されたジョブをキャンセルする方法については、CancelDataExport をご覧ください。
データ RBAC がデータ エクスポート API に適用される仕組み
エクスポート ジョブは、エクスポート ジョブを作成するユーザーのデータ RBAC スコープを継承します。これにより、不正なデータ抽出が防止されます。
データ アクセス スコープで許可されている範囲を超えるデータをエクスポートしようとすると、API はエクスポート ジョブの実行時にそのようなデータを自動的に除外します。完了したジョブ(ステータスが FINISHED_SUCCESS のジョブ)のメタデータの dataRbacFiltered フィールドの値は、データが除外されたかどうかを示します。dataRbacFiltered が true の場合、エクスポート ジョブに選択されたデータの一部またはすべてが、ジョブ作成者に適用されるデータ RBAC スコープ外であったため、除外されました。dataRbacFiltered が false の場合、エクスポート ジョブはデータ RBAC スコープの制限の影響を受けず、ジョブの一部として含まれるすべてのデータが正常にエクスポートされました。
API は、ジョブの作成時に作成者に適用されるデータ RBAC スコープを適用します。データ RBAC スコープの変更は、すでに作成されているジョブに遡及的に適用されません。
データ RBAC の詳細については、データ RBAC の概要をご覧ください。
一般的な問題のトラブルシューティング
API は、問題の診断に役立つ詳細なエラー メッセージを提供します。
| 正規コード | エラー メッセージ |
|---|---|
INVALID_ARGUMENT |
INVALID_REQUEST: Invalid request parameter PARAMETER_1, PARAMETER_2, ... PARAMETER_N. Please fix the request parameters and try again. |
PERMISSION_DENIED |
INSUFFICIENT_PERMISSIONS: Unable to validate request with the current CMEK key. Please fix the CMEK key and try again |
NOT_FOUND |
BUCKET_NOT_FOUND: The destination Google Cloud Storage bucket BUCKET_NAME does not exist. Please create the destination Google Cloud Storage bucket and try again. |
NOT_FOUND |
REQUEST_NOT_FOUND: The dataExportId:DATA_EXPORT_ID does not exist. Please add a valid dataExportId and try again. |
FAILED_PRECONDITION |
BUCKET_INVALID_REGION: The Google Cloud Storage bucket BUCKET_ID's region:REGION_1 is not the same region as the SecOps tenant region:REGION_2. Please create the Google Cloud Storage bucket in the same region as SecOps tenant and try again. |
FAILED_PRECONDITION |
INSUFFICIENT_PERMISSIONS: The Service Account P4SA does not have storage.objects.create, storage.objects.get and storage.buckets.get permissions on the destination Google Cloud Storage bucket BUCKET_NAME. Please provide the required access to the Service Account and try again. |
FAILED_PRECONDITION |
INVALID_CANCELLATION: The request status is in the STATUS stage and can't be cancelled. You can only cancel the request if the status is in the IN_QUEUE stage. |
RESOURCE_EXHAUSTED |
CONCURRENT_REQUEST_LIMIT_EXCEEDED: Maximum concurrent requests limit LIMIT reached for the request size SIZE_LIMIT. Please wait for the existing requests to complete and try again. |
RESOURCE_EXHAUSTED |
REQUEST_SIZE_LIMIT_EXCEEDED: The estimated export volume: ESTIMATED_VOLUME for the request is greater than maximum allowed export volume: ALLOWED_VOLUME per request. Please try again with a request within the allowed export volume limit. |
INTERNAL |
INTERNAL_ERROR: An Internal error occurred. Please try again. |
さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。