Linee guida per i contributi della community per le integrazioni delle risposte

Supportato in:

Google secops SOAR

Questo documento descrive le linee guida per l'invio di integrazioni di risposta a Google SecOps tramite i contributi della community. Tutte le integrazioni inviate vengono sottoposte a una procedura di verifica da parte del team ufficiale di Google SecOps, con particolare attenzione ai requisiti evidenziati in questo documento.

Metadati di integrazione della risposta

Nome

Il nome deve corrispondere al nome del prodotto con cui verrà integrata l'integrazione e non deve contenere caratteri speciali.

Il nome visualizzato deve essere scritto con spazi vuoti, ad esempio Vertex AI e non VertexAI.

Identificatore integrazione

L'identificatore dell'integrazione è un identificatore univoco dell'integrazione. Una volta creata l'integrazione, questo valore non può essere modificato. L'identificatore deve avere lo stesso valore di Name, ma con gli spazi vuoti rimossi.

L'identificatore è disponibile nella maggior parte delle posizioni della piattaforma.

Descrizione

La Descrizione deve fornire una panoramica generale del prodotto con cui viene creata l'integrazione e non deve superare i 500 caratteri. Deve contenere i seguenti dati:

This integration is owned by the "{vendor name}". Support Contact: {email}.

Evita di inserire URL nella descrizione.

Loghi

Ogni integrazione deve essere fornita con un'icona SVG. Questa icona deve adattarsi ai temi all'interno della piattaforma. Le icone devono ereditare il tema solo dalla piattaforma.

Devi convalidare il logo nelle seguenti pagine:

• Risposta > Configurazione dell'integrazione
• Risposta > Playbook > Playbook Designer
• Casi > Avviso > Visualizzazione playbook avvisi

Di seguito è riportato un esempio di logo SVG, progettato per corrispondere alla nostra guida di stile:

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>
        

Assicurati di codificare il file SVG prima di aggiungerlo al file di definizione dell'integrazione, come puoi vedere in altre integrazioni nell'hub dei contenuti.

Link alla documentazione

Nell'ambito dell'integrazione, puoi aggiungere un link che indirizzi gli utenti alla documentazione. È previsto che questa documentazione venga ospitata da te.

Gli utenti possono accedere al link alla documentazione dalla sezione Parametri della finestra di dialogo Configura istanza.

Parametri di configurazione

Tutte le integrazioni devono contenere parametri di configurazione (API Root + parametri di autenticazione), a meno che l'API sottostante non richieda alcuna autenticazione e l'API Root possa essere codificata in modo permanente. Per tutte le integrazioni in cui è necessaria l'autenticazione, deve essere presente un parametro Verify SSL.

Tutti i parametri devono avere una descrizione. La descrizione deve aiutare gli utenti a configurare l'integrazione all'interno della piattaforma. Evita di inserire URL nella descrizione dei parametri.

Azione di ping

L'azione Ping è un'azione speciale utilizzata dalla piattaforma per convalidare la connettività API. Questa azione è obbligatoria anche se l'integrazione non prevede altre azioni. Ogni volta che l'utente preme il pulsante Test all'interno della configurazione dell'integrazione, deve mostrare uno stato accurato della connettività.

Note di rilascio

La struttura generale delle note di rilascio deve seguire il seguente formato:

• {integration item} - {update}
• Ad esempio: Get Case Details - Added ability to fetch information about affected IOCs

A seconda della situazione, esistono note di rilascio uniche per scenari specifici:

• Se si tratta di una nuova integrazione: New Integration Added - {integration name}
• Se viene aggiunta una nuova azione: New Action Added - {action name}
• Se viene aggiunto un nuovo connettore: New Connector Added - {connector name}
• Se viene aggiunto un nuovo lavoro: New Job Added - {job name}
• Se a un'azione viene aggiunto un widget predefinito: {action name} - Added Predefined Widget.
• Se un widget predefinito viene aggiornato: {action name} - Updated Predefined Widget.
• Per le modifiche che interessano tutti gli elementi di integrazione: Integration - {Update}
• Per le modifiche che interessano tutte le azioni: Integration's Actions - {Update}
• Per le modifiche che interessano tutti i connettori: Integration's Connectors - {Update}
• Per le modifiche che interessano tutti i lavori: Integration's Jobs - {Update}

Se la release conteneva una modifica regressiva, nella nota di rilascio devi specificare REGRESSIVE!. Ad esempio, Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

