Utilizzo di moduli personalizzati con Security Health Analytics

Questa pagina spiega come creare, visualizzare, aggiornare ed eliminare moduli personalizzati per Security Health Analytics utilizzando la console Google Cloud o Google Cloud CLI.

Per informazioni più introduttive, consulta Panoramica dei moduli personalizzati per Security Health Analytics.

Prima di iniziare

Per poter lavorare con i moduli personalizzati, devi prima avere i seguenti prerequisiti:

È necessario il livello Premium di Security Command Center. Per ulteriori informazioni sui livelli di Security Command Center, consulta Panoramica dell'attivazione di Security Command Center.
Security Health Analytics deve essere abilitato. Per informazioni su come abilitare Security Health Analytics, consulta Abilitare o disabilitare un servizio integrato.
Al tuo account utente devono essere concessi uno o più ruoli IAM (Identity and Access Management) che contengono le autorizzazioni richieste. Per maggiori informazioni, consulta Autorizzazioni IAM richieste.
Se intendi scrivere moduli personalizzati e caricarli su Security Command Center utilizzando i comandi gcloud, devi avere Google Cloud CLI. Per informazioni sull'installazione di gcloud CLI, consulta Installare gcloud CLI.
Se l'API Security Command Center non è già abilitata, devi abilitarla prima di poter utilizzare i moduli personalizzati per Security Health Analytics. Puoi abilitare l'API Security Command Center nella pagina della libreria API della console Google Cloud.
Per comprendere i limiti di utilizzo per Security Health Analytics, consulta Quote dei moduli personalizzati.

Autorizzazioni IAM richieste

Per lavorare con i moduli personalizzati, devi disporre delle seguenti autorizzazioni IAM (Identity and Access Management):

Autorizzazione	Ruolo
securitycenter.securityhealthanalyticscustommodules.create securitycenter.securityhealthanalyticscustommodules.update securitycenter.securityhealthanalyticscustommodules.delete	roles/securitycenter.settingsEditor roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.get securitycenter.securityhealthanalyticscustommodules.list	roles/securitycenter.settingsViewer roles/securitycenter.adminViewer roles/securitycenter.admin
securitycenter.securityhealthanalyticscustommodules.test	roles/securitycenter.securityHealthAnalyticsCustomModulesTester roles/securitycenter.adminViewer roles/securitycenter.adminEditor roles/securitycenter.admin

Per ulteriori informazioni sulle autorizzazioni e sui ruoli IAM e su come concederli, consulta Concedere un ruolo IAM utilizzando la console Google Cloud.

Crea un modulo personalizzato

Questa sezione spiega come creare moduli personalizzati utilizzando la console Google Cloud o gcloud CLI.

Per testare il modulo personalizzato come passaggio del processo di creazione, devi preparare le definizioni delle risorse di test in un file YAML. Per le istruzioni, consulta Creare risorse di test in un file YAML.

Per creare un modulo personalizzato, seleziona il metodo che vuoi utilizzare dalle seguenti schede:

Console Google Cloud

Per creare un modulo personalizzato nella console Google Cloud, completa i seguenti passaggi:

Vai alla pagina Impostazioni di Security Command Center nella console Google Cloud.

Vai alle Impostazioni
Se richiesto, seleziona l'organizzazione, la cartella o il progetto in cui devi creare il modulo personalizzato.
Nella scheda Security Health Analytics, fai clic su Manage Settings (Gestisci impostazioni).
Fai clic sulla scheda Moduli.
Fai clic su Crea modulo. Si apre la pagina Crea modulo per Security Health Analytics.
Nel riquadro Configura modulo, definisci il nome visualizzato, le risorse da scansionare e la logica di rilevamento:
1. Nel campo Nome modulo, specifica un nome per il modulo. Il nome deve essere compreso tra 1 e 128 caratteri, iniziare con una lettera minuscola e contenere solo caratteri alfanumerici o trattini bassi. Questo nome diventa la categoria dei risultati prodotti dal rilevatore. Non puoi modificare il nome dopo la creazione del modulo.
2. In Aggiungi tipo di risorsa, specifica da uno a cinque tipi di risorse da scansionare. Non puoi specificare un tipo di risorsa più di una volta.
  
  Per un elenco dei tipi di risorse supportati, vedi Tipi di risorse supportati.
