Mengekspor log mentah ke bucket Google Cloud Storage yang dikelola sendiri

Didukung di:

Data Export API memfasilitasi ekspor massal data keamanan Anda dari Google Security Operations ke bucket Cloud Storage Google yang Anda kontrol. Kemampuan ini mendukung retensi data jangka panjang yang penting, serta mendukung analisis forensik historis, dan persyaratan kepatuhan yang ketat (seperti SOX dan GDPR).

Untuk mengetahui informasi referensi API yang mendetail, lihat Data Export API (enhanced).

Data Export API menyediakan solusi yang skalabel dan andal untuk ekspor data point-in-time dan menangani permintaan hingga 100 TB.

Sebagai pipeline terkelola, pipeline ini menawarkan fitur penting tingkat perusahaan, termasuk:

  • Percobaan ulang otomatis pada error sementara
  • Pemantauan status tugas yang komprehensif
  • Jejak audit lengkap untuk setiap tugas ekspor

API ini mempartisi data yang diekspor secara logis berdasarkan tanggal dan waktu dalam bucket Google Cloud Storage Anda.

Fitur ini memungkinkan Anda membangun alur kerja offload data berskala besar. Google SecOps mengelola kompleksitas proses ekspor untuk memberikan stabilitas dan performa.

Manfaat utama

API Ekspor Data memberikan solusi yang tangguh dan dapat diaudit untuk mengelola siklus proses data keamanan Anda, dengan manfaat utama berikut:

  • Keandalan: layanan ini menangani transfer data berskala besar. Sistem ini menggunakan strategi backoff eksponensial untuk otomatis mencoba ulang tugas ekspor yang mengalami masalah sementara (misalnya, masalah jaringan sementara), sehingga membuatnya tangguh. Jika tugas ekspor Anda gagal karena error sementara, tugas tersebut akan otomatis mencoba ulang beberapa kali. Jika tugas gagal secara permanen setelah semua percobaan ulang, sistem akan memperbarui statusnya menjadi FINISHED_FAILURE, dan respons API untuk tugas tersebut akan berisi pesan error mendetail yang menjelaskan penyebabnya.
  • Kemampuan audit yang komprehensif: untuk memenuhi standar kepatuhan dan keamanan yang ketat, sistem mencatat setiap tindakan yang terkait dengan tugas ekspor dalam jejak audit yang tidak dapat diubah. Jejak ini mencakup pembuatan, mulai, keberhasilan, atau kegagalan setiap tugas, beserta pengguna yang memulai tindakan, stempel waktu, dan parameter tugas.

  • Dioptimalkan untuk performa dan skala: API ini menggunakan sistem pengelolaan tugas yang tangguh. Sistem ini mencakup antrean dan prioritas untuk memberikan stabilitas platform dan mencegah satu tenant memonopoli resource.

  • Peningkatan integritas dan aksesibilitas data: sistem otomatis mengatur data ke dalam struktur direktori logis dalam bucket Google Cloud Storage, yang membantu Anda menemukan dan mengkueri rentang waktu tertentu untuk analisis historis.

  • Keamanan: API ini dirancang agar sepenuhnya mematuhi kunci enkripsi yang dikelola pelanggan (CMEK) (keamanan zero-trust) dan RBAC data (akses hak istimewa terendah). Tugas ekspor mewarisi cakupan visibilitas data pengguna yang memicu permintaan untuk mencegah ekstraksi data yang tidak sah. Pipeline ekspor juga terintegrasi sepenuhnya dengan Google Cloud Key Management Service, dan data tetap dienkripsi dalam penyimpanan di bucket Google Cloud Storage menggunakan kunci Anda sendiri.

Istilah dan konsep utama

  • Tugas ekspor: satu operasi asinkron untuk mengekspor rentang waktu tertentu dari data log ke bucket Google Cloud Storage. Sistem melacak setiap tugas dengan dataExportId yang unik.
  • Status tugas: status tugas ekspor saat ini dalam siklus prosesnya (misalnya, IN_QUEUE, PROCESSING, FINISHED_SUCCESS).
  • Bucket Google Cloud Storage: bucket Google Cloud Storage milik pengguna yang berfungsi sebagai tujuan untuk data yang diekspor.
  • Jenis log: kategori log tertentu yang dapat Anda ekspor (misalnya, NIX_SYSTEM, WINDOWS_DNS, CB_EDR). Untuk mengetahui detail selengkapnya, lihat daftar semua jenis log yang didukung.

Memahami struktur data yang diekspor

Setelah tugas berhasil diselesaikan, sistem akan menulis data ke bucket Cloud Storage Google Anda. Data lakehouse menggunakan struktur direktori tertentu yang dipartisi untuk menyederhanakan akses dan kueri data.

