Questa pagina è stata tradotta dall'API Cloud Translation.

Codifica di un modulo personalizzato per Security Health Analytics

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

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

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

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

Le specifiche proprietà obbligatorie e facoltative che compongono una definizione YAML sono trattati nella Procedura di programmazione.

Evita di creare rilevatori ridondanti

Per controllare il volume dei risultati, evita di creare ed eseguire moduli che contengono e una funzionalità ridondante.

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

Per ulteriori informazioni sulla disattivazione dei rilevatori, consulta Attiva e disattiva i rilevatori.

Passaggi di programmazione

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

Per codificare un modulo di definizione personalizzata, segui questi passaggi:

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 che il modulo personalizzato deve analizzare. R il tipo di risorsa non può essere specificato più di una volta in un modulo personalizzato definizione di Kubernetes. 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. Qualsiasi proprietà a cui fai riferimento nelle espressioni CEL devono esistere nel Definizione delle API Google Cloud di ogni tipo di risorsa specificato in resource_selector. Per attivare un risultato, l'espressione deve risolversi in TRUE. Ad esempio, nel seguente espressione, solo rotationPeriod valori maggiori di 2592000s trigger un risultato.
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
Per informazioni sulla scrittura di espressioni CEL, consulta le risorse seguenti:
- Tipi di risorse supportati. Fai clic su ciascuna risorsa per visualizzare le proprietà che puoi utilizzare nel Espressioni CEL.
- Scrittura di espressioni CEL.
- Riferimento alle proprietà di risorse e criteri nei moduli personalizzati.
Crea una proprietà description che spieghi la vulnerabilità o e l'errata configurazione rilevata dal modulo personalizzato. Questa spiegazione appare in ogni istanza dei risultati per aiutare gli investigatori 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 spiega come correggere il è stato rilevato un problema. gcloud CLI richiede un carattere di escape prima di alcuni caratteri, ad esempio le virgolette. Le seguenti l'esempio mostra l'utilizzo della barra rovesciata per eseguire l'escape di ogni serie 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 Console Google Cloud; i caratteri di escape non sono obbligatori.
Crea una proprietà severity e specifica il livello di gravità predefinito per l'errore i risultati creati da questo modulo. Valori comunemente utilizzati per l'attributo Le proprietà severity sono LOW, MEDIUM, HIGH e CRITICAL. Ad esempio,
```
severity: MEDIUM
```
Se vuoi, crea una proprietà custom_output e specifica le 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 analizzata o una stringa letterale. Le proprietà devono essere specificate come resource.PROPERTY_NAME. Le stringhe letterali devono essere racchiuse tra virgolette. L'esempio seguente mostra un custom_output definizione che restituisce sia un valore della proprietà, ovvero il valore rotationPeriod nella risorsa CryptoKey analizzata e 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 a 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'account principale organizzazione del modulo personalizzato o sostituisci --organization con --folders o --project e specifica l'ID di la cartella o il progetto padre.
- MODULE_DISPLAY_NAME con un nome da visualizzare come categoria di esiti quando il modulo personalizzato restituisce i 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 di il file YAML che contiene la definizione del modulo personalizzato.
Per ulteriori informazioni sull'utilizzo di Security Health Analytics personalizzato moduli, consulta Utilizzo dei moduli personalizzati per Security Health Analytics.

Latenze di scansione 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é dei seguenti:

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

Esempio di definizione di modulo personalizzato

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

Nell'esempio, tieni presente i seguenti elementi:

Il tipo di asset o risorsa da controllare è elencato in resource_selector in resource_types.
Il controllo che il modulo esegue sulle risorse, sulla sua logica di rilevamento, è definito nella sezione predicate, preceduta da expression.
Sono definite due proprietà sorgente personalizzate, duration e violation nella sezione custom_output.
La spiegazione del problema rilevato è specificata nel description proprietà.
Le indicazioni per correggere il problema rilevato: specificato nella proprietà recommendation. Le virgolette nella guida, è necessario inserire una barra rovesciata prima di ogni le virgolette.

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à delle risorse e dei criteri nei moduli personalizzati

Indipendentemente dal metodo utilizzato per creare un modulo personalizzato, la classe nella console Google Cloud o scrivendo la definizione personalmente, devi poter cercare le proprietà che puoi valutare 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 nell'API definizione 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. Per le proprietà di un criterio, consulta Norme.

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

