Configura un webhook SOAR

Supportata in:

Google SecOps SOAR

I webhook sono una soluzione leggera per l'importazione degli avvisi della tua organizzazione nella piattaforma SOAR di Google Security Operations.

Gli avvisi importati tramite webhook vengono visualizzati nella piattaforma con le stesse informazioni degli avvisi importati utilizzando i connettori.

Google consiglia di utilizzare un connettore o un webhook della stessa origine, ma non entrambi, per evitare di creare richieste duplicate.

I webhook sono ideali per scenari che richiedono una logica di mappatura di base, mentre i connettori sono più adatti per una mappatura avanzata e flessibile.

Configura un webhook per importare gli avvisi

Per configurare un webhook per l'importazione degli avvisi, segui questi passaggi:

1. Vai a Impostazioni > Gestione dei dati > Webhook SOAR.
2. Fai clic su Aggiungi Aggiungi webhook in entrata.
3. Inserisci un nome per il nuovo webhook e scegli un ambiente.
4. Fai clic su Salva. Dopo il salvataggio, il nuovo webhook viene visualizzato nella pagina principale.
5. Copia l'URL webhook e prendine nota per utilizzarlo in un secondo momento. Devi inserirlo nella piattaforma di origine come destinazione del webhook.

Nota: l'URL webhook viene visualizzato dopo il salvataggio. Copia immediatamente questo URL, poiché non sarà più visibile una volta che avrai lasciato la pagina. Questo URL è necessario per configurare la destinazione del webhook nella piattaforma di origine. Se salvi senza copiare l'URL, fai clic su memorizzato nella cache Genera nuovo URL per crearne uno nuovo.

Dati mappa

Dopo aver caricato un esempio JSON, puoi utilizzare la sezione Mappatura dei dati per mappare i campi del JSON di origine ai campi appropriati in Google Security Operations SOAR. Il sistema elabora il file JSON non elaborato e tu utilizzi l'interfaccia utente (UI) per stabilire le mappature.

1. Nella sezione Mappatura dei dati, fai clic su Carica esempio JSON. Fornisci un campione rappresentativo del payload JSON inviato dal tuo webhook.
2. Mappa i campi di Google Security Operations con i campi corrispondenti nell'esempio JSON. Ad esempio, per mappare il campo obbligatorio StartTime, puoi selezionare un campo timestamp dal tuo JSON, ad esempio Detections.Last.Update.
3. Utilizza il Generatore di espressioni per perfezionare i dati. Ad esempio, puoi utilizzare la funzione Formato data per convertire il timestamp nel formato millisecondi dell'epoca di Unix richiesto. Per saperne di più, consulta Utilizza Expression Builder.
4. Fai clic su Esegui in Expression Builder per testare la mappatura e visualizzare il risultato. Un segno di spunta verde indica che la mappatura è riuscita.
5. Il payload JSON del webhook deve contenere i campi obbligatori per la creazione delle richieste e l'importazione degli avvisi. Per maggiori dettagli, consulta Informazioni sullo schema JSON del webhook.
6. Dopo aver mappato tutti i campi necessari, fai clic su Salva e poi attiva il webhook.

Informazioni sulla mappatura dei campi di destinazione

Quando mappi i dati JSON, li mappi a campi standardizzati all'interno di Google Security Operations SOAR. Questi campi sono organizzati in categorie per aiutarti a normalizzare e strutturare i dati in entrata. I campi disponibili nell'interfaccia utente di mappatura dei dati si basano sull'ontologia del sistema interno. Le categorie principali includono:

• Campi delle entità: utilizza questi campi per i punti dati da cui il sistema può estrarre e modellare automaticamente le entità, come indirizzi IP, nomi di dominio, hash dei file e nomi utente. La mappatura di questi campi arricchisce l'avviso e migliora la correlazione e il pivoting.
• Campi degli eventi generici: utilizzali per i metadati degli eventi generali, come i timestamp (StartTime, EndTime), le descrizioni o i messaggi degli eventi e altri attributi degli eventi comuni.
• Metadati tecnici e del dispositivo: utilizza questi campi per i dettagli tecnici sull'origine dell'evento, come il fornitore e il prodotto del dispositivo di reporting (DeviceVendor, DeviceProduct), la gravità dell'evento e altri attributi tecnici simili.

Esplora i campi disponibili nello strumento di mappatura dei dati nell'interfaccia utente di Google Security Operations SOAR per trovare il campo di destinazione più appropriato per ogni dato nel payload JSON.

Informazioni sullo schema JSON del webhook

Per assicurarti che gli avvisi vengano importati ed elaborati correttamente da Google Security Operations SOAR, il payload JSON del webhook deve seguire una struttura specifica. Le tabelle seguenti descrivono in dettaglio i campi principali previsti nel payload JSON.