3. Nell'editor di espressioni, scrivi espressioni CEL per eseguire controlli booleani su una o più proprietà della risorsa specificata nell'ultimo passaggio. Per attivare un risultato, l'espressione deve risolversi in TRUE. Ad esempio, la seguente espressione attiva un risultato se per una risorsa CryptoKey è stato definito un periodo di rotazione e il periodo di rotazione è superiore a 2.592.000 secondi (30 giorni):
```
has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
```
  Per ulteriori informazioni, consulta le seguenti risorse:
4. Tocca Avanti. Viene visualizzato il riquadro Definisci i dettagli del risultato.
Nel riquadro Definisci i dettagli del risultato, descrivi il problema rilevato dal modulo personalizzato, includendo la gravità, il tipo di problema, come risolverlo e tutti i dati che vuoi includere nei risultati come proprietà sorgente personalizzate:
1. Nel campo Gravità, specifica la gravità del problema. Puoi specificare Low, Medium, High o Critical. Medium è l'impostazione predefinita.
  
  Per informazioni sui livelli di gravità, consulta Classificazioni della gravità per i risultati.
2. Nel campo Descrizione in corso, spiega il problema rilevato dal modulo personalizzato. Questa spiegazione viene visualizzata in ogni istanza di risultato per aiutare i team di sicurezza a comprendere e risolvere il problema rilevato.
3. Nel campo Trovare i passaggi successivi, spiega i passaggi che il team di sicurezza può eseguire per risolvere il problema rilevato.
  
  I passaggi vengono visualizzati con ogni istanza del risultato. Includi passaggi specifici che il team di sicurezza può eseguire per risolvere il problema il più rapidamente possibile.
4. (Facoltativo) Nel campo Proprietà dei risultati personalizzati, specifica fino a dieci coppie nome-valore per definire le proprietà sorgente personalizzate da restituire con ogni istanza del risultato. Le informazioni vengono restituite come proprietà sorgente nel JSON del risultato e vengono visualizzate nella scheda Proprietà sorgente nei dettagli del risultato nella console Google Cloud. Specifica il testo o i valori delle proprietà come coppie chiave-valore:
  - Nel campo Nome proprietà, specifica un nome per la proprietà sorgente personalizzata. Il nome deve essere conforme alle seguenti regole:
    - Il nome deve iniziare con una lettera minuscola.
    - Il nome deve contenere solo caratteri alfanumerici o trattini bassi.
    - Il nome deve avere una lunghezza compresa tra 1 e 128 caratteri.
    - Ciascun nome deve essere univoco tra le altre proprietà sorgente.
  - Nel campo Valore proprietà, specifica uno dei seguenti valori con un massimo di 1024 caratteri:
    - Una stringa di testo racchiusa tra virgolette. Le virgolette sono incluse nel limite di 1024 caratteri. Ad esempio: "This string provides additional useful information."
    - Qualsiasi proprietà della risorsa sottoposta a scansione. Ad esempio, se controlli la risorsa CryptoKey, puoi specificare resource.rotationPeriod. Viene restituito il valore della proprietà rotationPeriod.
5. Tocca Avanti. Viene visualizzato il riquadro Abilita modulo.
(Facoltativo) Utilizza il menu a discesa del riquadro Abilita modulo per specificare se il modulo personalizzato è abilitato o disabilitato al momento della creazione. Per impostazione predefinita, i moduli personalizzati vengono abilitati al momento della creazione. Se specifichi Disabilita, puoi abilitare il modulo in un secondo momento nella scheda Moduli della pagina delle impostazioni di Security Health Analytics.
Tocca Avanti. Si apre il riquadro Modulo di test.
(Facoltativo) Prima di creare il modulo personalizzato, ti consigliamo di testarlo.