Quando crei un modulo personalizzato, tutti i riferimenti diretti alla proprietà di una risorsa analizzata deve iniziare con resource, seguito da qualsiasi elemento padre e infine la proprietà target. Le proprietà sono separate in base al punto, utilizzando una notazione dot in stile JSON.

Di seguito sono riportati alcuni esempi di proprietà delle risorse e delle relative modalità di recupero:

resourceName: archivia il nome completo di una risorsa in Cloud Asset Inventory, per 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à dei criteri IAM della risorsa. Le uniche proprietà disponibili sono le associazioni e i ruoli all'interno delle associazioni.

Quando si fa riferimento alle proprietà dei criteri IAM, policy è proprietà di primo livello.

Di seguito sono riportati alcuni esempi di proprietà dei criteri IAM e del loro modo che è possibile recuperare:

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

Per ulteriori esempi, consulta la sezione Esempi di espressioni CEL.

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

Scrittura di espressioni CEL

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

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

Espressioni CEL per la logica di rilevamento

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

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

Se crei un modulo personalizzato nella console Google Cloud, scrivi queste espressioni nell'Editor espressioni nella pagina Configura modulo.

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

Che tu stia utilizzando la console Google Cloud o un file YAML le espressioni CEL che valutano le proprietà delle risorse, devono essere conformi le seguenti regole:

Le proprietà specificate in un'espressione CEL devono essere proprietà della risorsa scansionata, come definito nella definizione della risorsa nell'API. di testo.
Se un modulo personalizzato valuta più tipi di risorse, le proprietà che specificato nelle espressioni CEL devono essere comuni a ciascun tipo di risorsa valuta il modulo personalizzato.

Ad esempio, se definisci un modulo personalizzato invalid_cryptokey che controlla due tipi di risorse: cloudkms.googleapis.com/CryptoKey e cloudkms.googleapis.com/CryptoKeyVersion, potresti scrivere quanto segue perché sia la risorsa CryptoKey che CryptoKeyVersion di tipi includono la proprietà name:
```
predicate:
resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")
```
Tuttavia, non puoi specificare la seguente espressione nel invalid_cryptokey modulo personalizzato perché importTime e Le proprietà rotationPeriod valutate dall'espressione non sono condivise per entrambi i tipi di risorsa:
```
predicate:
resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
```
Tutte le enum in un'espressione CEL devono essere rappresentate come stringhe. Ad esempio, la seguente è un'espressione valida per cloudkms.googleapis.com/CryptoKeyVersion tipo di risorsa:
```
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 quanto segue:

Esempi di espressioni CEL

Nella tabella seguente sono elencate alcune espressioni CEL che possono essere utilizzate per per valutare le proprietà delle risorse. Puoi utilizzarli entrambi nella Console Google Cloud e nelle definizioni di moduli personalizzati YAML.

Tipo di risorsa	Spiegazione	Espressione CEL
Qualsiasi risorsa con un criterio IAM	Controllo dei criteri IAM per identificare i membri esterni al dominio	`!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 unico criterio	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 del virtual private cloud per trovare corrispondenze con i peer di rete	`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 interno in entrata per la Cloud Function	`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'abilitazione solo di API correlate all'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`	Verificare se gli ID progetto in un cluster Dataproc contengono il test o lo sviluppo delle sottostringhe	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

Espressioni CEL per le proprietà dei risultati personalizzati

Facoltativamente, per restituire informazioni aggiuntive con ogni risultato che può essere usata per trovare query, puoi definire fino a dieci proprietà personalizzate da restituire con i risultati generati dai moduli personalizzati.

Le proprietà personalizzate vengono visualizzate nelle proprietà sorgente del risultato nella sezione il relativo JSON e nella scheda Proprietà sorgente dei dettagli del risultato nella console Google Cloud.

Le proprietà personalizzate vengono definite come coppie di name-value.

Se crei un modulo personalizzato nella console Google Cloud, definisci le coppie name-value nelle proprietà dei risultati personalizzati della pagina Definisci i dettagli del risultato.

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

Che tu stia utilizzando la console Google Cloud o un file YAML file, vengono applicate le seguenti regole:

Specifica name come stringa di testo senza virgolette.
Specifica value in uno dei seguenti modi:
- Per restituire il valore di una proprietà, specifica la proprietà nel seguente modo: formato:
  
  RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
Nell'esempio:
- RESOURCE_TYPE può essere resource o policy.
- PROPERTY una o più proprietà principali di contenente 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, consulta Creazione e gestione di moduli personalizzati per Security Health Analytics.