Crea un'integrazione personalizzata

Supportato in:

Questo documento spiega come creare integrazioni personalizzate all'interno dell'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 utilizzarli in playbook, azioni manuali e agenti remoti. Sono supportate anche le funzionalità di importazione ed esportazione, in modo simile ad altri elementi dell'IDE.

Crea 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.

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 maggiori dettagli sulla definizione di diversi tipi di dipendenze utilizzando uv, consulta la documentazione di uv sulla gestione delle dipendenze.

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

Prerequisiti

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

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 radice dell'istanza e la chiave API precedente: 
    mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}
  4. Configura il percorso del repository principale locale: 
    mp config --root-path /path/to/cloned/content-hub
  5. Crea una sottodirectory personalizzata per le tue integrazioni proprietarie all'interno del layout del repository all'indirizzo: content-hub/content/response_integrations/custom/

Aggiungere dipendenze comuni o complesse a un'integrazione

Se hai un'integrazione creata nell'IDE che richiede TIPCommon o altre librerie multilivello, utilizza il seguente flusso di lavoro locale per gestire le sue 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. Passa alla cartella dell'integrazione appena estratta: 
    cd {INTEGRATION_NAME}
  4. Utilizza uv per inserire il pacchetto di file wheel TIPCommon richiesto. In questo modo vengono monitorati e scaricati 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 al relativo albero delle dipendenze appena monitorato nella tua istanza Google SecOps: 
    mp push --type integration --name "{INTEGRATION_NAME}"

Verifica dell'installazione

Per verificare che le dipendenze siano state pacchettizzate correttamente senza riscontrare un ciclo errorCode: 2000:

  • 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/Riproduci per eseguire il debug dell'esecuzione. Se lo script viene compilato senza errori e 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 Manager.
  2. Seleziona l'integrazione Armis e inserisci il nome di un manager.
  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
           ))

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 selezionata, 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à eseguito 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:

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

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

Implementare un'azione Ping

La logica dell'azione Ping funziona 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 ArmisManager auth per verificare l'autenticazione.

Attivare l'integrazione

Per abilitare l'integrazione:

  1. In Response > IDE, fai clic sul pulsante di attivazione/disattivazione Attiva/Disattiva in modo che sia impostato su ON.
  2. Fai clic su Salva. Un pulsante verde conferma l'operazione riuscita. Le credenziali dell'hub dei contenuti vengono trasmesse 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, 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.

Esportazione e importazione 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 che 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.