Esegui la migrazione dall'API SIEM legacy all'API Chronicle

Supportato in:

Questo documento ti aiuta a gestire le applicazioni che chiamano una delle API SIEM legacy (API Backstory e API Ingestion). Descrive i passaggi da seguire per configurare l'accesso programmatico e aggiornare tutti i riferimenti dagli endpoint API SIEM legacy agli endpoint API Chronicle moderni.

Per una rapida panoramica della procedura di migrazione, guarda il video incorporato.

La superficie API di Chronicle introduce diversi miglioramenti progettati per semplificare il processo di sviluppo e allinearsi agli standard delle API Google Cloud per una maggiore affidabilità, sicurezza, prestazioni e una migliore integrazione con Cloud Audit Logs, Cloud Monitoring, Cloud Identity e Identity and Access Management (IAM). Inoltre, risolve molti dei limiti e delle complessità delle API legacy.

Cosa cambierà?

Tutte le richieste programmatiche agli endpoint legacy dell'API Backstory e dell'API Ingestion devono essere trasferite alla moderna API Chronicle. Se la tua organizzazione utilizza integrazioni personalizzate, script di automazione o strumenti di terze parti che effettuano chiamate a questi endpoint legacy, devi aggiornare questi carichi di lavoro in modo che utilizzino endpoint e flussi di autenticazione moderni prima del 20 luglio 2027. Inoltre, se la tua organizzazione utilizza Google Security Operations SOAR, devi aggiornare le integrazioni e i connettori SOAR (ad esempio l'integrazione di Google Chronicle) per utilizzare l'API Chronicle. Per maggiori dettagli, vedi Eseguire la migrazione delle integrazioni SOAR.

Che cosa non cambia

Le azioni eseguite direttamente nell'interfaccia utente (UI) di Google Security Operations richiamano già la moderna API Chronicle. Se la tua organizzazione interagisce con Google SecOps solo tramite la UI o se le tue integrazioni chiamano già gli endpoint dell'API Chronicle, non devi fare nulla.

Modifiche e miglioramenti principali

La seguente tabella evidenzia le principali differenze tra l'API SIEM legacy e l'API Chronicle:

Livello di applicazione API SIEM legacy API Chronicle Dettagli
Gestione delle credenziali Procedura manuale che coinvolge i rappresentanti di Google Gestione self-service di service account, credenziali e autorizzazioni IAM La gestione self-service delle credenziali e di IAM semplifica l'onboarding ed elimina la dipendenza dalle richieste di assistenza manuali.
Standard di conformità Supporto limitato Supporto integrato per i controlli di residenza dei dati, i Controlli di servizio VPC, Access Transparency, CMEK e FedRAMP I moderni controlli dell'infrastruttura integrati soddisfano gli standard di conformità e normativi del settore.
Logging e controllo Stream di audit legacy Cloud Audit Logs integrato nel tuo progetto Google Cloud L'integrazione diretta fornisce tracce di audit e monitoraggio centralizzati.
Autenticazione Token API e credenziali del account di servizio OAuth 2.0 con supporto per i moderni metodi di autenticazione, inclusi Workload Identity e service account, come descritto in Autenticazione per Google Cloud API e servizi Questi metodi di autenticazione moderni offrono maggiore sicurezza e standardizzano il flusso delle credenziali.
Modelli di dati e progettazione di API Strutture proprietarie piatte Progettazione orientata alle risorse, architettura RESTful e denominazione standardizzata in base alle AIP Questo design moderno migliora la coerenza dei dati, rende l'API più intuitiva e semplifica la manipolazione degli oggetti.
Denominazione degli endpoint Incoerente RESTful e standardizzato Una denominazione coerente rende l'API più intuitiva e più facile da integrare.
Ecosistema Molto limitata Integrazione con MCP, Terraform, librerie client e SDK Ampia compatibilità con moderni strumenti cloud e framework di automazione.
Autorizzazione partner Token partner o chiave API utilizzati direttamente nei codici dei clienti Delega IAM tra progetti per le risorse tenant; metodi TenantService con ambito partner I metodi TenantService vengono eseguiti nel progetto partner. Tutte le altre API tenant richiedono la delega IAM tra progetti concessa dal tenant nel progetto tenant.

Autorizzazione partner

Per i workflow dei partner multi-tenant, l'autorizzazione nell'API Chronicle dipende dalla proprietà delle risorse. Il progetto che ospita una risorsa determina le credenziali e le autorizzazioni IAM di cui ha bisogno un partner. Limitare le operazioni del tenant alle credenziali delegate dal tenant è in linea con il principio di sicurezza fondamentale secondo cui i partner non devono essere in grado di accedere, recuperare o modificare i dati del tenant senza l'autorizzazione esplicita concessa dal tenant. La seguente tabella confronta l'autorizzazione del partner nell'API Backstory legacy e nell'API Chronicle:

API Metodi Ambito risorsa Autorizzazione
API Legacy Backstory /v1/partner/customer/* endpoint Tutti i codici cliente del partner I partner chiamano questi endpoint direttamente con i propri token partner o chiavi API.
API Chronicle: TenantService CreateTenant, ListTenants e UpdateTenant Istanza del partner: projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/* I partner chiamano questi metodi direttamente con i propri service account o credenziali che dispongono delle autorizzazioni chronicle.googleapis.com/tenants.* nel progetto partner.
API Chronicle: altri servizi, come InstanceService e ForwarderService GetInstance, UpdateInstance, GenerateForwarderFiles e altri metodi con ambito tenant Istanza del tenant: projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/... Le credenziali del partner da sole non possono accedere ai dati del tenant o modificarli. L'amministratore tenant deve concedere ruoli IAM, come roles/chronicle.admin, roles/chronicle.viewer o un ruolo personalizzato, al account di servizio del partner o all'entità federazione delle identità per i workload nel progetto Google Cloud del tenant.

Programmazione del ritiro

La versione precedente dell'API SIEM verrà ritirata il 20 luglio 2027. Ti consigliamo di completare la migrazione prima di questa data per evitare interruzioni del servizio:

  • A partire dal 26 ottobre 2026, non potrai più chiamare le API legacy (API Backstory e API Ingestion) dalle nuove istanze.
  • Entro il 20 luglio 2027, devi eseguire la migrazione di tutte le istanze esistenti all'API Chronicle, poiché le API legacy non saranno più disponibili.

Prima di iniziare

Prima di eseguire la migrazione all'API Chronicle, assicurati di completare le seguenti operazioni:

  • Esegui il deployment sull'infrastruttura SIEM moderna: assicurati che l'istanza venga eseguita il deployment sul progetto tuo o del tuo partner MSSP Google Cloud utilizzando l'infrastruttura SIEM moderna. Per istruzioni dettagliate, consulta la panoramica della migrazione SIEM.
  • Abilita l'API Chronicle:nella console Google Cloud , vai al progetto che ospita la tua istanza e abilita l'API Chronicle (chronicle.googleapis.com). Per maggiori dettagli, consulta Abilitare un'API nel tuo progetto Google Cloud .
  • Identifica le integrazioni SOAR:se il tuo ambiente connette Google SecOps SOAR a Google Security Operations SIEM, verifica i connettori esistenti. Per maggiori dettagli, vedi Eseguire la migrazione delle integrazioni SOAR.

Eseguire la migrazione delle integrazioni SOAR

Se la tua organizzazione collega Google SecOps SOAR a Google SecOps SIEM, devi eseguire la migrazione delle integrazioni e dei connettori SOAR (ad esempio l'integrazione di Google Chronicle) per utilizzare l'API Chronicle.

Per istruzioni dettagliate sull'upgrade dell'integrazione e dei connettori di Google Chronicle per utilizzare l'API Chronicle, inclusa l'individuazione della radice dell'API Chronicle del tuo ambiente e la configurazione delle credenziali di autenticazione, consulta Migrazione dall'API Backstory all'API Chronicle.

Esegui la migrazione all'API Chronicle

Esegui la migrazione degli script e delle integrazioni personalizzati dalle API legacy all'API Chronicle completando i seguenti passaggi:

  1. Controlla l'utilizzo dell'API: identifica tutti gli script personalizzati e le integrazioni nel tuo ambiente che richiamano endpoint legacy.
  2. Configura l'autenticazione e l'autorizzazione: configura l'ambiente per autenticare e autorizzare le richieste all'API Chronicle.
  3. Mappa gli endpoint e aggiorna gli URL: sostituisci gli endpoint legacy con i loro equivalenti regionali moderni.
  4. Aggiorna la logica dell'API: modifica i payload delle richieste e la gestione delle risposte in modo che corrispondano ai modelli di dati dell'API moderna.
  5. Testa l'integrazione: convalida le modifiche in un ambiente di staging prima di eseguire il deployment in produzione.

Controllare l'utilizzo dell'API

Controlla il tuo ambiente per identificare script personalizzati o integrazioni che richiamano backstory.googleapis.com o malachiteingestion-pa.googleapis.com. Puoi identificare queste integrazioni esaminando la base di codice, gli script di automazione e gli strumenti di terze parti. Se la tua organizzazione utilizza anche Google SecOps SOAR, consulta Eseguire la migrazione delle integrazioni SOAR.

Configurare l'autenticazione e l'autorizzazione

Configura il tuo ambiente per autenticare e autorizzare le richieste all'API Chronicle:

  1. Scegli un metodo di autenticazione:scegli come i tuoi workload si autenticano all'API Chronicle utilizzando uno dei metodi elencati. Per una maggiore sicurezza, ti consigliamo di utilizzare la federazione delle identità per i workload, in quanto evita la gestione e l'archiviazione di chiavi dei account di servizio di lunga durata. Per scenari di autenticazione avanzati (come la simulazione dell'identità del account di servizio), vedi Autenticarsi all'API Chronicle.
  2. Concedi le autorizzazioni IAM:concedi le autorizzazioni IAM richieste all'identità (il account di servizio o l'entità identità esterna) utilizzata per l'autenticazione. Consulta la mappatura degli endpoint API SIEM per trovare le autorizzazioni IAM specifiche richieste per gli endpoint moderni che sostituiscono le chiamate legacy.
    • Ruolo personalizzato (consigliato): crea un ruolo IAM personalizzato con le autorizzazioni richieste e concedi il ruolo personalizzato al account di servizio o all'entità identità esterna.
    • Ruolo predefinito:concedi un ruolo predefinito di Google SecOps al account di servizio o all'entità identità esterna. In questo modo, probabilmente verrà concesso un accesso superiore a quello necessario per un'automazione specifica.
    • Delega partner multitenant: se sei un MSSP o un partner che gestisce le risorse tenant al di fuori di TenantService (ad esempio GetInstance, UpdateInstance o GenerateForwarderFiles), l'amministratore tenant deve concedere esplicitamente al tuo account di servizio o all'entità di federazione delle identità per i workload i ruoli IAM richiesti nel progetto Google Cloud del tenant.

  3. Imposta la variabile di ambiente delle credenziali:configura l'ambiente di runtime in modo che utilizzi le credenziali con le Credenziali predefinite dell'applicazione (ADC) impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Questa variabile deve puntare al file JSON della chiave dell'account di servizio scaricato o al file di configurazione delle credenziali della federazione delle identità per i carichi di lavoro. Le librerie clientGoogle Cloud rilevano automaticamente questa variabile per autenticare le richieste:

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

  4. Aggiorna gli ambiti OAuth:aggiorna la stringa dell'ambito se gli script di integrazione legacy hanno richiesto esplicitamente gli ambiti OAuth per la generazione di token. L'ambito legacy non concede l'accesso alla moderna superficie API:

    • Ambito di Legacy Backstory: https://www.googleapis.com/auth/chronicle-backstory
    • Ambito di Chronicle: https://www.googleapis.com/auth/chronicle (o l'ambito più ampio https://www.googleapis.com/auth/cloud-platform).

Mappare gli endpoint e aggiornare gli URL

Acquisisci familiarità con la superficie dell'API Chronicle, mappa le chiamate legacy e aggiorna gli endpoint di servizio nella tua applicazione.

Esaminare la documentazione di riferimento

Acquisisci familiarità con la documentazione completa dell'API Chronicle.

Mappa gli endpoint all'API Chronicle

Identifica gli endpoint moderni corrispondenti per ciascuna delle chiamate API legacy effettuate dalla tua applicazione. Allo stesso modo, mappa i modelli di dati esistenti alle strutture moderne, tenendo conto di eventuali modifiche dello schema o campi aggiuntivi. Per i dettagli su tutti gli endpoint SIEM, consulta Mappatura degli endpoint API SIEM. Se il tuo flusso di lavoro interagisce anche con gli endpoint SOAR, consulta la tabella di mappatura degli endpoint API SOAR.

Aggiorna l'endpoint di servizio

Aggiorna l'URL di base delle chiamate API in modo che rimandi all'endpoint di servizio regionale corretto. L'API Chronicle è un servizio regionale, quindi devi chiamare l'endpoint di servizio regionale che corrisponde alla posizione della tua istanza Google SecOps.

Tutti gli endpoint moderni utilizzano un prefisso coerente, il che rende prevedibile l'indirizzo dell'endpoint finale. L'esempio seguente mostra la struttura dell'URL dell'endpoint moderno:

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

Questa struttura crea l'indirizzo finale dell'endpoint nel seguente modo:

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

Dove:

  • service_endpoint: Un indirizzo di servizio regionale.
  • api_version: la versione dell'API da interrogare. Può essere v1alpha, v1beta o v1.
  • project_id: il tuo ID progetto (lo stesso progetto che hai definito per le tue autorizzazioni IAM).
  • location: la posizione del progetto (regione), uguale agli endpoint regionali.
  • instance_id: il tuo ID cliente Google SecOps SIEM.

Indirizzi regionali:

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

Per un elenco completo di tutti gli endpoint supportati, consulta il riferimento ufficiale nella documentazione dell'endpoint di servizio dell'API Chronicle.

Ad esempio, per elencare tutte le regole di rilevamento per un'istanza nella località us, invia la seguente richiesta:

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

Allo stesso modo, per eseguire query sulle risorse SOAR come i casi utilizzando l'alias dell'endpoint regionale (rep), invia la seguente richiesta:

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

Aggiorna la logica API

Consulta il riferimento REST dell'API Chronicle per identificare e implementare le modifiche ai nomi dei campi e alle strutture dei dati nella tua applicazione. Anche se alcuni endpoint legacy potrebbero rimanere simili, devi aggiornare le integrazioni in modo che corrispondano ai modelli di dati e alle strutture degli endpoint più recenti.

Utilizza le librerie client Google Cloud

Semplifica l'integrazione per gestire automaticamente l'autenticazione, l'aggiornamento dei token e i dettagli di trasporto. Ti consigliamo di utilizzare le librerie client ufficiali Google Cloud . Il supporto dell'API Chronicle è disponibile in otto linguaggi di programmazione, tra cui Python, Go, Java, Node.js e C#. Per informazioni dettagliate sull'installazione e sull'utilizzo, consulta Librerie client e SDK.

Testare l'integrazione

Testa l'applicazione aggiornata in un ambiente di gestione temporanea prima di eseguire il deployment in produzione:

  1. Crea un piano di test:definisci gli scenari di test che coprono tutte le funzionalità di cui è stata eseguita la migrazione.
  2. Esegui test:esegui test automatici e manuali per confermare l'accuratezza e la validità.
  3. Monitora il rendimento:valuta il rendimento della tua applicazione con l'API moderna.

Risoluzione dei problemi

Questa sezione descrive come risolvere gli errori comuni che potresti riscontrare durante la migrazione.

HTTP 403 Forbidden o PERMISSION_DENIED

Se le chiamate API restituiscono un errore HTTP 403 Forbidden o PERMISSION_DENIED, verifica quanto segue:

  • Metodo di autenticazione e principal:assicurati di utilizzare le credenziali corrette.
    • Se utilizzi la federazione delle identità per i workload, verifica che l'entità identità esterna corrisponda all'entità associata ai ruoli IAM nel tuo progetto.
    • Se utilizzi un account di servizio, verifica che sia quello corretto e che non sia stato disattivato. Non utilizzare i service account legacy (che spesso contengono bk o malachite-cx nel loro indirizzo email) per gli endpoint API Chronicle moderni.
  • Ruoli IAM: verifica che al account di servizio o al principal di identità esterna siano stati concessi i ruoli IAM predefiniti o personalizzati richiesti (ad esempio Chronicle API Viewer o Chronicle API Editor) nel tuo progetto Google Cloud . Per le autorizzazioni granulari degli endpoint, consulta la sezione Mappatura degli endpoint API SIEM.

HTTP 401 - Non autorizzato o NON AUTENTICATO

Se le chiamate API non vanno a buon fine con HTTP 401 Unauthorized o UNAUTHENTICATED, controlla quanto segue:

  • Ambiti OAuth:verifica che gli script personalizzati richiedano l'ambito moderno: https://www.googleapis.com/auth/chronicle (o l'ambito più ampio https://www.googleapis.com/auth/cloud-platform). L'ambito precedente (https://www.googleapis.com/auth/chronicle-backstory) non concede l'accesso all'API Chronicle moderna.
  • Variabile di ambiente: verifica che la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sia impostata e punti al file di chiavi JSON o al file di configurazione della federazione delle identità per i workload corretto nel tuo ambiente di runtime.

Errore HTTP 404 - Non trovato o mancata corrispondenza regionale

Se le chiamate API restituiscono un errore HTTP 404 Not Found o non riescono a connettersi, controlla gli endpoint regionali:

  • Endpoint regionale:l'API Chronicle è un servizio regionale. Verifica di chiamare l'endpoint che corrisponde alla regione della tua istanza Google SecOps (ad esempio, https://europe-west3-chronicle.googleapis.com per un'istanza a Francoforte). L'invio di richieste a una regione diversa genererà errori. Per un elenco completo degli indirizzi regionali, consulta Aggiorna l'endpoint di servizio o il riferimento all'endpoint di servizio ufficiale.

Passaggi successivi

Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.