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, devi specificare dichiarazioni, definizioni e utilizzi delle variabili nel seguente ordine:

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

Nota: se escludi la sezione facoltativa match, 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 delle meta-section

La sezione di 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 della sezione meta valida: none meta: author = "Chronicle" severity = "HIGH"

Sintassi della sezione Eventi

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

• Dichiarazioni delle variabili
• Filtri variabili evento
• Join di variabili evento

Dichiarazioni delle variabili

Per le dichiarazioni delle variabili, utilizza la seguente sintassi:

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

Entrambi 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. Se il campo evento è un campo ripetuto, la variabile di corrispondenza può rappresentare qualsiasi valore dell'array. È anche possibile assegnare più campi evento a una singola variabile con corrispondenza o segnaposto. Questa è una condizione di join transitiva.

Ad esempio:

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

Equivaleno a:

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

Quando viene utilizzata una variabile, questa deve essere dichiarata tramite la relativa dichiarazione. Se una variabile viene utilizzata senza alcuna dichiarazione, viene considerata come un errore di compilazione.

Filtri variabili evento

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

Join di 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 evento (vedi dichiarazione variabile per una definizione di "transitive join"). L'espressione non deve includere elementi aritmetici.

Ad esempio, supponendo che la regola utilizzi $e1, $e2 e $e3, le seguenti sezioni events sono valide.

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 la condizione di single join è una catena or, una funzione per il confronto di 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 di corrispondenza

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

• Specifica il significato di ogni variabile di corrispondenza nella sezione events.
• Specifica la durata di tempo da utilizzare per correlare gli eventi dopo la parola chiave over. Gli eventi al di fuori della durata 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.

• Il tempo massimo che puoi specificare è 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 è di 5 minuti. Gli eventi a più di 5 minuti di distanza non vengono 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. La finestra temporale specificata è di 1 ora. Gli eventi a più di un'ora di distanza 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 temporale specificata è di 2 minuti. Gli eventi a intervalli di più di 2 minuti non vengono 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 del valore zero nella sezione della corrispondenza

