Campi ripetuti

Supportata in:

In Unified Data Model (UDM), alcuni campi sono etichettati come ripetuti, il che indica che sono elenchi di valori o altri tipi di messaggi. Questo documento fornisce informazioni su come utilizzare espressioni, segnaposto, indicizzazione di array e messaggi ripetuti per i campi UDM ripetuti.

Espressioni booleane e campi ripetuti

Le espressioni booleane modificate e non modificate possono agire su campi ripetuti.

Considera il seguente evento:

event_original {
  principal {
    // ip is a repeated field
    ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]

    hostname: "host"
  }
}

Espressioni modificate

Utilizza i modificatori any e all nelle espressioni nei campi ripetuti.

  • any: se un qualsiasi elemento del campo ripetuto soddisfa la condizione, l'evento nel suo complesso soddisfa la condizione. Ad esempio:

    • event_original soddisfa any $e.principal.ip = "192.0.2.1"
    • event_original non riesce any $e.repeated_field.field_a = "9.9.9.9"
  • all: se tutti gli elementi del campo ripetuto soddisfano la condizione, l'evento nel suo complesso soddisfa la condizione. Ad esempio:

    • event_original soddisfa net.ip_in_range_cidr(all $e.principal.ip, "192.0.2.0/8")
    • event_original non riesce all $e.principal.ip = "192.0.2.2"

Quando scrivi una condizione con any o all, tieni presente che negare la condizione con not potrebbe non avere lo stesso significato dell'utilizzo dell'operatore negato.

Ad esempio:

  • not all $e.principal.ip = "192.168.12.16" controlla se non tutti gli indirizzi IP corrispondono a 192.168.12.16, il che significa che la query verifica se almeno un indirizzo IP non corrisponde a 192.168.12.16
  • all $e.principal.ip != "192.168.12.16" verifica se tutti gli indirizzi IP non corrispondono a 192.168.12.16, il che significa che la query verifica che nessun indirizzo IP corrisponda a 192.168.12.16

Limitazioni:

  • Gli operatori any e all sono compatibili solo con i campi ripetuti (non con i campi scalari).
  • any e all non possono essere utilizzati per unire due campi ripetuti. Ad esempio, any $e1.principal.ip = $e2.principal.ip non è valido.
  • Gli operatori any e all non sono supportati con l'espressione dell'elenco di riferimento.

Espressioni non modificate

Ad esempio, considera un evento in cui il campo security_result è un campo ripetuto:

security_result[0].threat_id = "threat_a"
security_result[1].threat_id = "threat_b"
security_result[1].rule_name = "rule_b"
security_result[2].threat_id = "threat_c"

Una query di ricerca non modificata come $e.security_result.rule_name = "" restituisce questo evento perché il comportamento predefinito del campo ripetuto restituisce true se un elemento soddisfa la condizione. La query corrisponde all'indice 0 e all'indice 2, dove il campo rule_name non è presente (una stringa vuota).

Allo stesso modo, lo stesso evento corrisponde anche alla query $e.security_result.rule_name != "" perché la condizione è soddisfatta nell'indice 1.

Per verificare che il campo rule_name non sia presente in tutti gli elementi security_result, utilizza l'operatore all: all $e.security_result.rule_name = "". Questa query non corrisponde all'evento di esempio.

Con le espressioni non modificate, ogni elemento nel campo ripetuto viene trattato singolarmente. Se il campo ripetuto di un evento contiene n elementi, la query viene applicata a n copie dell'evento, in cui ogni copia ha uno degli elementi del campo ripetuto. Queste copie sono temporanee e non vengono archiviate.

Per il set di dati di esempio event_original precedente, viene applicata una regola alle seguenti copie:

testo dell'evento principal.ip principal.hostname
event_copy_1 "192.0.2.1" "host"
event_copy_2 "192.0.2.2" "host"
event_copy_3 "192.0.2.3" "host"

Se una copia dell'evento soddisfa tutte le condizioni non modificate nel campo ripetuto, l'evento nel suo complesso soddisfa tutte le condizioni. Pertanto, se hai più condizioni in un campo ripetuto, una singola copia dell'evento deve soddisfarle tutte. I seguenti esempi di query utilizzano il set di dati di esempio precedente per dimostrare questo comportamento.

Esempio: espressioni non modificate

La seguente regola restituisce una corrispondenza quando viene eseguita sul set di dati di esempio event_original, perché event_copy_1 soddisfa tutti i predicati degli eventi:

rule repeated_field_1 {
  meta:
  events:
    net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/8") // Checks if IP address matches 192.x.x.x
    $e.principal.ip = "192.0.2.1"
  condition:
    $e
}

