Esegui la migrazione all'API Chronicle

Supportata in:

Questo documento è rivolto a te 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. Inoltre, risolve le limitazioni e le complessità presenti nell'API precedente.

L'API SOAR legacy e le chiavi API saranno disponibili fino al 31 marzo 2027, 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 superfici delle API precedenti e quelle nuove:

Area della funzionalità API precedente Nuova API Dettagli
Autenticazione Token API OAuth 2.0 Il nuovo metodo di autenticazione offre una maggiore sicurezza e standardizza la procedura.
Modelli dati Strutture piatte Design orientato alle risorse Questo nuovo design migliora la coerenza dei dati 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.

Programmazione del ritiro

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

Passi per la migrazione

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

rivedi la documentazione

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

Mappa gli endpoint alla nuova superficie dell'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) Crea un'integrazione di gestione temporanea

Se stai modificando un'integrazione personalizzata o un componente di un'integrazione commerciale, ti consigliamo di eseguire prima il push delle modifiche a un'integrazione di gestione temporanea. Questo processo 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 andare al passaggio successivo. Per informazioni dettagliate sulla gestione temporanea dell'integrazione, consulta Testa le integrazioni in modalità temporanea.

Aggiorna 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 endpoint regionali.

Tutti i nuovi endpoint utilizzano un prefisso coerente, rendendo 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 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 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 tutte le richieste 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

Aggiorna il metodo di autenticazione

La nuova API utilizza Google Cloud IAM per l'autenticazione. Dovrai aggiornare l'applicazione o l'integrazione delle risposte 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 Autenticati nell'API Chronicle.

Mappa il account di servizio o l'identità del workload ai parametri SOAR

Se utilizzi un account di servizio o la federazione delle identità dei workload per l'autenticazione nell'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 workload l'accesso necessario ai ruoli e agli ambienti SOC.

Per concedere l'accesso a un service account o l'accesso alla federazione delle identità dei workload a Google SecOps, devi mappare l'identità ai parametri di controllo dell'accesso della piattaforma. Questa mappatura è un passaggio obbligatorio per fornire all'identità l'accesso necessario ai ruoli SOC e agli ambienti richiesti per eseguire attività automatizzate o operazioni API.

  1. Vai a Impostazioni > Gestione accessi > Mappatura dei gruppi.
  2. Fai clic su add Aggiungi.

  3. Completa i campi nella finestra di dialogo Aggiungi mappatura per mappare l'identità ai parametri di controllo dell'accesso della piattaforma.

    1. Nel campo IdP / User group (IdP/Gruppo di utenti), inserisci uno dei seguenti valori:
      • L'indirizzo email completo del tuo account di servizio, se l'identità è stata configurata utilizzando Cloud Identity.
      • La stringa dell'entità Workload Identity, se l'identità è stata configurata utilizzando la federazione delle identità per la forza lavoro.

    2. Configura i seguenti campi di controllo dell'accesso:

      Campo Descrizione
      Gruppi di autorizzazioni Seleziona i gruppi di autorizzazioni per definire i moduli e i sottomoduli a cui l'identità può accedere.
      Ruoli SOC Seleziona i ruoli SOC per definire il ruolo dell'identità (ad esempio Tier 1).
      Ambienti Seleziona gli ambienti o i gruppi di ambienti a cui l'identità può accedere (ad esempio Tutti gli ambienti).
      Membri del gruppo Inserisci gli indirizzi email degli utenti richiesti, se applicabile. Premi Invio dopo aver aggiunto ogni email.
      Azioni limitate Seleziona le azioni limitate per limitare operazioni specifiche all'interno dei moduli.

  4. Fai clic su Aggiungi.

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

Aggiorna 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 parte del codice esistente può essere riutilizzato. 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 all'interno della logica dell'applicazione.

Verifica la tua 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 scenari di test che coprano tutte le funzionalità migrate.
  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 la nuova API.

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