Rules Engine filtra in modo implicito i valori zero per tutti i segnaposto utilizzati nella sezione di corrispondenza ("" per la 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 pari a 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 pari a 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 disabilitare il filtro implicito dei valori zero, puoi utilizzare l'opzione allow_zero_values nella sezione opzioni.

Finestra 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 è diviso in un insieme di finestre di hop sovrapposte, ciascuna con la durata specificata nella sezione match. Gli eventi vengono quindi correlati all'interno di ciascun 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 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 gli 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 queste sequenze di eventi consiste nell'utilizzare le finestre scorrevoli. Le finestre scorrevoli con la durata specificata nella sezione match vengono generate all'inizio o alla fine con una variabile evento pivot specificata. Gli eventi sono quindi correlati all'interno di ciascuna 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 entro la durata della finestra scorrevole successiva all'evento e2.

Specifica finestre scorrevoli nella sezione match di una regola nel seguente modo:

<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 le finestre scorrevoli.

Nota: è noto che l'utilizzo di finestre scorrevoli al posto delle finestre di hop riduce le prestazioni. Google consiglia di utilizzare le finestre scorrevoli solo in casi specifici, ad esempio quando l'ordine degli eventi è assolutamente necessario o durante la ricerca della non 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 più eventi. Se una delle regole rientra in questa categoria, Google consiglia una delle seguenti soluzioni alternative:

• Converti la regola in modo da 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 anziché 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 a virgola mobile. Se compilato, il risk_score verrà mostrato nella vista Enterprise Insights per gli avvisi provenienti dai rilevamenti di 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 è impostato su 40.
• Se la regola non è configurata per generare un avviso, il valore di $risk_score è impostato su 15.

Il valore di $risk_score è archiviato nel campo UDM security_result.risk_score.

Tipi di dati delle variabili risultati

Ogni variabile 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 valori 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 l'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")

• funzioni che restituiscono un valore booleano, ad esempio:

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

• cercare in un elenco di riferimenti, ad esempio:

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

• e il confronto tra 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. Supportiamo numeri interi, valori in virgola mobile e stringhe.

Puoi omettere ELSE_CLAUSE se il tipo di dati è un numero intero o un 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 è stringa o se THEN_CLAUSE è una variabile segnaposto o una variabile risultato.

Operazioni matematiche

Puoi utilizzare operazioni matematiche per calcolare un tipo di dati con valori interi o fluttuanti nelle sezioni outcomee events di una regola. Chronicle supporta addizione, sottrazione, moltiplicazione, divisione e modulo 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, purché ogni operando e l'intera espressione aritmetica siano correttamente aggregate (vedi Aggregazioni):

• Campi evento numerici
• Variabili segnaposto numeriche definite nella sezione events
• Variabili di risultato numeriche definite nella sezione outcome
• Funzioni che restituiscono numeri interi o numeri in virgola mobile
• Aggregazioni che restituiscono numeri interi o numeri in virgola mobile

Il modulo non è consentito per i valori in virgola mobile.

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 singolo evento:

// 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 risultato nelle espressioni di assegnazione dei risultati

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

Nell'esempio seguente, la variabile risultato $risk_score ricava il suo valore dalla variabile 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 risultato possono essere utilizzate in qualsiasi tipo di espressione sul lato destro di un'assegnazione dei risultati, ad eccezione delle seguenti espressioni:

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

Aggregazioni

I campi di eventi ripetuti non sono valori scalari. 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. È un valore non scalabile. Invece, la variabile del campo evento $e.principal.hostname non è un campo ripetuto e ha solo 1 valore (ovvero un valore scalare).

Analogamente, sia i campi di eventi non ripetuti sia quelli di eventi ripetuti utilizzati nella sezione dei risultati di una regola con una finestra di corrispondenza non sono valori scalari. Ad esempio, la seguente regola raggruppa gli eventi utilizzando una sezione di corrispondenza e fa riferimento a un campo di eventi non ripetuti nella sezione dei risultati:

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

Qualsiasi finestra di 5 minuti su cui viene eseguita la regola potrebbe contenere zero, uno o più eventi. La sezione dei risultati funziona su tutti gli eventi in una finestra di corrispondenza. Qualsiasi variabile del campo evento a cui viene fatto riferimento nella sezione dei risultati può puntare a zero, uno o più valori del campo per ogni evento nella finestra di corrispondenza. Nella regola precedente, se una finestra di 5 minuti contiene 5 eventi $e, $e.principal.hostname nella sezione dei risultati rimanda a 5 nomi host diversi. 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 restituire un singolo valore scalare, qualsiasi valore non scalare da cui dipende un'assegnazione di risultato deve essere aggregato per generare un singolo valore scalare. In una sezione dei risultati, i seguenti sono valori non scalari e devono essere aggregati:

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

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 darà il valore aggregato e pertanto non è necessaria. L'eccezione è l'aggregazione array(), che può essere utilizzata per convertire un valore scalare in un array.

Le variabili risultato 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 valore massimo rispetto a tutti i valori possibili. Funziona solo con numeri interi e numeri in virgola mobile.
• min(): restituisce il valore minimo rispetto a tutti i valori possibili. Funziona solo con numeri interi e numeri in virgola mobile.
• sum(): restituisce la somma di tutti i valori possibili. Funziona solo con numeri interi e numeri in virgola mobile.
• count_distinct(): raccoglie tutti i valori possibili, quindi 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, poi restituisce un elenco di questi valori. L'elenco dei valori distinti verrà troncato in 25 elementi casuali. Viene applicata prima la deduplicazione per ottenere un elenco distinto, poi il troncamento.
• array(): si comporta come array_distinct(), ma restituisce un elenco non distinto di valori. Inoltre, l'elenco di valori viene troncato in 25 elementi casuali.

La funzione di aggregazione è importante quando una regola include una sezione condition che specifica che devono esistere più eventi, poiché la funzione di aggregazione funzionerà 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 della condizione richiede che sia presente più di un event per ogni rilevamento, le funzioni di aggregazione funzioneranno 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"

Quindi 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 che non era già stata 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ò utilizzare un campo evento che non è stato 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 già correlate nella sezione events. Le correlazioni si verificano quando due campi evento di variabili evento diverse vengono uguali.

Puoi trovare un esempio utilizzando la sezione dei risultati in Panoramica di YARA-L 2.0. Per maggiori dettagli sulla deduplicazione del rilevamento con la sezione dei risultati, consulta Creare analisi sensibili al contesto.

Sintassi della sezione delle condizioni

• specifica una condizione di corrispondenza per gli eventi e i segnaposto definiti nella sezione events. Per maggiori dettagli, consulta la sezione Condizionali di eventi e segnaposto riportata di seguito.
• (Facoltativo) utilizza 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.

Conteggio carattere

Il carattere # è un carattere speciale nella sezione condition. Se viene utilizzato prima di qualsiasi nome di 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 una volta.

Carattere valore

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

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

Condizionali di eventi e segnaposto

Elenca qui i predicati delle condizioni per gli eventi e le variabili segnaposto, uniti alla parola chiave and o or. La parola chiave and può essere utilizzata in qualsiasi condizione, ma la parola chiave or può essere utilizzata solo quando la regola ha una sola 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 nei condizionali di evento e segnaposto.

Condizioni limitate e illimitate

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

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

Le seguenti condizioni sono illimitate. Consentono di non esistere la variabile evento associata, ovvero è possibile che nessuna occorrenza dell'evento venga mostrata in un rilevamento e qualsiasi riferimento ai campi della variabile evento restituirà un valore pari a zero. Puoi usare condizioni illimitate per rilevare l'assenza di un evento in un determinato periodo di tempo. ad esempio un evento di minaccia senza un evento di mitigazione in una finestra di 10 minuti. Le regole che utilizzano condizioni senza limitazioni 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 non esistenti, 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 in ritardo.

Requisiti per l'assenza

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

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

Considera la seguente regola se la sezione della condizione è 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 <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 è vincolato.
• $u1 and !$u2 and $e1 and !$e2
  • $e2 è illimitato, il che è consentito perché è associato a $u1, che è limitato. Se $e2 non fosse associato a $u1, non sarebbe valido.
• #port > 50 and #ip = 0
  • Nella sezione delle condizioni non sono presenti eventi ed entità UDM; 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 non limitata. Tuttavia, le condizioni limitate sono più forti delle condizioni illimitate. Poiché $port è assegnato a $u1 e #port > 50 è una condizione limitata, $u1 è ancora vincolato.

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

• $u1 and $e1
  • Ogni evento e entità UDM che compaiono nella sezione Eventi devono apparire nella sezione Condizioni (o avere un segnaposto assegnato 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 almeno un evento UDM è vincolato.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • La parola chiave or non è supportata in 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
  • not parola chiave 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 non sono limitate. Ciò significa che nessuno degli eventi UDM è limitato e impedisce la compilazione della regola.

Nota: non utilizzare una variabile match nella sezione condition. È 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. Affinché venga restituito un valore della variabile match, deve esistere almeno un evento che lo contenga.

Nota: se utilizzi una finestra scorrevole, la variabile evento pivot deve essere coinvolta in almeno una condizione limitata.

Condizionali dei risultati

Elenca qui 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 in base al tipo di variabile risultato:

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

  $risk_score > 10

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

  $risk_score <= 5.5

• string: confronta con un valore letterale stringa = 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 nella 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 una condizione condizionale dei risultati in una regola che ha una sezione di corrispondenza, la regola verrà classificata come regola multi-evento per la quota della regola. Consulta gli articoli Regola per evento singolo e Regola per più eventi per ulteriori informazioni sulle classificazioni di eventi singoli e multipli.

Sintassi della sezione 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 un nome di opzione predefinito 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 l'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 opzioni della regola: allow_zero_values = true. In questo modo, impedisci alla regola di filtrare implicitamente i valori zero dei segnaposto utilizzati nella sezione della corrispondenza, come descritto in Gestione dei valori zero nella sezione della corrispondenza.

Espressioni booleane

Le espressioni booleane sono espressioni di tipo booleano.

Confronti

Per un'espressione binaria semplice da utilizzare come condizione, utilizza la sintassi seguente:

• <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. Queste 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 degli eventi. Per ulteriori dettagli, consulta la sezione Elenchi di riferimento.

Espressioni logiche

Puoi utilizzare gli operatori logici and e or logici nella sezione events, come illustrato 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 o (b e c)" quando gli operatori or e and sono definiti esplicitamente nell'espressione.

Se non è stato definito esplicitamente un operatore, nella sezione events i predicati vengono uniti utilizzando l'operatore and.

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

Ad esempio, considera le seguenti espressioni di confronto in cui or viene definito esplicitamente. È implicito l'operatore and.

$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 è definito esplicitamente, i predicati che circondano or vengono raggruppati e valutati per primi. L'ultimo predicato, $e2.field = "bar", viene unito implicitamente utilizzando and. Di conseguenza, 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 Chronicle. Contatta il tuo rappresentante di Chronicle 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 il rendimento (usa l'operatore anziché gli elenchi di riferimento).

Nell'esempio seguente, "USER_UNCATEGORIZED" e "USER_RESOURCE_DELETION" corrispondono a 15000 e 15014, quindi 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

Quando esiste un'espressione di confronto tra valori di stringa o un'espressione regolare, puoi aggiungere nocase alla fine dell'espressione per ignorare l'uso delle 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

Non può essere utilizzato se un tipo di campo è un valore enumerato. Gli esempi seguenti 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 Unified Data Model (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 sui campi ripetuti:

1. Modificato
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 insieme soddisfa la condizione.

• event_original soddisfa any $e.principal.ip = "192.0.2.1".
• event_original non riesce a risolvere 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 insieme 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 risolvere 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 negato.

Ad esempio:

• not all $e.principal.ip = "192.168.12.16" controlla se non tutti gli indirizzi IP corrispondono a 192.168.12.16, il che significa che la regola verifica 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 a 192.168.12.16, il che significa che la regola verifica 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).
• Non è possibile usare any e all per unire due campi ripetuti. Ad esempio, any $e1.principal.ip = $e2.principal.ip non è valido.
• Gli operatori any e all non sono supportati con l'espressione dell'elenco di riferimento.

Espressioni non modificate

Con le espressioni non modificate, ogni elemento nel campo ripetuto viene considerato singolarmente. Se il campo ripetuto di un evento contiene n elementi, la regola viene applicata a n copie dell'evento, in cui ogni copia contiene 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 il testo di un qualsiasi evento soddisfa tutte le condizioni non modificate nel campo ripetuto, l'evento nel suo insieme soddisfa tutte le condizioni. Ciò significa che se hai più condizioni in un campo ripetuto, la copia dell'evento deve soddisfare tutte le condizioni. 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 rispetto al 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é non esiste una copia dell'evento in $e.principal.ip che soddisfi tutti i predicati dell'evento.

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

Le espressioni modificate nei campi ripetuti sono compatibili con le espressioni non modificate sui campi ripetuti, poiché l'elenco degli elementi è lo stesso per ogni copia di eventi. Considera la seguente regola:

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

La regola viene applicata alle seguenti copie:

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

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

Un altro modo per considerare questi tipi di espressioni è:

• Le espressioni su campi ripetuti che utilizzano any o all sono presenti nell'elenco in event_original.
• Le espressioni nei campi ripetuti che non utilizzano any o all vengono eseguite su singoli eventi event_copy_n.

Campi e segnaposto ripetuti

I campi ripetuti funzionano con le assegnazioni di segnaposto. Analogamente alle espressioni non modificate sui campi ripetuti, viene creata una copia dell'evento per ogni elemento. Utilizzando lo stesso esempio di event_copy, il segnaposto prende il valore del valore del campo ripetuto del event_copy_n, per ogni copia dell'evento, dove n è il numero della copia dell'evento. Se il segnaposto viene utilizzato nella sezione delle corrispondenze, questo può comportare più corrispondenze.

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

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

  match:
    $host over 5m

  condition:
    $e
}

