Abbiamo riorganizzato la struttura di navigazione della documentazione per allinearla direttamente ai tuoi flussi di lavoro operativi. Per ulteriori informazioni, consulta le note di rilascio e il video dimostrativo.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

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

Supportato in:

Google secops SIEM

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 dell'API Chronicle introduce diversi miglioramenti progettati per semplificare la procedura di sviluppo e allinearsi agli Google Cloud standard API per una maggiore affidabilità, sicurezza, prestazioni e una migliore integrazione con Cloud Audit Logs, Cloud Monitoring, Cloud Identity e Identity and Access Management (IAM). Affronta anche molte delle limitazioni e delle complessità delle API legacy.

Cosa cambierà?

Tutte le richieste programmatiche agli endpoint API Backstory legacy e API Ingestion devono passare all'API Chronicle moderna. 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.

Cosa non cambierà?

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

Modifiche e miglioramenti principali

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

Area funzionalità	API SIEM legacy	API Chronicle	Dettagli
Gestione delle credenziali	Procedura manuale che coinvolge i rappresentanti di Google	Gestione self-service di account di servizio, 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, 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 auditing	Flussi di audit legacy	Cloud Audit Logs integrato nel tuo Google Cloud progetto	L'integrazione diretta fornisce audit trail e monitoraggio centralizzati.
Autenticazione	Token API e credenziali dell'account di servizio	OAuth 2.0 con supporto per i metodi di autenticazione moderni, tra cui Workload Identity e account di servizio, come descritto in Autenticazione per Google Cloud API e servizi	Questi metodi di autenticazione moderni forniscono una maggiore sicurezza e standardizzano il flusso delle credenziali.
Modelli di dati e progettazione API	Strutture piatte e proprietarie	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 standardizzata	Una denominazione coerente rende l'API più intuitiva e più facile da integrare.
Ecosistema	Molto limitato	Integrazione con MCP, Terraform, librerie client e SDK	Ampia compatibilità con i moderni strumenti cloud e framework di automazione.

Pianificazione del ritiro

La chiusura 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) 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 i seguenti passaggi:

Esegui il deployment sull'infrastruttura SIEM moderna: assicurati che l'istanza sia sottoposta a deployment 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 Google Cloud console, vai al progetto che ospita l'istanza e abilita l'API Chronicle (chronicle.googleapis.com). Per maggiori dettagli, consulta Abilitare un'API nel tuo Google Cloud progetto.

Esegui la migrazione all'API Chronicle

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

Controlla l'utilizzo dell'API: identifica tutti gli script e le integrazioni nel tuo ambiente che richiamano gli endpoint legacy.
Configura l'autenticazione e l'autorizzazione: configura l'ambiente per autenticare e autorizzare le richieste all'API Chronicle.
Mappa gli endpoint e aggiorna gli URL: sostituisci gli endpoint legacy con i relativi equivalenti regionali moderni.
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.
Verifica l'integrazione: convalida le modifiche in un ambiente di staging prima di eseguire il deployment in produzione.

Controlla l'utilizzo dell'API

Controlla l'ambiente per identificare gli script o le 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.

Configura l'autenticazione e l'autorizzazione

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

Scegli un metodo di autenticazione: scegli in che modo i tuoi carichi di lavoro eseguono l'autenticazione all'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 la gestione e l'archiviazione delle chiavi degli account di servizio a lunga durata. Per scenari di autenticazione avanzati (ad esempio la simulazione dell'identità dei account di servizio), consulta Eseguire l'autenticazione all'API Chronicle.
- Federazione delle identità per i workload (consigliata): configura la federazione delle identità per i workload per consentire ai carichi di lavoro in esecuzione all'esterno di Google Cloud di eseguire l'autenticazione utilizzando identità esterne.
- Account di servizio: se devi utilizzare gli account di servizio, crea un account di servizio nel tuo Google Cloud progetto e genera e scarica una chiave privata in formato JSON. Mantieni questa chiave al sicuro.
Concedi le autorizzazioni IAM: concedi le autorizzazioni IAM richieste all'identità (l'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 all'account di servizio o all'entità identità esterna. In genere, questo concede un accesso maggiore di quello necessario per un'automazione specifica.
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 rimandare al file JSON della chiave dell'account di servizio scaricato o al file di configurazione delle credenziali della federazione delle identità per i workload. Le Google Cloud librerie client rilevano automaticamente questa variabile per autenticare le richieste:
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
Aggiorna gli ambiti OAuth: aggiorna la stringa dell'ambito se gli script di integrazione legacy hanno richiesto esplicitamente gli ambiti OAuth per la generazione dei token. L'ambito legacy non concede l'accesso alla superficie dell'API moderna:
- Ambito Backstory legacy: https://www.googleapis.com/auth/chronicle-backstory
- Ambito 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

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

Esamina la documentazione di riferimento

Familiarizza 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 dettagli su tutti gli endpoint SIEM, consulta la 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, pertanto devi chiamare l'endpoint di servizio regionale che corrisponde alla località 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 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 emergenza regionale.
api_version: la versione dell'API da interrogare. 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); uguale agli endpoint regionali.
instance_id: l'ID cliente di Google Security Operations 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 relativa all'endpoint del servizio API Chronicle Service endpoint.

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

Aggiorna la logica dell'API

Esamina 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 Google Cloud le librerie client

Semplifica l'integrazione per gestire automaticamente l'autenticazione, l'aggiornamento dei token e i dettagli di trasporto. Ti consigliamo di utilizzare le Google Cloud librerie client ufficiali per farlo. 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 l'integrazione

Testa l'applicazione aggiornata in un'integrazione di staging prima di eseguire il deployment in produzione:

Crea un piano di test: definisci i casi di test che coprono tutte le funzionalità di cui è stata eseguita la migrazione.
Esegui i test: esegui test automatici e manuali per confermare l'accuratezza e la validità.
Monitora il rendimento: valuta il rendimento dell'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 ed entità: 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 venga utilizzato l'account di servizio corretto e che non sia stato disattivato. Non utilizzare gli account di servizio legacy (che spesso contengono bk o malachite-cx nel loro indirizzo email) per gli endpoint API Chronicle moderni.
Ruoli IAM: verifica che all'account di servizio o all'entità identità esterna siano stati concessi i ruoli IAM predefiniti o personalizzati richiesti (ad esempio Chronicle API Viewer o Chronicle API Editor) nel tuo Google Cloud progetto. Per le autorizzazioni degli endpoint granulari, consulta la 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, controlla quanto segue:

Ambiti OAuth: verifica che gli script richiedano l'ambito moderno: https://www.googleapis.com/auth/chronicle (o l'ambito più ampio https://www.googleapis.com/auth/cloud-platform). L'ambito legacy (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 rimandi al file della chiave JSON o al file di configurazione della federazione delle identità per i workload corretto nel tuo ambiente di runtime.

HTTP 404 Not Found 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 Aggiornare l'endpoint di servizio o il riferimento ufficiale dell'endpoint di servizio.

Passaggi successivi

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