Bermigrasi dari SIEM API lama ke Chronicle API

Didukung di:

Google SecOps SIEM

Perhatian: API lama dapat berdampak pada keamanan dan performa. SIEM API lama—Backstory API (termasuk Customer Management API) dan Ingestion API—akan dihentikan penggunaannya dan tidak berfungsi sepenuhnya pada 20 Juli 2027. Penggunaan API ini secara terus-menerus dapat menyebabkan masalah performa atau perilaku yang tidak terduga dalam produk. Anda harus segera memigrasikan semua panggilan terprogram API lama ke Chronicle API modern untuk memastikan stabilitas, keamanan, dan performa platform.

Dokumen ini membantu Anda mengelola aplikasi yang memanggil salah satu SIEM API lama (Backstory API dan Ingestion API). Dokumen ini menjelaskan langkah-langkah yang harus Anda ikuti untuk menyiapkan akses terprogram dan memperbarui referensi dari endpoint SIEM API lama ke endpoint Chronicle API modern.

Untuk ringkasan singkat proses migrasi, tonton video yang disematkan.

Permukaan Chronicle API memperkenalkan beberapa peningkatan yang dirancang untuk menyederhanakan proses pengembangan Anda dan selaras dengan Google Cloud standar API untuk meningkatkan keandalan, keamanan, performa, dan integrasi yang lebih kuat dengan Cloud Audit Logs, Cloud Monitoring, Cloud Identity, dan Identity and Access Management (IAM). API ini juga mengatasi banyak batasan dan kompleksitas API lama.

Apa saja yang berubah

Semua permintaan terprogram ke endpoint Backstory API dan Ingestion API lama harus bertransisi ke Chronicle API modern. Jika organisasi Anda menggunakan integrasi kustom, skrip otomatisasi, atau alat pihak ketiga yang melakukan panggilan ke endpoint lama ini, Anda harus memperbarui beban kerja tersebut untuk menggunakan endpoint dan alur autentikasi modern sebelum 20 Juli 2027. Selain itu, jika organisasi Anda menggunakan Google Security Operations SOAR, Anda harus memperbarui integrasi dan konektor SOAR (seperti integrasi Google Chronicle) untuk menggunakan Chronicle API. Untuk mengetahui detailnya, lihat Memigrasikan integrasi SOAR.

Yang tidak berubah

Tindakan yang dilakukan langsung di antarmuka pengguna (UI) Google Security Operations sudah memanggil Chronicle API modern. Jika organisasi Anda hanya berinteraksi dengan Google SecOps melalui UI, atau jika integrasi Anda sudah memanggil endpoint Chronicle API, Anda tidak perlu melakukan tindakan apa pun.

Perubahan dan peningkatan utama

Tabel berikut menunjukkan perbedaan utama antara SIEM API lama dan Chronicle API:

Area fitur	Legacy SIEM API	Chronicle API	Detail
Pengelolaan kredensial	Proses manual yang melibatkan perwakilan Google	Pengelolaan akun layanan, kredensial, dan izin IAM secara mandiri	Pengelolaan kredensial dan IAM layanan mandiri menyederhanakan proses aktivasi dan menghilangkan ketergantungan pada permintaan dukungan manual.
Standar kepatuhan	Dukungan terbatas	Dukungan bawaan untuk kontrol Residensi Data, Kontrol Layanan VPC, Transparansi Akses, CMEK, dan FedRAMP	Kontrol infrastruktur bawaan modern memenuhi standar kepatuhan dan peraturan industri.
Logging dan audit	Aliran audit lama	Cloud Audit Logs yang terintegrasi ke dalam Google Cloud project Anda	Integrasi langsung menyediakan audit trail dan pemantauan terpusat.
Autentikasi	Token API dan kredensial akun layanan	OAuth 2.0 dengan dukungan untuk metode autentikasi modern, termasuk Workload Identity dan akun layanan seperti yang dijelaskan dalam Autentikasi untuk Google Cloud API dan layanan	Metode autentikasi modern ini memberikan keamanan yang lebih baik dan menstandardisasi alur kredensial.
Model data dan desain API	Struktur datar dan eksklusif	Desain berorientasi resource, arsitektur RESTful, dan penamaan standar yang mengikuti AIP	Desain modern ini meningkatkan konsistensi data, membuat API lebih intuitif, dan menyederhanakan manipulasi objek.
Penamaan endpoint	Tidak konsisten	RESTful dan terstandarisasi	Penamaan yang konsisten membuat API lebih intuitif dan mudah diintegrasikan.
Ekosistem	Sangat terbatas	Integrasi dengan MCP, Terraform, library klien, dan SDK	Kompatibilitas luas dengan alat cloud modern dan framework otomatisasi.
Otorisasi partner	Token partner atau kunci API yang digunakan secara langsung di seluruh kode pelanggan	Delegasi IAM lintas project untuk resource tenant; metode TenantService yang tercakup dalam partner	Metode TenantService berjalan di project partner. Semua API tenant lainnya memerlukan delegasi IAM lintas project yang diberikan oleh tenant di project tenant.

