Sintassi del linguaggio YARA-L 2.0

Questa sezione descrive gli elementi principali della sintassi YARA-L. Vedi anche Panoramica della lingua YARA-L 2.0.

Struttura delle regole

Per YARA-L 2.0, è necessario specificare le dichiarazioni, le definizioni e gli utilizzi delle variabili nel seguente ordine:

1. meta
2. eventi
3. corrispondenza (facoltativo)
4. risultato (facoltativo)
5. condizione
6. opzioni (facoltativo)

Nota: se ometti la sezione match facoltativa, la regola può corrispondere a un singolo evento.

Di seguito viene illustrata la struttura generica di una regola:

rule <rule Name>
{
    meta:
    // Stores arbitrary key-value pairs of rule details, such as who wrote
    // it, what it detects on, version control, etc.

  events:
    // Conditions to filter events and the relationship between events.

  match:
    // Values to return when matches are found.

  outcome:
    // Additional information extracted from each detection.

  condition:
    // Condition to check events and the variables used to find matches.

  options:
    // Options to turn on or off while executing this rule.
}

Sintassi della meta-sezione

La sezione meta è composta da più righe, dove ogni riga definisce una coppia chiave-valore. Una parte della chiave deve essere una stringa senza virgolette, mentre una parte del valore deve essere una stringa tra virgolette:

<key> = "<value>"

Di seguito è riportato un esempio di riga di sezione meta valida:

meta:
    author = "Google"
    severity = "HIGH"

Sintassi della sezione Eventi

Nella sezione events, elenca i predicati per specificare quanto segue:

• Dichiarazioni di variabili
• Filtri variabili evento
• Partecipazioni variabili evento

Dichiarazioni di variabili

Per le dichiarazioni di variabili, utilizza la seguente sintassi:

• <EVENT_FIELD> = <VAR>
• <VAR> = <EVENT_FIELD>

Entrambe sono equivalenti, come mostrato nei seguenti esempi:

• $e.source.hostname = $hostname
• $userid = $e.principal.user.userid

Questa dichiarazione indica che questa variabile rappresenta il campo specificato per la variabile evento. Quando il campo dell'evento è un campo ripetuto, la variabile di corrispondenza può rappresentare qualsiasi valore nell'array. È anche possibile assegnare più campi evento a una singola variabile di corrispondenza o segnaposto. Questa è una condizione di join transitiva.

Ad esempio:

• $e1.source.ip = $ip
• $e2.target.ip = $ip

Equivale a:

• $e1.source.ip = $ip
• $e1.source.ip = $e2.target.ip

Quando viene utilizzata una variabile, questa deve essere dichiarata tramite la sua dichiarazione. L'utilizzo di una variabile senza alcuna dichiarazione viene considerato un errore di compilazione.

Filtri variabili evento

Un'espressione booleana che agisce su una singola variabile evento è considerata un filtro.

Partecipazioni variabili evento

Tutte le variabili evento utilizzate nella regola devono essere unite a ogni altra variabile evento in uno dei seguenti modi:

• Direttamente tramite un confronto di uguaglianza tra i campi evento delle due variabili evento unite, ad esempio: $e1.field = $e2.field. L'espressione non deve includere elementi aritmetici.

• Indirettamente tramite un join transitivo che coinvolge solo un campo event (consulta la dichiarazione di variabile per la definizione di "transitive join"). L'espressione non deve includere elementi aritmetici.

Ad esempio, supponendo che nella regola vengano utilizzati $e1, $e2 e $e3, sono valide le seguenti sezioni di events.

events:
  $e1.principal.hostname = $e2.src.hostname // $e1 joins with $e2
  $e2.principal.ip = $e3.src.ip // $e2 joins with $e3

events:
  // $e1 joins with $e2 via function to event comparison
  re.capture($e1.src.hostname, ".*") = $e2.target.hostname

events:
  // $e1 joins with $e2 via an `or` expression
  $e1.principal.hostname = $e2.src.hostname
  or $e1.principal.hostname = $e2.target.hostname
  or $e1.principal.hostname = $e2.principal.hostname

events:
  // all of $e1, $e2 and $e3 are transitively joined via the placeholder variable $ip
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = $ip

events:
  // $e1 and $e2 are transitively joined via function to event comparison
  re.capture($e2.principal.application, ".*") = $app
  $e1.principal.hostname = $app

Nota: se l'unica condizione di join è una catena or, una funzione per il confronto degli eventi o una combinazione di entrambe, la regola potrebbe avere un rendimento scarso.

Tuttavia, ecco alcuni esempi di sezioni events non valide.

events:
  // Event to arithmetic comparison is an invalid join condition for $e1 and $e2.
  $e1.principal.port = $e2.src.port + 1

events:
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = "192.1.2.0" //$e3 is not joined with $e1 or $e2.

events:
  $e1.src.port = $port

  // Arithmetic to placeholder comparison is an invalid transitive join condition.
  $e2.principal.port + 800 = $port

Sintassi della sezione delle corrispondenze

Nella sezione match, elenca le variabili di corrispondenza per gli eventi di gruppo prima di verificare le condizioni di corrispondenza. Questi campi vengono restituiti a ogni corrispondenza.

• Specifica cosa rappresenta ciascuna variabile di corrispondenza nella sezione events.
• Specifica la durata da utilizzare per correlare gli eventi dopo la parola chiave over. Gli eventi al di fuori della durata temporale vengono ignorati.

• Utilizza la seguente sintassi per specificare la durata: <number><m/h/d>

  dove m/h/d indica rispettivamente minuti, ore e giorni.

• Il tempo minimo che puoi specificare è 1 minuto.

• Puoi specificare un tempo massimo di 48 ore.

Di seguito è riportato un esempio di match valido:

$var1, $var2 over 5m

Questa istruzione restituisce $var1 e $var2 (definiti nella sezione events) quando la regola trova una corrispondenza. Il tempo specificato è 5 minuti. Gli eventi che si trovano a più di 5 minuti di distanza non sono correlati e pertanto vengono ignorati dalla regola.

Ecco un altro esempio di sezione match valida:

$user over 1h

Questa istruzione restituisce $user quando la regola trova una corrispondenza. L'intervallo di tempo specificato è di 1 ora. Gli eventi a distanza di più di un'ora non sono correlati. La regola non li considera un rilevamento.

Ecco un altro esempio di sezione match valida:

$source_ip, $target_ip, $hostname over 2m

Questa istruzione restituisce $source_ip, $target_ip e $hostname quando la regola trova una corrispondenza. La finestra di tempo specificata è di 2 minuti. Gli eventi a distanza di più di 2 minuti non sono correlati. La regola non li considera un rilevamento.

I seguenti esempi illustrano sezioni match non valide:

• var1, var2 over 5m // invalid variable name
• $user 1h // missing keyword

Gestione di valori zero nella sezione delle corrispondenze

Il Motore regole filtra implicitamente i valori zero per tutti i segnaposto utilizzati nella sezione delle corrispondenze ("" per stringa, 0 per i numeri, false per i valori booleani, il valore in posizione 0 per i tipi enumerati). L'esempio seguente illustra le regole che filtrano i valori zero.

rule ZeroValuePlaceholderExample {
  meta:
  events:
    // Because $host is used in the match section, the rule behaves
    // as if the following predicate was added to the events section:
    // $host != ""
    $host = $e.principal.hostname

    // Because $otherPlaceholder was not used in the match section,
    // there is no implicit filtering of zero values for $otherPlaceholder.
    $otherPlaceholder = $e.principal.ip

  match:
    $host over 5m

  condition:
    $e
}

Tuttavia, se un segnaposto viene assegnato a una funzione, le regole non filtrano implicitamente i valori zero dei segnaposto utilizzati nella sezione delle corrispondenze. L'esempio seguente illustra le regole che filtrano i valori zero:

rule ZeroValueFunctionPlaceholder {
  meta:
  events:
    // Even though $ph is used in the match section, there is no
    // implicit filtering of zero values for $ph, because $ph is assigned to a function.
    $ph = re.capture($e.principal.hostname, "some-regex")

  match:
    $ph over 5m

  condition:
    $e
}

Per disattivare il filtro implicito dei valori zero, puoi utilizzare l'opzione allow_zero_values nella sezione Opzioni.

Finestra di salto

Per impostazione predefinita, le regole YARA-L 2.0 con una sezione di corrispondenza vengono valutate utilizzando finestre hop. L'intervallo di tempo dell'esecuzione della regola è suddiviso in un insieme di finestre di hop sovrapposte, ognuna con la durata specificata nella sezione match. Gli eventi vengono quindi correlati all'interno di ogni finestra hop.

Ad esempio, per una regola eseguita nell'intervallo di tempo [1:00, 2:00], con una sezione match su 30m, un possibile insieme di finestre di hop sovrapposte che potrebbe essere generato è [1:00, 1:30], [1:03, 1:33] e [1:06, 1:36]. Queste finestre vengono utilizzate per correlare più eventi.

Finestra scorrevole

L'utilizzo delle finestre di hop non è un modo efficace per cercare eventi che si verificano in un ordine specifico (ad esempio, e1 si verifica fino a 2 minuti dopo il giorno e2). Un'occorrenza dell'evento e1 e un'occorrenza dell'evento e2 sono correlate solo se rientrano nella stessa finestra di hop generata.

Un modo più efficace per cercare tali sequenze di eventi è utilizzare finestre scorrevoli. Le finestre scorrevoli con la durata specificata nella sezione match vengono generate quando iniziano o terminano con una variabile evento pivot specificata. Gli eventi sono quindi correlati all'interno di ogni finestra scorrevole. In questo modo è possibile cercare gli eventi che si verificano in un ordine specifico (ad esempio, e1 si verifica entro 2 minuti da e2). Un'occorrenza dell'evento e1 e un'occorrenza dell'evento e2 sono correlate se l'evento e1 si verifica nella durata della finestra scorrevole dopo l'evento e2.

Specifica le finestre scorrevoli nella sezione match di una regola come segue:

<match-var-1>, <match-var-2>, ... over <duration> before|after <pivot-event-var>

La variabile evento pivot è la variabile evento su cui si basano le finestre scorrevoli. Se utilizzi la parola chiave before, vengono generate finestre scorrevoli che terminano con ogni occorrenza dell'evento pivot. Se viene utilizzata la parola chiave after, vengono generate finestre scorrevoli a partire da ogni occorrenza dell'evento pivot.

