Crea integrazioni personalizzate

Supportato in:

Google SecOps SOAR

Questo documento spiega i flussi di lavoro per la creazione di integrazioni personalizzate per Google SecOps. La best practice attuale consiste nello sviluppare le integrazioni localmente utilizzando l'IDE che preferisci e gestirle tramite GitHub utilizzando i moderni workflow GitOps. Per gli ambienti legacy o i prototipi rapidi, puoi anche creare integrazioni direttamente all'interno dell'IDE SOAR integrato.

Nota: per un framework di sviluppo standardizzato, linee guida per la garanzia di qualità e best practice per la creazione e l'invio di integrazioni personalizzate, consulta la guida alle integrazioni personalizzate.

IDE locale e flusso di lavoro GitHub (consigliato)

Il flusso di lavoro consigliato è lo sviluppo delle integrazioni localmente e la loro gestione tramite GitHub. Questo approccio è in linea con le moderne pratiche GitOps, consentendo un migliore controllo della versione, una collaborazione più efficace e una gestione automatizzata delle dipendenze.

Per passaggi tecnici dettagliati, guide all'installazione e comandi moderni che utilizzano lo strumento Marketplace CLI e il gestore di pacchetti uv, consulta il repository GitHub ufficiale di Chronicle Content Hub.

Panoramica concettuale del flusso di lavoro

Per sviluppare integrazioni personalizzate localmente, ti consigliamo di seguire questo ciclo di vita GitOps. Per la sintassi esatta e aggiornata di questi comandi, consulta la documentazione ufficiale dell'interfaccia a riga di comando MP su GitHub.

1. Fork e clonazione: clona il repository content-hub ufficiale sulla tua macchina di sviluppo locale.
2. Installa gli strumenti: installa lo strumento CLI mp e il gestore di pacchetti Python uv.
3. Autenticazione: accedi al tuo ambiente Google SecOps tramite l'interfaccia a riga di comando MP utilizzando l'URL dell'istanza e le chiavi API.
4. Sviluppa in locale: utilizza l'IDE che preferisci (come VS Code o PyCharm) per scrivere il codice di integrazione, sfruttando gli strumenti di debug e test locali.
5. Gestisci le dipendenze: utilizza uv per dichiarare e gestire le dipendenze (come TIPCommon) nel file pyproject.toml locale.
6. Sincronizza:utilizza i comandi mp pull e mp push per sincronizzare il codice locale con l'istanza Google SecOps per i test e il deployment.

In alternativa: crea un'integrazione personalizzata nell'IDE integrato

Se gestisci integrazioni legacy, testi rapidamente uno script o lavori in un ambiente in cui lo sviluppo locale è limitato, puoi utilizzare l'IDE integrato.

Caso d'uso: crea un'integrazione Armis personalizzata

Per creare l'integrazione personalizzata nell'IDE, segui questi passaggi:

1. Nel menu principale, vai a Risposta > IDE.
2. Fai clic su Create New Item (Crea nuovo elemento) e seleziona Integration (Integrazione).
3. Inserisci un nome e fai clic su Crea.

L'integrazione è ora elencata con l'opzione Impostazioni Impostazioni, che indica che si tratta di un'integrazione personalizzata.

Fai clic su Impostazioni Impostazioni per visualizzare le impostazioni di integrazione in cui puoi definire l'icona, la descrizione, le dipendenze Python e i parametri di integrazione.

Nota: le dipendenze dello script sono librerie Python richieste dalla tua integrazione personalizzata. Le dipendenze possono essere caricate come file .WHL, .TAR, .GZ o .PY. Ogni integrazione viene eseguita nel proprio ambiente virtuale, consentendoti di utilizzare versioni di librerie specifiche, indipendentemente da ciò che è installato sul sistema sottostante.

Se utilizzi un file .WHL personalizzato o proprietario (ad esempio TIPCommon) che richiede sottodipendenze nidificate, devi caricare manualmente i singoli file wheel per l'intero albero delle dipendenze prima di salvare. La mancata risoluzione delle dipendenze nidificate comporta un errore errorCode: 2000 generico. Per un monitoraggio avanzato delle dipendenze, ti consigliamo di utilizzare il flusso di lavoro con IDE locale e GitHub.

Crea un gestore personalizzato