Per testare un modulo personalizzato, segui questi passaggi:
1. Crea un file YAML che contiene le definizioni delle risorse di test per le risorse controllate dal modulo personalizzato.
  
  Per informazioni su come creare un file di dati di test, consulta Creare risorse di test in un file YAML.
2. In Carica il file YAML, fai clic su Sfoglia per caricare il file YAML che contiene le definizioni della risorsa di test. Il test si avvia automaticamente quando viene caricato il file.
3. In Anteprima dei risultati dei test, controlla i risultati.
  - Se il file YAML contiene errori di sintassi o altri errori, nella parte inferiore della pagina del browser viene visualizzato un messaggio di errore mobile.
  - Se il test ha esito positivo, il test restituisce le seguenti informazioni:
    - Il nome visualizzato del modulo personalizzato.
    - Il nome arbitrario specificato nella proprietà resource nel file dei dati di test.
    - L'organizzazione, la cartella o il progetto in cui è stato, o sarà, creato il modulo personalizzato.
I risultati dei test non vengono archiviati o scritti in Security Command Center.

Per ulteriori informazioni, consulta la sezione Test di moduli personalizzati.
Fai clic su Crea. Tornerai alla pagina Moduli e dovresti vedere il modulo che hai creato con lo stato Abilitato.

I nuovi moduli personalizzati non sono immediatamente disponibili per l'uso da parte di Security Health Analytics nelle analisi. Per maggiori informazioni, consulta Latenza del rilevamento.

Interfaccia a riga di comando gcloud

Per creare un modulo personalizzato utilizzando i comandi gcloud, devi prima codificare la definizione del modulo personalizzato in un file YAML che include espressioni CEL per la logica di rilevamento e le proprietà di output.

Al termine, caricherai la definizione in Security Command Center utilizzando i comandi di gcloud CLI.

Codifica una definizione di modulo personalizzato in un file YAML in base alle istruzioni riportate in Codificare un modulo personalizzato per Security Health Analytics.
Salva il file YAML in una posizione accessibile alla tua istanza di gcloud CLI.
Carica la definizione personalizzata su Security Command Center:
```
gcloud scc custom-modules sha create \
    PARENT_FLAG=PARENT_ID \
    --display-name="MODULE_DISPLAY_NAME" \
    --enablement-state="ENABLEMENT_STATE" \
    --custom-config-from-file=MODULE_FILE_NAME.yaml
```
Sostituisci quanto segue:
- PARENT_FLAG: il livello al quale stai creando il modulo personalizzato, ovvero --organization, --folder o --project.
- PARENT_ID: l'ID dell'organizzazione, della cartella o del progetto in cui stai creando il modulo personalizzato.
- ENABLEMENT_STATE: enabled o disabled.
- MODULE_DISPLAY_NAME: il nome della categoria di risultati da visualizzare quando il modulo personalizzato restituisce un risultato. Il nome deve essere compreso tra 1 e 128 caratteri, iniziare con una lettera minuscola e contenere solo caratteri alfanumerici o trattini bassi.
- MODULE_FILE_NAME: il percorso e il nome file del file YAML che contiene la definizione del modulo personalizzato.

Latenza del rilevamento

Dopo aver creato o aggiornato la definizione di un modulo personalizzato, potrebbe verificarsi un ritardo di diverse ore prima che il modulo personalizzato nuovo o aggiornato sia disponibile per l'utilizzo nelle analisi.

La creazione o la modifica di un modulo personalizzato non attiva una scansione. Quando un modulo personalizzato è disponibile per l'uso, Security Health Analytics non inizia a utilizzare i moduli personalizzati fino a quando la prima scansione batch o una modifica alla configurazione della risorsa di destinazione non attiva una scansione in tempo reale.