Le note di rilascio sono disponibili nel riquadro laterale Dettagli integrazione visualizzato quando fai clic sul pulsante Dettagli nell'integrazione.

Controllo delle versioni

Ogni aggiornamento dell'integrazione deve essere seguito da un aggiornamento +1 della versione dell'integrazione. Le versioni devono essere rappresentate come un numero intero. Le versioni secondarie come 11.1.3 o 11.1 non sono consentite.

Tag

(Facoltativo) Puoi aggiungere tag all'integrazione. Evita di creare nuovi tipi di tag; utilizza quelli già presenti nella piattaforma. Se non vedi un tag adatto a te, consulta il team di verifica.

Note generali

• Testa tutti i contenuti dell'integrazione prima dell'invio.
• Esamina tutti i contenuti dell'integrazione per individuare potenziali vulnerabilità e dipendenze vulnerabili.
• Utilizza sempre l'ultima versione supportata di Python durante lo sviluppo (Python 3.11).

Azioni

Nome

Il Nome dell'azione deve puntare all'attività che viene eseguita, ad esempio Recupera dettagli richiesta, Elenca eventi entità o Esegui ricerca.

Se l'azione è progettata per funzionare principalmente con le entità, è preferibile inserire Entity nel nome, ad esempio Enrich Entities.

I nomi delle azioni devono essere espressi in 2-3 parole.

Descrizione

La Descrizione dell'azione deve evidenziare all'utente quale sarà il risultato dell'esecuzione dell'azione.

Se l'azione funziona con le entità, devi aggiungere informazioni sul tipo di entità supportate. Ad esempio:

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

Se l'azione funziona in modalità Async, devi fornire la seguente nota nella descrizione:

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

Cerca di limitare la descrizione a 500 caratteri.

Parametri azione

I parametri di configurazione dell'azione devono avere un nome intuitivo. Evita di utilizzare caratteri speciali e cerca di limitare il nome del parametro azione a 2-4 parole.

La descrizione del parametro deve spiegare all'utente l'impatto che ha sull'esecuzione dell'azione. Se il parametro supporta una quantità predeterminata di valori supportati, all'interno della descrizione fornisci la seguente sezione: Possible Values: {value 1}, {value 2}

Output azione (risultato dello script)

Il risultato dello script deve rappresentare un semplice esito dell'azione. Nella maggior parte dei casi, dovrebbe puntare a una variabile chiamata is_success, che può assumere i valori true o false.

In generale, se l'azione ha terminato l'esecuzione e ha eseguito un'operazione, is_success deve essere true.

Output dell'azione (risultato JSON)

Il risultato JSON è l'output più importante dell'azione. Tutti i dati disponibili nel risultato JSON saranno accessibili durante l'esecuzione del playbook. Verifica che all'output venga inviato un oggetto JSON valido.

I risultati JSON hanno un limite di 15 MB.

Quando crei un risultato JSON, assicurati che non ci siano chiavi che saranno uniche durante l'esecuzione. Ad esempio, il seguente oggetto JSON rappresenta una struttura scadente in quanto non sarebbe utilizzabile nei playbook:

{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}
    

Formatta invece il testo in questo modo:

[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]
   

Se utilizzi entità all'interno dell'azione e restituisci risultati per entità, la best practice è strutturare il risultato JSON nel seguente modo:

[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]
    

Valuta sempre come l'output dell'azione può essere utilizzato all'interno dell'automazione.

Assicurati che sia presente un esempio JSON per l'azione.

L'esempio JSON viene utilizzato dalla piattaforma all'interno del generatore di espressioni durante la procedura di creazione del playbook. Un campione JSON accurato migliora notevolmente l'esperienza di creazione del playbook. Rimuovi tutte le informazioni PII dagli esempi JSON.

Output azione (arricchimento entità)

Se le azioni vengono eseguite sulle entità, durante l'esecuzione dell'azione puoi aggiungere metadati aggiuntivi. La struttura di questi metadati deve seguire questo formato: {integration identifier}_{key}. Ad esempio: WebRisk_is_malicious.

Puoi trovare i metadati aggiunti nella pagina dei dettagli delle entità.

Output azione (messaggio di output)

Il messaggio di output deve spiegare all'utente in modo più descrittivo come è andata l'esecuzione dell'azione. Deve indirizzare l'utente al risultato dell'esecuzione dell'azione.

Se alcune entità sono state arricchite correttamente, ma altre no, la best practice è fornire informazioni sullo stato di ogni entità fornita nel messaggio.

