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

Supportata 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 del processo di migrazione, guarda il video incorporato.

La superficie dell'API 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 maggiore integrazione con Cloud Audit Logs, Cloud Monitoring, Cloud Identity e Identity and Access Management (IAM). Inoltre, risolve molte delle limitazioni e delle complessità delle API legacy.

Cosa cambierà?

Tutte le richieste programmatiche agli endpoint legacy dell'API Backstory e dell'API Ingestion devono passare 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 i workload 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 (come l'integrazione di Google Chronicle) per utilizzare l'API Chronicle. Per maggiori dettagli, vedi Esegui 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:

Area della funzionalità 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à Assistenza limitata Supporto integrato per i controlli della residenza dei dati, i Controlli di servizio VPC, Access Transparency, CMEK e FedRAMP I moderni controlli integrati dell'infrastruttura 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 dell'account di servizio OAuth 2.0 con supporto di metodi di autenticazione moderni, tra cui Workload Identity e service account, come descritto in Autenticazione per API e servizi Google Cloud Questi metodi di autenticazione moderni offrono una maggiore sicurezza e standardizzano il flusso delle credenziali.
Modelli di dati e progettazione di API Strutture piatte e proprietarie Design orientato 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 facile da integrare.
Ecosistema Molto limitata Integrazione con MCP, Terraform, librerie client e SDK Ampia compatibilità con i moderni strumenti cloud e framework di automazione.
Autorizzazione partner Token partner o chiave API utilizzati direttamente nei codici cliente 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 necessarie a un partner. L'ambito delle 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 tabella seguente mette a confronto l'autorizzazione dei partner nell'API Backstory precedente e nell'API Chronicle:

API Metodi Ambito risorsa Autorizzazione
API Backstory legacy /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 del tenant deve concedere i 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 disattivazione dell'API SIEM legacy è prevista per 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) da 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 i seguenti passaggi:

  • Esegui il deployment su un'infrastruttura SIEM moderna: assicurati che il deployment dell'istanza venga eseguito nel tuo progetto o in quello 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 Abilitazione di 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 Esegui la migrazione delle integrazioni SOAR.

Esegui la migrazione delle integrazioni SOAR

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

Per istruzioni dettagliate sull'upgrade dell'integrazione e dei connettori di Google Chronicle per l'utilizzo dell'API Chronicle, tra cui 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 e le integrazioni personalizzati nel tuo ambiente che richiamano gli 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 gestione temporanea prima di eseguire il deployment in produzione.

Controlla l'utilizzo dell'API

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

Configura l'autenticazione e l'autorizzazione

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

  1. Scegli un metodo di autenticazione: scegli come i tuoi workload si autenticano nell'API Chronicle utilizzando uno dei metodi elencati. Ti consigliamo di utilizzare la federazione delle identità per i workload per una maggiore sicurezza, in quanto evita di gestire e archiviare chiavi dei account di servizio di lunga durata. Per scenari di autenticazione avanzati (come la simulazione dell'identità dei account di servizio), consulta Autenticati nell'API Chronicle.
  2. Concedi le autorizzazioni IAM:concedi le autorizzazioni IAM richieste all'identità (il account di servizio o l'entità dell'identità esterna) utilizzata per l'autenticazione. Consulta la sezione 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 concedilo al account di servizio o all'entità con identità esterna.
    • Ruolo predefinito: concedi un ruolo predefinito di Google SecOps al account di servizio o all'entità con identità esterna. In questo modo, probabilmente concederai più accesso del necessario per un'automazione specifica.
    • Delega dei partner multi-tenant: se sei un MSSP o un partner che gestisce le risorse dei tenant al di fuori di TenantService (ad esempio GetInstance, UpdateInstance o GenerateForwarderFiles), l'amministratore del tenant deve concedere esplicitamente al tuo account di servizio o al principal di Workload Identity Federation 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 client diGoogle 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 richiedevano esplicitamente gli ambiti OAuth per la generazione dei token. L'ambito legacy non concede l'accesso alla superficie API moderna:

    • Ambito di Backstory legacy: 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).

Mappa gli endpoint e aggiorna gli URL

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

Esamina 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 allo schema o campi aggiuntivi. Per i dettagli su tutti gli endpoint SIEM, consulta Mappatura degli endpoint API SIEM. Se il tuo workflow 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 del servizio regionale che corrisponde alla località della tua istanza di Google SecOps.

Tutti gli endpoint moderni utilizzano un prefisso coerente, rendendo 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 rende l'indirizzo finale dell'endpoint come segue:

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 su cui eseguire la query. Può essere v1alpha, v1beta o v1.
  • project_id: l'ID progetto (lo stesso progetto definito per le autorizzazioni IAM).
  • location: la località del progetto (regione); corrisponde agli endpoint regionali.
  • instance_id: l'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 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, ad esempio 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

Verifica la configurazione del firewall

Se utilizzi firewall o proxy autenticati tra il tuo ambiente e internet, configura le regole per consentire le connessioni HTTPS in uscita sulla porta TCP 443. Consenti l'accesso ai seguenti host:

  • Endpoint API Chronicle: <var>REGION</var>-chronicle.googleapis.com o chronicle.<var>REGION</var>.rep.googleapis.com
  • Endpoint di autenticazione di Google: oauth2.googleapis.com, www.googleapis.com e accounts.google.com (più sts.googleapis.com e iamcredentials.googleapis.com se utilizzi la federazione delle identità per i carichi di lavoro o la simulazione dell'identità dei account di servizio)

Per i dettagli completi sugli endpoint, le indicazioni sugli intervalli IP di Google, le opzioni di connettività privata e i passaggi di verifica, consulta Verifica la configurazione del firewall per l'API Chronicle.

Aggiorna la logica dell'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. Sebbene alcuni endpoint legacy possano rimanere simili, devi aggiornare le tue 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. A questo scopo, ti consigliamo di utilizzare le librerie client Google Cloud ufficiali. Il supporto dell'API Chronicle è disponibile in otto linguaggi di programmazione, tra cui Python, Go, Java, Node.js e C#. Per i dettagli sull'installazione e sull'utilizzo, consulta Librerie client e SDK.

Verifica la tua integrazione

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

  1. Crea un piano di test:definisci scenari di test che coprano tutte le funzionalità di cui è stata eseguita la migrazione.
  2. Esegui i test:esegui test automatici e manuali per confermare l'accuratezza e la validità.
  3. Monitora le prestazioni:valuta le prestazioni 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 entità:assicurati di utilizzare le credenziali corrette.
    • Se utilizzi la federazione delle identità per i workload, verifica che l'entità dell'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 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 all'entità 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 Mappatura degli endpoint API SIEM.

HTTP 401 Unauthorized o UNAUTHENTICATED

Se le chiamate API non vanno a buon fine con HTTP 401 Unauthorized o UNAUTHENTICATED, verifica 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 della chiave JSON o al file di configurazione della federazione delle identità per i workload corretti nel tuo ambiente di runtime.

HTTP 404 - Non trovato o mancate corrispondenze regionali

Se le chiamate API restituiscono un 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 corrispondente 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 ufficiale per l'endpoint di servizio.

Passaggi successivi

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