Di seguito sono riportati alcuni esempi di utilizzi validi di finestre scorrevoli:

• $var1, $var2 over 5m after $e1
• $user over 1h before $e2

Vedi un esempio di regola per finestre scorrevoli.

Nota: è noto che l'utilizzo di finestre scorrevoli al posto delle finestre hop rallenta le prestazioni. Google consiglia di utilizzare le finestre scorrevoli solo in casi specifici, ad esempio quando l'ordine degli eventi è assolutamente necessario o quando si cerca la mancata esistenza di eventi.

Google consiglia di non utilizzare finestre scorrevoli per le regole relative a eventi singoli, poiché le finestre scorrevoli sono progettate per rilevare eventi multipli. Se una delle tue regole rientra in questa categoria, Google consiglia una delle seguenti soluzioni alternative:

• Converti la regola per utilizzare più variabili evento e aggiorna la sezione della condizione se la regola richiede più di un'occorrenza dell'evento.
  • Facoltativamente, valuta la possibilità di aggiungere filtri per i timestamp invece di utilizzare una finestra scorrevole. Ad esempio, $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
• Rimuovi la finestra scorrevole.

Sintassi della sezione dei risultati

Nella sezione outcome, puoi definire fino a 20 variabili di risultato, con nomi arbitrari. Questi risultati verranno archiviati nei rilevamenti generati dalla regola. Ogni rilevamento può avere valori diversi per i risultati.

Il nome del risultato, $risk_score, è speciale. Facoltativamente, puoi definire un risultato con questo nome e, in caso affermativo, deve essere un tipo intero o in virgola mobile. Se compilato, risk_score verrà mostrato nella vista Enterprise Insights per gli avvisi provenienti dai rilevamenti delle regole.

Se non includi una variabile $risk_score nella sezione dei risultati di una regola, viene impostato uno dei seguenti valori predefiniti:

• Se la regola è configurata per generare un avviso, il valore di $risk_score è 40.
• Se la regola non è configurata per generare un avviso, il valore di $risk_score è 15.

Il valore di $risk_score viene memorizzato nel campo UDM security_result.risk_score.

Tipi di dati delle variabili dei risultati

Ogni variabile di risultato può avere un tipo di dati diverso, determinato dall'espressione utilizzata per calcolarla. Supportiamo i seguenti tipi di dati dei risultati:

• integer
• galleggianti
• string
• elenchi di numeri interi
• elenchi di numeri in virgola mobile
• elenchi di stringhe

Logica condizionale

Puoi utilizzare la logica condizionale per calcolare il valore di un risultato. I condizionali vengono specificati utilizzando il seguente pattern di sintassi:

if(BOOL_CLAUSE, THEN_CLAUSE)
if(BOOL_CLAUSE, THEN_CLAUSE, ELSE_CLAUSE)

Puoi leggere un'espressione condizionale come "se BOOL_CLAUSE è true, restituisce THEN_CLAUSE, altrimenti restituisce ELSE_CLAUSE".

BOOL_CLAUSE deve restituire un valore booleano. Un'espressione BOOL_CLAUSE assume una forma simile a quella delle espressioni nella sezione events. Ad esempio, può contenere:

• Nomi dei campi UDM con operatore di confronto, ad esempio:

  if($context.graph.entity.user.title = "Vendor", 100, 0)

• variabile segnaposto definita nella sezione events, ad esempio:

  if($severity = "HIGH", 100, 0)

• un'altra variabile di risultato definita nella sezione outcome, ad esempio:

  if($risk_score > 20, "HIGH", "LOW")

• che restituiscono un valore booleano, ad esempio:

  if(re.regex($e.network.email.from, `.*altostrat.com`), 100, 0)

• cercalo in un elenco di riferimento, ad esempio:

  if($u.principal.hostname in %my_reference_list_name, 100, 0)

• e un confronto per l'aggregazione, ad esempio:

  if(count($login.metadata.event_timestamp.seconds) > 5, 100, 0)

THEN_CLAUSE ed ELSE_CLAUSE devono essere dello stesso tipo di dati. Sono supportati numeri interi, numeri in virgola mobile e stringhe.

Puoi omettere ELSE_CLAUSE se il tipo di dati è intero o numero in virgola mobile. Se omesso, ELSE_CLAUSE restituisce 0. Ad esempio:

`if($e.field = "a", 5)` is equivalent to `if($e.field = "a", 5, 0)`

Devi fornire ELSE_CLAUSE se il tipo di dati è di tipo stringa o se THEN_CLAUSE è una variabile segnaposto o una variabile di risultato.

Operazioni matematiche

Puoi utilizzare operazioni matematiche per calcolare il tipo di dati interi o in virgola mobile nelle sezioni outcome e events di una regola. Google Security Operations supporta addizioni, sottrazioni, moltiplicazioni, divisioni e moduli come operatori di primo livello in un calcolo.

Lo snippet seguente è un calcolo di esempio nella sezione outcome:

outcome:
  $risk_score = max(100 + if($severity = "HIGH", 10, 5) - if($severity = "LOW", 20, 0))

Le operazioni matematiche sono consentite sui seguenti tipi di operandi, a condizione che ogni operando e l'intera espressione aritmetica siano aggregati correttamente (vedi Aggregazioni):

• Campi dell'evento numerico
• Variabili segnaposto numeriche definite nella sezione events
• Variabili di risultato numeriche definite nella sezione outcome
• Funzioni che restituiscono int o numeri in virgola mobile
• Aggregazioni che restituiscono int o numeri in virgola mobile

Il modulo non è consentito sui valori mobili.

Variabili segnaposto nei risultati

Durante il calcolo delle variabili di risultato, puoi utilizzare le variabili segnaposto definite nella sezione Eventi della regola. In questo esempio, supponiamo che $email_sent_bytes sia stato definito nella sezione degli eventi della regola:

Esempio di evento singolo:

// No match section, so this is a single-event rule.

outcome:
  // Use placeholder directly as an outcome value.
  $my_outcome = $email_sent_bytes

  // Use placeholder in a conditional.
  $other_outcome = if($file_size > 1024, "SEVERE", "MODERATE")

condition:
  $e

Esempio di più eventi:

match:
  // This is a multi event rule with a match section.
  $hostname over 5m

outcome:
  // Use placeholder directly in an aggregation function.
  $max_email_size = max($email_sent_bytes)

  // Use placeholder in a mathematical computation.
  $total_bytes_exfiltrated = sum(
    1024
    + $email_sent_bytes
    + $file_event.principal.file.size
  )

condition:
  $email_event and $file_event

Variabili di risultato nelle espressioni di assegnazione dei risultati

Le variabili di risultato possono essere utilizzate per ricavare altre variabili di risultato, simili alle variabili segnaposto definite nella sezione events. Puoi fare riferimento a una variabile di risultato nell'assegnazione di un'altra variabile di risultato con un token $ seguito dal nome della variabile. Le variabili di risultato devono essere definite prima di potervi fare riferimento nel testo della regola. Se utilizzate in un'espressione di assegnazione, le variabili di risultato non devono essere aggregate (vedi Aggregazioni).

Nell'esempio seguente, la variabile di risultato $risk_score deriva il suo valore dalla variabile di risultato $event_count:

Esempio di più eventi:

match:
  // This is a multi event rule with a match section.
  $hostname over 5m

outcome:
  // Aggregates all timestamp on login events in the 5 minute match window.
  $event_count = count($login.metadata.event_timestamp.seconds)
  
  // $event_count cannot be aggregated again.
  $risk_score = if($event_count > 5, "SEVERE", "MODERATE")

  // This is the equivalent of the 2 outcomes above combined.
  $risk_score2 = if(count($login.metadata.event_timestamp.seconds) > 5, "SEVERE", "MODERATE")

condition:
  $e

Le variabili di risultato possono essere utilizzate in qualsiasi tipo di espressione sul lato destro di un'assegnazione dei risultati, tranne nelle seguenti espressioni:

• Aggregazioni
• Chiamate di funzione Arrays.length()
• Con modificatori any o all

Aggregazioni

I campi evento ripetuto sono valori non scalabili. In altre parole, una singola variabile punta a più valori. Ad esempio, la variabile del campo evento $e.target.ip è un campo ripetuto e può avere zero, uno o più valori IP. si tratta di un valore non scalabile. La variabile del campo evento $e.principal.hostname non è un campo ripetuto e ha solo 1 valore (ovvero un valore scalare).

Allo stesso modo, sia i campi evento non ripetuto sia i campi evento ripetuti utilizzati nella sezione dei risultati di una regola con una finestra di corrispondenza sono valori non scalabili. Ad esempio, la seguente regola raggruppa gli eventi utilizzando una sezione di corrispondenza e fa riferimento a un campo evento non ripetuto nella sezione dei risultati:

rule OutcomeAndMatchWindow{
  ...
  match:
    $userid over 5m
  outcome:
    $hostnames = array($e.principal.hostname)
  ...
}

Qualsiasi finestra di 5 minuti in cui viene eseguita la regola può contenere zero, uno o più eventi. La sezione dei risultati opera su tutti gli eventi in una finestra della corrispondenza. Qualsiasi variabile di campo evento a cui viene fatto riferimento nella sezione dei risultati può puntare a zero, uno o più valori del campo per ciascun evento nella finestra delle corrispondenze. Nella regola precedente, se una finestra di 5 minuti contiene 5 eventi $e, $e.principal.hostname nella sezione dei risultati punta a 5 diversi nomi host. La variabile del campo evento $e.principal.hostname è quindi un valore non scalabile nella sezione dei risultati di questa regola.

Poiché le variabili di risultato devono sempre produrre un singolo valore scalare, qualsiasi valore non scalabile da cui dipende un'assegnazione dei risultati deve essere aggregato per ottenere un singolo valore scalare. In una sezione dei risultati, i seguenti sono valori non scalabili e devono essere aggregati:

• Campi evento (ripetuto o non ripetuto) quando la regola utilizza una sezione di corrispondenza
• Segnaposto di eventi (ripetuti o non ripetuti) quando la regola utilizza una sezione di corrispondenza
• Campi evento ripetuti quando la regola non utilizza una sezione di corrispondenza
• Segnaposto di eventi ripetuti quando la regola non utilizza una sezione di corrispondenze