Per ulteriori informazioni sui tipi di scansione di Security Health Analytics, consulta Tipi di scansione di Security Health Analytics.

Aggiornare un modulo personalizzato

Puoi aggiornare la maggior parte delle proprietà dei moduli personalizzati di Security Health Analytics.

Le seguenti proprietà di un modulo personalizzato non possono essere modificate:

Il nome visualizzato.
L'ID del modulo personalizzato.
Il nome completo della risorsa del modulo personalizzato.

Quando aggiorni un modulo personalizzato, gli eventuali risultati emessi in precedenza dal modulo personalizzato non vengono aggiornati contemporaneamente. Se le modifiche al modulo comportano modifiche ai risultati emessi, questi rifletteranno le modifiche solo dopo la successiva scansione in tempo reale o batch di Security Health Analytics.

Per modificare un modulo personalizzato, puoi utilizzare la console Google Cloud o gcloud CLI. Fai clic su una delle seguenti schede per visualizzare le istruzioni.

Console Google Cloud

Per aggiornare un modulo personalizzato esistente nella console Google Cloud, segui questi passaggi:

Vai alla pagina Impostazioni di Security Command Center nella console Google Cloud.

Vai alle Impostazioni
Nel selettore dei progetti, seleziona l'organizzazione, la cartella o il progetto in cui il modulo personalizzato è stato originariamente creato. Non puoi modificare un modulo personalizzato altrove.
Nella scheda Security Health Analytics, fai clic su Manage Settings (Gestisci impostazioni).
Seleziona la scheda Moduli. Vengono visualizzati tutti i moduli di rilevamento di Security Health Analytics.
Utilizza il campo del filtro nella parte superiore dell'elenco dei moduli o scorri per trovare il modulo personalizzato che devi modificare.
Sul lato destro della riga del modulo personalizzato, fai clic sull'icona del menu Azione, .
Nel menu Azione, fai clic sull'icona Modifica (). Viene visualizzata la pagina Visualizza modulo che mostra la scheda Configura modulo.
Modifica i campi personalizzati dei moduli di ogni scheda nella pagina Visualizza modulo in base alle esigenze.
(Facoltativo) Prima di salvare gli aggiornamenti, ti consigliamo di verificarli.

Per testare un modulo personalizzato, segui questi passaggi:
1. Crea un file YAML che contiene le definizioni delle risorse di test per le risorse controllate dal modulo personalizzato.
  
  Per informazioni su come creare un file di dati di test, consulta Creare risorse di test in un file YAML.
2. In Carica il file YAML, fai clic su Sfoglia per caricare il file YAML che contiene le definizioni della risorsa di test. Il test si avvia automaticamente quando viene caricato il file.
3. In Anteprima dei risultati dei test, controlla i risultati.
  - Se il file YAML contiene errori di sintassi o altri errori, nella parte inferiore della pagina del browser viene visualizzato un messaggio di errore mobile.
  - Se il test ha esito positivo, il test restituisce le seguenti informazioni:
    - Il nome visualizzato del modulo personalizzato.
    - Il nome arbitrario specificato nella proprietà resource nel file dei dati di test.
    - L'organizzazione, la cartella o il progetto in cui è stato, o sarà, creato il modulo personalizzato.
I risultati dei test non vengono archiviati o scritti in Security Command Center.

Per ulteriori informazioni, consulta la sezione Test di moduli personalizzati.
Fai clic su Salva in fondo alla pagina. Le modifiche vengono applicate al modulo personalizzato.

Interfaccia a riga di comando gcloud

Per aggiornare un modulo personalizzato utilizzando gcloud CLI, devi prima modificare la definizione YAML del modulo personalizzato, quindi utilizzare i comandi gcloud per aggiornare il modulo personalizzato in Security Health Analytics.

