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.

La superficie dell'API Chronicle introduce diversi miglioramenti progettati per semplificare il processo di sviluppo e allinearsi agli Google Cloud standard API per una maggiore affidabilità, sicurezza, rendimento e una migliore integrazione con Cloud Audit Logs, Cloud Monitoring e Cloud Identity and Identity and Access Management (IAM). Affronta anche molte delle limitazioni e delle complessità presenti nell'API precedente.

Cosa cambierà?

Tutte le richieste programmatiche agli endpoint API Backstory e API Ingestion legacy 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 API Chronicle, non devi intraprendere alcuna azione.

Prerequisiti

Prima di eseguire la migrazione all'API Chronicle, assicurati che la tua istanza sia sottoposta a deployment nel tuo Google Cloud progetto utilizzando l'infrastruttura SIEM moderna. Per istruzioni dettagliate, consulta la panoramica della migrazione SIEM.

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 Stream 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, inclusi 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 OneMCP, 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, le nuove istanze non potranno più chiamare le API legacy (API Backstory e API Ingestion).
  • Se hai un'istanza esistente, hai tempo fino al 20 luglio 2027 per completare la migrazione all'API Chronicle.

Configura l'autenticazione e l'autorizzazione

L'API Chronicle utilizza IAM standard Google Cloud per controllo dell'accesso sicuro. Devi configurare l'ambiente in modo che utilizzi le Google Cloud credenziali.

1. Configura il Google Cloud progetto

2. Imposta la variabile di ambiente delle credenziali

Configura l'ambiente di runtime in modo che utilizzi la chiave scaricata con le Credenziali predefinite dell'applicazione (ADC) impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Le Google Cloud librerie client rilevano automaticamente questa variabile per autenticare le richieste:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

3. Aggiorna gli ambiti OAuth

Se gli script di integrazione legacy hanno richiesto esplicitamente gli ambiti OAuth per la generazione dei token, devi aggiornare la stringa dell'ambito. L'ambito legacy non concede l'accesso alla superficie 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).

Per scenari di autenticazione più avanzati (come la federazione delle identità per i workload per l'autenticazione senza chiavi o la simulazione dell'identità dei account di servizio), consulta Autenticarsi all'API Chronicle.

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 i 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

Un endpoint di servizio è l'URL di base che specifica l'indirizzo di rete di un servizio API. Un singolo servizio può avere più endpoint di servizio. L'API Chronicle è un servizio regionale e supporta solo gli endpoint regionali.

Tutti gli endpoint moderni utilizzano un prefisso coerente, il che rende prevedibile l'indirizzo dell'endpoint finale. Il seguente esempio 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 SIEM di Google Security Operations.

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 API

Analizza i modelli di dati e le strutture degli endpoint moderni forniti nel riferimento API. Non tutti i metodi sono stati modificati in modo significativo e alcuni codici esistenti possono essere riutilizzati. L'obiettivo principale è esaminare la documentazione di riferimento più recente e, per ogni caso d'uso specifico, identificare e implementare le modifiche necessarie ai nomi dei campi e alle strutture dei dati nella logica dell'applicazione.

Utilizza Google Cloud le librerie client

Per semplificare l'integrazione e gestire automaticamente l'autenticazione, l'aggiornamento dei token e i dettagli di trasporto, ti consigliamo di utilizzare lelibrerie 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 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 eseguirne il deployment in produzione:

  1. Crea un piano di test: definisci i casi di test che coprono tutte le funzionalità migrate.
  2. Esegui i test: esegui test automatici e manuali per confermare l'accuratezza e la validità.
  3. Monitora il rendimento: valuta il rendimento dell'applicazione con l'API moderna.

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