Otorisasi partner

Untuk alur kerja partner multi-tenant, otorisasi di Chronicle API bergantung pada kepemilikan resource. Project yang menghosting resource menentukan kredensial dan izin IAM yang diperlukan partner. Mencakup operasi tenant ke kredensial yang didelegasikan tenant selaras dengan prinsip keamanan inti bahwa partner tidak boleh dapat mengakses, mengambil, atau mengubah data tenant tanpa izin eksplisit yang diberikan oleh tenant. Tabel berikut membandingkan otorisasi partner di Backstory API lama dan Chronicle API:

API	Metode	Cakupan resource	Otorisasi
Legacy Backstory API	/v1/partner/customer/* endpoint	Semua kode pelanggan partner	Partner memanggil endpoint ini secara langsung dengan token partner atau kunci API mereka sendiri.
Chronicle API: TenantService	CreateTenant, ListTenants, dan UpdateTenant	Instance partner: projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/*	Partner memanggil metode ini secara langsung dengan akun layanan atau kredensial mereka sendiri yang memiliki izin chronicle.googleapis.com/tenants.* dalam project partner.
Chronicle API: layanan lain, seperti InstanceService dan ForwarderService	GetInstance, UpdateInstance, GenerateForwarderFiles, dan metode lainnya yang tercakup dalam cakupan tenant	Instance tenant: projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/...	Kredensial partner saja tidak dapat mengakses atau mengubah data tenant. Administrator tenant harus memberikan peran IAM, seperti roles/chronicle.admin, roles/chronicle.viewer, atau peran kustom, ke akun layanan partner atau principal Workload Identity Federation di project Google Cloud tenant.

Jadwal penghentian

SIEM API lama dijadwalkan akan dihentikan pada 20 Juli 2027. Sebaiknya selesaikan migrasi Anda sebelum tanggal ini untuk menghindari gangguan layanan:

• Mulai 26 Oktober 2026, Anda tidak dapat lagi memanggil API lama (Backstory API dan Ingestion API) dari instance baru.
• Paling lambat 20 Juli 2027, Anda harus memigrasikan semua instance yang ada ke Chronicle API, karena API lama tidak akan tersedia lagi.

Sebelum memulai

Sebelum bermigrasi ke Chronicle API, pastikan Anda menyelesaikan hal berikut:

Catatan: Jika Anda menggunakan Managed Instance, Penyedia Layanan Keamanan Terkelola (MSSP) Anda mungkin telah menyelesaikan beberapa langkah ini untuk Anda.

• Men-deploy di infrastruktur SIEM modern: Pastikan instance di-deploy di project Google Cloud Anda atau partner MSSP Anda menggunakan infrastruktur SIEM modern. Untuk petunjuk mendetail, lihat Ringkasan migrasi SIEM.
• Aktifkan Chronicle API: Di Google Cloud konsol, buka project yang menghosting instance Anda dan aktifkan Chronicle API (chronicle.googleapis.com). Untuk mengetahui detailnya, lihat Mengaktifkan API di project Google Cloud .
• Identifikasi integrasi SOAR: Jika lingkungan Anda menghubungkan Google SecOps SOAR ke Google Security Operations SIEM, verifikasi konektor yang ada. Untuk mengetahui detailnya, lihat Memigrasikan integrasi SOAR.

Memigrasikan integrasi SOAR

Jika organisasi Anda menghubungkan Google SecOps SOAR ke Google SecOps SIEM, Anda harus memigrasikan integrasi dan konektor SOAR (seperti integrasi Google Chronicle) untuk menggunakan Chronicle API.

Untuk mengetahui petunjuk mendetail tentang mengupgrade integrasi dan konektor Google Chronicle agar menggunakan Chronicle API—termasuk menemukan root Chronicle API lingkungan Anda dan mengonfigurasi kredensial autentikasi—lihat Migrasi dari Backstory API ke Chronicle API.

Bermigrasi ke Chronicle API

Migrasikan skrip dan integrasi kustom Anda dari API lama ke Chronicle API dengan menyelesaikan langkah-langkah berikut:

1. Audit penggunaan API: Identifikasi semua skrip dan integrasi kustom di lingkungan Anda yang memanggil endpoint lama.
2. Siapkan autentikasi dan otorisasi: Konfigurasi lingkungan Anda untuk mengautentikasi dan mengizinkan permintaan ke Chronicle API.
3. Memetakan endpoint dan memperbarui URL: Ganti endpoint lama dengan endpoint regional modern yang setara.
4. Perbarui logika API: Sesuaikan payload permintaan dan penanganan respons agar sesuai dengan model data API modern.
5. Uji integrasi Anda: Validasi perubahan di lingkungan staging sebelum men-deploy ke produksi.

Mengaudit penggunaan API

Audit lingkungan Anda untuk mengidentifikasi skrip atau integrasi kustom yang memanggil backstory.googleapis.com atau malachiteingestion-pa.googleapis.com. Anda dapat mengidentifikasi integrasi ini dengan meninjau codebase, skrip otomatisasi, dan alat pihak ketiga. Jika organisasi Anda juga menggunakan Google SecOps SOAR, lihat Memigrasikan integrasi SOAR.

Menyiapkan autentikasi dan otorisasi

Konfigurasi lingkungan Anda untuk mengautentikasi dan memberi otorisasi permintaan ke Chronicle API:

1. Pilih metode autentikasi: Pilih cara beban kerja Anda melakukan autentikasi ke Chronicle API menggunakan salah satu metode yang tercantum. Sebaiknya gunakan Workload Identity Federation untuk keamanan yang lebih baik, karena tidak perlu mengelola dan menyimpan kunci akun layanan yang memiliki masa berlaku panjang. Untuk skenario autentikasi lanjutan (seperti peniruan akun layanan), lihat Mengautentikasi ke Chronicle API.
   • Workload Identity Federation (direkomendasikan): Siapkan Workload Identity Federation untuk mengizinkan workload yang berjalan di luar Google Cloud melakukan autentikasi menggunakan identitas eksternal.
   • Akun Layanan: Jika Anda harus menggunakan akun layanan, buat akun layanan di project Google Cloud Anda, lalu buat dan download kunci pribadi dalam format JSON. Pastikan kunci ini tetap aman.
2. Memberikan izin IAM: Berikan izin IAM yang diperlukan ke identitas (baik akun layanan maupun pokok identitas eksternal) yang digunakan untuk autentikasi. Lihat Pemetaan endpoint API SIEM untuk menemukan izin IAM spesifik yang diperlukan untuk endpoint modern yang menggantikan panggilan lama Anda.
   • Peran kustom (direkomendasikan): Buat peran IAM kustom dengan izin yang diperlukan, lalu berikan peran kustom tersebut ke akun layanan atau pokok identitas eksternal.
   • Peran yang telah ditetapkan: Berikan peran yang telah ditetapkan Google SecOps kepada akun layanan atau akun utama identitas eksternal. Hal ini kemungkinan akan memberikan lebih banyak akses daripada yang diperlukan untuk otomatisasi tertentu.
   • Delegasi partner multi-tenant: Jika Anda adalah MSSP atau partner yang mengelola resource tenant di luar TenantService (seperti GetInstance, UpdateInstance, atau GenerateForwarderFiles), administrator tenant harus memberikan peran IAM yang diperlukan secara eksplisit kepada akun layanan atau prinsipal Workload Identity Federation Anda di project Google Cloud tenant.

3. Tetapkan variabel lingkungan kredensial: Konfigurasi lingkungan runtime Anda untuk menggunakan kredensial dengan Kredensial Default Aplikasi (ADC) dengan menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS. Variabel ini harus mengarah ke file JSON kunci akun layanan yang didownload atau file konfigurasi kredensial Workload Identity Federation. Library klienGoogle Cloud akan otomatis mendeteksi variabel ini untuk mengautentikasi permintaan:

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

4. Perbarui cakupan OAuth: Perbarui string cakupan jika skrip integrasi lama Anda secara eksplisit meminta cakupan OAuth untuk pembuatan token. Cakupan lama tidak memberikan akses ke platform API modern:

   • Cakupan Backstory lama: https://www.googleapis.com/auth/chronicle-backstory
   • Cakupan Chronicle: https://www.googleapis.com/auth/chronicle (atau cakupan https://www.googleapis.com/auth/cloud-platform yang lebih luas).

Memetakan endpoint dan memperbarui URL

Pahami tampilan Chronicle API, petakan panggilan lama, dan perbarui endpoint layanan di aplikasi Anda.

Meninjau dokumentasi referensi

Pahami dokumentasi komprehensif untuk Chronicle API.

Memetakan endpoint ke Chronicle API

Identifikasi endpoint modern yang sesuai untuk setiap panggilan API lama yang dilakukan aplikasi Anda. Demikian pula, petakan model data yang ada ke struktur modern, dengan memperhitungkan perubahan skema atau kolom tambahan. Untuk mengetahui detail di semua endpoint SIEM, lihat Pemetaan endpoint SIEM API. Jika alur kerja Anda juga berinteraksi dengan endpoint SOAR, lihat tabel pemetaan endpoint API SOAR.

Memperbarui endpoint layanan

Perbarui URL dasar panggilan API Anda agar mengarah ke endpoint layanan regional yang benar. Chronicle API adalah layanan regional, jadi Anda harus memanggil endpoint layanan regional yang cocok dengan lokasi instance Google SecOps Anda.

Semua endpoint modern menggunakan awalan yang konsisten, sehingga alamat endpoint akhir dapat diprediksi. Contoh berikut menunjukkan struktur URL endpoint modern:

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

Struktur ini membuat alamat akhir ke endpoint sebagai berikut:

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

Dengan:

• service_endpoint: Alamat layanan regional.
• api_version: Versi API yang akan dikueri. Dapat berupa v1alpha, v1beta, atau v1.
• project_id: Project ID Anda (project yang sama dengan yang Anda tetapkan untuk izin IAM).
• location: Lokasi project Anda (region); sama dengan endpoint regional.
• instance_id: ID pelanggan Google SecOps SIEM Anda.

Alamat regional:

• africa-south1: https://africa-south1-chronicle.googleapis.com atau https://chronicle.africa-south1.rep.googleapis.com
• asia-northeast1: https://asia-northeast1-chronicle.googleapis.com atau https://chronicle.asia-northeast1.rep.googleapis.com
• asia-south1: https://asia-south1-chronicle.googleapis.com atau https://chronicle.asia-south1.rep.googleapis.com
• asia-southeast1: https://asia-southeast1-chronicle.googleapis.com atau https://chronicle.asia-southeast1.rep.googleapis.com
• asia-southeast2: https://asia-southeast2-chronicle.googleapis.com atau https://chronicle.asia-southeast2.rep.googleapis.com
• australia-southeast1: https://australia-southeast1-chronicle.googleapis.com atau https://chronicle.australia-southeast1.rep.googleapis.com
• europe-west12: https://europe-west12-chronicle.googleapis.com atau https://chronicle.europe-west12.rep.googleapis.com
• europe-west2: https://europe-west2-chronicle.googleapis.com atau https://chronicle.europe-west2.rep.googleapis.com
• europe-west3: https://europe-west3-chronicle.googleapis.com atau https://chronicle.europe-west3.rep.googleapis.com
• europe-west6: https://europe-west6-chronicle.googleapis.com atau https://chronicle.europe-west6.rep.googleapis.com
• europe-west9: https://europe-west9-chronicle.googleapis.com atau https://chronicle.europe-west9.rep.googleapis.com
• me-central1: https://me-central1-chronicle.googleapis.com atau https://chronicle.me-central1.rep.googleapis.com
• me-central2: https://me-central2-chronicle.googleapis.com atau https://chronicle.me-central2.rep.googleapis.com
• me-west1: https://me-west1-chronicle.googleapis.com atau https://chronicle.me-west1.rep.googleapis.com
• northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com atau https://chronicle.northamerica-northeast2.rep.googleapis.com
• southamerica-east1: https://southamerica-east1-chronicle.googleapis.com atau https://chronicle.southamerica-east1.rep.googleapis.com
• Amerika Serikat (us): https://us-chronicle.googleapis.com atau https://chronicle.us.rep.googleapis.com
• Eropa (eu): https://eu-chronicle.googleapis.com atau https://chronicle.eu.rep.googleapis.com

Untuk mengetahui daftar lengkap semua endpoint yang didukung, lihat referensi resmi di dokumentasi Endpoint layanan Chronicle API.

Misalnya, untuk mencantumkan semua aturan deteksi untuk instance di lokasi us, kirim permintaan berikut:

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

Demikian pula, untuk membuat kueri resource SOAR seperti Kasus menggunakan alias endpoint regional (rep), kirim permintaan berikut:

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

Memperbarui logika API

Tinjau referensi REST API Chronicle untuk mengidentifikasi dan menerapkan perubahan pada nama kolom dan struktur data di aplikasi Anda. Meskipun beberapa endpoint lama mungkin tetap serupa, Anda harus memperbarui integrasi agar sesuai dengan model data dan struktur endpoint terbaru.

Menggunakan Google Cloud library klien

Sederhanakan integrasi Anda untuk menangani autentikasi, penggantian token, dan detail transportasi secara otomatis. Sebaiknya gunakan Google Cloud library klien resmi untuk melakukannya. Dukungan Chronicle API tersedia di delapan bahasa pemrograman, termasuk Python, Go, Java, Node.js, dan C#. Untuk mengetahui detail penginstalan dan penggunaan, lihat Library klien dan SDK.

Menguji integrasi Anda

Uji aplikasi yang telah diupdate di lingkungan staging sebelum men-deploy ke produksi:

1. Buat rencana pengujian: Tentukan kasus pengujian yang mencakup semua fungsi yang dimigrasikan.
2. Jalankan pengujian: Jalankan pengujian otomatis dan manual untuk mengonfirmasi akurasi dan validitas.
3. Memantau performa: Menilai performa aplikasi Anda dengan API modern.

Memecahkan masalah

Bagian ini menjelaskan cara mengatasi error umum yang mungkin Anda alami selama migrasi.

HTTP 403 Forbidden atau PERMISSION_DENIED

Jika panggilan API Anda menampilkan error HTTP 403 Forbidden atau PERMISSION_DENIED, verifikasi hal berikut:

• Metode autentikasi dan entitas: Pastikan Anda menggunakan kredensial yang benar.
  • Jika menggunakan Workload Identity Federation, pastikan pokok identitas eksternal cocok dengan pokok yang terikat ke peran IAM di project Anda.
  • Jika menggunakan akun layanan, verifikasi bahwa akun layanan yang benar sedang digunakan dan belum dinonaktifkan. Jangan gunakan akun layanan lama (yang sering kali berisi bk atau malachite-cx di alamat emailnya) untuk endpoint API Chronicle modern.
• Peran IAM: Pastikan bahwa akun layanan atau akun utama identitas eksternal telah diberi peran IAM bawaan atau kustom yang diperlukan (seperti Chronicle API Viewer atau Chronicle API Editor) di project Google Cloud Anda. Untuk izin endpoint API terperinci, lihat Pemetaan endpoint API SIEM.

HTTP 401 Unauthorized atau UNAUTHENTICATED

Jika panggilan API Anda gagal dengan HTTP 401 Unauthorized atau UNAUTHENTICATED, periksa hal berikut:

• Cakupan OAuth: Pastikan skrip kustom Anda meminta cakupan modern: https://www.googleapis.com/auth/chronicle (atau cakupan https://www.googleapis.com/auth/cloud-platform yang lebih luas). Cakupan lama (https://www.googleapis.com/auth/chronicle-backstory) tidak memberikan akses ke Chronicle API modern.
• Variabel lingkungan: Pastikan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ditetapkan dan mengarah ke file kunci JSON atau file konfigurasi Workload Identity Federation yang benar di lingkungan runtime Anda.

HTTP 404 Not Found atau ketidakcocokan regional

Jika panggilan API Anda menampilkan HTTP 404 Not Found atau gagal terhubung, periksa endpoint regional Anda:

• Endpoint regional: Chronicle API adalah layanan regional. Verifikasi bahwa Anda memanggil endpoint yang cocok dengan region instance Google SecOps Anda (misalnya, https://europe-west3-chronicle.googleapis.com untuk instance di Frankfurt). Mengirim permintaan ke region yang berbeda akan menghasilkan error. Untuk mengetahui daftar lengkap alamat regional, lihat Memperbarui endpoint layanan atau Referensi endpoint layanan resmi.

Langkah berikutnya

• Pemetaan endpoint API SIEM
• Melakukan autentikasi ke Chronicle API
• Referensi REST Chronicle API
• Library klien dan SDK
• Metode penyerapan Chronicle API
• Mengupgrade integrasi Google Chronicle di SOAR

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