I campi evento scalari, i segnaposto di eventi scalari e le costanti possono essere aggregati in un'aggregazione in una regola che non utilizza una sezione di corrispondenza. Tuttavia, la maggior parte delle aggregazioni restituirà il valore aggregato e non è quindi necessario. L'eccezione è l'aggregazione array(), che può essere utilizzata per convertire un valore scalare in un array.

Le variabili dei risultati vengono trattate come aggregazioni: non devono essere riaggregate quando fanno riferimento a un'altra assegnazione dei risultati.

Puoi utilizzare le seguenti funzioni di aggregazione:

• max(): restituisce il numero massimo di valori rispetto a tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.
• min(): restituisce il numero minimo di valori rispetto a tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.
• sum(): restituisce la somma di tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.
• count_distinct(): raccoglie tutti i valori possibili, poi restituisce il conteggio distinto dei valori possibili.
• count(): si comporta come count_distinct(), ma restituisce un conteggio non distinto di valori possibili.
• array_distinct(): raccoglie tutti i possibili valori distinti e restituisce un elenco di questi valori. L'elenco dei valori distinti verrà troncato a 25 elementi casuali. Viene applicata prima la deduplicazione per ottenere un elenco distinto e poi il troncamento.
• array(): si comporta come array_distinct(), ma restituisce un elenco non distinto di valori. Inoltre, tronca l'elenco dei valori a 25 elementi casuali.

La funzione aggregata è importante quando una regola include una sezione condition che specifica che devono esistere più eventi, perché la funzione aggregata opera su tutti gli eventi che hanno generato il rilevamento.

Ad esempio, se le sezioni outcome e condition contengono:

outcome:
  $asset_id_count = count($event.principal.asset_id)
  $asset_id_distinct_count = count_distinct($event.principal.asset_id)

  $asset_id_list = array($event.principal.asset_id)
  $asset_id_distinct_list = array_distinct($event.principal.asset_id)

condition:
  #event > 1

Poiché la sezione delle condizioni richiede la presenza di più di un event per ogni rilevamento, le funzioni aggregate operano su più eventi. Supponiamo che i seguenti eventi abbiano generato un rilevamento:

event:
  // UDM event 1
  asset_id="asset-a"

event:
  // UDM event 2
  asset_id="asset-b"

event:
  // UDM event 3
  asset_id="asset-b"

I valori dei risultati saranno:

• $asset_id_count = 3
• $asset_id_distinct_count = 2
• $asset_id_list = ["asset-a", "asset-b", "asset-b"]
• $asset_id_distinct_list = ["asset-a", "asset-b"]

Aspetti da considerare quando si utilizza la sezione dei risultati:

Altre note e limitazioni:

• La sezione outcome non può fare riferimento a una nuova variabile segnaposto non ancora definita nella sezione events o nella sezione outcome.
• La sezione outcome non può utilizzare variabili evento che non sono state definite nella sezione events.
• La sezione outcome può usare un campo evento che non era utilizzato nella sezione events, dato che la variabile evento a cui appartiene il campo evento era già definita nella sezione events.
• La sezione outcome può correlare solo le variabili evento che sono già state correlate nella sezione events. Le correlazioni si verificano quando due campi evento di variabili evento diverse vengono equiparati.

Puoi trovare un esempio utilizzando la sezione dei risultati in Panoramica dello YARA-L 2.0. Consulta Creare analisi sensibili al contesto per i dettagli sulla deduplicazione del rilevamento con la sezione dei risultati.

Sintassi della sezione delle condizioni

• specificare una condizione di corrispondenza per eventi e segnaposto definiti nella sezione events. Per maggiori dettagli, consulta la sezione Condizionali di evento e segnaposto riportata di seguito.
• (Facoltativo) Usa la parola chiave and per specificare una condizione di corrispondenza utilizzando le variabili di risultato definite nella sezione outcome. Per ulteriori dettagli, consulta la sezione Condizionali dei risultati riportata di seguito.

Conteggio caratteri

Il carattere # è un carattere speciale nella sezione condition. Se viene utilizzato prima del nome di qualsiasi evento o variabile segnaposto, rappresenta il numero di eventi o valori distinti che soddisfano tutte le condizioni della sezione events.

Ad esempio, #c > 1 significa che la variabile c deve verificarsi più di 1 volta.

Carattere valore

Il carattere $ è un carattere speciale nella sezione condition. Se viene utilizzato prima del nome di qualsiasi variabile di risultato, rappresenta il valore di quel risultato.

Se viene utilizzata prima del nome di qualsiasi evento o variabile segnaposto (ad esempio, $event), rappresenta #event > 0.

Condizionali di evento e segnaposto

Qui sono elencati i predicati delle condizioni per eventi e variabili segnaposto, uniti alla parola chiave and o or. La parola chiave and può essere utilizzata in qualsiasi condizione, mentre la parola chiave or può essere utilizzata solo quando la regola ha una singola variabile evento.

Un esempio valido di utilizzo di or tra due segnaposto per lo stesso evento:

rule ValidConditionOr {
  meta:
  events:
      $e.metadata.event_type = "NETWORK_CONNECTION"

      // Note that all placeholders use the same event variable.
      $ph = $e.principal.user.userid  // Define a placeholder variable to put in match section.
      $ph2 = $e.principal.ip  // Define a second placeholder variable to put in condition section.
      $ph3 = $e.principal.hostname  // Define a third placeholder variable to put in condition section.

  match:
    $ph over 5m

  condition:
    $ph2 or $ph3
}

Esempio non valido di utilizzo di or tra due condizioni in eventi diversi:

rule InvalidConditionOr {
  meta:
  events:
      $e.metadata.event_type = "NETWORK_CONNECTION"
      $e2.graph.metadata.entity_type = "FILE"
      $e2.graph.entity.hostname  = $e.principal.hostname

      $ph = $e.principal.user.userid  // Define a placeholder variable to put in match section.

  match:
    $ph over 5m

  condition:
    $e or $e2 // This line will cause an error because there is an or between events.
}

Nota: non utilizzare la parola chiave not nelle condizionali dell'evento e dei segnaposto.

Condizioni limitate e illimitate

Le seguenti condizioni sono condizioni limitate. Forzano l'esistenza della variabile evento associata, il che significa che almeno un'occorrenza dell'evento deve apparire in qualsiasi rilevamento.

• $var // equivalent to #var > 0
• #var > n // where n >= 0
• #var >= m // where m > 0

Le seguenti condizioni sono condizioni illimitate. Permettono che la variabile evento associata non esista, il che significa che è possibile che nessuna occorrenza dell'evento compaia in un rilevamento e qualsiasi riferimento ai campi nella variabile evento produrrà un valore zero. Condizioni illimitate possono essere usate per rilevare l'assenza di un evento in un determinato periodo di tempo. ad esempio un evento di minaccia senza evento di mitigazione in una finestra di 10 minuti. Le regole che usano condizioni illimitate sono chiamate regole di non esistenza.

• !$var // equivalent to #var = 0
• #var >= 0
• #var < n // where n > 0
• #var <= m // where m >= 0

Nota: per le regole che non esistono, il motore di rilevamento aggiunge un ritardo di 1 ora alla latenza prevista (in base alla frequenza di esecuzione della regola) per consentire i dati che arrivano in ritardo.

Requisiti di inesistenza

Affinché una regola non in esistenza venga compilata, deve soddisfare i seguenti requisiti:

1. Almeno un evento UDM deve avere una condizione limitata (ossia, deve esistere almeno un evento UDM).
2. Se un segnaposto ha una condizione illimitata, deve essere associato ad almeno un evento UDM limitato.
3. Se un'entità ha una condizione illimitata, deve essere associata ad almeno un evento UDM limitato.

Considera la seguente regola con la sezione delle condizioni omessa:

rule NonexistenceExample {
  meta:
  events:
      $u1.metadata.event_type = "NETWORK_CONNECTION" // $u1 is a UDM event.
      $u2.metadata.event_type = "NETWORK_CONNECTION" // $u2 is a UDM event.
      $e1.graph.metadata.entity_type = "FILE"        // $e1 is an Entity.
      $e2.graph.metadata.entity_type = "FILE"        // $e2 is an Entity.

      $user = $u1.principal.user.userid // Match variable is required for Multi-Event Rule.

      // Placeholder Associations:
      //   u1        u2 
      //   |  \    /
      // port   ip
      //   |       \
      //   e1        e2
      $u1.target.port = $port
      $e1.graph.entity.port = $port
      $u1.principal.ip = $ip
      $u2.target.ip = $ip
      $e2.graph.entity.ip = $ip

      // UDM-Entity Associations:
      // u1 - u2
      // |  \  |
      // e1   e2
      $u1.metadata.event_type = $u2.metadata.event_type
      $e1.graph.entity.hostname = $u1.principal.hostname
      $e2.graph.entity.hostname = $u1.target.hostname
      $e2.graph.entity.hostname = $u2.principal.hostname

  match:
    $user over 5m

  condition:
      <condition_section>
}

Di seguito sono riportati esempi validi per il <condition_section>:

• $u1 and !$u2 and $e1 and $e2
  • Tutti gli eventi e le entità UDM sono presenti nella sezione della condizione.
  • Almeno un evento UDM è limitato.
• $u1 and !$u2 and $e1 and !$e2
  • $e2 è illimitato, che è consentito perché è associato all'elemento $u1, che è limitato. Se $e2 non fosse associato a $u1, non sarebbe valido.
• #port > 50 and #ip = 0
  • Non sono presenti eventi ed entità UDM nella sezione della condizione; tuttavia, i segnaposto presenti coprono tutti gli eventi e le entità UDM.
  • $ip è assegnato sia a $u1 che a $u2 e #ip = 0 è una condizione illimitata. Tuttavia, le condizioni limitate sono più forti di quelle illimitate. Poiché $port è assegnato a $u1 e #port > 50 è una condizione limitata, $u1 è ancora limitato.

Di seguito sono riportati esempi non validi per <condition_section>:

• $u1 and $e1
  • Ogni evento e entità UDM che compare nella sezione Eventi deve apparire nella sezione Condizioni (o avere un segnaposto assegnato che appare nella sezione Condizioni).
• $u1, $u2, $e1, $u2, #port > 50
  • Le virgole non sono consentite come separatori di condizioni.
• !$u1 and !$u2 and $e1 and $e2
  • Viola il primo requisito secondo cui è limitato almeno un evento UDM.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • or parola chiave non è supportata con condizioni illimitate.
• ($u1 or $u2) and $e1 and $e2
  • La parola chiave or non è supportata tra variabili evento diverse.
