Questa pagina spiega come programmare la definizione di un 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 è composta da un set strutturato di proprietà che utilizzi per definire i seguenti elementi di un modulo personalizzato di 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 costituiscono una definizione YAML sono trattate nella sezione Passaggi di programmazione.
Evitare di creare rilevatori ridondanti
Per controllare il volume dei risultati, evita di creare ed eseguire moduli che contengono funzionalità ridondanti.
Ad esempio, se crei un modulo personalizzato che verifica la presenza di chiavi di crittografia che non vengono ruotate dopo 30 giorni, valuta la possibilità di disattivare il rilevatore integrato di Security Health Analytics KMS_KEY_NOT_ROTATED
, in quanto il relativo controllo, che utilizza un valore di 90 giorni, sarebbe superfluo.
Per maggiori informazioni sulla disattivazione dei rilevatori, consulta Abilitare e disabilitare i rilevatori.
Passaggi di programmazione
Codifica 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 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 possa analizzare. 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, vedi Tipi di risorse supportati.
Crea una proprietà
predicate
e specifica una o più espressioni CEL che controllano le proprietà dei tipi di risorse da scansionare. Qualsiasi proprietà a cui fai riferimento nelle espressioni CEL deve esistere nella definizione dell'API Google Cloud di ogni tipo di risorsa specificato inresource_selector
. Per attivare un risultato, l'espressione deve risolversi inTRUE
. Ad esempio, nella seguente espressione, solo i valorirotationPeriod
superiori a2592000s
attivano un risultato.predicate: expression: resource.rotationPeriod > duration("2592000s")
Per informazioni sulla scrittura di espressioni CEL, consulta le seguenti risorse:
- Tipi di risorse supportati. Fai clic su ciascuna risorsa per visualizzare le proprietà che puoi utilizzare nelle espressioni CEL.
- Scrittura di espressioni CEL.
- Riferimento alle proprietà delle risorse e dei criteri nei moduli personalizzati.
Crea una proprietà
description
che spiega la vulnerabilità o l'errata configurazione rilevata dal modulo personalizzato. Questa spiegazione viene visualizzata in ogni istanza del risultato 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 risolvere il problema rilevato. Gcloud CLI richiede un carattere di escape prima di alcuni caratteri, ad esempio le virgolette. L'esempio seguente 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 la console Google 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 comunemente utilizzati per la proprietàseverity
sonoLOW
,MEDIUM
,HIGH
eCRITICAL
. Ad esempio:severity: MEDIUM
Se vuoi, puoi creare una proprietà
custom_output
e specificare 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 comeresource.PROPERTY_NAME
. Le stringhe letterali devono essere racchiuse tra virgolette. L'esempio seguente mostra una definizionecustom_output
che restituisce sia un valore di proprietà, il valore dirotationPeriod
nella risorsaCryptoKey
analizzata, 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 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'organizzazione principale del modulo personalizzato oppure sostituisci il flag--organization
con--folders
o--project
e specifica l'ID della cartella o del progetto padre.MODULE_DISPLAY_NAME
con un nome da visualizzare come categoria di risultati 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 maggiori informazioni sull'utilizzo dei moduli personalizzati di Security Health Analytics, consulta Utilizzo di 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 inizia a utilizzare un nuovo modulo personalizzato solo dopo che:
- 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.
Definizione di modulo personalizzato di esempio
L'esempio seguente mostra una definizione di modulo personalizzato completata che attiva un risultato se il valore della proprietà rotationPeriod
di una risorsa cloudkms.googleapis.com/CryptoKey
è superiore a 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, tieni presente i seguenti elementi:
- Il tipo di asset o risorsa da controllare è elencato nella sezione
resource_selector
inresource_types
. - Il controllo eseguito dal modulo sulle risorse, la sua logica di rilevamento, viene definito nella sezione
predicate
preceduta daexpression
. - Due proprietà sorgente personalizzate,
duration
eviolation
, sono definite nella sezionecustom_output
. - La spiegazione del problema rilevato è specificata nella
proprietà
description
. - Le indicazioni per risolvere il problema rilevato sono specificate nella proprietà
recommendation
. Poiché le virgolette compaiono nelle indicazioni, è necessario un carattere di escape barra rovesciata prima di ogni virgola.
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 criteri nei moduli personalizzati
Indipendentemente dal metodo utilizzato per creare un modulo personalizzato (utilizzando la console Google Cloud o scrivendo la definizione personalmente), devi essere in grado di cercare le proprietà che puoi valutare nel modulo personalizzato. Inoltre, devi 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.
Le proprietà di un criterio sono disponibili nella documentazione di riferimento dell'API IAM. Per le proprietà di un criterio, consulta Criteri.
Riferimento a una proprietà di una risorsa in una definizione di modulo personalizzato
Quando crei un modulo personalizzato, tutti i riferimenti diretti alla proprietà di una risorsa analizzata devono iniziare con resource
, seguito da eventuali proprietà padre e infine dalla proprietà target. Le proprietà sono separate
da un punto, utilizzando una notazione di punti in stile JSON.
Di seguito sono riportati alcuni esempi di proprietà delle risorse e di 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
: doverotationPeriod
è una proprietà diresource
.resource.metadata.name
: dovename
è una proprietà secondaria dimetadata
, che è una proprietà secondaria diresource
.
Riferimento alle proprietà dei criteri IAM
Puoi creare espressioni CEL che valutano i criteri 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 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 di come possono essere recuperate:
policy.bindings
, dovebindings
è una proprietà dipolicy
.policy.version
, doveversion
è una proprietà dipolicy
.
Per ulteriori esempi, consulta Esempi di espressioni CEL.
Per informazioni sulle proprietà di un criterio, consulta la sezione Criteri.
Scrittura di espressioni CEL
Quando crei un modulo personalizzato, utilizzi le espressioni CEL per valutare le proprietà della risorsa analizzata. Facoltativamente, puoi anche utilizzare le espressioni CEL per definire coppie name
-value
personalizzate che restituiscano informazioni aggiuntive con i risultati.
Che tu stia creando un modulo personalizzato nella console Google Cloud o scrivendo la definizione del modulo personalizzato in un file YAML, le espressioni CEL che definisci sono le stesse.
Espressioni CEL per la logica di rilevamento
Puoi codificare 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 risolversi in un valore booleano true
per attivare un risultato.
Se stai creando un modulo personalizzato nella console Google Cloud, puoi scrivere le espressioni nell'Editor espressioni nella pagina Configura modulo.
Se stai codificando un modulo personalizzato in un file YAML, aggiungi queste espressioni
nella proprietà predicate
.
Indipendentemente dall'utilizzo della console Google Cloud o di un file YAML, le espressioni CEL che valutano le proprietà delle risorse devono essere conformi alle seguenti regole:
- Le proprietà specificate in un'espressione CEL devono essere proprietà della risorsa analizzata, come definito nella definizione API del tipo di risorsa.
Se un modulo personalizzato valuta più tipi di risorsa, le proprietà specificate nelle espressioni CEL devono essere comuni a ogni tipo di risorsa valutato dal modulo personalizzato.
Ad esempio, se definisci un modulo personalizzato denominato
invalid_cryptokey
che controlla due tipi di risorse:cloudkms.googleapis.com/CryptoKey
ecloudkms.googleapis.com/CryptoKeyVersion
, potresti scrivere la seguente espressione, perché entrambi i tipi di risorsaCryptoKey
eCryptoKeyVersion
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
erotationPeriod
valutate dall'espressione non sono condivise da 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, quella 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 sulla tecnologia 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 console Google 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 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 Virtual Private Cloud per corrispondere ai 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 il 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 solo l'abilitazione delle API relative 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 di test o sviluppo | 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 possono essere utilizzate per trovare le 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 nel relativo JSON e nella scheda Proprietà sorgente dei dettagli del risultato nella console Google Cloud.
Puoi definire 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à dei risultati personalizzati nella pagina Definisci i dettagli del risultato.
Se stai codificando un modulo personalizzato in un file YAML, le coppie name
-value
vengono elencate come properties
nella proprietà custom_output
.
Indipendentemente dall'utilizzo della console Google Cloud o di un file YAML, si applicano le seguenti regole:
- Specifica
name
come stringa di testo senza virgolette. Specifica
value
come uno dei seguenti:Per restituire il valore di una proprietà, specifica la proprietà nel seguente formato:
RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
Nell'esempio:
RESOURCE_TYPE
può essereresource
opolicy
.PROPERTY
una o più proprietà principali della proprietà che contengono 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 moduli personalizzati, consulta le seguenti pagine:
- Per testare i moduli personalizzati, consulta Testare 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.