Modifica la definizione del modulo personalizzato. Per informazioni su come codificare la definizione di un modulo personalizzato, consulta Codifica di un modulo personalizzato per Security Health Analytics.
Salva il file YAML modificato in una posizione accessibile a gcloud CLI.
Aggiorna il modulo personalizzato in Security Health Analytics inviando il seguente comando:
```
gcloud scc custom-modules sha update MODULE_ID \
   PARENT_FLAG=PARENT_ID \
   --enablement-state="ENABLED" \
   --custom-config-from-file=MODULE_FILE_NAME.yaml
```
Sostituisci quanto segue:
- MODULE_ID: l'ID o il nome completo della risorsa del modulo personalizzato.
- PARENT_FLAG: il livello a cui è stato creato il modulo personalizzato, --organization, --folder o --project.
- PARENT_ID: l'ID dell'organizzazione, della cartella o del progetto in cui è stato creato il modulo personalizzato.
- MODULE_FILE_NAME: il percorso e il nome file del file YAML che contiene la definizione del modulo personalizzato.

Visualizza un modulo personalizzato

Seleziona una scheda per scoprire come visualizzare la definizione di un modulo personalizzato.

Console Google Cloud

Per visualizzare i moduli personalizzati nella console Google Cloud, segui questi passaggi:

Vai alla pagina Security Health Analytics nelle impostazioni di Security Command Center.

Vai alle Impostazioni
Fai clic sulla scheda Moduli. Si apre il riquadro Moduli.
Se necessario, utilizza il campo del filtro nella parte superiore dell'elenco dei moduli per trovare il modulo personalizzato da modificare.
Per visualizzare i dettagli della definizione del modulo personalizzato, fai clic sull'icona del menu azione, , sul lato destro della riga del modulo personalizzato.
Nel menu Azione, fai clic sull'icona Modifica, . La pagina Visualizza modulo si apre e mostra la scheda Configura modulo.
Fai clic sulle schede nella pagina Visualizza modulo per visualizzare tutti i campi della definizione del modulo personalizzato.

Interfaccia a riga di comando gcloud

Per visualizzare i dettagli di un modulo personalizzato, inserisci il seguente comando:

gcloud scc custom-modules sha get MODULE_ID \
      PARENT_FLAG=PARENT_ID

Sostituisci quanto segue:

MODULE_ID: l'ID o il nome completo della risorsa del modulo personalizzato.
PARENT_FLAG: il livello a cui è stato creato il modulo personalizzato, --organization, --folder o --project.
PARENT_ID: l'ID dell'organizzazione, della cartella o del progetto in cui è stato creato il modulo personalizzato.

Elenco moduli personalizzati

Seleziona una scheda per scoprire come visualizzare un elenco di moduli personalizzati.

Console Google Cloud

Vai alla pagina Security Health Analytics nelle impostazioni di Security Command Center.

Vai alle Impostazioni
Fai clic sulla scheda Moduli. Si apre il riquadro Moduli.
Fai clic nel campo del filtro nella parte superiore dell'elenco dei moduli per visualizzare l'elenco dei tipi di filtro.
Seleziona Tipo e inserisci Custom. L'elenco dei moduli viene aggiornato in modo da mostrare solo i moduli personalizzati.

Interfaccia a riga di comando gcloud

Per visualizzare un elenco di moduli personalizzati, inserisci il seguente comando:

gcloud scc custom-modules sha list \
    PARENT_FLAG=PARENT_ID

Sostituisci quanto segue:

PARENT_FLAG: il livello a cui è stato creato il modulo personalizzato, --organization, --folder o --project.
PARENT_ID: l'ID dell'organizzazione, della cartella o del progetto in cui è stato creato il modulo personalizzato.

Eliminare un modulo personalizzato

Puoi eliminare un modulo personalizzato dall'organizzazione, dalla cartella o dal progetto in cui è stato creato oppure da un'organizzazione o una cartella padre. Non puoi eliminare un modulo personalizzato da una cartella o un progetto che lo eredita.

Per scoprire come eliminare un modulo personalizzato, seleziona una delle seguenti schede.

Console Google Cloud