Campi principali di richieste e avvisi

Questi campi rappresentano le proprietà di primo livello dell'avviso o del caso in fase di creazione.

Campo	Tipo	Formato consigliato	Obbligatorio	Descrizione	Esempio
TicketId	Stringa	UUID	Sì	Un identificatore univoco globale (GUID) interno per una richiesta all'interno della piattaforma SOAR. Il requisito di unicità di TicketId è condizionale e dipende da DisplayId: Se viene fornito un DisplayId univoco, non è necessario che TicketId sia univoco. Se DisplayId non viene fornito, TicketId deve essere univoco. TicketId ha spesso lo stesso valore di DisplayId.	"f7167971-f641-432f-a06f-ebca3caaa9dd"
SourceSystemName	Stringa	Testo	Sì	Il nome del sistema esterno (ad esempio, SIEM o un sistema di rilevamento e risposta degli endpoint (EDR)) che ha inviato gli avvisi originali a SOAR.	"Splunk"
Name	Stringa	Testo	Sì	Il titolo o il nome della richiesta, spesso tratto dal tipo o dal riepilogo dell'avviso di origine.	"Suspicious Login Attempt"
DeviceVendor	Stringa	Testo	Sì	Il fornitore del dispositivo o del prodotto che ha generato l'avviso. Anche questo può essere mappato dai dati sugli eventi.	"Palo Alto Networks"
RuleGenerator	Stringa	Testo	Sì	Il nome della regola nel sistema di origine (ad esempio, una regola di correlazione SIEM) che ha generato l'avviso.	"Brute Force Attempt Detected"
StartTime	Stringa o numero intero	Millisecondi dall'epoca (UTC) o stringa ISO8601 (ad esempio, "2026-04-09T14:30:00Z")	Sì	L'ora di inizio dell'evento più recente nella richiesta. Se fornisci un numero intero, deve essere espresso in millisecondi dell'epoca di Unix.	1670000000000 o "2026-04-09T14:30:00Z"
Environment	Stringa	Testo	No	Il nome dell'ambiente SOAR a cui appartiene l'avviso. Deve corrispondere a un ambiente definito nelle Impostazioni.	"Default Environment"
Description	Stringa	Testo	No	Una breve descrizione della richiesta o dell'avviso.	"Failed login followed by success from new IP"
DisplayId	Stringa	UUID o stringa	No	Un identificatore utilizzato per scopi di visualizzazione all'interno della UI di SOAR. Questo campo è la chiave primaria che il sistema controlla per rilevare gli avvisi duplicati. Un avviso viene rifiutato come duplicato se DisplayId non è univoco. Questo controllo di unicità su DisplayId ha la precedenza su TicketId. DisplayId ha spesso lo stesso valore di TicketId.	"f7167971-f641-432f-a06f-ebca3caaa9dd"
Reason	Stringa	Testo	No	Il motivo per cui l'avviso è stato creato o attivato.	"Unusual file access patterns detected."
DeviceProduct	Stringa	Testo	No	Il nome del prodotto del fornitore che ha generato l'avviso. Anche questo può essere mappato dai dati sugli eventi.	"Cortex XDR"
EndTime	Stringa o numero intero	Millisecondi dall'epoca (UTC) o stringa ISO8601 (ad esempio, "2026-04-09T14:30:00Z")	No	L'ora di fine dell'ultimo evento della richiesta. Se fornisci un numero intero, deve essere espresso in millisecondi dell'epoca di Unix.	1670000060000 o "2026-04-09T14:31:00Z"
Priority	Numero intero	0-100	No	Il livello di priorità della richiesta. Se non viene fornito, il valore predefinito è 40. (0-19: Informativo, 20-39: Basso, 40-59: Medio, 60-79: Alto, 80-100: Critico)	80
EventsList	Array	Array di oggetti JSON	No	Un array contenente uno o più oggetti evento non elaborati così come ricevuti dall'origine. Consulta Invio di dati sugli eventi non elaborati.	[ { ... }, { ... } ]
EventProduct	Stringa	Testo	No	Il prodotto che ha creato gli eventi.	"Cortex XDR"
EventName	Stringa	Testo	No	Il titolo o il nome dell'evento, spesso tratto dal tipo di avviso o dal riepilogo di origine.	"Suspicious Login Attempt"

Invio di dati sugli eventi non elaborati: l'array EventsList

Devi inviare il payload JSON non elaborato che rappresenta gli eventi così come provengono dal sistema di origine all'interno dell'array EventsList. Questo oggetto è un elemento dell'array EventsList. Poi, esegui la mappatura di campi come source_ip e timestamp utilizzando l'interfaccia utente di mappatura dei dati.

