Crea un connettore personalizzato

Supportato in:

Google secops SOAR

Nota:questo documento presuppone che tu abbia una conoscenza pratica di Python e della programmazione orientata agli oggetti.

Utilizza questo documento per scoprire come l'SDK SOAR crea integrazioni personalizzate per strumenti di terze parti che potrebbero non essere disponibili nell'Hub dei contenuti. I connettori vengono utilizzati per importare i dati da origini dati che di solito, ma non sempre, hanno una sorta di coda di avvisi. Casi, avvisi ed eventi vengono creati nella piattaforma utilizzando l'interazione del connettore con l'applicazione Google SecOps. Un connettore importerà i dati degli eventi di base, li assegnerà a un avviso e poi invierà l'avviso all'applicazione Google SecOps e alla relativa pipeline di trattamento dei dati.

Nota:scopri di più sulla libreria comune TIP.

Per creare un connettore personalizzato, segui questi passaggi di alto livello:

1. Crea una classe Manager che contenga la logica API per lo strumento di terze parti.
2. Crea il connettore utilizzando l'IDE.

Crea l'amministratore

Il primo passaggio per creare un connettore è creare una classe Manager che contenga tutta la logica API richiesta per la tecnologia con cui esegui l'integrazione. Ad esempio, l'integrazione di Netskope in Google SecOps include un gestore predefinito. Questo gestore contiene tutta la logica necessaria per interagire con l'API Netskope e può essere utilizzato come modello per la tua implementazione.

Crea il connettore

Nell'IDE, crea un nuovo connettore seguendo le istruzioni riportate in Creare un'integrazione personalizzata. L'IDE genererà un modello generico che include commenti al codice che descrivono la struttura e i requisiti di base di uno script del connettore.

Sebbene la logica del connettore possa variare, il processo in genere include questi passaggi principali:

1. Utilizza l'API dello strumento di terze parti per recuperare avvisi, rilevamenti o eventi. Nel caso di Netskope, questa operazione viene gestita dal metodo get_alerts(). Per assicurarti che gli avvisi non vengano duplicati, invia una query per timestamp e aggiornala dopo ogni esecuzione.
2. Crea un avviso utilizzando la classe AlertInfo (in precedenza CaseInfo), assegnando tutti i campi obbligatori
3. Recupera e appiattisci i dati degli eventi associati per evitare problemi con elenchi e dizionari nidificati, quindi aggiungi gli eventi appiattiti all'avviso.
4. Ordina gli avvisi per ora e memorizza il timestamp più recente da utilizzare nella query successiva.

Nota:un avviso può contenere più eventi. Ad esempio, le piattaforme SIEM correlano più eventi in un singolo allarme (come Trellix ESM) o reato (come QRadar). Al contrario, gli strumenti di rilevamento degli endpoint in genere generano un evento per avviso. La logica del connettore deve riflettere la struttura dell'origine dati.

Importazioni e SDK

Ogni connettore deve:

• Importa il corso SiemplifyConnectorExecution da SiemplifyConnectors. Questa classe viene in genere istanziata nella funzione main() del connettore. Lo script termina quando questo oggetto passa un elenco di avvisi all'applicazione Google SecOps utilizzando il metodo return_package().
• Importa il corso AlertInfo da SiemplifyConnectorsDataModel. L'istanza di questa classe crea l'oggetto avviso. In questo esempio, viene rinominato in SiemplifyAlertInfo per evitare confusione con gli oggetti di avviso integrati del sistema di origine (Netskope), dove questa ridenominazione è facoltativa.

Il modulo SiemplifyUtils fornisce metodi di uso comune per la registrazione, la gestione dei formati dei dati, le conversioni di tempo e altro ancora. Ti consigliamo di importare output_handler, dict_to_flat e unix_now, in quanto sono essenziali per la funzionalità di base, inclusa la gestione dell'ora.

La maggior parte dei connettori importa anche la classe Manager dell'integrazione. Alcune integrazioni includono più di un gestore. A seconda del caso d'uso, è possibile importare anche altre librerie Python standard.

Nota:i connettori meno recenti possono utilizzare CaseInfo da SiemplifyConnectors. Si tratta della stessa classe di AlertInfo e riflette una convenzione di denominazione ritirata.

Variabili costanti

È buona norma dichiarare alcune variabili costanti per un utilizzo successivo.

Figura 1: variabili costanti

Esempio di script per creare l'avviso Google SecOps

