Eseguire la migrazione all'API Chronicle

Supportato in:

Questo documento si applica se chiami l'API SOAR in modo programmatico utilizzando integrazioni, script personalizzati o azioni personalizzate. Questo documento descrive i passaggi e le considerazioni per aiutarti ad aggiornare i riferimenti API programmatici ai nuovi endpoint API SOAR nell'ambito dell'API Chronicle.

La superficie dell'API Chronicle introduce diversi miglioramenti progettati per semplificare il processo di sviluppo. Affronta anche le limitazioni e le complessità presenti nella vecchia API.

La vecchia API SOAR e le chiavi API saranno disponibili fino al 30 settembre 2026, dopodiché non funzioneranno più.

Prerequisiti

Prima di eseguire la migrazione dell'API SOAR, devi:

Modifiche e miglioramenti principali

La seguente tabella evidenzia le principali differenze tra le vecchie e le nuove superfici API:

Area funzionalità Vecchia API Nuova API Dettagli
Autenticazione Token API OAuth 2.0 Il nuovo metodo di autenticazione offre una maggiore sicurezza e standardizza il processo.
Modelli dati Strutture piatte Progettazione orientata alle risorse Questo nuovo design migliora la coerenza dei dati e semplifica la manipolazione degli oggetti.
Denominazione degli endpoint Flussi di lavoro RESTful e standardizzata Una denominazione coerente rende l'API più intuitiva e più facile da integrare.

Pianificazione del ritiro

Il ritiro completo della vecchia superficie API per SOAR è previsto per il 30 settembre 2026. Ti consigliamo di completare la migrazione prima di questa data per evitare interruzioni del servizio.

Passi per la migrazione

Questa sezione descrive i passaggi per eseguire la migrazione delle applicazioni all'API Chronicle:

Rivedere la documentazione

Acquisisci familiarità con la documentazione completa della nuova API, inclusa la Guida di riferimento dell'API Chronicle.

Mappare gli endpoint alla nuova superficie API

Identifica i nuovi endpoint corrispondenti per ciascuna delle vecchie chiamate API effettuate dalla tua applicazione. Allo stesso modo, mappa i vecchi modelli di dati a quelli nuovi, tenendo conto di eventuali modifiche strutturali o nuovi campi. Per maggiori dettagli, consulta la tabella di mappatura degli endpoint API.

(Facoltativo) Creare un'integrazione di gestione temporanea

Se stai modificando un'integrazione personalizzata o un componente di un'integrazione commerciale, ti consigliamo di eseguire il push delle modifiche prima a un'integrazione di gestione temporanea. Questa procedura ti consente di eseguire test senza influire sui flussi di automazione di produzione. Se stai eseguendo la migrazione di un'applicazione personalizzata che utilizza l'API SOAR, puoi passare al passaggio successivo. Per maggiori dettagli sulla gestione temporanea dell'integrazione, consulta Testare le integrazioni in modalità di gestione temporanea.

Aggiornare l'endpoint di servizio e gli URL

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. Chronicle è un servizio regionale e supporta solo gli endpoint regionali.

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

[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://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1: https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12: https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2: https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3: https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6: https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9: https://chronicle.europe-west9.rep.googleapis.com

  • me-central1: https://chronicle.me-central1.rep.googleapis.com

  • me-central2: https://chronicle.me-central2.rep.googleapis.com

  • me-west1: https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

  • us: https://chronicle.us.rep.googleapis.com

  • eu: https://chronicle.eu.rep.googleapis.com

Ad esempio, per ottenere un elenco di tutti i casi di un progetto negli Stati Uniti:

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

Aggiornare il metodo di autenticazione

La nuova API utilizza Google Cloud IAM per l'autenticazione. Dovrai aggiornare l'applicazione o l'integrazione della risposta per implementare questo nuovo flusso di autenticazione. Assicurati che l'utente che esegue lo script disponga delle autorizzazioni corrette per gli endpoint a cui sta tentando di accedere. Per implementare questo nuovo flusso, devi aggiornare le integrazioni o le applicazioni di risposta. Assicurati che l'utente che esegue lo script disponga delle autorizzazioni necessarie per gli endpoint di destinazione. Per istruzioni dettagliate, consulta la pagina Autenticarsi all'API Chronicle.

Mappare il account di servizio o l'identità del carico di lavoro ai parametri SOAR

Se utilizzi un account di servizio o la federazione delle identità per i workload per autenticarti all'API Chronicle, devi autorizzarlo all'interno della piattaforma per assicurarti che possa comunicare correttamente con Google SecOps. Questa mappatura è necessaria per fornire al account di servizio o all'identità del carico di lavoro l'accesso necessario ai ruoli SOC e agli ambienti.

Per mappare il account di servizio:

  1. Vai a Impostazioni SOAR > Avanzate > Mappatura gruppi.

  2. Fai clic su add Aggiungi.

  3. Nella finestra di dialogo Aggiungi ruolo, inserisci l'indirizzo email completo del service account o la stringa dell'entità Workload Identity nel campo Ruolo IAM / gruppo IdP.

  4. Seleziona i ruoli SOC e gli ambienti appropriati.

  5. Fai clic su Aggiungi.

Per informazioni più dettagliate sulla mappatura di utenti e service account, consulta Mappare gli utenti nella piattaforma utilizzando l'identità di terze parti o Mappare gli utenti nella piattaforma utilizzando Cloud Identity.

Aggiornare la logica dell'API

Analizza i nuovi modelli di dati e le strutture degli endpoint forniti nel riferimento API. Non tutti i metodi sono cambiati in modo significativo e alcuni codici esistenti possono essere riutilizzati. L'obiettivo principale è esaminare la nuova documentazione di riferimento 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.

Verificare l'integrazione

Testa l'applicazione aggiornata in un'integrazione di gestione temporanea 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 la nuova API.

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