Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzo di moduli personalizzati con Security Health Analytics

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

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

Prima di iniziare

Prima di poter utilizzare i moduli personalizzati, devi disporre dei seguenti prerequisiti:

Devi disporre del livello Premium di Security Command Center. Per saperne di più sui livelli di Security Command Center, consulta la panoramica dell'attivazione di Security Command Center.
Security Health Analytics deve essere abilitato. Per informazioni su come attivare Security Health Analytics, consulta Attivare o disattivare un servizio integrato.
Al tuo account utente devono essere assegnati uno o più ruoli IAM (Identity and Access Management) che contengono le autorizzazioni richieste. Per ulteriori informazioni, consulta Autorizzazioni IAM richieste.
Se intendi scrivere i tuoi moduli personalizzati e caricarli in Security Command Center utilizzando i comandi gcloud, devi disporre di Google Cloud CLI. Per informazioni sull'installazione dellgcloud CLI, consulta Installare l'interfaccia a riga di comando gcloud.
Se l'API Security Command Center non è già abilitata, devi farlo prima di poter utilizzare i moduli personalizzati per Security Health Analytics. Puoi attivare l'API Security Command Center nella pagina Libreria API della console Google Cloud.
Per comprendere i limiti di utilizzo di Security Health Analytics, consulta Quote dei moduli personalizzati.

Autorizzazioni IAM richieste

Per utilizzare 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 saperne di più sui ruoli e sulle autorizzazioni IAM e su come concederli, consulta Concedere un ruolo IAM utilizzando la console Google Cloud.

Creare un modulo personalizzato

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

Per testare il modulo personalizzato come passaggio della procedura 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 tra le 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 Gestisci impostazioni.
Fai clic sulla scheda Moduli.
Fai clic su Crea modulo. Viene visualizzata 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, deve iniziare con una lettera minuscola e contenere solo caratteri alfanumerici o trattini bassi. Questo nome diventa la categoria di risultati degli elementi rilevati da questo rilevatore. Non puoi modificare il nome dopo aver creato il 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, consulta Tipi di risorse supportati.
3. Nell'editor di espressioni, scrivi le espressioni CEL per eseguire controlli booleani su una o più proprietà della risorsa specificata nell'ultimo passaggio. Per attivare un rilevamento, l'espressione deve risolvere in TRUE. Ad esempio, la seguente espressione attiva un rilevamento se per una risorsa CryptoKey è definito un periodo di rotazione e questo è superiore a 2.592.000 secondi (30 giorni):
```
has(resource.rotationPeriod) && (resource.rotationPeriod > duration('2592000s'))
```
  Per ulteriori informazioni, consulta le seguenti risorse:
4. Fai clic su Avanti. Viene visualizzato il riquadro Definire i dettagli del risultato.
Nel riquadro Definire i dettagli del rilevamento, descrivi il problema rilevato dal modulo personalizzato, inclusa la gravità, la descrizione del problema, la procedura per risolverlo e tutti i dati da includere nei rilevamenti come proprietà dell'origine personalizzata:
1. Nel campo Gravità, specifica la gravità del problema. Puoi specificare Low, Medium, High o Critical. Medium è il valore predefinito.
  
  Per informazioni sui livelli di gravità, consulta Classificazioni della gravità per i risultati.
2. Nel campo Descrizione del rilevamento, spiega il problema rilevato dal modulo personalizzato. Questa spiegazione viene visualizzata in ogni istanza del risultato per aiutare i team di sicurezza a comprendere e risolvere il problema rilevato.
3. Nel campo Passaggi successivi, spiega i passaggi che il tuo team di sicurezza può intraprendere per risolvere o gestire in altro modo il problema rilevato.
  
  I passaggi vengono visualizzati con ogni istanza del rilevamento. Includi passaggi specifici che il team di sicurezza può seguire per risolvere il problema il più rapidamente possibile.
4. (Facoltativo) Nel campo Proprietà dei risultati personalizzati, specifica fino a 10 coppie nome-valore per definire le proprietà di origine personalizzate da restituire con ogni istanza del risultato. Le informazioni vengono restituite come proprietà di origine nel file JSON del rilevamento e vengono visualizzate nella scheda Proprietà di origine nei dettagli del rilevamento nella console Google Cloud. Specifica i valori di testo o proprietà come coppie chiave-valore:
  - Nel campo Nome proprietà, specifica un nome per la proprietà dell'origine 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.
    - Ogni nome deve essere univoco tra le altre proprietà di origine.
  - Nel campo Valore proprietà, specifica uno dei seguenti valori con un massimo di 1024 caratteri:
    - Una stringa di testo racchiusa tra virgolette. Le virgolette rientrano nel limite di 1024 caratteri. Ad esempio: "This string provides additional useful information."
    - Qualsiasi proprietà della risorsa in fase di scansione. Ad esempio, se stai controllando la risorsa CryptoKey, puoi specificare resource.rotationPeriod. Viene restituito il valore della proprietà rotationPeriod.
5. Fai clic su Avanti. Viene visualizzato il riquadro Attiva modulo.
(Facoltativo) Utilizza il menu a discesa del riquadro Attiva modulo per specificare se il modulo personalizzato deve essere attivato o disattivato al momento della creazione. Per impostazione predefinita, i moduli personalizzati vengono attivati al momento della creazione. Se specifichi Disattiva, puoi attivare il modulo in un secondo momento nella scheda Moduli della pagina delle impostazioni di Security Health Analytics.
Fai clic su Avanti. Viene visualizzato il riquadro Test del modulo.
(Facoltativo) Prima di creare il modulo personalizzato, ti consigliamo di testarlo.

Per testare un modulo personalizzato:
1. Crea un file YAML contenente definizioni di 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 contenente le definizioni delle risorse di test. Il test inizia automaticamente al caricamento del file.
3. In Anteprima dei risultati del test, controlla i risultati.
  - Se il file YAML contiene errori di sintassi o di altro tipo, nella parte inferiore della pagina del browser viene visualizzato un messaggio di errore.
  - Se il test va a buon fine, restituisce le seguenti informazioni:
    - Il nome visualizzato del modulo personalizzato.
    - Il nome arbitrario specificato per la proprietà resource nel file di dati di test.
    - L'organizzazione, la cartella o il progetto in cui è stato o verrà creato il modulo personalizzato.
I risultati dei test non vengono memorizzati o scritti in Security Command Center.

Per ulteriori informazioni, consulta Testare i moduli personalizzati.
Fai clic su Crea. Tornerai alla pagina Moduli e dovresti vedere il modulo che hai creato con lo stato Attivato.

I nuovi moduli personalizzati non sono immediatamente disponibili per Security Health Analytics nelle analisi. Per ulteriori informazioni, consulta la sezione 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 includa le espressioni CEL per la logica di rilevamento e le proprietà di output.

Una volta completata la definizione, caricala in Security Command Center utilizzando i comandi gcloud CLI.

Scrivi una definizione di modulo personalizzato in un file YAML in base alle istruzioni riportate in Scrivere un modulo personalizzato per Security Health Analytics.
Salva il file YAML in una posizione accessibile alla tua istanza gcloud CLI.
Carica la definizione personalizzata in 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 a cui stai creando il modulo personalizzato, --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 che vuoi 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 del file YAML che contiene la definizione del modulo personalizzato.

Latenza del rilevamento

Dopo aver creato o aggiornato la definizione di un modulo personalizzato, può verificarsi un ritardo fino a 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. Una volta che un modulo personalizzato è disponibile per l'utilizzo, Security Health Analytics non inizia a utilizzarlo finché 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 analisi di Security Health Analytics, consulta Tipi di analisi 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, eventuali risultati emessi dal modulo personalizzato in precedenza non vengono aggiornati contemporaneamente. Se le modifiche al modulo comportano modifiche ai risultati emessi, questi rifletteranno le modifiche solo dopo la successiva scansione batch o in tempo reale di Security Health Analytics.

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

Console Google Cloud

Per aggiornare un modulo personalizzato esistente nella console Google Cloud:

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

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

Per testare un modulo personalizzato:
1. Crea un file YAML contenente definizioni di 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 contenente le definizioni delle risorse di test. Il test inizia automaticamente al caricamento del file.
3. In Anteprima dei risultati del test, controlla i risultati.
  - Se il file YAML contiene errori di sintassi o di altro tipo, nella parte inferiore della pagina del browser viene visualizzato un messaggio di errore.
  - Se il test va a buon fine, restituisce le seguenti informazioni:
    - Il nome visualizzato del modulo personalizzato.
    - Il nome arbitrario specificato per la proprietà resource nel file di dati di test.
    - L'organizzazione, la cartella o il progetto in cui è stato o verrà creato il modulo personalizzato.
I risultati dei test non vengono memorizzati o scritti in Security Command Center.

Per ulteriori informazioni, consulta Testare i 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 la gcloud CLI, innanzitutto modifica la definizione YAML del modulo personalizzato e poi utilizza i comandi gcloud per aggiornarlo in Security Health Analytics.

Modifica la definizione del modulo personalizzato. Per informazioni su come codificare una definizione di modulo personalizzato, consulta Codificare un modulo personalizzato per Security Health Analytics.
Salva il file YAML modificato in una posizione accessibile alla gcloud CLI.
Aggiorna il modulo personalizzato in Security Health Analytics emettendo 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 del file YAML che contiene la definizione del modulo personalizzato.

Visualizzare un modulo personalizzato

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

Console Google Cloud

Per visualizzare i moduli personalizzati nella console Google Cloud:

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

Vai alle impostazioni
Fai clic sulla scheda Moduli. Viene visualizzato il riquadro Moduli.
Se necessario, utilizza il campo di 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 Azioni sul lato destro della riga del modulo personalizzato.
Nel menu Azione, fai clic sull'icona Modifica,. Viene visualizzata la pagina Visualizza modulo con 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.

Elenca i 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. Viene visualizzato 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. Gli elenchi dei moduli vengono aggiornati 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 o da un'organizzazione o una cartella principale. 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 la tua organizzazione, la tua cartella o il tuo progetto.
Nella scheda Security Health Analytics, fai clic su Gestisci impostazioni.
Seleziona la scheda Moduli. Vengono visualizzati tutti i moduli di rilevamento di Security Health Analytics.
Utilizza il campo di filtro nella parte superiore dell'elenco dei moduli o scorri per trovare il modulo personalizzato da modificare.
Sul lato destro della riga del modulo personalizzato, fai clic sull'icona del menu di azioni .
Nel 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 inattivi da Security Health Analytics nella scansione batch successiva.

Esaminare i risultati

I risultati generati dai moduli personalizzati possono essere visualizzati nella console Google Cloud, nella console Security Operations (per i clienti Enterprise) o nell'API Security Command Center.

Console

Console Google Cloud

Nella console Google Cloud, vai alla pagina Risultati di Security Command Center.
Vai a Risultati
Seleziona il tuo progetto o la tua organizzazione Google Cloud.
Nella sezione Filtri rapidi, nella sottosezione Nome visualizzato dell'origine, seleziona Personalizzato di Security Health Analytics. I risultati della query sui risultati vengono aggiornati in modo da mostrare solo i risultati di questa origine.
Per visualizzare i dettagli di un determinato riscontro, fai clic sul nome del riscontro nella colonna Categoria. Viene visualizzato il riquadro dei dettagli del risultato e la scheda Riepilogo.
Nella scheda Riepilogo, esamina i dettagli del risultato, incluse informazioni su ciò che è stato rilevato, la risorsa interessata e, se disponibili, i passaggi che puoi svolgere per risolvere il problema.
(Facoltativo) Per visualizzare la definizione JSON completa del rilevamento, fai clic sulla scheda JSON.

Console Security Operations

Nella console Security Operations, vai alla pagina Risultati.
```
https://CUSTOMER_SUBDOMAIN.backstory.chronicle.security/posture/findings
```
Sostituisci CUSTOMER_SUBDOMAIN con l'identificatore specifico del cliente.
Nella sezione Aggregazioni, fai clic per espandere la sottosezione Nome visualizzato della sorgente.
Seleziona Security Health Analytics personalizzato. I risultati della query sui risultati vengono aggiornati in modo da mostrare solo i risultati di questa origine.
Per visualizzare i dettagli di un determinato riscontro, fai clic sul nome del riscontro nella colonna Categoria. Viene visualizzato il riquadro dei dettagli del risultato e la scheda Riepilogo.
Nella scheda Riepilogo, esamina i dettagli del risultato, incluse informazioni su ciò che è stato rilevato, la risorsa interessata e, se disponibili, i passaggi che puoi svolgere per risolvere il problema.
(Facoltativo) Per visualizzare la definizione JSON completa del rilevamento, 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 seguente comando:

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

L'output del display 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 il seguente comando:
```
gcloud scc findings list ORGANIZATION_ID --source=SOURCE_ID
```

Per elencare i risultati per un modulo personalizzato specifico, esegui il seguente comando:

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

Passaggi successivi

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