Un avviso viene creato istanziando un oggetto della classe AlertInfo come descritto in precedenza. In questo esempio, viene rinominato in SiemplifyAlertInfo() per evitare confusione con il sistema di origine. L'oggetto alert_info include diverse proprietà obbligatorie che devono essere definite affinché l'applicazione elabori correttamente l'avviso. La funzione build_alert_info riceve un avviso di Netskope (in formato JSON non elaborato, ricevuto dall'API) e l'oggetto Siemplify come input. Analizza poi l'avviso di Netskope e assegna i valori pertinenti ai campi `alert_info`.

Questa funzione utilizza anche le costanti definite in precedenza. Tutte le proprietà impostate sull'oggetto alert_info diventano parte dell'oggetto avviso all'interno dell'applicazione Google SecOps.

La riga 35 (in Figura 2) evidenzia una parte importante di questo processo: l'avviso viene appiattito utilizzando il metodo dict_to_flat, quindi aggiunto alla proprietà events.

Figura 2: esempio di script per creare un avviso

 

Un avviso può contenere più eventi. In questo caso, devi includere la logica per gestire ogni evento in modo appropriato. In questo esempio, ogni avviso contiene un solo evento, quindi l'implementazione predefinita è sufficiente.

Il metodo dict_to_flat viene utilizzato per appiattire la struttura JSON non elaborata. In questo modo, eviterai problemi con elenchi e dizionari nidificati. Le coppie chiave-valore compresse sono versioni leggermente modificate degli originali.

Esamina la seguente logica nella Figura 2:

• A display_id viene assegnato un valore generato in modo casuale utilizzando la libreria uuid. Gli avvisi di Netskope non forniscono un campo UUID, ma se fosse disponibile, potrebbe essere utilizzato.
• ticket_id è impostato in modo che corrisponda a display_id. Entrambi i campi devono essere univoci per ogni avviso nel sistema. Questa unicità è garantita dalla generazione di un UUID casuale.
• name è il nome dell'avviso e verrà visualizzato nella GUI.
• rule_generator si riferisce alla regola che ha generato l'avviso nel sistema di origine. Questo campo potrebbe non essere sempre presente nei dati non elaborati. Se manca, puoi assegnare qualsiasi valore stringa, ma non deve essere lasciato vuoto.
• start_time e end_time rappresentano i timestamp dell'avviso. In questo esempio, l'avviso Netskope fornisce un timestamp Unix epoch, che deve essere moltiplicato per 1000 per convertirlo in millisecondi. Questo è il formato previsto per Google SecOps. Se l'origine utilizza un formato diverso, devi convertirlo. Consulta il modulo SiemplifyUtils.py per metodi utili di conversione dell'ora.
• priority: l'applicazione Google SecOps assegna una priorità a ogni richiesta in base alla priorità del relativo avviso. L'API Google SecOps mappa i valori numerici alle etichette visive utilizzando il seguente schema, in cui il valore intero viene passato nel connettore: {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100} dove il valore intero è quello passato nel connettore. Ad esempio, il passaggio di `100` contrassegna l'avviso come Critico nella GUI. In questo connettore, una funzione di supporto aggiuntiva mappa i valori di gravità di Netskope a questa scala di priorità utilizzando la costante `SEVERITY_MAP`. Tuttavia, poiché i campi di gravità di Netskope non sono coerenti, la mappatura richiede una logica aggiuntiva per valutare più campi.
• A device_vendor e device_product vengono assegnati valori dalle costanti definite in precedenza nello script.
• environment è fondamentale quando utilizzi più ambienti in Google SecOps. In questo caso, proviene dall'oggetto siemplify e si allinea all'ambiente selezionato per il connettore nella piattaforma.
• Nella riga 37 (Figura 3), il connettore modifica il dizionario degli eventi di base aggiungendo una nuova chiave, product_name, con il valore"Netskope". Ciò è necessario perché i dati non elaborati non includono un campo prodotto coerente che può essere utilizzato per la mappatura e la modellazione nell'ontologia della piattaforma.

  

  Figura 3: modifica dell'evento di base

Esempio di script per eseguire il connettore

La funzione main contiene la logica di esecuzione principale per il connettore:

• Il decoratore output_handler viene utilizzato a scopo di debug e non è trattato in questo documento.
• La funzione main include un parametro facoltativo, is_test_run, il cui valore predefinito è False. Come suggerisce il nome, questo parametro determina se il connettore deve importare gli avvisi in produzione o essere eseguito in modalità di test dalla scheda Test connettore nell'applicazione.