• not $u1 and $u2 and $e1 and $e2
  • La parola chiave not non è consentita per le condizioni evento e segnaposto.
• #port < 50 and #ip = 0
  • I segnaposto presenti coprono tutti gli eventi e le entità UDM; tuttavia, tutte le condizioni sono illimitate. Ciò significa che nessuno degli eventi UDM è limitato, con la conseguente mancata compilazione della regola.

Nota: non utilizzare una variabile match nella sezione condition. Si tratta di un errore semantico poiché gli eventi vengono raggruppati in base al valore della variabile match.

Nota: non specificare solo condizioni illimitate su tutte le variabili event a cui è assegnata una variabile match. È un errore semantico. Per restituire un valore della variabile match, deve esistere almeno un evento che contenga il valore.

Nota: se si utilizza una finestra scorrevole, la variabile dell'evento pivot deve essere coinvolta in almeno una condizione limitata.

Condizionali dei risultati

Qui sono elencati i predicati delle condizioni per le variabili di risultato, uniti alla parola chiave and o or o preceduti dalla parola chiave not.

Specifica le condizionali dei risultati in modo diverso a seconda del tipo di variabile di risultato:

• integer: confronta con un valore letterale intero con operatori =, >, >=, <, <=, !=, ad esempio:

  $risk_score > 10

• float: confronto con un valore letterale in virgola mobile con gli operatori =, >, >=, <, <=, !=, ad esempio:

  $risk_score <= 5.5

• string: confronta con un valore letterale stringa con = o !=, ad esempio:

  $severity = "HIGH"

• elenco di numeri interi o array: specifica la condizione utilizzando la funzione arrays.contains, ad esempio:

  arrays.contains($event_ids, "id_1234")

Nota: se utilizzi la parola chiave or all'interno della sottosezione <event/placeholder condizionali>, devi racchiudere l'intera sottosezione tra parentesi. Ad esempio, quanto segue è valido: ($e1 or $e2) and $outcome > 0.

Classificazione delle regole

Se specifichi un condizionale di risultato in una regola che ha una sezione di corrispondenza, la regola verrà classificata come regola multi-evento per la quota delle regole. Consulta le regole per gli eventi singoli e le regole per gli eventi multipli per scoprire di più sulle classificazioni di eventi singoli e multipli.

Sintassi della sezione delle opzioni

Nella sezione options, puoi specificare le opzioni per la regola. Ecco un esempio di come specificare la sezione delle opzioni:

rule RuleOptionsExample {
  // Other rule sections

  options:
    allow_zero_values = true
}

Puoi specificare le opzioni utilizzando la sintassi key = value, dove key deve essere il nome di un'opzione predefinita e value deve essere un valore valido per l'opzione, come specificato per le seguenti opzioni:

allow_zero_values

I valori validi per questa opzione sono true e false, che determinano se questa opzione è abilitata o meno. Il valore predefinito è false. Questa opzione è disabilitata se non è specificata nella regola.

Per attivare questa impostazione, aggiungi quanto segue alla sezione delle opzioni della regola: allow_zero_values = true. In questo modo impedirai alla regola di filtrare implicitamente il valore zero dei segnaposto utilizzati nella sezione delle corrispondenze, come descritto nella gestione dei valori zero nella sezione delle corrispondenze.

Espressioni booleane

Le espressioni booleane sono espressioni di tipo booleano.

Confronti

Affinché un'espressione binaria venga utilizzata come condizione, utilizza la seguente sintassi:

• <EXPR> <OP> <EXPR>

L'espressione può essere un campo evento, una variabile, un valore letterale o un'espressione di funzione.

Ad esempio:

• $e.source.hostname = "host1234"
• $e.source.port < 1024
• 1024 < $e.source.port
• $e1.source.hostname != $e2.target.hostname
• $e1.metadata.collected_timestamp.seconds > $e2.metadata.collected_timestamp.seconds
• $port >= 25
• $host = $e2.target.hostname
• "google-test" = strings.concat($e.principal.hostname, "-test")
• "[e-mail]" = re.replace($e.network.email.from, "com", "org")

Se entrambi i lati sono valori letterali, viene considerato un errore di compilazione.

Funzioni

Alcune espressioni di funzione restituiscono un valore booleano, che può essere utilizzato come singolo predicato nella sezione events. Tali funzioni sono:

• re.regex()
• net.ip_in_range_cidr()

Ad esempio:

• re.regex($e.principal.hostname, `.*\.google\.com`)
• net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

Espressioni elenco di riferimento

Puoi utilizzare gli elenchi di riferimento nella sezione Eventi. Per ulteriori dettagli, consulta la sezione sugli elenchi di riferimento.

Espressioni logiche

Puoi utilizzare gli operatori logici and e or logici nella sezione events come mostrato nei seguenti esempi:

• $e.metadata.event_type = "NETWORK_DNS" or $e.metadata.event_type = "NETWORK_DHCP"
• ($e.metadata.event_type = "NETWORK_DNS" and $e.principal.ip = "192.0.2.12") or ($e.metadata.event_type = "NETWORK_DHCP" and $e.principal.mac = "AB:CD:01:10:EF:22")
• not $e.metadata.event_type = "NETWORK_DNS"

Per impostazione predefinita, l'ordine di precedenza dal più alto al più basso è not, and, or.

Ad esempio, "a o b e c" viene valutato come "a or (b e c)" quando gli operatori or e and sono definiti in modo esplicito nell'espressione.

Nella sezione events, i predicati vengono uniti utilizzando l'operatore and se un operatore non è definito in modo esplicito.

L'ordine di valutazione potrebbe essere diverso se nell'espressione è implicito l'operatore and.

Ad esempio, considera le seguenti espressioni di confronto in cui or è definito in modo esplicito. L'operatore and è implicito.

$e1.field = "bat"
or $e1.field = "baz"
$e2.field = "bar"

Questo esempio viene interpretato come segue:

($e1.field = "bat" or $e1.field = "baz")
and ($e2.field = "bar")

Poiché or viene definito in modo esplicito, i predicati che circondano or vengono raggruppati e valutati per primi. L'ultimo predicato, $e2.field = "bar", viene unito implicitamente utilizzando and. Il risultato è che l'ordine di valutazione cambia.

Nota: esiste un limite al numero di valori and e or che puoi specificare per una singola regola. Questo limite varia a seconda della complessità della regola e dei dati nel tuo account Google Security Operations. Contatta il tuo rappresentante Google Security Operations per informazioni sulle alternative a questo tipo di regola.

Tipi enumerati

Puoi utilizzare gli operatori con i tipi enumerati. Può essere applicato alle regole per semplificare e ottimizzare le prestazioni (utilizza un operatore anziché gli elenchi di riferimento).

Nell'esempio seguente, "USER_UNCATEGORIZED" e "USER_RESOURCE_DELETION" corrispondono a 15000 e 15014, pertanto la regola cercherà tutti gli eventi elencati:

$e.metadata.event_type >= "USER_CATEGORIZED" and $e.metadata.event_type <= "USER_RESOURCE_DELETION"

Elenco degli eventi:

• USER_RESOURCE_DELETION
• USER_RESOURCE_UPDATE_CONTENT
• USER_RESOURCE_UPDATE_PERMISSIONS
• USER_STATS
• USER_UNCATEGORIZED

Modificatore nocase

In presenza di un'espressione di confronto tra valori stringa o di un'espressione regolare, puoi aggiungere nocase alla fine dell'espressione per ignorare le lettere maiuscole.

• $e.principal.hostname != "http-server" nocase
• $e1.principal.hostname = $e2.target.hostname nocase
• $e.principal.hostname = /dns-server-[0-9]+/ nocase
• re.regex($e.target.hostname, `client-[0-9]+`) nocase

Questa opzione non può essere utilizzata quando un tipo di campo è un valore enumerato. I seguenti esempi non sono validi e genereranno errori di compilazione:

• $e.metadata.event_type = "NETWORK_DNS" nocase
• $e.network.ip_protocol = "TCP" nocase

Campi ripetuti

Nel modello di dati unificato (UDM), alcuni campi sono etichettati come ripetuti, a indicare che si tratta di elenchi di valori o di altri tipi di messaggi.

Campi ripetuti ed espressioni booleane

Esistono due tipi di espressioni booleane che agiscono su campi ripetuti:

1. Modificata
2. Non modificato

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

Le seguenti sezioni descrivono lo scopo e come utilizzare i modificatori any e all nelle espressioni.

tutte

Se qualsiasi elemento del campo ripetuto soddisfa la condizione, l'evento nel suo complesso soddisfa la condizione.

• event_original soddisfa any $e.principal.ip = "192.0.2.1".
• event_original non riesce a inviare any $e.repeated_field.field_a = "9.9.9.9.

tutte

Se tutti gli elementi del campo ripetuto soddisfano la condizione, l'evento nel suo complesso soddisfa la condizione.

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

Nota: per utilizzare any o all con una funzione, il modificatore deve precedere il campo ripetuto e non la funzione. Ad esempio, re.regex(any $e.about.hostname, `server-[0-9]+`) è valido, mentre any re.regex($e.about.hostname, `server-[0-9]+`) non lo è.

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 di negate.

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 regola sta controllando se almeno un indirizzo IP non corrisponde a 192.168.12.16.
• all $e.principal.ip != "192.168.12.16" controlla se tutti gli indirizzi IP non corrispondono 192.168.12.16, il che significa che la regola sta controllando che nessun indirizzo IP corrisponda a 192.168.12.16.

Vincoli:

• 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 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 regola 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:

copia 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 la copia di un evento qualsiasi soddisfa tutte le condizioni non modificate nel campo ripetuto, l'evento nel suo complesso soddisfa tutte le condizioni. Ciò significa che se sono presenti più condizioni su un campo ripetuto, la copia dell'evento deve soddisfarle tutte. I seguenti esempi di regole utilizzano il set di dati di esempio precedente per dimostrare questo comportamento.

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 di 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é in $e.principal.ip non esiste una copia degli eventi che soddisfi tutti i predicati degli eventi.

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 di elementi è lo stesso per ogni copia dell'evento. Prendi in considerazione 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:

copia dell'evento	principal.ip	qualsiasi valore $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, la corrispondenza dell'evento nel suo insieme.

Ecco un altro modo per considerare questi tipi di espressioni:

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

Campi ripetuti e segnaposto