I gestori sono wrapper per le API di strumenti di terze parti. Sebbene non siano obbligatori, ti consigliamo di utilizzarli per le integrazioni che interagiscono con strumenti esterni. I gestori non devono eseguire l'importazione dall'SDK. Dopo la creazione, importale in connettori, azioni e job.

Per creare un gestore personalizzato, segui questi passaggi:

1. Nell'IDE, fai clic su Crea nuovo elemento e seleziona Gestore.
2. Seleziona l'integrazione Armis e inserisci il nome di un gestore.
   
3. Modifica ed esegui questo script:

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token = api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) The response to validate
       :param error_msg: (str) The error message to display
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

Nota: non è necessario un gestore per le azioni di base. Tuttavia, ti consigliamo di crearne una quando raggruppi piccole azioni per l'analisi e la trasformazione dei dati.

Parametri, configurazione di Google SecOps Content Hub e azione Ping

I parametri definiti nelle impostazioni di integrazione vengono visualizzati nella configurazione di Google SecOps Content Hub. I parametri includono:

• Radice API: l'URL di base del servizio a cui ti stai connettendo.
• API Secret: una chiave riservata utilizzata per autenticare l'applicazione con il servizio.
• Casella di controllo Verifica SSL: se abilitata, verifica che il certificato SSL per la connessione al server Armis sia valido.
• Casella di controllo Esegui da remoto: un'impostazione che determina se il codice o l'attività verranno eseguiti su un server remoto anziché localmente. Quando questa opzione è attiva, il sistema invia le istruzioni e i dati necessari a un server dedicato per l'elaborazione.

Per aggiornare i parametri, segui questi passaggi:

1. Inserisci le credenziali corrette.
2. Fai clic su Salva > Test.

Nota: fai sempre clic su Salva dopo aver aggiornato le credenziali. Tutte le integrazioni di terze parti devono implementare un'azione Ping. Il pulsante Test esegue questa azione per convalidare la connettività.

Se l'azione Ping non è presente, il pulsante Test non va a buon fine e viene visualizzata una X rossa.

Implementa un'azione Ping

La logica dell'azione Ping agisce come un'autenticazione riuscita.

Per implementare un'azione Ping, segui questi passaggi:

1. Nell'IDE, crea una nuova Azione nell'integrazione di Armis denominata Ping.
2. Utilizza il metodo auth ArmisManager per verificare l'autenticazione.

Attiva l'integrazione

Per attivare l'integrazione, segui questi passaggi:

1. In Risposta > IDE, fai clic sul pulsante di attivazione/disattivazione Attiva/Disattiva in modo che sia impostato su ON.
2. Fai clic su Salva. Un pulsante di attivazione/disattivazione verde conferma l'esito positivo. Le credenziali dell'hub dei contenuti vengono passate ad ArmisManager. Se auth viene completato senza errori, il pulsante Test mostra un segno di spunta verde.

Utilizza il metodo extract_configuration_param per importare i parametri dalla configurazione dell'integrazione. In alternativa, utilizza extract_action_param per definire i parametri all'interno dell'azione stessa. Tuttavia, l'azione Ping deve sempre utilizzare i parametri di configurazione, poiché vengono testati dall'hub dei contenuti.

Visualizza le integrazioni personalizzate

Vai all'hub dei contenuti e cerca l'integrazione personalizzata che hai creato. Se non hai creato un'immagine durante la configurazione iniziale, verrà assegnata l'immagine personalizzata predefinita. Tieni presente che gli aggiornamenti dell'hub dei contenuti non eseguono l'override o l'eliminazione di eventuali integrazioni personalizzate.

Esporta e importa nell'IDE

Esegui una delle seguenti operazioni:

• Per importare le integrazioni, segui questi passaggi:
1. Carica un file ZIP con la struttura di cartelle corretta. L'integrazione viene visualizzata nell'IDE e nell'hub dei contenuti.
2. Fai clic su Importa. L'integrazione viene visualizzata sia nell'IDE che nell'Hub dei contenuti.
3. Il sistema genera un file ZIP contenente la definizione, gli script e la configurazione. La cartella Managers non è inclusa automaticamente.
• Per esportare le integrazioni, segui questi passaggi:
• Fai clic su Esporta per scaricare il pacchetto.

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