Esamina la suddivisione della logica di esecuzione principale per riga di script:

Figura 3: modifica dell'evento di base

• Le righe 56 e 57 inizializzano due elenchi vuoti utilizzati durante l'esecuzione.
• Nella riga 58, la classe SiemplifyConnectorExecution crea un'istanza dell'oggetto siemplify. Questo oggetto gestisce la maggior parte del comportamento di runtime del connettore.
• Alla riga 61 viene creata un'istanza di Connector Allowlist. Sebbene non venga utilizzato in questo connettore, è comunemente utilizzato in altri connettori e non viene trattato in questa guida.
• Nelle righe 67-69, le variabili sono definite per i parametri del connettore, ad esempio le credenziali di autenticazione o le impostazioni di configurazione.
• Nella riga 71, viene creata un'istanza dell'oggetto NetskopeManager e vengono passati i parametri pertinenti per consentire l'autenticazione. La logica interna del gestore che gestisce l'autenticazione non viene mostrata in questo esempio.
• Nella riga 73, recupera un timestamp da un file locale creato durante le esecuzioni precedenti del connettore. Questo timestamp viene utilizzato per evitare di rielaborare gli stessi avvisi.
• Nelle righe 74 e 75 viene gestito il caso in cui il connettore viene eseguito per la prima volta e il timestamp non è ancora impostato (ad esempio, quando il valore predefinito è "0"). Poiché Netskope richiede l'ora dell'epoca Unix e non accetta "0" come ora di inizio valida, viene utilizzata la funzione `unix_now` per recuperare l'ora corrente in millisecondi. Questo valore viene diviso per `1000` per convertirlo in secondi Unix. Le ore di inizio e di fine risultanti vengono quindi passate al metodo `get_alerts` in Manager. Mentre molte API accettano solo un orario di inizio, l'API Netskope richiede sia l'orario di inizio che quello di fine per le query di avviso basate sul tempo.
Nota: la gestione di ora e timestamp è uno degli aspetti più complessi della creazione di un connettore. Sistemi di terze parti diversi restituiscono timestamp in vari formati e alcuni potrebbero non supportare le query basate sullo stesso formato restituito. È essenziale una conoscenza approfondita dell'API del sistema di origine.
• Nella riga 77, recupera un elenco di avvisi da Netskope. Se il connettore è in modalità test, viene selezionato solo l'ultimo avviso nell'elenco (righe 79-80).

Overflow Logic

Il connettore scorre quindi gli avvisi recuperati e crea un avviso da ciascuno utilizzando la funzione build_alert_info definita in precedenza. Aggiunge ogni avviso all'elenco all_alerts, inizializzato in precedenza. La parte successiva della logica del connettore gestisce l'overflow.
L'overflow è un meccanismo di soglia che impedisce l'inserimento di un numero eccessivo di avvisi in un breve periodo di tempo, soprattutto quando gli avvisi condividono lo stesso ambiente, prodotto e generatore di regole. Sebbene non sia obbligatorio, ti consigliamo di implementare la logica di overflow come best practice per evitare il peggioramento delle prestazioni.

Esamina la suddivisione della logica di overflow per riga di script nella Figura 4:

• Nelle righe 104-105, se un alert non è classificato come overflow, viene aggiunto all'elenco degli avvisi da importare.



Figura 4: meccanismo di overflow.

Terminare l'esecuzione del connettore

Se il connettore non è in esecuzione in modalità di test, il timestamp deve essere aggiornato per riflettere l'ultimo avviso recuperato. In questo modo, gli stessi avvisi non vengono reingestiti durante il ciclo di esecuzione successivo. L'elenco all_alerts è ordinato per timestamp, in modo che anche gli avvisi in overflow contribuiscano a determinare il timestamp più recente.

Esamina la suddivisione della logica di esecuzione del connettore per riga di script nella Figura 5:

• Nella riga 126, l'elenco degli avvisi non in overflow viene inviato all'applicazione, dove gli avvisi vengono creati e visualizzati nella GUI.
• Nelle righe 128-131, viene determinato se il connettore è in esecuzione in modalità di test. Per determinare questo valore vengono utilizzati gli argomenti di sistema passati dall'applicazione, ad esempio quando si fa clic su Esegui connettore una volta nella scheda Test.
  

  

  Figura 5: interruzione dell'esecuzione del connettore

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