I campi ripetuti funzionano con le assegnazioni di segnaposto. Come nel caso delle 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 valore del campo ripetuto di event_copy_n per ciascuna delle copie di eventi, dove n è il numero della copia dell'evento. Se il segnaposto viene utilizzato nella sezione delle corrispondenze, è possibile che vengano generate più corrispondenze.

L'esempio seguente genera una corrispondenza. Il segnaposto $ip è uguale a 192.0.2.1 per event_copy_1 e 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 poiché si trova nella sezione delle corrispondenze. Di conseguenza, ottieni tre corrispondenze in cui ciascuna corrispondenza ha 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
}

Nota: any e all non possono essere utilizzati quando si assegna un campo ripetuto a una variabile segnaposto o quando si unisce un campo di un altro evento. Ad esempio, any $e.principal.ip = $ip non è valido.

Risultati che utilizzano segnaposto assegnati a campi ripetuti

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

Prendi in considerazione 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 consiste nella copia degli eventi:

copia 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:

copia 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 è escluso perché "192.0.2.3" non soddisfa $ip = "192.0.2.1" or $ip = "192.0.2.2".

La sezione delle corrispondenze raggruppa quindi le variabili di corrispondenza e la sezione dei risultati eseguirà l'aggregazione su ogni gruppo:

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

Il valore $o = array_distinct($ip) viene calcolato utilizzando il valore $ip della fase precedente e non la fase di copia dell'evento.

Infine, la sezione delle condizioni filtrerà ogni gruppo. Poiché questa regola verifica solo l'esistenza di $e, la riga della 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 appariranno nell'esempio di evento perché quest'ultimo utilizza event_original.

Indicizzazione degli array

Puoi eseguire l'indicizzazione di array su campi ripetuti. Per accedere all'ennesimo elemento di campo ripetuto, utilizza la sintassi standard dell'elenco (gli elementi hanno un indice pari a 0). Un elemento fuori intervallo restituisce il valore predefinito.

• $e.principal.ip[0] = "192.168.12.16"
• $e.principal.ip[999] = "" Se sono presenti meno di 1000 elementi, il valore viene restituito come true.

Vincoli:

• 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 solo un indice per ip.

Messaggi ripetuti

Quando un campo message viene ripetuto, un effetto imprevisto è quello di ridurre la probabilità di una corrispondenza. come illustrato nei seguenti esempi.

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. Prendi in considerazione 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:

copia 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 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:

copia dell'evento	about.ip	informazioni su[1].nomehost
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 comportamenti imprevisti perché la regola repeated_message_1 non ha generato alcuna indicizzazione degli array e non ha prodotto corrispondenze, mentre la regola repeated_message_2 ha utilizzato l'indicizzazione degli array e generato una corrispondenza.

Commenti

