Creare integrazioni personalizzate

Supportato in:

Google secops SOAR

Questo documento spiega come creare integrazioni personalizzate nell'ambiente di sviluppo integrato (IDE) utilizzando la stessa struttura delle integrazioni commerciali. Puoi trovare e configurare integrazioni personalizzate nell'Hub dei contenuti per vari ambienti. Puoi quindi utilizzarle in playbook, azioni manuali e agenti remoti. È supportata anche la funzionalità di importazione ed esportazione, simile ad altri elementi dell'IDE.

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

Creare un'integrazione personalizzata nell'IDE

Puoi creare un'integrazione personalizzata per il prodotto Armis e creare un gestore insieme a un'azione Ping. Per questa procedura si presuppone la conoscenza di Python e della programmazione orientata agli oggetti.

Caso d'uso: creare un'integrazione Armis personalizzata

Per creare l'integrazione personalizzata nell'IDE:

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

L'integrazione è ora elencata con l'opzione Impostazioni Impostazioni, a indicare 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 degli script sono librerie Python richieste dall'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 specifiche della libreria, indipendentemente da ciò che è installato nel sistema sottostante. Ad esempio, per utilizzare una versione diversa della libreria delle richieste, scaricala da una fonte attendibile come PyPI o GitHub e aggiungila come dipendenza dello script.
Per le dipendenze che richiedono un wheel binario precompilato (come i pacchetti con estensioni C), la piattaforma SOAR utilizza cpython standard creato in base all' manylinux_2_17_x86_64 architettura. Quando selezioni un file .WHL, verifica che sia compatibile con questo tag.
Se una libreria non è installata nell'ambiente virtuale, l'integrazione utilizza la versione installata nel sistema.

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 (ad esempio: anyio, certifi, httpx, idna o sniffio) prima di salvare. Se non riesci a risolvere le dipendenze nidificate, si verifica un errore generico errorCode: 2000. Per un elenco completo delle librerie della piattaforma richieste, consulta la Guida della community su come recuperare TIPCommon.

Se un pacchetto di dipendenze non ha un file wheel precompilato (.WHL) disponibile per l'architettura manylinux_2_17_x86_64 o se hai bisogno di una versione specifica del codice sorgente, puoi fornire un URL diretto al codice sorgente (ad esempio, un file .tar.gz). Il resolver delle dipendenze della piattaforma, uv, supporta la definizione di questi URL di origine nella tabella [tool.uv.sources] all'interno del file pyproject.toml. Ad esempio:

[project]
# ... other project fields ...

[tool.uv.sources]
compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" }
dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }

Per ulteriori dettagli sulla definizione di diversi tipi di dipendenze utilizzando uv, consulta la documentazione su Gestione delle dipendenze.uv

Workflow consigliato: gestione avanzata delle dipendenze utilizzando mp CLI

Per le integrazioni che richiedono librerie esterne complesse o multilivello come TIPCommon, Google consiglia di ignorare completamente i caricamenti manuali dell'IDE e di svilupparli localmente utilizzando lo strumento Marketplace CLI (mp). Questo strumento monitora e impacchetta automaticamente le dipendenze nidificate utilizzando il uv gestore di pacchetti.

Prerequisiti

• Python 3.11 o versioni successive installato sulla macchina di sviluppo locale.
• Il gestore di pacchetti Python uv installato (consulta la uv guida all'installazione).

Configurazione iniziale

1. Crea un fork e clona il repository ufficiale dell'Hub dei contenuti nel tuo ambiente locale.
2. Installa lo strumento mp utilizzando uv:

   uv tool install mp --from git+https://github.com/chronicle/content-hub.git#subdirectory=packages/mp

3. Accedi al tuo ambiente Google SecOps utilizzando l'URL principale dell'istanza e la chiave API legacy:

   mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}

   Nota: lo strumento CLI richiede l'URL dell'istanza SOAR legacy e il formato della chiave API per l'autenticazione.