L'esempio seguente genera tre corrispondenze. Il segnaposto $ip ha valori diversi per ognuna delle diverse copie event_copy_n. Il raggruppamento viene eseguito su $ip poiché si trova nella sezione delle corrispondenze. Pertanto, ottieni tre corrispondenze in cui ogni corrispondenza ha un valore diverso per la variabile di corrispondenza $ip. Ogni corrispondenza include 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 assegni un campo ripetuto a una variabile segnaposto o unisciti a 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 soddisfano le sezioni precedenti.

Considera la seguente regola:

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

  match:
    $host over 5m

  outcome:
    $o = array_distinct($ip)

  condition:
    $e
}

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

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

La sezione di corrispondenza raggruppa quindi in base alle variabili di corrispondenza e la sezione dei risultati eseguirà l'aggregazione su ciascun gruppo:

$host	$	€ 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 semplicemente l'esistenza di $e, la riga precedente genererà un singolo rilevamento.

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

Indicizzazione degli array

Puoi eseguire l'indicizzazione di array su campi ripetuti. Per accedere all'n-esima elemento di campo ripetuto, utilizza la sintassi dell'elenco standard (gli elementi sono indicizzati 0). Un elemento fuori intervallo restituisce il valore predefinito.

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

Vincoli:

• Un indice deve essere un valore letterale intero non negativo. Ad esempio, $e.principal.ip[-1] non è valido.
• I valori che hanno 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 dell'array. Ad esempio, $e.intermediary.ip[0] non è valido perché intermediary e ip sono entrambi campi ripetuti, ma esiste un indice solo per ip.

