Campi ripetuti

Supportato in:

Nel modello 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 sui 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 la negazione della 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

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.

La regola viene applicata alle seguenti copie:

event copy 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 nei campi ripetuti sono compatibili con le espressioni non modificate nei campi ripetuti perché l'elenco degli 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:

event copy 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 considerare 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 nei 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 della corrispondenza, possono verificarsi più corrispondenze.

Esempio: segnaposto del campo ripetuto

L'esempio seguente genera una corrispondenza. Il segnaposto `$ip` è uguale a `192.0.2.1` per `event_copy_1`, il che soddisfa i predicati nella 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 delle corrispondenze. 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
}

L'esecuzione di questa regola prevede quattro fasi. La prima fase è la copia degli eventi:

event copy $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à quindi le righe che non corrispondono ai filtri:

event copy $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 verrà quindi raggruppata in base alle variabili di corrispondenza e la sezione outcome eseguirà l'aggregazione su ogni 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 dell'evento.

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 soddisfano tutte le condizioni nella sezione degli eventi. Tuttavia, tutti gli elementi di e.principal.ip verranno visualizzati nell'esempio di evento perché 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 di numero 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 solo indice 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 nei 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:

event copy 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 di array con espressioni non modificate su campi di 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ò portare a un comportamento imprevisto perché la regola repeated_message_1 non aveva l'indicizzazione dell'array e non ha prodotto corrispondenze, mentre la regola repeated_message_2 utilizzava l'indicizzazione dell'array e ha prodotto una corrispondenza.

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