Esempio di oggetto evento nell'array EventsList

{
  "event_id": "9a8b7c-1234-5678",
  "timestamp": "2026-07-01T07:29:50Z",
  "signature": "UserLoginFailed",
  "severity": "Medium",
  "user_name": "administrator",
  "source_ip": "192.168.1.50",
  "destination_ip": "10.0.0.10",
  "domain": "CORP",
  "status": "Failure",
  "Reason": "Wrong Password",
  "EventProduct": "Acme Firewall",
  "EventName": "Failed Login Attempt"
}

Considerazioni principali e best practice

• Timestamp: utilizza i millisecondi dell'epoca di Unix per tutti i campi StartTime e EndTime al livello più alto (come numero intero). All'interno dei dati sugli eventi, fornisci i timestamp così come sono nell'origine; li convertirai nell'interfaccia utente di mappatura dei dati.
• Campi obbligatori: assicurati che tutti i campi contrassegnati con "Sì" nella colonna Obbligatorio siano presenti nel payload JSON.
• Array EventsList: questo array è fondamentale. Anche se l'avviso rappresenta un singolo evento, deve essere inserito nell'array EventsList.
• UI di mappatura dei dati: utilizza lo strumento di mappatura dei dati nella UI di configurazione del webhook per mappare i campi del JSON non elaborato ai campi SOAR di Google Security Operations appropriati.
• Unicità: DisplayId deve essere univoco per ogni nuovo avviso per evitare la deduplicazione. TicketId deve essere univoco se DisplayId non viene fornito.
• Stato della risposta: una risposta HTTP 200 OK dall'endpoint di importazione dei webhook conferma che il payload è stato ricevuto, ma non garantisce che verrà creato un avviso. La creazione degli avvisi può non riuscire durante l'elaborazione downstream a causa della struttura del payload o delle regole di filtro. Puoi monitorare lo stato di elaborazione downstream utilizzando la funzionalità Raccogli i log della piattaforma SOAR.
• Test: utilizza le schede Carica esempio JSON e Test nella pagina Configurazione webhook di SOAR per convalidare la struttura e le mappature del payload.

Nota sulla visualizzazione del timestamp degli eventi: quando i dati sugli eventi vengono importati utilizzando i webhook, la visualizzazione dei campi del timestamp nell'elenco dei dettagli degli avvisi può variare. La piattaforma tenta di formattare i campi che sembrano correlati al tempo, supponendo che il valore sia fornito in millisecondi epoch. Se un campo timestamp (spesso contenente "time" nel nome, ad esempio `@timestamp`) viene inviato in un formato diverso dai millisecondi epoch (ad esempio, `MM/DD/YYYY HH:MM:SS` o `YYYY-MM-DDTHH:MM:SSz`), la visualizzazione elenco potrebbe non mostrare l'ora come previsto. Questo perché il sistema tenta di interpretarlo come millisecondi dall'epoca. Puoi visualizzare il valore non elaborato originale inviato nel webhook facendo doppio clic sul campo del timestamp nell'elenco degli eventi. Per ottenere risultati di visualizzazione più coerenti sulla piattaforma, configura il sistema di origine in modo che invii i valori di ora in millisecondi epoch, se possibile, o assicurati che la conversione sia corretta nell'interfaccia utente di mappatura dei dati.

Testa il webhook

Nella scheda Test puoi testare la funzionalità end-to-end del webhook e visualizzare descrizioni dettagliate degli errori.

1. Nella scheda Test, copia l'URL webhook.
2. Carica un file JSON con i dati pertinenti.
3. Fai clic su Esegui. I risultati vengono visualizzati insieme all'output.

Configura la piattaforma CrowdStrike

Questo caso d'uso illustra i passaggi in CrowdStrike per consentire al webhook di iniziare l'importazione degli avvisi nella piattaforma Google SecOps.

1. Nella dashboard di CrowdStrike Falcon, vai al Falcon Store e installa il componente aggiuntivo Webhooks.
2. Configura il webhook con il nome e l'URL webhook che hai copiato dalla piattaforma Google SecOps, quindi fai clic su Salva.
3. Vai alla sezione Workflows.
4. Fai clic su Crea un workflow.
5. Seleziona un trigger, ad esempio Nuovo rilevamento, e fai clic su Avanti.
6. Seleziona Aggiungi azione.
7. Nella sezione Personalizza azione, seleziona Notifiche dal menu Tipo di azione e seleziona Chiama webhook dal menu Azione.
8. Seleziona il nome che hai aggiunto nel passaggio iniziale e tutti i campi necessari, quindi fai clic su Fine.

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