Struktur jalur direktori: gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/logdata-SHARD_INDEX.csv

Dengan:

  • GCS_BUCKET_NAME: mengacu pada nama bucket Google Cloud Storage Anda.
  • EXPORT_JOB_NAME: mengacu pada UUID dataExportId unik tugas ekspor Anda (tanpa tanda hubung di jalur objek).
  • LOGTYPE: mengacu pada nama jenis log untuk data yang diekspor (misalnya, GCP_DNS atau WINDOWS_DNS).
  • EVENT_TIME_BUCKET: mengacu pada bucket jam stempel waktu peristiwa log yang diekspor, yang dibulatkan ke bawah ke awal jam UTC (YYYY/MM/DD/HH/00/00). Misalnya, 2025/08/25/01/00/00 berisi log dengan stempel waktu peristiwa antara 01:00:00 UTC dan 01:59:59 UTC pada 25 Agustus 2025.
  • EPOCH_EXECUTION_TIME: mengacu pada stempel waktu epoch Unix 20 digit yang diisi dengan angka nol dalam mikrodetik yang menunjukkan kapan eksekusi tugas ekspor dimulai (misalnya, 00001756083600000000).
  • logdata-SHARD_INDEX.csv: mengacu pada file yang di-sharding dengan indeks 0 yang berisi log mentah (misalnya, logdata-0.csv dan logdata-1.csv). Setiap shard file menargetkan ukuran perkiraan 100 MB.

Contoh jalur objek yang diekspor:

gs://my-archive-bucket/b4a3c2d1e8f76a5b4c3d2e1f0a9b8c7d/GCP_DNS/2025/08/25/01/00/00/00001756083600000000/logdata-0.csv

Manifes penyelesaian ekspor (exported_paths.txt):

Saat tugas ekspor selesai dengan status FINISHED_SUCCESS dan menulis setidaknya satu file log, pipeline juga menulis file manifes ke gs://GCS_BUCKET_NAME/EXPORT_JOB_NAME/exported_paths.txt (jika tidak ada log yang cocok dengan filter ekspor atau rentang waktu, tidak ada file manifes yang ditulis dan dataExportStatus.exportedGlobPatterns kosong). Setiap baris di exported_paths.txt mencantumkan pola glob menggunakan awalan /bigstore/ (/bigstore/GCS_BUCKET_NAME/EXPORT_JOB_NAME/LOGTYPE/EVENT_TIME_BUCKET/EPOCH_EXECUTION_TIME/*, yang dipetakan ke gs://GCS_BUCKET_NAME/.../*) untuk direktori partisi per jam yang ditulis oleh tugas. Tugas otomatisasi atau pemadatan downstream dapat membaca manifes ini untuk menghitung semua partisi yang diekspor tanpa mencantumkan seluruh bucket.

Performa dan batasan

Layanan ini memiliki batasan khusus berikut untuk memastikan stabilitas platform dan alokasi resource yang adil:

  • Volume data maksimum per tugas: setiap tugas ekspor dapat meminta data hingga 100 TB. Untuk set data yang lebih besar, Google merekomendasikan untuk membagi ekspor menjadi beberapa tugas dengan rentang waktu yang lebih kecil.
  • Tugas serentak: setiap tenant pelanggan dapat menjalankan atau mengantrekan maksimum tiga tugas ekspor secara serentak. Sistem akan menolak permintaan pembuatan tugas baru yang melebihi batas ini.
  • Waktu penyelesaian tugas: volume data yang diekspor menentukan waktu penyelesaian tugas. Satu tugas dapat memerlukan waktu hingga 18 jam.
  • Format ekspor dan cakupan data: API mendukung ekspor massal pada waktu tertentu, dengan batasan dan fitur berikut:
    • Hanya log mentah: Anda hanya dapat mengekspor log mentah, (bukan log UDM, peristiwa UDM, atau deteksi). Untuk mempelajari cara mengekspor data UDM, lihat Mengekspor ke project BigQuery yang dikelola sendiri.
    • Format file dan kompresi data: API mengekspor data sebagai string log mentah yang tidak dikompresi dan dibatasi baris baru di dalam file bernama logdata-SHARD_INDEX.csv (menargetkan ukuran perkiraan 100 MB per shard). Meskipun memiliki ekstensi nama file CSV, file tersebut tidak diformat sebagai kolom yang dipisahkan koma: setiap entri log mentah (misalnya, objek JSON mentah, baris syslog, atau data CEF) ditulis verbatim diikuti dengan karakter baris baru (\n) tanpa meng-escape baris baru yang disematkan, sehingga log mentah multi-baris (seperti payload XML atau stack trace) dapat mencakup beberapa baris dalam file shard. Format file output tidak dapat diubah melalui API; untuk menyimpan arsip dalam format kolom terkompresi seperti Apache Parquet, jalankan langkah pemadatan downstream setelah tugas ekspor mencapai FINISHED_SUCCESS.