La seguente regola non restituisce una corrispondenza quando viene eseguita sul set di dati di esempio event_original, perché non esiste una copia dell'evento in $e.principal.ip che soddisfi _tutti_ i predicati dell'evento.

rule repeated_field_2 {
  meta:
  events:
    $e.principal.ip = "192.0.2.1"
    $e.principal.ip = "192.0.2.2"
  condition:
    $e
}

Le espressioni modificate sui campi ripetuti sono compatibili con le espressioni non modificate sui campi ripetuti perché l'elenco di elementi è lo stesso per ogni copia dell'evento. Considera la seguente regola:

rule repeated_field_3 {
  meta:
  events:
    any $e.principal.ip = "192.0.2.1"
    $e.principal.ip = "192.0.2.3"
  condition:
    $e
}

La regola viene applicata alle seguenti copie:

testo dell'evento principal.ip any $e.principal.ip
event_copy_1 "192.0.2.1" ["192.0.2.1", "192.0.2.2", "192.0.2.3"]
event_copy_2 "192.0.2.2" ["192.0.2.1", "192.0.2.2", "192.0.2.3"]
event_copy_3 "192.0.2.3" ["192.0.2.1", "192.0.2.2", "192.0.2.3"]

In questo caso, tutte le copie soddisfano any $e.principal.ip = "192.0.2.1", ma solo event_copy_3 soddisfa $e.principal.ip = "192.0.2.3". Di conseguenza, l'evento nel suo complesso corrisponderà.

Un altro modo di pensare a questi tipi di espressioni è:

  • Le espressioni sui campi ripetuti che utilizzano any o all operano sull'elenco in event_original.
  • Le espressioni sui campi ripetuti che non utilizzano any o all operano su singoli eventi event_copy_n.

Segnaposto e campi ripetuti

I campi ripetuti funzionano con le assegnazioni dei segnaposto. Analogamente alle espressioni non modificate sui campi ripetuti, viene creata una copia dell'evento per ogni elemento. Utilizzando lo stesso esempio di event_copy, il segnaposto assume il valore del campo ripetuto di event_copy_n per ciascuna delle copie dell'evento, dove n è il numero della copia dell'evento. Se il segnaposto viene utilizzato nella sezione di corrispondenza, possono essere trovate più corrispondenze.

Esempio: segnaposto di un campo ripetuto

L'esempio seguente genera una corrispondenza. Il segnaposto "$ip" è uguale a "192.0.2.1" per "event_copy_1", che soddisfa i predicati della regola. Gli esempi di eventi della corrispondenza contengono un singolo elemento, "event_original".

// Generates 1 match.
rule repeated_field_placeholder1 {
  meta:
  events:
    $ip = $e.principal.ip
    $ip = "192.0.2.1"
    $host = $e.principal.hostname

  match:
    $host over 5m

  condition:
    $e
}

L'esempio seguente genera tre corrispondenze. Il segnaposto $ip è uguale a valori diversi per ciascuna delle diverse copie di event_copy_n. Il raggruppamento viene eseguito su $ip perché si trova nella sezione di corrispondenza. Pertanto, ottieni tre corrispondenze, ognuna con un valore diverso per la variabile di corrispondenza $ip. Ogni corrispondenza ha lo stesso esempio di evento: un singolo elemento, event_original.

// Generates 3 matches.
rule repeated_field_placeholder2 {
  meta:
  events:
    $ip = $e.principal.ip
    net.ip_in_range_cidr($ip, "192.0.2.0/8") // Checks if IP matches 192.x.x.x

  match:
    $ip over 5m

  condition:
    $e
}

Risultati dell'utilizzo di segnaposto assegnati a campi ripetuti

I segnaposto vengono assegnati a ogni elemento di ogni campo ripetuto, non all'intero elenco. Quando vengono utilizzati nella sezione outcome, il risultato viene calcolato utilizzando solo gli elementi che hanno soddisfatto le sezioni precedenti.

Considera la seguente regola:

rule outcome_repeated_field_placeholder {
  meta:
  events:
    $ip = $e.principal.ip
    $ip = "192.0.2.1" or $ip = "192.0.2.2"
    $host = $e.principal.hostname

  match:
    $host over 5m

  outcome:
    $o = array_distinct($ip)

  condition:
    $e
}

Esistono quattro fasi di esecuzione per questa regola. La prima fase è la copia degli eventi:

testo dell'evento $ip $host $e
event_copy_1 "192.0.2.1" "host" event_id
event_copy_2 "192.0.2.2" "host" event_id
event_copy_3 "192.0.2.3" "host" event_id

La sezione degli eventi filtrerà le righe che non corrispondono ai filtri:

testo dell'evento $ip $host $e
event_copy_1 "192.0.2.1" "host" event_id
event_copy_2 "192.0.2.2" "host" event_id

event_copy_3 viene filtrato perché "192.0.2.3" non soddisfa $ip = "192.0.2.1" or $ip = "192.0.2.2".

La sezione match raggrupperà quindi in base alle variabili di corrispondenza e la sezione outcome eseguirà l'aggregazione su ciascun gruppo:

$host $o $e
"host" ["192.0.2.1", "192.0.2.2"] event_id

$o = array_distinct($ip) viene calcolato utilizzando $ip della fase precedente e non della fase di copia degli eventi.

Infine, la sezione condition filtrerà ogni gruppo. Poiché questa regola controlla solo l'esistenza di $e, la riga precedente produrrà un singolo rilevamento.

$o non contiene tutti gli elementi di $e.principal.ip perché non tutti gli elementi soddisfacevano tutte le condizioni nella sezione degli eventi. Tuttavia, tutti gli elementi di e.principal.ip verranno visualizzati nell'esempio di evento perché quest'ultimo utilizza event_original.

Indicizzazione degli array

Puoi eseguire l'indicizzazione degli array sui campi ripetuti. Per accedere all'ennesimo elemento del campo ripetuto, utilizza la sintassi standard dell'elenco (gli elementi sono indicizzati a partire da 0). Un elemento fuori dai limiti restituisce il valore predefinito.

  • $e.principal.ip[0] = "192.168.12.16"
  • $e.principal.ip[999] = "" Se sono presenti meno di 1000 elementi, il risultato è true.

Limitazioni:

  • Un indice deve essere un valore letterale intero non negativo. Ad esempio, $e.principal.ip[-1] non è valido.
  • I valori con un tipo int (ad esempio, un segnaposto impostato su int) non vengono conteggiati.
  • L'indicizzazione degli array non può essere combinata con any o all. Ad esempio, any $e.intermediary.ip[0] non è valido.
  • L'indicizzazione degli array non può essere combinata con la sintassi della mappa. Ad esempio, $e.additional.fields[0]["key"] non è valido.
  • Se il percorso del campo contiene più campi ripetuti, tutti i campi ripetuti devono utilizzare l'indicizzazione degli array. Ad esempio, $e.intermediary.ip[0] non è valido perché intermediary e ip sono entrambi campi ripetuti, ma esiste un indice solo per ip.

Messaggi ripetuti

Quando un campo message viene ripetuto, un effetto indesiderato è la riduzione della probabilità di una corrispondenza. Questo è illustrato negli esempi seguenti.

Considera il seguente evento:

event_repeated_message {
  // about is a repeated message field.
  about {
    // ip is a repeated string field.
    ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]

    hostname: "alice"
  }
  about {
    hostname: "bob"
  }
}

Come indicato per le espressioni non modificate sui campi ripetuti, viene creata una copia temporanea dell'evento per ogni elemento del campo ripetuto. Considera la seguente regola:

rule repeated_message_1 {
  meta:
  events:
    $e.about.ip = "192.0.2.1"
    $e.about.hostname = "bob"
  condition:
    $e
}

La regola viene applicata alle seguenti copie:

testo dell'evento about.ip about.hostname
event_copy_1 "192.0.2.1" "alice"
event_copy_2 "192.0.2.2" "alice"
event_copy_3 "192.0.2.3" "alice"
event_copy_4 "" "bob"

L'evento non corrisponde alla regola perché non esiste una copia dell'evento che soddisfi tutte le espressioni.

Messaggi ripetuti e indicizzazione degli array

Un altro comportamento imprevisto può verificarsi quando si utilizza l'indicizzazione degli array con espressioni non modificate nei campi dei messaggi ripetuti. Considera la seguente regola di esempio che utilizza l'indicizzazione degli array:

rule repeated_message_2 {
  meta:
  events:
    $e.about.ip = "192.0.2.1"
    $e.about[1].hostname = "bob"
  condition:
    $e
}

La regola viene applicata alle seguenti copie:

testo dell'evento about.ip about[1].hostname
event_copy_1 "192.0.2.1" "bob"
event_copy_2 "192.0.2.2" "bob"
event_copy_3 "192.0.2.3" "bob"
event_copy_4 "" "bob"

Poiché event_copy_1 soddisfa tutte le espressioni in repeated_message_2, l'evento corrisponde alla regola.

Ciò può causare un comportamento imprevisto perché la regola repeated_message_1 non aveva l'indicizzazione degli array e non ha prodotto corrispondenze, mentre la regola repeated_message_2 ha utilizzato l'indicizzazione degli array e ha prodotto una corrispondenza.

Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.