Vai alla pagina Impostazioni di Security Command Center nella console Google Cloud.

Vai alle Impostazioni
Se richiesto, seleziona l'organizzazione, la cartella o il progetto.
Nella scheda Security Health Analytics, fai clic su Manage Settings (Gestisci impostazioni).
Seleziona la scheda Moduli. Vengono visualizzati tutti i moduli di rilevamento di Security Health Analytics.
Utilizza il campo del filtro nella parte superiore dell'elenco dei moduli o scorri per trovare il modulo personalizzato che devi modificare.
Sul lato destro della riga del modulo personalizzato, fai clic sull'icona del menu Azione, .
Dal menu Azione, fai clic su Elimina. Viene visualizzata la finestra di dialogo Elimina modulo personalizzato.
Nella finestra di dialogo, fai clic su Elimina.

Interfaccia a riga di comando gcloud

Per eliminare un modulo personalizzato, inserisci il seguente comando:

gcloud scc custom-modules sha delete MODULE_ID \
    PARENT_FLAG=PARENT_ID

Sostituisci quanto segue:

MODULE_ID: l'ID o il nome completo della risorsa del modulo personalizzato.
PARENT_FLAG: il livello a cui è stato creato il modulo personalizzato, --organization, --folder o --project.
PARENT_ID: l'ID dell'organizzazione, della cartella o del progetto in cui è stato creato il modulo personalizzato.

I risultati relativi ai moduli personalizzati eliminati vengono contrassegnati come non attivi da Security Health Analytics nella scansione batch successiva.

Esame dei risultati

I risultati generati dai moduli personalizzati possono essere visualizzati nella console Google Cloud o nell'API Security Command Center.

Console Google Cloud

Puoi visualizzare i risultati generati dai tuoi moduli personalizzati con gli altri risultati di Security Command Center nella console Google Cloud.

Per visualizzare i risultati:

Vai alla pagina Risultati nella console Google Cloud.

Vai a Risultati
Se richiesto, seleziona la tua organizzazione.
Nel riquadro Filtri rapidi, scorri verso il basso fino alla sezione Nome visualizzato dell'origine e fai clic su Security Health Analytics Custom. Il riquadro Risultati delle query dei risultati viene aggiornato per mostrare solo i risultati dei moduli personalizzati di Security Health Analytics.

Se non vedi Security Health Analytics Custom, nessun modulo personalizzato ha restituito risultati.
Per visualizzare i dettagli di un risultato specifico, nella colonna Categoria del riquadro Risultati della query dei risultati, fai clic sul nome della categoria del risultato. Il riquadro dei dettagli del risultato si espande mostrando un riepilogo dei dettagli del risultato.
Se per il modulo personalizzato sono state definite proprietà sorgente personalizzate, puoi visualizzarle facendo clic sulla scheda Proprietà sorgente.
Per visualizzare la definizione JSON completa del risultato, fai clic sulla scheda JSON.

Interfaccia a riga di comando gcloud

Per visualizzare i risultati:

Apri una finestra del terminale.

Per ottenere l'ID origine per Security Health Analytics, esegui il comando seguente:

gcloud scc sources describe organizations/ORGANIZATION_ID \
--source-display-name='Security Health Analytics Custom'

L'output di visualizzazione dovrebbe essere simile al seguente. Nell'esempio, SOURCE_ID è un ID assegnato dal server per le origini di sicurezza.

description: ...
displayName: Security Health Analytics Custom
name: organizations/ORGANIZATION_ID/sources/SOURCE_ID

Per elencare tutti i risultati generati dai moduli personalizzati, esegui questo comando:
```
gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID
```

Per elencare i risultati relativi a un modulo personalizzato specifico, esegui questo comando:

gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID --filter="category=\"MODULE_NAME\""

Passaggi successivi

Puoi gestire i risultati generati da moduli personalizzati come tutti i risultati in Security Command Center. Per istruzioni, consulta le seguenti informazioni: