Questa pagina è stata tradotta dall'API Cloud Translation.

Creare un modulo personalizzato per Security Health Analytics

Questa pagina spiega come codificare una definizione di modulo personalizzato utilizzando il Common Expression Language (CEL) e YAML.

Utilizza Google Cloud CLI per caricare le definizioni dei moduli personalizzati in Security Health Analytics.

Nel file YAML, una definizione di modulo personalizzato è costituita da un insieme strutturato di proprietà che utilizzi per definire i seguenti elementi di un modulo personalizzato Security Health Analytics:

Le risorse da scansionare.
La logica di rilevamento da utilizzare.
Le informazioni da fornire ai team di sicurezza in modo che possano comprendere, classificare e risolvere rapidamente il problema rilevato.

Le proprietà specifiche obbligatorie e facoltative che compongono una definizione YAML sono trattate nella sezione Passaggi di codifica.

Evitare di creare rilevatori ridondanti

Per controllare il volume di ricerca, evita di creare ed eseguire moduli che contengano funzionalità ridondanti.

Ad esempio, se crei un modulo personalizzato che verifica le chiavi di crittografia che non vengono ruotate dopo 30 giorni, valuta la possibilità di disattivare il rilevatore Security Health Analytics integrato KMS_KEY_NOT_ROTATED, perché il suo controllo, che utilizza un valore di 90 giorni, sarebbe superfluo.

Per ulteriori informazioni sulla disattivazione dei rilevatori, vedi Attivare e disattivare i rilevatori.

Passaggi di codifica

Codifichi la definizione di un modulo personalizzato per Security Health Analytics come una serie di proprietà YAML, alcune delle quali contengono espressioni CEL.

Per codificare un modulo di definizione personalizzato:

Crea un file di testo con l'estensione del nome file yaml.
Nel file di testo, crea una proprietà resource_selector e specifica da uno a cinque tipi di risorse da scansionare per il modulo personalizzato. Un tipo di risorsa non può essere specificato più di una volta in una definizione di modulo personalizzato. Ad esempio:
```
resource_selector:
 resource_types:
 ‐ cloudkms.googleapis.com/CryptoKey
```
I tipi di risorse specificati devono essere supportati da Security Command Center. Per un elenco dei tipi di risorse supportati, consulta Tipi di risorse supportati.
Crea una proprietà predicate e specifica una o più espressioni CEL che controllano le proprietà dei tipi di risorse da analizzare. Tutte le proprietà a cui fai riferimento nelle espressioni CEL devono esistere nella definizione dell'APIGoogle Cloud di ogni tipo di risorsa che specifichi in resource_selector. Per attivare un risultato, l'espressione deve restituire TRUE. Ad esempio, nell'espressione seguente, solo i valori di rotationPeriod maggiori di 2592000s attivano un risultato.
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
Per assistenza nella scrittura di espressioni CEL, consulta le seguenti risorse:
- Tipi di risorse supportati. Fai clic su ogni risorsa per visualizzare le proprietà che puoi utilizzare nelle espressioni CEL.
- Scrivere espressioni CEL.
- Fare riferimento alle proprietà di risorse e policy nei moduli personalizzati.
Crea una proprietà description che descriva la vulnerabilità o la configurazione errata rilevata dal modulo personalizzato. Questa spiegazione viene visualizzata in ogni istanza del risultato per aiutare gli esaminatori a comprendere il problema rilevato. Il testo deve essere racchiuso tra virgolette. Ad esempio:
```
description: "The rotation period of
 the identified cryptokey resource exceeds 30 days, the
 maximum rotation period that our security guidelines allow."
```
Crea una proprietà recommendation che spieghi come risolvere il problema rilevato. Gcloud CLI richiede un carattere di escape prima di determinati caratteri, ad esempio le virgolette. L'esempio seguente mostra l'utilizzo della barra rovesciata per eseguire l'escape di ogni insieme di virgolette:
```
recommendation: "To fix this issue go to
  https://console.cloud.google.com/security/kms. Click the key-ring that
  contains the key. Click the key. Click \"Edit rotation period\". Then
  set the rotation period to at most 30 days."
```
Se crei o aggiorni un modulo personalizzato utilizzando la consoleGoogle Cloud , i caratteri di escape non sono necessari.
Crea una proprietà severity e specifica la gravità predefinita per i risultati creati da questo modulo. I valori utilizzati più di frequente per la proprietà severity sono LOW, MEDIUM, HIGH e CRITICAL. Ad esempio,
```
severity: MEDIUM
```
Se vuoi, crea una proprietà custom_output e specifica informazioni aggiuntive da restituire con ogni risultato. Specifica le informazioni da restituire come una o più coppie nome-valore. Puoi restituire il valore di una proprietà della risorsa scansionata o una stringa letterale. Le proprietà devono essere specificate come resource.PROPERTY_NAME. Le stringhe letterali devono essere racchiuse tra virgolette. Il seguente esempio mostra una definizione custom_output che restituisce sia un valore della proprietà, il valore di rotationPeriod nella risorsa CryptoKey scansionata, sia una stringa di testo, "Excessive rotation period for CryptoKey":
```
 custom_output:
   properties:
     - name: duration
       value_expression:
         expression: resource.rotationPeriod
     - name: note
       value_expression:
         expression: "Excessive rotation period for CryptoKey"
```
Salva il file in una posizione accessibile alla gcloud CLI.
Carica la definizione in Security Health Analytics con il seguente comando:
```
 gcloud scc custom-modules sha create \
     --organization=organizations/ORGANIZATION_ID \
     --display-name="MODULE_DISPLAY_NAME" \
     --enablement-state="ENABLED" \
     --custom-config-from-file=DEFINITION_FILE_NAME.yaml
```
Sostituisci i seguenti valori:
- ORGANIZATION_ID con l'ID dell'organizzazione principale del modulo personalizzato o sostituisci il flag --organization con --folders o --project e specifica l'ID della cartella o del progetto principale.
- MODULE_DISPLAY_NAME con un nome da visualizzare come categoria di esiti quando il modulo personalizzato restituisce risultati. Il nome deve essere compreso tra 1 e 128 caratteri, iniziare con una lettera minuscola e contenere solo caratteri alfanumerici o trattini bassi.
- DEFINITION_FILE_NAME con il percorso e il nome file del file YAML che contiene la definizione del modulo personalizzato.
Per ulteriori informazioni sull'utilizzo dei moduli personalizzati di Security Health Analytics, consulta Utilizzo dei moduli personalizzati per Security Health Analytics.

Scansiona le latenze per i nuovi moduli personalizzati

La creazione di un modulo personalizzato non attiva una nuova scansione.

Security Health Analytics non inizia a utilizzare un nuovo modulo personalizzato finché non si verifica una delle seguenti condizioni:

La prima scansione batch dopo la creazione del modulo personalizzato. A seconda di quando crei un modulo personalizzato nella pianificazione della scansione batch, potresti dover attendere fino a 24 ore prima che Security Health Analytics inizi a utilizzare il modulo personalizzato.
Una modifica a una risorsa di destinazione attiva una scansione in tempo reale.

Esempio di definizione di un modulo personalizzato

Il seguente esempio mostra una definizione di modulo personalizzato completata che attiva un risultato se il valore della proprietà rotationPeriod di una risorsa cloudkms.googleapis.com/CryptoKey è maggiore di 2.592.000 secondi (30 giorni). L'esempio restituisce due valori facoltativi nella sezione custom_output: il valore di resource.rotationPeriod e una nota come stringa di testo.

Nell'esempio, nota i seguenti elementi:

Il tipo di asset o risorsa da controllare è elencato nella sezione resource_selector sotto resource_types.
Il controllo che il modulo esegue sulle risorse, la sua logica di rilevamento, è definito nella sezione predicate preceduta da expression.
Nella sezione custom_output sono definite due proprietà di origine personalizzate, duration e violation.
La spiegazione del problema rilevato è specificata nella proprietà description.
Le indicazioni per risolvere il problema rilevato sono specifiche nella proprietà recommendation. Poiché le virgolette vengono visualizzate nelle indicazioni, è necessario un carattere di escape della barra rovesciata prima di ogni virgoletta.

severity: HIGH
description: "Regular key rotation helps provide protection against
compromised keys, and limits the number of encrypted messages available
to cryptanalysis for a specific key version."
recommendation: "To fix this issue go to
https://console.cloud.google.com/security/kms. Click the key-ring that
contains the key. Click the key. Click \"Edit rotation period\". Then
set the rotation period to at most 30 days."
resource_selector:
  resource_types:
  - cloudkms.googleapis.com/CryptoKey
predicate:
  expression: resource.rotationPeriod > duration("2592000s")
custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.rotationPeriod
    - name: violation
      value_expression:
        expression:
          "Excessive rotation period for CryptoKey"

Fare riferimento alle proprietà di risorse e policy nei moduli personalizzati

Indipendentemente dal metodo utilizzato per creare un modulo personalizzato, tramite la consoleGoogle Cloud o scrivendo tu stesso la definizione, devi essere in grado di cercare le proprietà che puoi valutare nel modulo personalizzato. Devi anche sapere come fare riferimento a queste proprietà in una definizione di modulo personalizzato.

Trovare le proprietà di una risorsa o di un criterio

Le proprietà di una risorsa Google Cloud sono definite nella definizione API della risorsa. Puoi trovare questa definizione facendo clic sul nome della risorsa in Tipi di risorse supportati.

Puoi trovare le proprietà di un criterio nella documentazione di riferimento dell'API IAM. Per le proprietà di un criterio, vedi Criterio.

Fare riferimento a una proprietà di risorsa in una definizione di modulo personalizzato

Quando crei un modulo personalizzato, tutti i riferimenti diretti alla proprietà di una risorsa scansionata devono iniziare con resource, seguito da eventuali proprietà principali e infine dalla proprietà di destinazione. Le proprietà sono separate da un punto, utilizzando una notazione con punti in stile JSON.

Di seguito sono riportati esempi di proprietà delle risorse e come possono essere recuperate:

resourceName: memorizza il nome completo di una risorsa in Cloud Asset Inventory, ad esempio //cloudresourcemanager.googleapis.com/projects/296605646631.
resource.rotationPeriod: dove rotationPeriod è una proprietà di resource.
resource.metadata.name: dove name è una proprietà secondaria di metadata, che è una proprietà secondaria di resource.

Proprietà dei criteri IAM di riferimento

Puoi creare espressioni CEL che valutano il criterio IAM di una risorsa facendo riferimento alle proprietà del criterio IAM della risorsa. Le uniche proprietà disponibili sono le associazioni e i ruoli all'interno delle associazioni.

Quando fai riferimento alle proprietà dei criteri IAM, policy è la proprietà di primo livello.

Di seguito sono riportati alcuni esempi di proprietà dei criteri IAM e come possono essere recuperati:

policy.bindings, dove bindings è una proprietà di policy.
policy.version, dove version è una proprietà di policy.

Per altri esempi, vedi Espressioni CEL di esempio.

Per informazioni sulle proprietà di un criterio, consulta Criterio.

Scrivere espressioni CEL

Quando crei un modulo personalizzato, utilizzi le espressioni CEL per valutare le proprietà della risorsa analizzata. Facoltativamente, puoi anche utilizzare espressioni CEL per definire coppie name-value personalizzate che restituiscono informazioni aggiuntive con i risultati.

Che tu stia creando un modulo personalizzato nella Google Cloud console o scrivendo tu stesso la definizione del modulo personalizzato in un file YAML, le espressioni CEL che definisci sono le stesse.

Espressioni CEL per la logica di rilevamento

Codifichi la logica di rilevamento di un modulo personalizzato utilizzando espressioni CEL con operatori CEL standard per valutare le proprietà delle risorse analizzate.

Le espressioni possono essere semplici controlli di un singolo valore o espressioni composte più complesse che controllano più valori o condizioni. In ogni caso, l'espressione deve restituire un valore booleano true per attivare un risultato.

Se stai creando un modulo personalizzato nella console Google Cloud , scrivi queste espressioni nell'editor di espressioni nella pagina Configura modulo.

Se stai codificando un modulo personalizzato in un file YAML, aggiungi queste espressioni alla proprietà predicate.

Indipendentemente dal fatto che utilizzi la console Google Cloud o un file YAML, le espressioni CEL che valutano le proprietà delle risorse devono rispettare le seguenti regole:

Le proprietà specificate in un'espressione CEL devono essere proprietà della risorsa scansionata, come definito nella definizione API del tipo di risorsa.
Se un modulo personalizzato valuta più tipi di risorse, le proprietà che specifichi nelle espressioni CEL devono essere comuni a ogni tipo di risorsa valutato dal modulo personalizzato.

Ad esempio, se definisci un modulo personalizzato chiamato invalid_cryptokey che controlla due tipi di risorse: cloudkms.googleapis.com/CryptoKey e cloudkms.googleapis.com/CryptoKeyVersion, puoi scrivere la seguente espressione, perché entrambi i tipi di risorse CryptoKey e CryptoKeyVersion includono la proprietà name:
```
predicate:
resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")
```
Tuttavia, non puoi specificare la seguente espressione nel modulo personalizzato invalid_cryptokey perché le proprietà importTime e rotationPeriod valutate dall'espressione non sono condivise da entrambi i tipi di risorse:
```
predicate:
resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
```
Tutti gli enum in un'espressione CEL devono essere rappresentati come stringhe. Ad esempio, la seguente è un'espressione valida per il tipo di risorsa cloudkms.googleapis.com/CryptoKeyVersion:
```
resource.state = "PENDING_GENERATION"
```
Il risultato delle espressioni CEL che definisci nella proprietà predicate deve essere un valore booleano. Un risultato viene attivato solo se il risultato è true.

Per ulteriori informazioni su CEL, consulta le seguenti risorse:

Espressioni CEL di esempio

La seguente tabella elenca alcune espressioni CEL che possono essere utilizzate per valutare le proprietà delle risorse. Puoi utilizzarli sia nella consoleGoogle Cloud sia nelle definizioni dei moduli personalizzati YAML.

Tipo di risorsa	Spiegazione	Espressione CEL
Qualsiasi risorsa con un criterio IAM	Controllo dei criteri IAM per identificare i membri di domini esterni	`!policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com')))`
`cloudkms.googleapis.com/CryptoKey`	Controllo del periodo di rotazione della chiave Cloud KMS	`has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')`
Più tipi di risorse con un'unica policy	Controlla se il nome della risorsa inizia con `dev` o `devAccess` in base al tipo di risorsa	`(resource.type == 'compute.googleapis.com/Disk' && resource.name.startsWith('projects/PROJECT_ID/regions/ REGION/disks/devAccess')) \|\| (resource.type == 'compute.googleapis.com/Instance ' && resource.name.startsWith('projects/PROJECT_ID/zones/REGION/instances/dev-'))`
`compute.googleapis.com/Network`	Regola di peering Virtual Private Cloud per trovare le reti peer	`resource.selfLink.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default') \|\| resource.peerings.exists(p, p.network.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/shared$'))`
`cloudfunctions.googleapis.com/CloudFunction`	Consenti solo traffico in entrata interno per la funzione Cloud Run	`has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY')`
`compute.googleapis.com/Instance`	Il nome della risorsa corrisponde al pattern	`resource.name.matches('^gcp-vm-(linux\|windows)-v\\d+$')`
`serviceusage.googleapis.com/Service`	Consenti l'attivazione solo delle API correlate allo spazio di archiviazione	`resource.state == 'ENABLED' && !( resource.name.matches('storage-api.googleapis.com') \|\| resource.name.matches('bigquery-json.googleapis.com') \|\| resource.name.matches('bigquery.googleapis.com') \|\| resource.name.matches('sql-component.googleapis.com') \|\| resource.name.matches('spanner.googleapis.com'))`
`sqladmin.googleapis.com/Instance`	Sono consentiti solo IP pubblici nella lista consentita	`(resource.instanceType == 'CLOUD_SQL_INSTANCE' && resource.backendType == 'SECOND_GEN' && resource.settings.ipConfiguration.ipv4Enabled ) && !(resource.ipAddresses.all(ip, ip.type != 'PRIMARY' \|\| ip.ipAddress.matches('IP_ADDRESS'))))`
`dataproc.googleapis.com/Cluster`	Verifica se gli ID progetto in un cluster Dataproc contengono le sottostringhe testing o development	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

Espressioni CEL per le proprietà dei risultati personalizzati

Se vuoi restituire ulteriori informazioni con ogni risultato che possono essere utilizzate nelle query di ricerca, puoi definire fino a dieci proprietà personalizzate da restituire con i risultati generati dai tuoi moduli personalizzati.

Le proprietà personalizzate vengono visualizzate nelle proprietà di origine del problema nel relativo JSON e nella scheda Proprietà di origine dei dettagli del problema nella consoleGoogle Cloud .

Definisci le proprietà personalizzate come coppie name-value.

Se stai creando un modulo personalizzato nella console Google Cloud , definisci le coppie name-value nella sezione Proprietà personalizzate del risultato della pagina Definisci dettagli del risultato.

Se stai codificando un modulo personalizzato in un file YAML, elenca le coppie name-value come properties nella proprietà custom_output.

Indipendentemente dal fatto che utilizzi la console Google Cloud o un file YAML, si applicano le seguenti regole:

Specifica name come stringa di testo senza virgolette.
Specifica value come uno dei seguenti valori:
- Per restituire il valore di una proprietà, specifica la proprietà nel seguente formato:
  
  RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
Nell'esempio:
- RESOURCE_TYPE può essere resource o policy.
- PROPERTY una o più proprietà padre della proprietà che contiene il valore da restituire.
- PROPERTY_TO_RETURN è la proprietà che contiene il valore da restituire.
- Per restituire una stringa di testo, racchiudila tra virgolette.

L'esempio seguente mostra due coppie name-value definite correttamente in custom_output in un file YAML:

custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.name
    - name: property_with_text
      value_expression:
        expression: "Note content"

Passaggi successivi

Per testare, inviare, visualizzare e aggiornare i moduli personalizzati, consulta le seguenti pagine:

Per testare i moduli personalizzati, consulta Testare i moduli personalizzati per Security Health Analytics.
Per caricare, visualizzare e aggiornare i moduli personalizzati, vedi Creazione e gestione di moduli personalizzati per Security Health Analytics.