Funzioni di trasformazione personalizzate e operatori logici

Supportato in:

Google secops SOAR

Nota: questa funzionalità è coperta dai Termini delle offerte pre-GA dei Termini di servizio specifici del servizio Google Security Operations. Le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Per saperne di più, consulta le linee guida per i servizi di assistenza tecnica di Google SecOps e i Termini di servizio specifici di Google SecOps.

Puoi creare funzioni di trasformazione e operatori logici personalizzati basati su Python direttamente all'interno dell'IDE e utilizzarli nei playbook per casi d'uso complessi e versatili.

Pacchetti di estensioni

Un pacchetto di estensioni è un tipo di integrazione specializzato progettato per fungere da contenitore per funzioni di trasformazione personalizzate e operatori logici. A differenza delle integrazioni standard, i pacchetti di estensioni non richiedono la configurazione dell'istanza e possono essere creati direttamente dall'IDE.

Best practice per i pacchetti di estensioni

• Consolidamento:crea un pacchetto di estensioni principale e aggiungici più funzioni di trasformazione o operatori logici.
• Separazione: crea un nuovo pacchetto di estensioni quando hai bisogno di un insieme diverso di librerie Python (dipendenze) che potrebbero entrare in conflitto con il pacchetto principale.

Importante:la creazione di pacchetti di estensioni nell'IDE richiede l'autorizzazione Tutti gli ambienti.

Creare un pacchetto di estensioni

Per creare un nuovo pacchetto di estensioni:

1. Vai a Response > IDE.
2. Fai clic su Aggiungi Crea nuovo elemento.
3. Seleziona Pacchetto di estensioni dal menu a discesa.
4. Fornisci un nome univoco per il pacchetto di estensioni.
Nota:il nome non può essere modificato dopo la creazione.
5. Fai clic su Salva.

Carica dipendenze

Come le integrazioni standard, i pacchetti di estensioni vengono eseguiti in un ambiente virtuale in cui puoi gestire le librerie Python.

Per gestire le tue raccolte:

1. Apri le impostazioni del pacchetto di estensioni nell'IDE.
2. Aggiungi le librerie Python richieste da PyPi o caricale dal tuo computer.

Queste dipendenze sono disponibili per tutti i trasformatori e gli operatori logici contenuti in questo pacchetto di estensioni specifico.

Importazione ed esportazione

Puoi importare ed esportare manualmente i pacchetti di estensioni direttamente nell'interfaccia dell'IDE.

Nota:l'importazione e l'esportazione potrebbero non essere disponibili per i clienti che non hanno ancora completato la migrazione di fase 2. Per maggiori informazioni, consulta la panoramica della migrazione SOAR.

Trasformatori personalizzati

I Custom Transformers sono funzioni Python definite dall'utente che estendono le funzioni predefinite nel builder di espressioni. Puoi crearle direttamente nell'IDE per estrarre e manipolare i dati e possono essere utilizzate insieme alle funzioni integrate esistenti.

Crea un transformer personalizzato

Per definire un nuovo trasformatore personalizzato:

1. Nell'IDE, individua il pacchetto di estensioni di destinazione.
2. Seleziona il pacchetto di estensioni di destinazione per aggiungere un nuovo elemento al pacchetto.
3. Seleziona Funzione di trasformazione personalizzata.
4. Assegnagli un nome.
Nota:il nome non può essere modificato dopo la creazione.
5. (Facoltativo) Aggiungi una descrizione. Viene visualizzato quando passi il mouse sopra il trasformatore personalizzato nel generatore di espressioni.
6. Definisci la logica dello script utilizzando Python. Puoi utilizzare il modello predefinito fornito come punto di partenza.
   • Lo script deve includere una funzione main come mostrato nel modello predefinito.
   • Lo script deve restituire un risultato al generatore di espressioni utilizzando la funzione end dell'SDK.
   • L'input del trasformatore personalizzato può essere di diversi tipi (ad esempio stringa o elenco). Assicurati di convertirlo nel tipo previsto nella funzione main.
   • Puoi utilizzare solo un sottoinsieme dei metodi SDK all'interno dell'IDE per i trasformatori:
     • transformer.extract_param("ParamName"): Per recuperare i valori di input.
     • transformer.LOGGER: Per scrivere log per il debug.
     • transformer.end(result): Per restituire il valore trasformato.
7. Crea parametri:
   • Ogni funzione di trasformazione personalizzata include un parametro Input predefinito. Questo parametro rappresenta i dati di input, ovvero il segnaposto a cui si applica la funzione. Non puoi eliminare questo parametro.
   • Inoltre, puoi aggiungere parametri facoltativi da utilizzare all'interno della funzione.
8. (Facoltativo) Documentazione: definisci la documentazione nel prodotto per lo strumento di creazione delle espressioni:
   • Input previsto: descrivi il tipo di dati che la funzione prevede di ricevere per questo trasformatore (ad esempio "Stringa" o "Elenco di stringhe").
   • Output previsto:descrivi il tipo di dati che la funzione prevede di restituire per questo trasformatore (ad esempio, "booleano").
   • Esempio di utilizzo: fornisci un esempio di come richiamare la funzione (ad esempio, if_empty("new_value")).

