Sviluppare transformer personalizzati

Supportato in:

Google secops SOAR

Nota: questa funzionalità è coperta dai Termini delle offerte pre-GA dei Termini di servizio specifici per 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 per Google SecOps.
Se questa funzionalità non è visibile nel tuo ambiente, consulta Gestire le funzionalità in anteprima o contatta l'amministratore di sistema.

Puoi creare funzioni di trasformazione e operatori logici personalizzati basati su Python direttamente nell'IDE e utilizzarli nelle guide strategiche 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 e operatori logici personalizzati. 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 aggiungi 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 essere 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 Risposta > 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.

Caricare le 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 librerie:

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 transformer 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 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 saperne di più, consulta la panoramica della migrazione di SOAR.

Transformer personalizzati

I transformer personalizzati sono funzioni Python definite dall'utente che estendono le funzioni predefinite nel generatore di espressioni. Puoi crearli direttamente nell'IDE per estrarre e manipolare i dati e possono essere utilizzati insieme alle funzioni integrate esistenti.

Creare un transformer personalizzato

Per definire un nuovo transformer 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. Assegna un nome.
Nota: il nome non può essere modificato dopo la creazione.
5. (Facoltativo) Aggiungi una descrizione. Viene visualizzata quando passi il mouse sopra il transformer 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 main funzione come mostrato in il modello predefinito.
   • Lo script deve restituire un risultato al generatore di espressioni utilizzando la funzione end dell'SDK.
   • L'input del transformer personalizzato può essere di tipi diversi (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 transformer:
     • 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 transformer 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 in-product per il generatore di espressioni:
   • Input previsto: descrivi il tipo di dati che la funzione prevede di ricevere per questo transformer (ad esempio, "Stringa" o "Elenco di stringhe").
   • Output previsto: descrivi il tipo di dati che la funzione prevede di restituire per questo transformer (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 una guida strategica. 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 pesante o l'esecuzione di query su origini esterne.

Utilizzare i transformer personalizzati nel generatore di espressioni

Una volta salvati, i transformer personalizzati vengono visualizzati nell'elenco delle funzioni del generatore 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 per tutti i segnaposto (JSON e non JSON)

Il generatore di espressioni supporta tutti i segnaposto esposti nel progettista di guide strategiche, inclusi i risultati non JSON.

Per i segnaposto non JSON:

• Puoi inserire manualmente dati di esempio nel generatore di espressioni per testare la logica rispetto 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 reinserire i dati di esempio.

Gestione degli errori

Se una funzione di trasformazione personalizzata rileva un errore durante l'esecuzione, l'azione della guida strategica che utilizza il transformer non riesce. Il messaggio di errore specifico generato dallo script Python viene visualizzato sullo schermo nella visualizzazione di esecuzione della guida strategica, consentendoti di risolvere direttamente i problemi della logica.

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 il pacchetto di estensioni di destinazione.
2. Seleziona Operatore logico personalizzato.
3. Assegna un nome.
Nota: il nome non può essere modificato dopo la creazione.
4. (Facoltativo) Aggiungi una descrizione per il menu degli operatori logici nel progettista di guide strategiche.
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 SDK all'interno dell'IDE per 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 definite.

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 (nessun lato destro).

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. Come best practice, concentrati sulle trasformazioni dirette dei dati ed evita di eseguire query su origini esterne o di eseguire un'elaborazione pesante.

Utilizzare nelle guide strategiche

Gli operatori logici personalizzati vengono visualizzati nel menu degli operatori in Condizioni della guida strategica, Condizioni dell'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 personalizzata rileva un errore durante l'esecuzione, la condizione o il passaggio della guida strategica che utilizza l'operatore non riesce. Il messaggio di errore restituito dallo script Python viene visualizzato nella visualizzazione di esecuzione della guida strategica 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.