Prasyarat dan arsitektur

Bagian ini menguraikan arsitektur sistem dan persyaratan yang diperlukan untuk menggunakan API Ekspor Data serta menjelaskan arsitektur sistem secara mendetail. Gunakan informasi ini untuk memverifikasi bahwa lingkungan Anda telah dikonfigurasi dengan benar.

Sebelum menggunakan Data Export API, selesaikan langkah-langkah prasyarat berikut untuk menyiapkan tujuan Google Cloud Storage dan memberikan izin yang diperlukan:

  1. Memberikan izin kepada pengguna. Untuk menggunakan Ekspor Data API, Anda memerlukan izin berikut di project BYOP Google Cloud yang ditautkan ke tenant Google SecOps Anda:

    Izin ini merupakan bagian dari peran IAM yang telah ditetapkan berikut:

    • Chronicle API Admin: memberikan izin penuh untuk membuat, memperbarui, membatalkan, dan melihat tugas ekspor menggunakan API. Peran ini memberikan akses global.
    • Chronicle API Viewer: memberikan akses hanya baca untuk melihat konfigurasi dan histori tugas menggunakan API. Tanpa peran restrictedDataAccess, pengguna dengan peran ini dapat melihat semua data (lihat langkah + Add Another Role dan tambahkan kondisi).
  2. Terapkan cakupan RBAC data ke pengguna. Lakukan hal berikut untuk membatasi pengguna ke cakupan akses data tertentu:

    1. Pastikan cakupan RBAC data yang ingin Anda terapkan sudah dibuat di bagian Setelan > Pengelolaan Akses > Akses Data > Cakupan. Catat nama lengkap setiap cakupan yang ingin Anda tetapkan kepada pengguna.
    2. Membuat peran khusus Identity and Access Management (IAM) untuk pengelolaan ekspor data. Karena peran yang telah ditetapkan mungkin memberikan terlalu banyak akses, atau tidak memiliki kombinasi izin tertentu, lakukan hal berikut untuk membuat peran khusus yang disesuaikan untuk mengelola ekspor data dalam konteks yang tercakup:

      1. Di konsol Google Cloud , buka IAM & Admin > Roles.
      2. Klik + Create Role.
      3. Masukkan judul (misalnya, SecOps Scoped Data Export User).
      4. Masukkan ID (misalnya, secopsScopedDataExportUser).
      5. Klik + Add Permissions.
      6. Filter untuk izin Chronicle dan tambahkan izin yang relevan yang tercantum di langkah pertama (Memberikan izin kepada pengguna API).
      7. Klik Create.
  3. Memberikan peran IAM kepada pengguna. Di halaman IAM, lakukan hal berikut untuk menetapkan peran yang diperlukan kepada pengguna Anda:

    1. Buka IAM & Admin > IAM.
    2. Klik + Grant Access.
    3. Untuk New principals, masukkan alamat email pengguna.
    4. Lakukan hal berikut untuk menetapkan peran:

      1. Tambahkan peran khusus yang Anda buat (misalnya, SecOps Scoped Data Export User).
      2. Klik + Add Another Role dan tambahkan peran Chronicle API Restricted Data Access (restrictedDataAccess). Peran ini sangat penting untuk menandai pengguna sebagai subjek cakupan data.
  4. Tambahkan IAM Condition ke binding peran Chronicle API Restricted Data Access. Lakukan tindakan berikut untuk menautkan pengguna ke cakupan data tertentu:

    1. Klik Add IAM Condition.
    2. Gunakan Pembuat kondisi atau Editor kondisi untuk menentukan cakupan yang diizinkan, menggunakan nama cakupan yang dibuat pada langkah pertama sebagai Nama resource. Misalnya, untuk menggunakan cakupan bernama scope_test, tetapkan kondisi resource.name.endsWith("/dataAccessScopes/scope_test").

    Untuk mempelajari lebih lanjut cara RBAC data diterapkan untuk API Ekspor Data, lihat Cara RBAC data diterapkan ke API Ekspor Data.

  5. Membuat bucket Google Cloud Storage. Di project Google Cloud Anda, buat bucket Google Cloud Storage baru (tujuan untuk data yang diekspor) di region yang sama dengan tenant Google SecOps Anda. Jadikan pribadi, untuk mencegah akses yang tidak sah. Untuk pengarsipan jangka panjang, konfigurasikan bucket dengan kelas penyimpanan default STANDARD untuk penulisan dan verifikasi ekspor awal (atau pemadatan Parquet downstream opsional), dan gunakan Object Lifecycle Management (aturan SetStorageClass) untuk mentransisikan objek ke penyimpanan COLDLINE atau ARCHIVE. Untuk mengetahui detailnya, lihat Membuat bucket.

  6. Memberikan izin ke Akun Layanan. Lakukan hal berikut untuk memberikan peran IAM yang diperlukan kepada Akun Layanan Google SecOps, yang ditautkan ke tenant Google SecOps Anda, untuk menulis data ke bucket Anda:

    1. Panggil endpoint API FetchServiceAccountForDataExport untuk mengidentifikasi Akun Layanan unik instance Google SecOps Anda. API akan menampilkan email Akun Layanan.

      Contoh permintaan:

      {
        "parent": "projects/myproject/locations/us/instances/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      }
      

      Contoh respons:

      {
        "service_account_email": "service-1234@gcp-sa-chronicle.iam.gserviceaccount.com"
      }
      
    2. Berikan peran IAM berikut kepada akun utama Akun Layanan Google SecOps untuk bucket Google Cloud Storage tujuan, yang memungkinkan layanan Google SecOps menulis file data yang diekspor ke bucket Google Cloud Storage Anda:

      • Storage object administrator (roles/storage.objectAdmin)
      • Legacy bucket reader (roles/storage.legacyBucketReader)

      Untuk mengetahui detailnya, lihat Memberikan akses ke Akun Layanan Google SecOps.

  7. Selesaikan autentikasi. API Ekspor Data mengautentikasi panggilan Anda. Untuk menyiapkan autentikasi ini, ikuti petunjuk di bagian berikut:

    1. Metode autentikasi untuk layanan Google Cloud
    2. Kredensial default aplikasi

Kasus penggunaan utama dan alur kerja inti

Data Export API menyediakan serangkaian endpoint untuk membuat tugas ekspor data dan mengelola seluruh siklus proses ekspor data massal. Anda melakukan semua interaksi menggunakan panggilan API.

Kasus penggunaan berikut menjelaskan cara membuat, memantau, dan mengelola tugas ekspor data.

Membuat tugas ekspor data baru

Sistem menyimpan spesifikasi tugas ekspor data di instance Google SecOps resource induk. Instance ini adalah sumber data log untuk tugas ekspor.

Memantau status tugas ekspor data

Anda dapat melihat detail dan status tugas ekspor data untuk tugas ekspor tertentu, atau mengonfigurasi filter untuk melihat jenis tugas tertentu.

  • Untuk mempelajari cara melihat tugas ekspor tertentu, lihat GetDataExport.

  • Untuk mempelajari cara mencantumkan jenis tugas ekspor data tertentu menggunakan filter, lihat ListDataExport.

Membatalkan tugas dalam antrean

Anda dapat membatalkan tugas saat statusnya IN_QUEUE.

Untuk mempelajari cara membatalkan tugas dalam antrean, lihat CancelDataExport.

Cara penerapan RBAC data ke API Ekspor Data

Tugas ekspor mewarisi cakupan RBAC data pengguna yang membuat tugas ekspor, sehingga mencegah ekstraksi data yang tidak sah.

Jika Anda mencoba mengekspor data yang berada di luar cakupan akses data yang diizinkan, API akan otomatis mengecualikan data tersebut saat menjalankan tugas ekspor. Nilai kolom dataRbacFiltered dalam metadata tugas yang telah selesai (yaitu, tugas dengan status FINISHED_SUCCESS) menunjukkan apakah data dikecualikan. Jika dataRbacFiltered adalah true, beberapa atau semua data yang dipilih untuk tugas ekspor akan dikecualikan karena berada di luar cakupan RBAC data yang berlaku untuk pembuat tugas. Jika dataRbacFiltered adalah false, tugas ekspor tidak terpengaruh oleh batasan cakupan RBAC data, dan semua data yang disertakan sebagai bagian dari tugas berhasil diekspor.

API menerapkan cakupan RBAC data yang berlaku untuk pembuat pada saat pembuatan tugas. Setiap perubahan dalam cakupan RBAC data tidak berlaku secara retroaktif untuk tugas yang telah dibuat.

Untuk mempelajari lebih lanjut RBAC data, lihat Ringkasan RBAC data.

Memecahkan masalah umum

API ini memberikan pesan error yang mendetail untuk membantu mendiagnosis masalah.

Kode kanonis Pesan error
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.

Perlu bantuan lain? Dapatkan jawaban dari anggota Komunitas dan profesional Google SecOps.