Messaggi ripetuti

Quando un campo message viene ripetuto, un effetto imprevisto è la riduzione della 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 su campi ripetuti, viene creata una copia temporanea dell'evento per ogni elemento del campo ripetuto. Considera la seguente regola:

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

La regola viene applicata alle seguenti copie:

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	""	"marco"

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

Messaggi ripetuti e indicizzazione di array

Quando si utilizza l'indicizzazione di array con espressioni non modificate su campi di messaggi ripetuti, si può verificare un altro comportamento imprevisto. Considera la seguente regola di esempio che utilizza l'indicizzazione dell'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[1].nomehost
event_copy_1	"192.0.2.1"	"marco"
event_copy_2	"192.0.2.2"	"marco"
event_copy_3	"192.0.2.3"	"marco"
event_copy_4	""	"marco"

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

Questo può causare comportamenti imprevisti perché la regola repeated_message_1 non disponeva dell'indicizzazione dell'array e non ha prodotto corrispondenze, mentre la regola repeated_message_2 ha utilizzato l'indicizzazione dell'array e ha generato una corrispondenza.

Commenti

Definisci i commenti con due barre (// comment) o i commenti su più righe preceduti da barra/asterisco (/* comment */), come faresti in C.

Valori letterali

Sono supportati numeri interi non negativi, valori letterali in virgola mobile, stringhe, valori letterali booleani ed espressioni regolari.

Valori letterali stringa ed espressioni regolari

È possibile utilizzare uno qualsiasi dei seguenti caratteri di virgolette per racchiudere le stringhe in YARA-L 2.0. Tuttavia, il testo citato viene interpretato in modo diverso a seconda di quale utilizzi.

1. Virgolette doppie ("): da utilizzare per stringhe normali. Deve includere caratteri di escape.
   Ad esempio: "ciao\tmondo",\t viene interpretato come una scheda

2. Tra virgolette (`) per interpretare letteralmente tutti i caratteri.
   Ad esempio: "hello\tworld" —\t non viene interpretato come una scheda

Per le espressioni regolari, hai due possibilità.

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

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

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/

Google consiglia di utilizzare le virgolette inglesi per le stringhe nelle espressioni regolari per facilitare la leggibilità.

Operatori

In YARA-L puoi utilizzare i seguenti operatori:

Operatore	Description
=	uguale/dichiarazione
!=	non uguale
<	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 i campi nome, origine evento e evento. Le origini consentite sono udm (per gli eventi normalizzati) e graph (per gli eventi entità). Se l'origine viene omessa, udm viene impostato come sorgente predefinita. I campi evento sono rappresentati da una catena di .<field name> (ad esempio, $e.field1.field2). Le catene di campi evento 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 il significato di ogni variabile di corrispondenza nella sezione events.

• Variabili segnaposto: dichiara e definisci le variabili 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 riuscirà perché $var non è associato a una variabile evento: $e.field != $var

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

Keywords

Le parole chiave in 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, match, matchminsumarrayarray_distinctcountcount_distinctisnull

Maps

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

Strutture ed etichette

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

Per cercare una coppia chiave-valore specifica sia in struct che in Label, 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 della 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 seguenti casi.

Combinazione di any o all parole chiave con una mappa

Ad esempio, non è supportato quanto segue: 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 alle chiavi i cui valori sono altri tipi primitivi come i numeri interi.

Gestione valori duplicati

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

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à della chiave. Per convenzione, una mappa dovrebbe avere chiavi univoche, quindi Chronicle 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 da predecesso.

  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"] restituirebbe 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 supportate da Chronicle in Detection Engine.

Queste funzioni possono essere utilizzate nelle seguenti aree di una regola:

• Sezione events.
• BOOL_CLAUSE di un condizionale nella sezione dei risultati.

arrays.length

arrays.length(repeatedField)

Descrizione

Restituisce il numero di elementi del campo ripetuti.

Tipi di dati dei parametri

LIST

Tipo restituito

NUMBER

Esempi di codice

Esempio 1

Restituisce il numero di elementi del campo ripetuti.

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

Esempio 2

Se lungo il percorso sono presenti più campi ripetuti, viene restituito il numero totale di elementi dei campi ripetuti.

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

math.abs

math.abs(numericExpression)

Descrizione

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

Tipi di dati dei parametri

NUMBER

Tipo restituito

NUMBER

Esempi di codice

Esempio 1

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

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

metrics

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

Per ulteriori informazioni, consulta la sezione Metriche YARA-L.

net.ip_in_range_cidr

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 IP UDM e un intervallo CIDR. YARA-L può gestire sia i campi singolari sia quelli ripetuti per l'indirizzo IP.

Per eseguire ricerche in un intervallo di indirizzi IP, specifica un campo UDM ip e un intervallo CIDR (Classless Inter-Domain Routing). YARA-L può gestire sia i campi singolari sia quelli ripetuti per l'indirizzo IP.

Tipi di dati dei parametri

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 una regola di esempio che utilizza l'istruzione net.ip_in_range_cidr(), consulta la regola di esempio in Evento singolo nell'intervallo di indirizzi IP.

re.regex

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

• Utilizzo della sintassi YARA - Correlata agli eventi. Di seguito è riportata una rappresentazione generica di questa sintassi: none $e.field = /regex/
• Utilizzo della sintassi YARA-L - come una funzione che prende i seguenti parametri:
  • Campo a cui è applicata l'espressione regolare.
  • Espressione regolare specificata come stringa. Puoi utilizzare il modificatore nocase dopo le stringhe per indicare che la ricerca deve ignorare le lettere maiuscole. Di seguito è riportata una rappresentazione generica di questa sintassi: none 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 trovare la corrispondenza esatta o solo un prefisso o un suffisso, includi i caratteri di ancoraggio ^ (iniziale) e $ (finali) 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.*/.

Tipi di dati dei parametri

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

re.capture(stringText, regex)

Descrizione

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

Questa funzione accetta due argomenti:

• stringText: la stringa originale da ricercare.
• 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 di acquisizione, la funzione restituisce la prima intera sottostringa corrispondente. Se l'espressione regolare contiene un gruppo di acquisizione, restituisce la prima sottostringa corrispondente. La definizione di due o più gruppi di acquisizione restituisce un errore di compilazione.

Tipi di dati dei parametri

STRING, STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

In questo esempio, se $e.principal.hostname contiene "aaa1bbaa2", quanto segue è vero, perché la funzione restituisce la prima istanza. Questo esempio non ha 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

re.replace(stringText, replaceRegex, replacementText)

Descrizione

Esegue la sostituzione di un'espressione regolare.

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 da quella originale stringText, dove tutte le sottostringhe che corrispondono al pattern in replaceRegex vengono sostituite con il valore in replacementText. Puoi utilizzare cifre con carattere di escape barra rovesciata (da \1 a \9) all'interno di replacementText per inserire il testo corrispondente al gruppo tra parentesi corrispondente nel pattern replaceRegex. Usa \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 dei parametri

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, quindi restituisce il risultato. Osserva l'uso delle funzioni nidificate.

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

Esempio 2

Questo esempio utilizza cifre con carattere di escape barra rovesciato nell'argomento replacementText per fare riferimento alle corrispondenze al 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

Tieni presente i seguenti casi quando hai a che fare con stringhe vuote e re.replace():

Utilizzo di una 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")

strings.base64_decode

strings.base64_decode(encodedString)

Descrizione

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

Questa funzione prende una stringa codificata in Base64 come argomento. Se encodedString non è una stringa valida con codifica Base64, la funzione restituisce encodedString senza modifiche.

Tipi di dati dei parametri

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

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

strings.coalesce

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 hanno come risultato 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 degli argomenti sono campi evento, gli attributi devono provenire dallo stesso evento.

Tipi di dati dei parametri

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente include le 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 null dell'evento $e con i valori nell'elenco di riferimento ip_watchlist. L'ordine in cui gli argomenti vengono uniti in questa chiamata è lo stesso dell'ordine in cui sono elencati nella condizione della regola:

1. $e.principal.ip viene valutato per primo.
2. Successivamente viene valutata la metrica $e.src.ip.
3. Successivamente viene valutata la metrica $e.target.ip.
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 all'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

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

Descrizione

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

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

Tipi di dati dei parametri

STRING, FLOAT, INT

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente include una variabile di tipo stringa e una variabile di tipo intero come argomenti. Entrambi principal.hostname e 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 un valore letterale stringa 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 a virgola mobile come argomenti. Se rappresentati come stringhe, i valori in virgola mobile che sono numeri interi vengono formattati senza il punto decimale (ad esempio, 1,0 è rappresentato come "1"). Inoltre, i valori in virgola mobile che superano i sedici cifre decimali vengono troncati al sedicesimo posto 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 con valori interi e un valore letterale a 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

strings.to_lower(stringText)

Descrizione

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

Tipi di dati dei parametri

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

strings.to_upper(stringText)

Descrizione

Questa funzione accetta una stringa di input e restituisce una stringa dopo aver modificato tutti i caratteri in maiuscolo

Tipi di dati dei parametri

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

timestamp.current_seconds()

Descrizione

Restituisce un numero intero che rappresenta l'ora corrente in secondi Unix. Corrisponde approssimativamente al timestamp di rilevamento e si basa sul momento in cui viene eseguita la regola.

Tipi di dati dei parametri

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 attuali, quindi confrontandola utilizzando un operatore maggiore di.

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

timestamp.get_date

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 il timestamp.

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

Ecco alcuni esempi di identificatori di fuso orario validi, che puoi passare come secondo argomento alle funzioni di estrazione temporale:

"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 dei parametri

INT, STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è stato omesso, quindi per impostazione predefinita è "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

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 dopo l'epoca di Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente questo valore.
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando le letterali stringa. Le opzioni sono:
  • Il nome del database TZ, ad esempio "America/Los_Angeles". Per ulteriori informazioni, consulta la colonna"Nome database TZ" di questa pagina.
  • La differenza del fuso orario rispetto al fuso orario UTC, nel formato (+|-)H[H][:M[M]], ad esempio "-08:00".

Ecco alcuni esempi di identificatori time_zone validi, che puoi passare come secondo argomento alle funzioni di estrazione temporale:

"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 dei parametri

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è stato omesso, quindi per impostazione predefinita è "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

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 dopo l'epoca di Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente questo valore.
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando le letterali stringa. Le opzioni sono:
  • Il nome del database TZ, ad esempio "America/Los_Angeles". Per ulteriori informazioni, consulta la colonna"Nome database TZ" di questa pagina.
  • La differenza del fuso orario rispetto al fuso orario UTC, nel formato (+|-)H[H][:M[M]], ad esempio "-08:00".

Ecco alcuni esempi di identificatori time_zone validi, che puoi passare come secondo argomento alle funzioni di estrazione temporale:

"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 dei parametri

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è stato omesso, quindi per impostazione predefinita è "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

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 a partire da domenica. Ad esempio, 1 = domenica e 2 = lunedì.

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

Ecco alcuni esempi di identificatori di fuso orario validi, che puoi passare come secondo argomento alle funzioni di estrazione temporale:

"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 dei parametri

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è stato omesso, quindi per impostazione predefinita è "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_week

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 precedenti alla prima domenica dell'anno rientrano nella settimana 0.

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

Ecco alcuni esempi di identificatori time_zone validi, che puoi passare come secondo argomento alle funzioni di estrazione temporale:

"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 dei parametri

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

In questo esempio, l'argomento time_zone è stato omesso, quindi per impostazione predefinita è "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

Assegnazione da funzione a 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, sono previste due limitazioni dall'assegnazione della funzione all'assegnazione di segnaposto:

1. Ogni segnaposto nella funzione per l'assegnazione di 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, l'esempio seguente 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, è possibile utilizzare più di un campo dello stesso evento negli argomenti delle chiamate 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

Per ulteriori informazioni sul comportamento degli elenchi di riferimento e sulla sintassi degli elenchi di riferimento, consulta la nostra pagina sugli elenchi di riferimento.

Puoi utilizzare gli elenchi di riferimento nelle sezioni events o outcome. Di seguito è riportata la sintassi per utilizzare i 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 usare l'operatore not e l'operatore nocase con gli elenchi di riferimento, come mostrato qui: ```none // Escludi gli eventi i cui nomi host corrispondono a sottostringhe in my_regex_list. non $e.principal.hostname nella regex %my_regex_list.

// I nomi host degli eventi devono corrispondere ad almeno una stringa in my_string_list (senza distinzione tra maiuscole e minuscole). $e.principal.hostname in %my_string_list nocase ```

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

Per motivi legati alle prestazioni, il motore di rilevamento limita l'utilizzo dell'elenco di riferimento.

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

Controllo del tipo

Chronicle esegue il controllo dei tipi in base alla sintassi YARA-L durante la creazione di regole nell'interfaccia. Gli errori di controllo del tipo visualizzati consentono di rivedere la regola in modo da garantire che funzioni come previsto.

Di seguito sono riportati 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 di regole multi-evento contengono esempi di eventi per fornire un contesto sugli eventi che hanno causato il rilevamento. Esiste un limite di massimo 10 esempi di evento per ogni variabile evento definita nella regola. Ad esempio, se una regola definisce 2 variabili evento, ogni rilevamento può avere fino a 20 esempi di eventi. Il limite si applica separatamente a ogni variabile evento. Se una variabile evento contiene due eventi applicabili in questo rilevamento e l'altra variabile evento contiene 15 eventi applicabili, il rilevamento risultante contiene 12 campioni di eventi (2 + 10).

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

Se vuoi maggiori informazioni sugli eventi che hanno causato il rilevamento, puoi utilizzare le aggregazioni nella sezione dei risultati per generare ulteriori informazioni nel rilevamento.

Se stai visualizzando i rilevamenti nell'interfaccia utente, puoi scaricare tutti gli esempi di eventi per un rilevamento. Per scoprire di più, vedi Scaricare gli eventi.