4. Configura il percorso del repository principale locale:

   mp config --root-path /path/to/cloned/content-hub

5. Crea una sottodirectory personalizzata per le integrazioni proprietarie all'interno del layout del repository in: content-hub/content/response_integrations/custom/

Aggiungere TIPCommon o dipendenze complesse a un'integrazione

Se hai un'integrazione creata nell'IDE che richiede TIPCommon o altre librerie multilivello, utilizza il seguente workflow locale per gestire le relative dipendenze in modo sicuro:

1. Vai alla directory di integrazione personalizzata all'interno del repository clonato:

   cd content-hub/content/response_integrations/custom/

2. Estrai la struttura di integrazione esistente dall'istanza Google SecOps:

   mp pull --type integration --name "{INTEGRATION_NAME}"

3. Cambia directory nella cartella di integrazione appena estratta:

   cd {INTEGRATION_NAME}

4. Utilizza uv per inserire il pacchetto di file wheel TIPCommon richiesto. Questo strumento monitora e scarica automaticamente i wheel delle sottodipendenze nidificate nella configurazione del pacchetto dell'ambiente locale:

   uv pip install /path/to/wheels/TIPCommon-your-version-py3-none-any.whl

5. Esegui il push dell'integrazione completamente compilata insieme all'albero delle dipendenze appena monitorato nell'istanza Google SecOps:

   mp push --type integration --name "{INTEGRATION_NAME}"

Verificare l'installazione

Per verificare che le dipendenze siano state impacchettate correttamente senza riscontrare un errorCode: 2000 loop:

• Apri l'integrazione personalizzata all'interno dell'IDE.
• Aggiungi una riga di test per importare un modulo dal pacchetto, ad esempio: from TIPCommon.extraction import extract_action_param
• Fai clic sul pulsante Test/Esegui per eseguire il debug dell'esecuzione. Se lo script viene compilato correttamente senza generare un ModuleNotFoundError, le dipendenze nidificate vengono risolte correttamente.

Creare un gestore personalizzato

I gestori sono wrapper per le API di strumenti di terze parti. Sebbene non siano obbligatori, li consigliamo per le integrazioni che interagiscono con strumenti esterni. I gestori non devono importare dall'SDK. Dopo la creazione, importali in connettori, azioni e job.

Per creare un gestore personalizzato:

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 lo script seguente:

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: un gestore non è obbligatorio per le azioni di base. Tuttavia, ti consigliamo di crearne uno 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à verrà eseguita su un server remoto anziché localmente. Quando questa opzione è abilitata, il sistema invia le istruzioni e i dati necessari a un server dedicato per l'elaborazione.

Per aggiornare i parametri:

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

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

Se l'azione Ping non è presente, il pulsante Testa non funziona e viene visualizzata una X rossa.

Implementare un'azione Ping

La logica dell'azione Ping si comporta come un'autenticazione riuscita.

Per implementare un'azione Ping:

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

Abilitare l'integrazione

Per abilitare l'integrazione:

1. In Risposta > IDE, sposta l'opzione di attivazione/disattivazione Attiva/Disattiva su ON.
2. Fai clic su Salva. Un'opzione di attivazione/disattivazione verde conferma l'operazione. Le credenziali dell'Hub dei contenuti vengono trasmesse ad ArmisManager. Se auth viene completato senza errori, il pulsante Testa 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, in quanto vengono testati dall'Hub dei contenuti.

Visualizzare 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 sostituiscono né eliminano le integrazioni personalizzate.

Esportare e importare nell'IDE

Esegui una delle seguenti operazioni:

• Per importare le integrazioni:
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 sia nell'Hub dei contenuti.
3. Il sistema genera un file ZIP contenente la definizione, gli script e la configurazione. La cartella Gestori non è inclusa automaticamente.
• Per esportare le integrazioni:
• 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.