Puoi testare la logica della funzione di trasformazione personalizzata direttamente nell'IDE prima di utilizzarla in un playbook. In questo modo puoi verificare che lo script Python gestisca correttamente vari tipi di input e parametri e restituisca i risultati previsti.

Timeout

• Timeout predefinito: 1 minuto.
• Timeout massimo:3 minuti.

Nota: poiché la piattaforma attende il completamento della funzione, devi ridurre al minimo il tempo di esecuzione. Concentrati sulle trasformazioni dirette dei dati ed evita l'elaborazione o l'esecuzione di query pesanti su origini esterne.

Utilizzare i trasformatori personalizzati nel builder di espressioni

Una volta salvate, le trasformazioni personalizzate vengono visualizzate nell'elenco delle funzioni del builder di espressioni insieme alle funzioni integrate. Sono identificati dal formato: ExtensionPackName.TransformerName. Se passi il mouse sopra la funzione, viene visualizzata la documentazione generata dalle descrizioni dei parametri.

Supporto di tutti i segnaposto (JSON e non JSON)

Lo strumento di creazione espressioni supporta tutti i segnaposto esposti in Playbook Designer, inclusi i risultati non JSON.

Per i segnaposto non JSON:

• Puoi inserire manualmente dati di esempio nel generatore di espressioni per testare la logica in base a vari tipi di input: stringa, elenco (valori separati da virgola) e JSON.
• Il test con un tipo di input non garantisce che il segnaposto restituirà quel tipo specifico in fase di runtime.
• La maggior parte dei segnaposto viene risolta come stringhe, ad eccezione di tipi specifici che vengono risolti come stringa o elenco in base alla quantità (ad esempio, entity.identifier). Per questi, è consigliabile trattare sempre l'input come un elenco.

Nota:i dati di esempio sono temporanei e non vengono salvati dopo la chiusura del generatore di espressioni o il salvataggio dell'espressione. Se riapri il generatore, devi inserire di nuovo i dati di esempio.

Gestione degli errori

Se una funzione di trasformazione personalizzata rileva un errore durante l'esecuzione, l'azione del playbook che utilizza il trasformatore non va a buon fine. Il messaggio di errore specifico generato dallo script Python viene visualizzato sullo schermo all'interno della visualizzazione di esecuzione del playbook, consentendoti di risolvere i problemi relativi alla logica direttamente.

Operatori logici personalizzati

Gli operatori logici personalizzati ti consentono di definire la tua logica booleana per confrontare i valori.

Creare un operatore logico personalizzato

Per definire un nuovo operatore logico:

1. Nell'IDE, individua l'Extension Pack di destinazione.
2. Seleziona Operatore logico personalizzato.
3. Assegnagli un nome.
Nota:il nome non può essere modificato dopo la creazione.
4. (Facoltativo) Aggiungi una descrizione per il menu degli operatori logici in Playbook Designer.
5. Definisci la logica dello script utilizzando Python. Puoi utilizzare il modello predefinito fornito come punto di partenza.
   • Lo script deve includere una funzione main.
   • Lo script deve restituire un risultato booleano alla condizione utilizzando la funzione end dell'SDK.
   • Puoi utilizzare solo un sottoinsieme dei metodi dell'SDK all'interno dell'IDE per gli operatori logici:
   • logical_operator.extract_param("ParamName"): Per recuperare i valori di input.
   • logical_operator.LOGGER: Per scrivere log per il debug.
   • logical_operator.end(result): il risultato è un valore booleano (true o false).

Puoi testare la logica dell'operatore logico personalizzato direttamente nell'IDE. In questo modo puoi inserire valori di test per gli argomenti e verificare che la funzione restituisca il risultato booleano corretto (True o False) in base alle condizioni che hai definito.

Parametri

Gli operatori logici personalizzati accettano due parametri: Lato sinistro (obbligatorio e non modificabile) e Lato destro (facoltativo; può essere disattivato dall'utente).

• Esempio 1: if [left side] not in [right side].
• Esempio 2: if [left side] is greater than 80 (nessuna parte destra).

Timeout

• Timeout predefinito: 1 minuto.
• Timeout massimo:3 minuti.

Nota: poiché la piattaforma attende il completamento della funzione, devi ridurre al minimo il tempo di esecuzione. La best practice consiste nel concentrarsi sulle trasformazioni dirette dei dati ed evitare di eseguire query su origini esterne o di eseguire elaborazioni pesanti.

Utilizzo nei playbook

Gli operatori logici personalizzati vengono visualizzati nel menu degli operatori all'interno di Condizioni playbook, Condizioni azione precedente e Selezione entità.

Gli operatori logici personalizzati sono selezionabili insieme agli operatori standard (ad esempio "Uguale a" o "Contiene").

Gestione degli errori

Se una funzione di operatore logico personalizzato rileva un errore durante l'esecuzione, la condizione o il passaggio del playbook che utilizza l'operatore non andrà a buon fine. Il messaggio di errore restituito dallo script Python viene visualizzato nella visualizzazione di esecuzione del playbook per facilitare la risoluzione dei problemi.

Limitazioni

• Le funzioni di trasformazione personalizzate e gli operatori logici non sono supportati in Trigger o Webhook.

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