Indica i commenti con due barre (// comment) o i commenti su più righe da impostare utilizzando una barra e asterischi (/* comment */), come in C.

Valori letterali

Sono supportati numeri interi e decimali non negativi, stringhe, booleani ed espressioni regolari.

Valori letterali stringhe ed espressioni regolari

Puoi utilizzare una delle virgolette seguenti per racchiudere le stringhe in YARA-L 2.0. Tuttavia, il testo tra virgolette viene interpretato in modo diverso a seconda di quale viene utilizzata.

1. Virgolette doppie ("): da utilizzare per le stringhe normali. Deve includere caratteri di escape.
   Ad esempio: "hello\tworld" —\t è interpretato come una scheda

2. Virgolette arretrate (`): vengono utilizzate per interpretare letteralmente tutti i caratteri.
   Ad esempio: "hello\tworld" —\t non è interpretato come una tabulazione

Per le espressioni regolari, hai due opzioni:

Se vuoi utilizzare le espressioni regolari direttamente senza la funzione re.regex(), utilizza /regex/ per i valori letterali delle espressioni regolari.

Puoi utilizzare i valori letterali stringa anche come valori letterali di espressioni regolari quando utilizzi la funzione re.regex(). Tieni presente che per i valori letterali stringa con virgolette, devi eseguire l'escape dei caratteri barra rovesciata con barre rovesciate, che possono sembrare complicate.

Ad esempio, le seguenti espressioni regolari sono equivalenti:

• re.regex($e.network.email.from, `.*altostrat\.com`)
• re.regex($e.network.email.from, ".*altostrat\\.com")
• $e.network.email.from = /.*altostrat\.com/

Per una leggibilità più agevole, Google consiglia di utilizzare le virgolette iniziali per le stringhe nelle espressioni regolari.

Operatori

In YARA-L puoi utilizzare i seguenti operatori:

Operatore	Descrizione
=	uguale/dichiarazione
!=	diverso
<	minore di
<=	minore o uguale a
>	maggiore di
>=	maggiore o uguale a

Variabili

In YARA-L 2.0, tutte le variabili sono rappresentate come $<variable name>.

Puoi definire i seguenti tipi di variabili:

• Variabili evento: rappresentano gruppi di eventi in forma normalizzata (UDM) o eventi di entità. Specifica le condizioni per le variabili evento nella sezione events. Puoi identificare le variabili evento utilizzando un nome, un'origine evento e i campi evento. Le origini consentite sono udm (per gli eventi normalizzati) e graph (per gli eventi entità). Se l'origine viene omessa, udm viene impostata come origine predefinita. I campi evento sono rappresentati come una catena di .<nome campo> (ad esempio, $e.field1.field2). Le catene di campi degli eventi iniziano sempre dall'origine di primo livello (UDM o Entità).

• Variabili di corrispondenza: dichiarale nella sezione match. Le variabili di corrispondenza diventano campi di raggruppamento per la query, poiché viene restituita una riga per ogni insieme univoco di variabili di corrispondenza (e per ogni finestra temporale). Quando la regola trova una corrispondenza, vengono restituiti i valori della variabile di corrispondenza. Specifica cosa rappresenta ciascuna variabile di corrispondenza nella sezione events.

• Variabili segnaposto: dichiara e definisci nella sezione events. Le variabili segnaposto sono simili alle variabili di corrispondenza. Tuttavia, puoi utilizzare le variabili segnaposto nella sezione condition per specificare le condizioni di corrispondenza.

Nota: ogni variabile segnaposto deve essere mappata a un campo evento. Ad esempio, se fai riferimento solo al seguente segnaposto in questa singola riga di una regola, la compilazione non andrebbe a buon fine poiché $var non è associato a una variabile evento: $e.field != $var

.

Utilizza le variabili di corrispondenza e segnaposto per dichiarare le relazioni tra i campi evento tramite condizioni di join transitive (per ulteriori dettagli, consulta la sintassi della sezione Eventi).

Keywords

Le parole chiave nello standard YARA-L 2.0 non fanno distinzione tra maiuscole e minuscole. Ad esempio, and o AND sono equivalenti. I nomi delle variabili non devono essere in conflitto con le parole chiave. Ad esempio, $AND o $outcome non sono validi.

Di seguito sono riportate le parole chiave per le regole del motore di rilevamento: rule, meta, match, over, events, condition, outcome, options, and, or, not, nocase, in, regex, cidr, before, after, all, any, if, max, match, match, match, match, matchminsumarrayarray_distinctcountcount_distinctisnull

Maps

YARA-L supporta l'accesso alla mappa per struct ed etichette.

Structs ed etichette

Alcuni campi UDM utilizzano il tipo di dati Struct o Etichetta.

Per cercare una coppia chiave-valore specifica sia in Struct che in Etichetta, utilizza la sintassi standard della mappa:

// A Struct field.
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// A Label field.
$e.metadata.ingestion_labels["MetadataKeyDeletion"] = "startup-script"

L'accesso alla mappa restituisce sempre una stringa.

Richieste supportate

Sezione Eventi e risultati

// Using a Struct field in the events section
events:
  $e.udm.additional.fields["pod_name"] = "kube-scheduler"

// Using a Label field in the outcome section
outcome:
  $value = array_distinct($e.metadata.ingestion_labels["MetadataKeyDeletion"])

Assegnazione di un valore di mappa a un segnaposto

$placeholder = $u1.metadata.ingestion_labels["MetadataKeyDeletion"]

Utilizzo di un campo mappa in una condizione di join

// using a Struct field in a join condition between two udm events $u1 and $u2
$u1.metadata.event_type = $u2.udm.additional.fields["pod_name"]

Richieste non supportate

Le mappe non sono supportate nei casi indicati di seguito.

Combinazione di any o all parole chiave con una mappa

Ad esempio, quanto segue non è supportato:

all $e.udm.additional.fields["pod_name"] = "kube-scheduler"

Altri tipi di valori

La sintassi della mappa può restituire solo un valore stringa. Nel caso dei tipi di dati Struct, la sintassi della mappa può accedere solo alle chiavi i cui valori sono stringhe. Non è possibile accedere a chiavi i cui valori sono altri tipi primitivi come i numeri interi.

Gestione dei valori duplicati

Gli accessi alla mappa restituiscono sempre un singolo valore. Nel caso limite insolito in cui l'accesso alla mappa possa fare riferimento a più valori, l'accesso alla mappa restituirà il primo valore in modo deterministico.

Ciò può verificarsi in uno dei seguenti casi:

• Un'etichetta ha una chiave duplicata.

  La struttura delle etichette rappresenta una mappa, ma non applica l'univocità delle chiavi. Per convenzione, una mappa deve avere chiavi univoche, pertanto Google Security Operations sconsiglia di compilare un'etichetta con chiavi duplicate.

  Il testo della regola $e.metadata.ingestion_labels["dupe-key"] restituirà il primo valore possibile, val1, se eseguito sul seguente esempio di dati:

  // Disrecommended usage of label with a duplicate key:
  event {
    metadata{
      ingestion_labels{
        key: "dupe-key"
        value: "val1" // This is the first possible value for "dupe-key"
      }
      ingestion_labels{
        key: "dupe-key"
        value: "val2"
      }
    }
  }
  

• Un'etichetta ha un campo ripetuto predecessore.

  Un campo ripetuto potrebbe contenere un'etichetta come campo secondario. Due voci diverse nel campo ripetuto di primo livello potrebbero contenere etichette che hanno la stessa chiave. Il testo della regola $e.security_result.rule_labels["key"] restituisce il primo valore possibile, val3, se eseguito sul seguente esempio di dati:

  event {
    // security_result is a repeated field.
    security_result {
      threat_name: "threat1"
      rule_labels {
        key: "key"
        value: "val3" // This is the first possible value for "key"
      }
    }
    security_result {
      threat_name: "threat2"
      rule_labels {
        key: "key"
        value: "val4"
      }
    }
  }
  

Funzioni

Questa sezione descrive le funzioni YARA-L 2.0 che è possibile utilizzare nelle regole e nella ricerca dei motori di rilevamento.

Nota: l'uso della variabile evento $e è facoltativo quando nella ricerca viene utilizzato YARA-L. Sia principal.hostname sia $e.principal.hostname sono supportati nella ricerca.

Queste funzioni possono essere utilizzate nelle seguenti parti di una regola YARA-L:

• Sezione events.
• BOOL_CLAUSE di un condizionale nella sezione Risultati.

arrays.length

Supportato in:

Regole Ricerca

arrays.length(repeatedField)

Descrizione

Restituisce il numero di elementi di campo ripetuti.

Tipi di dati del parametro

LIST

Tipo restituito

NUMBER

Esempi di codice

Esempio 1

Restituisce il numero di elementi di campo ripetuti.

arrays.length($e.principal.ip) = 2

Esempio 2

Se lungo il percorso sono presenti più campi ripetuti, questo restituisce il numero totale di elementi di campo ripetuti.

arrays.length($e.intermediary.ip) = 3

impronta

Supportato in:

Regole

hash.fingerprint2011(byteOrString)

Descrizione

Questa funzione calcola l'hash fingerprint2011 di una sequenza o una stringa di byte di input. Questa funzione restituisce un valore INT senza segno nell'intervallo [2, 0xFFFFFFFFFFFFFFFF].

Nota: questa funzione non deve essere utilizzata come hash crittografico sicuro.

Tipi di dati del parametro

BTYE, STRING

Tipo restituito

INT

Esempio di codice

id_fingerprint = hash.fingerprint2011("user123")

gruppo

Supportato in:

Cerca

group(field1, field2, field3, ...)

Descrizione

Raggruppa i campi di tipo simile in una variabile segnaposto.

Nella ricerca UDM, i campi raggruppati vengono utilizzati per cercare in più campi di tipo simile. La funzione di gruppo è simile ai campi raggruppati, ma consente di selezionare i campi da raggruppare per attivare un rilevamento. Puoi utilizzare la funzione di gruppo per raccogliere informazioni su una specifica entità (ad esempio, un nome host, un indirizzo IP o un ID utente) in diversi tipi di nomi.

Nota: per la ricerca, puoi utilizzare i campi raggruppati nella sezione degli eventi, ma non nelle sezioni delle corrispondenze e dei risultati.

Esempi di codice

Esempio 1

Raggruppa tutti gli indirizzi IP e fornisci un conteggio decrescente dell'indirizzo IP più diffuso nell'intervallo di tempo analizzato.

$ip = group(principal.ip, about.ip, target.ip)
$ip != ""
match:
  $ip
outcome:
  $count = count_distinct(metadata.id)
order:
  $count desc

math.abs

Supportato in:

Regole Ricerca

math.abs(numericExpression)

Descrizione

Restituisce il valore assoluto di un numero intero o un'espressione in virgola mobile.

Tipi di dati del parametro

NUMBER

Tipo restituito

NUMBER

Esempi di codice

Esempio 1

Questo esempio restituisce True se l'evento si trova a più di 5 minuti dall'ora specificata (in secondi dall'epoca di Unix), a prescindere dal fatto che l'evento si sia verificato prima o dopo l'orario specificato. Una chiamata a math.abs non può dipendere da più variabili o segnaposto. Ad esempio, non puoi sostituire il valore di tempo impostato come hardcoded di 1643687343 nell'esempio seguente con $e2.metadata.event_timestamp.seconds.

300 < math.abs($e1.metadata.event_timestamp.seconds - 1643687343)

math.log

Supportato in:

Regole Ricerca

math.log(numericExpression)

Descrizione

Restituisce il valore logaritmico naturale di un numero intero o un'espressione in virgola mobile.

Tipi di dati del parametro

NUMBER

Tipo restituito

NUMBER

Esempi di codice

Esempio 1

math.log($e1.network.sent_bytes) > 20

math.round

Supportato in:

Cerca

math.round(numericExpression, decimalPlaces)

Descrizione

Restituisce un valore arrotondato al numero intero più vicino o al numero di cifre decimali specificato.

Tipi di dati del parametro

NUMBER

Tipo restituito

NUMBER

Esempi di codice

math.round(10.7) // returns 11
math.round(1.2567, 2) // returns 1.25
math.round(-10.7) // returns -11
math.round(-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer

metrics

Supportato in:

Regole

Le funzioni metriche possono aggregare grandi quantità di dati storici. Puoi utilizzare questo campo nella regola utilizzando metrics.functionName() nella sezione dei risultati.

Per ulteriori informazioni, consulta le metriche YARA-L.

net.ip_in_range_cidr

Supportato in:

Regole Ricerca

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Descrizione

Restituisce true quando l'indirizzo IP specificato si trova all'interno della subnet specificata.

Puoi utilizzare YARA-L per cercare eventi UDM in tutti gli indirizzi IP all'interno di una subnet utilizzando l'istruzione net.ip_in_range_cidr(). Sono supportati sia IPv4 sia IPv6.

Per eseguire ricerche in un intervallo di indirizzi IP, specifica un campo UDM IP e un intervallo CIDR. YARA-L può gestire campi di indirizzi IP singoli e ripetuti.

Per eseguire la ricerca in un intervallo di indirizzi IP, specifica un campo UDM ip e un intervallo CIDR (Classless Inter-Domain Routing). YARA-L può gestire campi di indirizzi IP singoli e ripetuti.

Tipi di dati del parametro

STRING, STRING

Tipo restituito

BOOL

Esempi di codice

Esempio 1

Esempio di IPv4:

net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

Esempio 2

Esempio di IPv6:

net.ip_in_range_cidr($e.network.dhcp.yiaddr, "2001:db8::/32")

Per un esempio di regola che utilizza l'istruzione net.ip_in_range_cidr(), vedi la regola di esempio in Singolo evento entro intervallo di indirizzi IP.)

re.regex

Supportato in:

Regole Ricerca

Puoi definire la corrispondenza delle espressioni regolari in YARA-L 2.0 utilizzando una delle seguenti sintassi:

• Utilizzo della sintassi YARA-L: correlato agli eventi. Di seguito è riportata una rappresentazione generica di questa sintassi:

  $e.field = /regex/
  

• Utilizzo della sintassi YARA-L: come funzione che prende i seguenti parametri:

  • Campo a cui viene applicata l'espressione regolare.
  • Espressione regolare specificata come stringa.

  Di seguito è riportata una rappresentazione generica di questa sintassi:

  re.regex($e.field, `regex`)
  

Descrizione

Questa funzione restituisce true se la stringa contiene una sottostringa che corrisponde all'espressione regolare fornita. Non è necessario aggiungere .* all'inizio o alla fine dell'espressione regolare.

Note

• Per corrispondere alla stringa esatta o solo a un prefisso o a un suffisso, includi i caratteri di ancoraggio ^ (inizio) e $ (fine) nell'espressione regolare. Ad esempio, /^full$/ corrisponde esattamente a "full", mentre /full/ potrebbe corrispondere a "fullest", "lawfull" e "joyfully".
• Se il campo UDM include caratteri di nuova riga, regexp corrisponde solo alla prima riga del campo UDM. Per applicare la corrispondenza completa dei campi UDM, aggiungi (?s) all'espressione regolare. Ad esempio, sostituisci /.*allUDM.*/ con /(?s).*allUDM.*/.
• Puoi utilizzare il modificatore di nocase dopo le stringhe per indicare che la ricerca deve ignorare le lettere maiuscole.

Tipi di dati del parametro

STRING, STRING

Tipi di espressione del parametro

ANY, ANY

Tipo restituito

BOOL

Esempi di codice

Esempio 1

// Equivalent to $e.principal.hostname = /google/
re.regex($e.principal.hostname, "google")

re.capture

Supportato in:

Regole Ricerca

re.capture(stringText, regex)

Descrizione

Acquisisce (estrae) i dati da una stringa utilizzando il pattern di espressione regolare fornito nell'argomento.

Questa funzione accetta due argomenti:

• stringText: la stringa originale in cui cercare.
• regex: l'espressione regolare che indica il pattern da cercare.

L'espressione regolare può contenere 0 o 1 gruppi Capture tra parentesi. Se l'espressione regolare contiene 0 gruppi Capture, la funzione restituisce la prima sottostringa corrispondente. Se l'espressione regolare contiene un gruppo Capture, restituisce la prima sottostringa corrispondente per il gruppo Capture. La definizione di due o più gruppi di cattura restituisce un errore del compilatore.

Tipi di dati del parametro

STRING, STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

In questo esempio, se $e.principal.hostname contiene "aaa1bbaa2", la funzione seguente sarebbe vera, perché la funzione restituisce la prima istanza. In questo esempio non sono presenti gruppi di acquisizione.

"aaa1" = re.capture($e.principal.hostname, "a+[1-9]")

Esempio 2

Questo esempio acquisisce tutto ciò che segue il simbolo @ in un'email. Se il campo $e.network.email.from è [e-mail], l'esempio restituisce google.com. L'esempio seguente contiene un gruppo di acquisizione.

"google.com" = re.capture($e.network.email.from , "@(.*)")

Esempio 3

Se l'espressione regolare non corrisponde a nessuna sottostringa nel testo, la funzione restituisce una stringa vuota. Puoi omettere gli eventi in cui non si verifica alcuna corrispondenza escludendo la stringa vuota, il che è particolarmente importante quando utilizzi re.capture() con una disuguaglianza:

// Exclude the empty string to omit events where no match occurs.
"" != re.capture($e.network.email.from , "@(.*)")

// Exclude a specific string with an inequality.
"google.com" != re.capture($e.network.email.from , "@(.*)")

re.replace

Supportato in:

Regole Ricerca

re.replace(stringText, replaceRegex, replacementText)

Descrizione

Esegue una sostituzione di espressioni regolari.

Questa funzione accetta tre argomenti:

• stringText: la stringa originale.
• replaceRegex: l'espressione regolare che indica il pattern da cercare.
• replacementText: il testo da inserire in ogni corrispondenza.

Restituisce una nuova stringa derivata dall'originale stringText, dove tutte le sottostringhe corrispondenti al pattern in replaceRegex vengono sostituite con il valore in replacementText. Puoi utilizzare cifre con una barra rovesciata (da \1 a \9) all'interno di replacementText per inserire il testo corrispondente al gruppo tra parentesi corrispondente nel pattern replaceRegex. Utilizza \0 per fare riferimento all'intero testo corrispondente.

La funzione sostituisce le corrispondenze non sovrapposte e darà la priorità alla sostituzione della prima occorrenza trovata. Ad esempio, re.replace("banana", "ana", "111") restituisce la stringa "b111na".

Tipi di dati del parametro

STRING, STRING e STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

Questo esempio acquisisce tutto ciò che segue il simbolo @ in un'email, sostituisce com con org e restituisce il risultato. Nota l'uso delle funzioni nidificate.

"[e-mail]" = re.replace($e.network.email.from, "com", "org")

Esempio 2

Questo esempio utilizza cifre con escape barra rovesciata nell'argomento replacementText per fare riferimento alle corrispondenze con il pattern replaceRegex.

"test1.com.google" = re.replace(
                       $e.principal.hostname, // holds "test1.test2.google.com"
                       "test2\.([a-z]*)\.([a-z]*)",
                       "\\2.\\1"  // \\1 holds "google", \\2 holds "com"
                     )

Esempio 3

Nota i seguenti casi quando lavori con stringhe vuote e re.replace():

Stringa vuota come replaceRegex:

// In the function call below, if $e.principal.hostname contains "name",
// the result is: 1n1a1m1e1, because an empty string is found next to
// every character in `stringText`.
re.replace($e.principal.hostname, "", "1")

Per sostituire una stringa vuota, puoi utilizzare "^$" come replaceRegex:

// In the function call below, if $e.principal.hostname contains the empty
// string, "", the result is: "none".
re.replace($e.principal.hostname, "^$", "none")

sample_rate

Supportato in:

Regole

optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

Descrizione

Questa funzione determina se includere un evento in base a una strategia di campionamento deterministica. Questa funzione restituisce:

• true per una frazione di valori di input, equivalente a (rateNumerator / rateDenominator), che indica che l'evento deve essere incluso nel campione.
• false che indica che l'evento non deve essere incluso nel campione.

Questa funzione è utile per gli scenari di ottimizzazione in cui vuoi elaborare solo un sottoinsieme di eventi. Equivalente a:

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Tipi di dati del parametro

• byteOrString: espressione che restituisce BYTE o STRING.
• rateNumerator: "INT"
• rateDenominator: "INT"

Tipo restituito

BOOL

Esempio di codice

events:
    $e.metadata.event_type = "NETWORK_CONNECTION"
    $asset_id = $e.principal.asset.asset_id
    optimization.sample_rate($e.metadata.id, 1, 5) // Only 1 out of every 5 events

  match:
    $asset_id over 1h

  outcome:
    $event_count = count_distinct($e.metadata.id)
  // estimate the usage by multiplying by the inverse of the sample rate
    $usage_past_hour = sum(5.0 * $e.network.sent_bytes)

 condition:
  // Requiring a certain number of events after sampling avoids bias (e.g. a
  // device with just 1 connection will still show up 20% of the time and
  // if we multiply that traffic by 5, we'll get an incorrect estimate)
  $e and ($usage_past_hour > 1000000000) and $event_count >= 100

strings.base64_decode

Supportato in:

Regole Ricerca

strings.base64_decode(encodedString)

Descrizione

Restituisce una stringa contenente la versione decodificata in base64 della stringa codificata.

Questa funzione prende come argomento una stringa codificata in base64. Se encodedString non è una stringa codificata in base64 valida, la funzione restituisce encodedString invariato.

Tipi di dati del parametro

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

"test" = strings.base64_decode($e.principal.domain.name)

strings.coalesce

Supportato in:

Regole Ricerca

strings.coalesce(a, b, c, ...)

Descrizione

Questa funzione accetta un numero illimitato di argomenti e restituisce il valore della prima espressione che non restituisce una stringa vuota (ad esempio, "valore diverso da zero"). Se tutti gli argomenti restituiscono una stringa vuota, la chiamata di funzione restituisce una stringa vuota.

Gli argomenti possono essere valori letterali, campi evento o chiamate di funzione. Tutti gli argomenti devono essere di tipo STRING. Se alcuni argomenti sono campi evento, gli attributi devono provenire dallo stesso evento.

Tipi di dati del parametro

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente include variabili stringa come argomenti. La condizione restituisce true quando (1) $e.network.email.from è [e-mail] o (2) $e.network.email.from è vuoto e $e.network.email.to è [e-mail].

"[e-mail]" = strings.coalesce($e.network.email.from, $e.network.email.to)

Esempio 2

L'esempio seguente chiama la funzione coalesce con più di due argomenti. Questa condizione confronta il primo indirizzo IP non nullo dell'evento $e con i valori nell'elenco di riferimento ip_watchlist. L'ordine in cui gli argomenti vengono uniti in questa chiamata è uguale all'ordine in cui sono enumerati nella condizione della regola:

1. $e.principal.ip viene valutato per primo.
2. $e.src.ip viene valutato successivamente.
3. $e.target.ip viene valutato successivamente.
4. Infine, la stringa "Nessun IP" viene restituita come valore predefinito se i campi ip precedenti non sono impostati.

strings.coalesce($e.principal.ip, $e.src.ip, $e.target.ip, "No IP") in %ip_watchlist

Esempio 3

L'esempio seguente tenta di unire principal.hostname dall'evento $e1 e dall'evento $e2. Restituisce un errore del compilatore perché gli argomenti sono variabili evento diverse.

// returns a compiler error
"test" = strings.coalesce($e1.principal.hostname, $e2.principal.hostname)

strings.concat

Supportato in:

Regole Ricerca

strings.concat(a, b, c, ...)

Descrizione

Restituisce la concatenazione di un numero illimitato di elementi, ognuno dei quali può essere una stringa, un numero intero o un valore in virgola mobile.

Se alcuni argomenti sono campi evento, gli attributi devono provenire dallo stesso evento.

Tipi di dati del parametro

STRING, FLOAT, INT

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente include una variabile stringa e una variabile intera come argomenti. Sia principal.hostname che principal.port provengono dallo stesso evento, $e, e sono concatenati per restituire una stringa.

"google:80" = strings.concat($e.principal.hostname, ":", $e.principal.port)

Esempio 2

L'esempio seguente include una variabile stringa e una stringa letterale come argomenti.

"google-test" = strings.concat($e.principal.hostname, "-test") // Matches the event when $e.principal.hostname = "google"

Esempio 3

L'esempio seguente include una variabile stringa e un valore letterale in virgola mobile come argomenti. Se rappresentati come stringhe, i numeri in virgola mobile sono numeri interi vengono formattati senza la virgola decimale (ad esempio, 1,0 è rappresentato come "1"). Inoltre, i numeri in virgola mobile che superano sedici cifre decimali vengono troncati alla sedicesima posizione decimale.

"google2.5" = strings.concat($e.principal.hostname, 2.5)

Esempio 4

L'esempio seguente include una variabile stringa, un valore letterale stringa, una variabile intero e un valore letterale in virgola mobile come argomenti. Tutte le variabili provengono dallo stesso evento, $e, e sono concatenate con i valori letterali per restituire una stringa.

"google-test802.5" = strings.concat($e.principal.hostname, "-test", $e.principal.port, 2.5)

Esempio 5

L'esempio seguente tenta di concatenare principal.port dall'evento $e1, con principal.hostname dall'evento $e2. Restituisce un errore del compilatore perché gli argomenti sono variabili evento diverse.

// Will not compile
"test" = strings.concat($e1.principal.port, $e2.principal.hostname)

strings.to_lower

Supportato in:

Regole Ricerca

strings.to_lower(stringText)

Descrizione

Questa funzione prende una stringa di input e restituisce una stringa dopo aver modificato tutti i caratteri in minuscolo

Tipi di dati del parametro

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente restituisce true.

"[e-mail]" = strings.to_lower($e.network.email.to)

strings.to_upper

Supportato in:

Regole Ricerca

strings.to_upper(stringText)

Descrizione

Questa funzione prende una stringa di input e restituisce una stringa dopo aver modificato tutti i caratteri in lettere maiuscole

Tipi di dati del parametro

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente restituisce true.

"[e-mail]" = strings.to_upper($e.network.email.to)

timestamp.current_seconds

Supportato in:

Regole Ricerca

timestamp.current_seconds()

Descrizione

Restituisce un numero intero che rappresenta l'ora corrente in secondi Unix. È quasi uguale al timestamp di rilevamento e si basa su quando viene eseguita la regola.

Tipi di dati del parametro

NONE

Tipo restituito

INT

Esempi di codice

Esempio 1

L'esempio seguente restituisce true se il certificato è scaduto da più di 24 ore. Calcola la differenza di tempo sottraendo i secondi Unix correnti e confrontandoli con un operatore "maggiore di".

86400 < timestamp.current_seconds() - $e.network.tls.certificate.not_after

timestamp.get_date

Supportato in:

Regole Ricerca

timestamp.get_date(unix_seconds [, time_zone])

Descrizione

Questa funzione restituisce una stringa nel formato YYYY-MM-DD, che rappresenta il giorno in cui si trova un timestamp.

• unix_seconds è un numero intero che rappresenta il numero di secondi passati dall'epoca di Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente quel valore.
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari usando valori letterali stringa. Le opzioni sono:
  • Il nome del database TZ, ad esempio "America/Los_Angeles". Per maggiori informazioni, consulta la colonna"Nome database TZ" in questa pagina
  • La differenza del fuso orario rispetto a UTC, nel formato (+|-)H[H][:M[M]], ad esempio: "-08:00".

Di seguito sono riportati alcuni esempi di specificatori di fuso orario validi, che puoi passare come secondo argomento alle funzioni di estrazione del tempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipi di dati del parametro

INT, STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è omesso, quindi il valore predefinito è "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts) = "2024-02-19"

Esempio 2

In questo esempio viene utilizzato un valore letterale stringa per definire time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts, "America/Los_Angeles") = "2024-02-20"

timestamp.get_minute

Supportato in:

Regole Ricerca

timestamp.get_minute(unix_seconds [, time_zone])

Descrizione

Questa funzione restituisce un numero intero nell'intervallo [0, 59] che rappresenta il minuto.

• unix_seconds è un numero intero che rappresenta il numero di secondi passati dall'epoca di Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente quel valore.
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari usando valori letterali stringa. Le opzioni sono:
  • Il nome del database TZ, ad esempio "America/Los_Angeles". Per maggiori informazioni, consulta la colonna"Nome database TZ" in questa pagina
  • La differenza del fuso orario rispetto a UTC, nel formato (+|-)H[H][:M[M]], ad esempio: "-08:00".

Di seguito sono riportati alcuni esempi di specificatori time_zone validi, che puoi passare come secondo argomento alle funzioni di estrazione del tempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipi di dati del parametro

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è omesso, quindi il valore predefinito è "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Esempio 2

In questo esempio viene utilizzato un valore letterale stringa per definire time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_hour

Supportato in:

Regole Ricerca

timestamp.get_hour(unix_seconds [, time_zone])

Descrizione

Questa funzione restituisce un numero intero nell'intervallo [0, 23] che rappresenta l'ora.

• unix_seconds è un numero intero che rappresenta il numero di secondi passati dall'epoca di Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente quel valore.
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari usando valori letterali stringa. Le opzioni sono:
  • Il nome del database TZ, ad esempio "America/Los_Angeles". Per maggiori informazioni, consulta la colonna"Nome database TZ" in questa pagina
  • La differenza del fuso orario rispetto a UTC, nel formato (+|-)H[H][:M[M]], ad esempio: "-08:00".

Di seguito sono riportati alcuni esempi di specificatori time_zone validi, che puoi passare come secondo argomento alle funzioni di estrazione del tempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipi di dati del parametro

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è omesso, quindi il valore predefinito è "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Esempio 2

In questo esempio viene utilizzato un valore letterale stringa per definire time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_day_of_week

Supportato in:

Regole Ricerca

timestamp.get_day_of_week(unix_seconds [, time_zone])

Descrizione

Questa funzione restituisce un numero intero nell'intervallo [1, 7] che rappresenta il giorno della settimana che inizia da domenica. Ad esempio, 1 = domenica e 2 = lunedì.

• unix_seconds è un numero intero che rappresenta il numero di secondi passati dall'epoca di Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente quel valore.
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari usando valori letterali stringa. Le opzioni sono:
  • Il nome del database TZ, ad esempio "America/Los_Angeles". Per maggiori informazioni, consulta la colonna"Nome database TZ" in questa pagina
  • La differenza del fuso orario rispetto a UTC, nel formato (+|-)H[H][:M[M]], ad esempio: "-08:00".

Di seguito sono riportati alcuni esempi di specificatori di fuso orario validi, che puoi passare come secondo argomento alle funzioni di estrazione del tempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipi di dati del parametro

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è omesso, quindi il valore predefinito è "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6

Esempio 2

In questo esempio viene utilizzato un valore letterale stringa per definire time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts, "America/Los_Angeles") = 6

timestamp.get_timestamp

Supportato in:

Regole Ricerca

timestamp.get_timestamp(unix_seconds, optional timestamp_format, optional timezone)

Descrizione

Questa funzione restituisce una stringa nel formato YYYY-MM-DD, che rappresenta il giorno in cui si trova un timestamp.

• unix_seconds è un numero intero che rappresenta il numero di secondi passati dall'epoca di Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente quel valore.
• timestamp_format è facoltativo ed è una stringa che rappresenta il formato del timestamp. Se omesso, il valore predefinito è %F %T. Puoi specificare il formato utilizzando i valori letterali stringa. Per le opzioni, vedi Formattare gli elementi per le parti di data e ora
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è GMT. Puoi specificare i fusi orari usando valori letterali stringa. Le opzioni sono le seguenti:
  • Il nome del database del fuso orario IANA (TZ), ad esempio America/Los_Angeles. Per ulteriori informazioni, consulta l'elenco dei fusi orari del database tz su Wikipedia.
  • La differenza del fuso orario rispetto a UTC, nel formato (+|-)H[H][:M[M]], ad esempio: "-08:00".

Di seguito sono riportati alcuni esempi di specificatori time_zone validi, che puoi passare come secondo argomento alle funzioni di estrazione del tempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipi di dati del parametro

INT, STRING e STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è omesso, quindi il valore predefinito è GMT.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts) = "2024-02-22 10:43:51"

Esempio 2

In questo esempio viene utilizzato un valore letterale stringa per definire time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%F %T", "America/Los_Angeles") = "2024-02-22 10:43:51"

Esempio 3

In questo esempio viene utilizzato un valore letterale stringa per definire timestamp_format.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%Y-%m", "GMT") = "2024-02"

timestamp.get_week

Supportato in:

Regole Ricerca

timestamp.get_week(unix_seconds [, time_zone])

Descrizione

Questa funzione restituisce un numero intero nell'intervallo [0, 53] che rappresenta la settimana dell'anno. Le settimane iniziano con la domenica. Le date antecedenti la prima domenica dell'anno sono nella settimana 0.

• unix_seconds è un numero intero che rappresenta il numero di secondi passati dall'epoca di Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente quel valore.
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari usando valori letterali stringa. Le opzioni sono:
  • Il nome del database TZ, ad esempio "America/Los_Angeles". Per maggiori informazioni, consulta la colonna"Nome database TZ" in questa pagina
  • La differenza del fuso orario rispetto a UTC, nel formato (+|-)H[H][:M[M]], ad esempio: "-08:00".

Di seguito sono riportati alcuni esempi di specificatori time_zone validi, che puoi passare come secondo argomento alle funzioni di estrazione del tempo:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Tipi di dati del parametro

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è omesso, quindi il valore predefinito è "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0

Esempio 2

In questo esempio viene utilizzato un valore letterale stringa per definire time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts, "America/Los_Angeles") = 0

Funzione per l'assegnazione di segnaposto

Puoi assegnare il risultato di una chiamata di funzione a un segnaposto nella sezione events. Ad esempio:

$placeholder = strings.concat($e.principal.hostname, "my-string").

Puoi quindi utilizzare le variabili segnaposto nelle sezioni match, condition e outcome. Tuttavia, l'assegnazione di funzioni a segnaposto presenta due limitazioni:

1. Ogni segnaposto nell'assegnazione di funzioni a segnaposto deve essere assegnato a un'espressione contenente un campo evento. Ad esempio, i seguenti esempi sono validi:

   $ph1 = $e.principal.hostname
   $ph2 = $e.src.hostname
   
   // Both $ph1 and $ph2 have been assigned to an expression containing an event field.
   $ph1 = strings.concat($ph2, ".com")
   

   $ph1 = $e.network.email.from
   $ph2 = strings.concat($e.principal.hostname, "@gmail.com")
   
   // Both $ph1 and $ph2 have been assigned to an expression containing an event field.
   $ph1 = strings.to_lower($ph2)
   

   Tuttavia, il seguente esempio non è valido:

   $ph1 = strings.concat($e.principal.hostname, "foo")
   $ph2 = strings.concat($ph1, "bar") // $ph2 has NOT been assigned to an expression containing an event field.
   

2. La chiamata di funzione deve dipendere da un solo evento. Tuttavia, più di un campo dello stesso evento può essere utilizzato negli argomenti della chiamata di funzione. Ad esempio, quanto segue è valido:

   $ph = strings.concat($event.principal.hostname, "string2")

   $ph = strings.concat($event.principal.hostname, $event.src.hostname)

   Tuttavia, quanto segue non è valido:

   $ph = strings.concat("string1", "string2")

   $ph = strings.concat($event.principal.hostname, $anotherEvent.src.hostname)

Sintassi degli elenchi di riferimento

Consulta la nostra pagina sugli elenchi di riferimento per ulteriori informazioni sul comportamento e sulla sintassi dell'elenco di riferimento.

Puoi utilizzare gli elenchi di riferimento nelle sezioni events o outcome. Ecco la sintassi per l'utilizzo di vari tipi di elenchi di riferimento in una regola:

// STRING reference list
$e.principal.hostname in %string_reference_list

// REGEX reference list
$e.principal.hostname in regex %regex_reference_list

// CIDR reference list
$e.principal.ip in cidr %cidr_reference_list

Puoi anche utilizzare l'operatore not e l'operatore nocase con gli elenchi di riferimento, come mostrato nell'esempio seguente:

// Exclude events whose hostnames match substrings in my_regex_list.
not $e.principal.hostname in regex %my_regex_list

// Event hostnames must match at least 1 string in my_string_list (case insensitive).
$e.principal.hostname in %my_string_list nocase

L'operatore nocase è compatibile con gli elenchi STRING e REGEX.

Per motivi legati alle prestazioni, Detection Engine limita l'uso degli elenchi di riferimento.

• Massimo in istruzioni in una regola, con o senza operatori speciali: 7
• Massimo di istruzioni in con l'operatore regex: 4
• Massimo di istruzioni in con l'operatore cidr: 2

Controllo del tipo

Google Security Operations esegue il controllo del tipo in base alla sintassi YARA-L durante la creazione delle regole all'interno dell'interfaccia. Gli errori di controllo dei tipi visualizzati consentono di rivedere la regola in modo da garantire che funzioni come previsto.

Ecco alcuni esempi di predicati non validi:

// $e.target.port is of type integer which cannot be compared to a string.
$e.target.port = "80"

// "LOGIN" is not a valid event_type enum value.
$e.metadata.event_type = "LOGIN"

Campionamento degli eventi di rilevamento

I rilevamenti delle regole per più eventi contengono campioni di eventi per fornire il contesto degli eventi che hanno causato il rilevamento. È previsto un limite di massimo 10 esempi di eventi per ogni variabile evento definita nella regola. Ad esempio, se una regola definisce 2 variabili evento, ogni rilevamento può avere fino a 20 campioni di eventi. Il limite si applica a ogni variabile evento separatamente. Se una variabile evento ha 2 eventi applicabili in questo rilevamento e l'altra variabile evento ha 15 eventi applicabili, il rilevamento risultante contiene 12 campioni di eventi (2 + 10).

Eventuali campioni di eventi che superano il limite vengono omessi dal rilevamento.

Se vuoi saperne di più sugli eventi che hanno causato il rilevamento, puoi utilizzare le aggregazioni nella sezione dei risultati per restituire informazioni aggiuntive nel rilevamento.

Se visualizzi i rilevamenti nella UI, puoi scaricare tutti gli esempi di eventi per un rilevamento. Per ulteriori informazioni, vedi Scaricare eventi.