Se ritieni che si sia verificato un errore critico durante l'esecuzione dell'azione, assicurati che sia presente un messaggio dettagliato per questa situazione e che l'azione non vada a buon fine. Quando l'azione non va a buon fine, l'esecuzione del playbook corrispondente viene interrotta finché l'errore non viene risolto o ignorato manualmente.

Alcuni esempi di messaggi di output:

• Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
• Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
• None of the provided entities were found in VirusTotal.
• Successfully executed query "{query}" in Google SecOps.

Se l'azione deve non riuscire e interrompere l'esecuzione del playbook, è consigliabile che il messaggio di output abbia la seguente struttura:

"Error executing action "{action name}". Reason: {error}'

Evita di inserire l'intero traceback per gli errori. Cerca invece di indirizzare l'utente al problema effettivo in linguaggio naturale.

Connettori

Nome

Il Nome del connettore deve indirizzare l'utente ai dati che verranno importati. In generale, la struttura del nome dovrebbe essere la seguente:

• {integration display name} - {data that is being ingested} Connector
• Ad esempio: Crowdstrike - Pull Alerts Connector

Descrizione

La Descrizione del connettore deve evidenziare all'utente cosa verrà importato dal connettore, ad esempio Pull alerts from Crowdstrike. Inoltre, devi fornire informazioni sul supporto degli elenchi dinamici, ad esempio Dynamic List works with the display_name parameter.

In questo caso, la descrizione finale sarà simile alla seguente:

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

Cerca di limitare la descrizione a 500 caratteri.

Parametri del connettore

I parametri di configurazione del connettore devono avere un nome intuitivo. Evita di utilizzare caratteri speciali e cerca di limitare il nome del parametro azione a 2-4 parole.

La descrizione del parametro deve spiegare all'utente l'impatto di questo parametro sull'esecuzione del connettore.

Se il parametro supporta una quantità predeterminata di valori supportati, all'interno della descrizione fornisci la seguente sezione: Possible Values: {value 1}, {value 2}. deve avere i seguenti parametri:

• Max Alerts To Fetch: indica quanti {object} devono essere elaborati durante un'iterazione del connettore.
• Max {Hours/Days} Backwards: determina l'ora di inizio della prima iterazione del connettore. Ad esempio, se Ore massime indietro è impostato su 1, il connettore inizierà a estrarre i dati da un'ora prima.
• Verifica SSL: verifica la connettività all'API/istanza.

Mappatura dell'ontologia

Per ogni connettore creato, è consigliabile fornire il mapping dell'ontologia per verificare che i clienti reciproci ottengano la migliore esperienza.

Il mapping dell'ontologia viene utilizzato per creare automaticamente entità (indicatori di compromissione e asset). Inoltre, vengono definiti i metadati critici dei campi di sistema come Ora di inizio e Ora di fine.

Elenco dinamico

L'elenco dinamico è una funzionalità facoltativa che ti consente di creare un filtro avanzato per l'importazione. Ti offre la flessibilità di creare qualsiasi logica personalizzata, offrendo al contempo un'esperienza utente unica. Il caso d'uso più comune è definire una lista consentita o una lista bloccata per l'importazione.

Se stai creando una logica personalizzata per l'elenco dinamico, assicurati che sia fornita nella descrizione del connettore. Inoltre, è consigliabile utilizzare un parametro Utilizza elenco dinamico come blocklist per supportare anche la logica inversa.

Job

Nome

Il nome del job deve spiegare all'utente cosa sta facendo. In generale, la struttura del nome dovrebbe essere la seguente:

• {integration display name} - {process} Job
• Ad esempio: ServiceNow - Sync Incidents Job

Descrizione

La Descrizione del job deve evidenziare all'utente cosa fa il job durante le iterazioni, ad esempio This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

Cerca di limitare la descrizione a 500 caratteri.

Parametri del job

I parametri di configurazione del job devono avere un nome intuitivo. Evita di utilizzare caratteri speciali e cerca di limitare il nome del parametro azione a 2-4 parole.

La descrizione del parametro deve spiegare all'utente l'impatto di questo parametro sull'esecuzione del job.

Se il parametro supporta una quantità predeterminata di valori supportati, all'interno della descrizione fornisci la seguente sezione:

Possible Values: {value 1}, {value 2}.

Oltre ai parametri di autenticazione, tutti i job devono avere i seguenti parametri:

• Max {Hours/Days} Backwards: determina l'ora di inizio della prima iterazione del job.
• Verifica SSL: verifica la connettività all'API/istanza.

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