Sintassi del linguaggio YARA-L 2.0

Supportato in:

Google SecOps SIEM

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

Struttura della regola

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

1. meta
2. eventi
3. match (facoltativo)
4. outcome (facoltativo)
5. condizione
6. options (facoltativo)

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

Di seguito è 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 sezione meta

La sezione meta è composta da più righe, in cui ogni riga definisce una coppia chiave-valore. Una parte della chiave deve essere una stringa senza virgolette e 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 delle variabili evento
• Unioni di variabili evento

Dichiarazioni di variabili

Per le dichiarazioni delle variabili, utilizza la seguente sintassi:

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

Entrambi sono equivalenti, come mostrato negli esempi seguenti:

• $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 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

Sono equivalenti a:

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

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

Filtri delle variabili evento

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

Unioni 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 operazioni aritmetiche.

• In modo indiretto tramite una join transitiva che coinvolge solo un campo evento (vedi dichiarazione di variabili per una definizione di "join transitiva"). L'espressione non deve includere operazioni aritmetiche.

Ad esempio, supponendo che nella regola vengano utilizzati $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 l'unica condizione di join è una catena or, una funzione di confronto degli eventi o una combinazione di entrambe, il rendimento della regola potrebbe essere scarso.

Tuttavia, di seguito sono riportati 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 verificare le condizioni di corrispondenza. Questi campi vengono restituiti con ogni corrispondenza.

• Specifica cosa rappresenta ogni variabile di corrispondenza nella sezione events.
• Specifica la durata del 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 è 5 minuti. Gli eventi distanti più di 5 minuti non sono correlati e quindi 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 distanti 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. L'intervallo di tempo specificato è di 2 minuti. Gli eventi distanti 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 del valore zero nella sezione delle corrispondenze

Il motore delle regole filtra in modo implicito i valori zero per tutti i segnaposto utilizzati nella sezione di corrispondenza ("" per le stringhe, 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 è assegnato a una funzione, le regole non escludono 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 delle opzioni.

Finestra Hop

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

Ad esempio, per una regola eseguita nell'intervallo di tempo [1:00, 2:00], con una sezione match superiore a 30m, un possibile insieme di finestre di hop sovrapposte che possono essere generate è [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 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 è 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 vengono poi correlati all'interno di ogni finestra mobile. In questo modo è possibile cercare 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 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 della finestra mobile:

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

Consulta un esempio di regola con finestra a scorrimento.

Nota: l'utilizzo di finestre scorrevoli anziché finestre di hop comporta un rendimento più lento. Google consiglia di utilizzare le finestre scorrevoli solo per casi specifici, ad esempio quando l'ordine degli eventi è assolutamente necessario o quando si cerca l'assenza di eventi.

Google consiglia di non utilizzare le finestre scorrevoli per le regole a evento singolo, perché le finestre scorrevoli sono progettate per rilevare più eventi. Se una delle tue regole rientra in questa categoria, Google consiglia una delle seguenti soluzioni alternative:

• Converti la regola in modo che utilizzi più variabili evento e aggiorna la sezione della condizione se la regola richiede più di un'occorrenza dell'evento.
  • Se vuoi, puoi anche aggiungere filtri dei timestamp anziché utilizzare una finestra mobile. Ad esempio, $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
• Rimuovi la finestra scorrevole.

Sintassi della sezione relativa al risultato

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

Il nome dell'esito, $risk_score, è speciale. Se vuoi, puoi definire un risultato con questo nome, che deve essere di tipo intero o float. Se compilato, il valore risk_score verrà visualizzato nella visualizzazione Approfondimenti aziendali per gli avvisi provenienti dai rilevamenti delle regole.

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

• Se la regola è configurata per generare un avviso, $risk_score è impostato su 40.
• Se la regola non è configurata per generare un avviso, $risk_score viene impostato su 15.

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

Tipi di dati delle variabili di risultato

Ogni variabile di risultato può avere un tipo di dati diverso, che viene determinato dall'espressione utilizzata per calcolarla. Sono supportati i seguenti tipi di dati sugli esiti:

• integer
• floats
• string
• Elenchi di numeri interi
• elenchi di numeri decimali
• 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 CLAUSE_THEN, altrimenti restituisce ELSE_CLAUSE".

La clausola BOOL deve restituire un valore booleano. Un'espressione BOOL_CLAUSE ha 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 esito 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)

• cerca in un elenco di riferimento, ad esempio:

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

• Confronto di aggregazioni, ad esempio:

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

Le clausole THEN_CLAUSE ed ELSE_CLAUSE devono avere lo stesso tipo di dati. Sono supportati numeri interi, numeri con virgola mobile e stringhe.

Puoi omettere la clausola ELSE_CLAUSE se il tipo di dati è un numero intero o un numero decimale. Se omessa, la clausola ELSE_CLAUSE ha valore 0. Ad esempio:

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

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

Operazioni matematiche

Puoi utilizzare operazioni matematiche per calcolare il tipo di dati interi o con virgola mobile nelle sezioni outcomee events di una regola. Google Security Operations supporta l'addizione, la sottrazione, la moltiplicazione, la divisione e il modulo come operatori di primo livello in un calcolo.

Il seguente snippet è 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 ciascun operando e l'intera espressione aritmetica siano aggregati correttamente (vedi Aggregazioni):

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

Il modulo non è consentito sui valori float.

Variabili segnaposto nei risultati

Quando calcoli le variabili di esito, puoi utilizzare le variabili segnaposto definite nella sezione degli 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 esito nelle espressioni di assegnazione dell'esito

Le variabili di esito possono essere utilizzate per ricavare altre variabili di esito, in modo simile 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. Le variabili di esito devono essere definite prima di poter essere richiamate nel testo della regola. Se utilizzate in un'espressione di assegnazione, le variabili di esito non devono essere aggregate (vedi Aggregazioni).

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

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

Aggregazioni

I campi evento ripetuti sono valori non 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 scalare. La variabile del campo evento $e.principal.hostname non è un campo ripetuto e ha un solo valore (ovvero un valore scalare).

Analogamente, sia i campi evento non ripetuti sia i campi evento ripetuti utilizzati nella sezione relativa al risultato di una regola con una finestra di corrispondenza sono valori non scalari. Ad esempio, la seguente regola raggruppa gli eventi utilizzando una sezione di corrispondenza e fa riferimento a un campo evento non ripetuto nella sezione di esito:

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

Qualsiasi finestra di 5 minuti in cui viene eseguita la regola potrebbe contenere zero, uno o più eventi. La sezione relativa al risultato opera su tutti gli eventi in una finestra di corrispondenza. Qualsiasi variabile di campo evento a cui si fa riferimento nella sezione risultato 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 punta a 5 host name diversi. La variabile del campo evento $e.principal.hostname è quindi un valore non scalare nella sezione relativa al risultato di questa regola.

Poiché le variabili di esito devono sempre restituire un singolo valore scalare, qualsiasi valore non scalare da cui dipende un'assegnazione di esito deve essere aggregato per produrre un singolo valore scalare. In una sezione relativa ai risultati, i seguenti sono valori non scalari e devono essere aggregati:

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

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

Le variabili di esito vengono trattate come aggregazioni: non devono essere riaggregate quando vengono citate in un'altra assegnazione di esito.

Puoi utilizzare le seguenti funzioni di aggregazione:

• max(): restituisce il massimo di tutti i valori possibili. Funziona solo con numeri interi e con valori decimali.
• min(): restituisce il minimo tra tutti i valori possibili. Funziona solo con numeri interi e con valori decimali.
• sum(): restituisce la somma di tutti i valori possibili. Funziona solo con numeri interi e con valori decimali.
• 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 dei possibili valori.
• array_distinct(): raccoglie tutti i possibili valori distinti, quindi restituisce un elenco di questi valori. L'elenco dei valori distinti verrà troncato a 25 elementi casuali. Viene applicata prima la deduplica per ottenere un elenco distinto, poi la troncatura.
• array(): si comporta come array_distinct(), ma restituisce un elenco non distinto di valori. Inoltre, tronca l'elenco dei valori a 25 elementi casuali.
• period_start_for_max(): inizio del periodo di tempo in cui si è verificato il valore massimo elencato.
• period_start_for_min(): inizio del periodo di tempo in cui si è verificato il valore minimo elencato.

La funzione aggregata è importante quando una regola include una sezione condition che specifica che devono esistere più eventi, perché la funzione aggregata opererà 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 più di un event per ogni rilevamento, le funzioni aggregate opereranno 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 degli esiti 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 conoscere quando si utilizza la sezione relativa al risultato:

Altre note e limitazioni:

• La sezione outcome non può fare riferimento a una nuova variabile segnaposto che non sia 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 è già stata 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 che utilizza la sezione relativa al risultato in Panoramica del linguaggio YARA-L 2.0. Per informazioni dettagliate sul rilevamento dell'eliminazione delle duplicati con la sezione relativa al risultato, consulta Creare analisi sensibili al contesto.

Sintassi della sezione Condizione

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

Carattere di conteggio

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

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

Carattere del valore

Il carattere $ è un carattere speciale nella sezione condition. Se viene utilizzato prima del nome di una variabile di esito, rappresenta il valore di quell'esito.

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

Istruzioni condizionali per eventi e segnaposto

Elenca qui i predicati della condizione per gli eventi e le variabili segnaposto, uniti con la parola chiave and o or. La parola chiave and può essere utilizzata tra 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 nello 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
}

Un esempio non valido di utilizzo di or tra due condizioni su 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 criteri condizionali di eventi e segnaposto.

Condizioni con limiti e senza limiti

Le seguenti condizioni sono condizioni con limiti. Forzano l'esistenza della variabile dell'evento associata, il che significa che in ogni rilevamento deve essere visualizzata almeno un'occorrenza dell'evento.

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

Le seguenti condizioni sono condizioni senza limiti. Consentono di non associare la variabile evento, il che significa che è possibile che nessuna occorrenza di l'evento venga visualizzata in un rilevamento e che qualsiasi riferimento ai campi della variabile evento restituisca un valore pari a zero. Le condizioni illimitate possono essere utilizzate per rilevare la mancanza di un evento in un determinato periodo di tempo. Ad esempio, un evento di minaccia senza un evento di mitigazione in un intervallo di 10 minuti. Le regole che utilizzano 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 di non esistenza, il motore di rilevamento aggiunge un ritardo di 1 ora alla latenza prevista (in base alla frequenza di esecuzione della regola) per consentire l'arrivo dei dati in ritardo.

Requisiti per la non esistenza

Affinché una regola con esistenza non sia compilata, deve soddisfare i seguenti requisiti:

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

Prendi in considerazione la seguente regola con 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 è limitato.
• $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 della condizione non sono presenti eventi ed entità UDM; tuttavia, i segnaposto presenti coprono tutti gli eventi ed entità UDM.
  • $ip è assegnato sia a $u1 che a $u2 e #ip = 0 è una condizione illimitata. Tuttavia, le condizioni con limiti sono più stringenti di quelle senza limiti. Poiché $port è assegnato a $u1 e #port > 50 è una condizione con limiti, $u1 è ancora limitato.

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

• $u1 and $e1
  • Ogni evento ed entità UDM visualizzato nella sezione Eventi deve essere visualizzato anche nella sezione Condizione (o deve avere un segnaposto assegnato che viene visualizzato nella sezione Condizione).
• $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 che prevede che almeno un evento UDM sia limitato.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • La parola chiave or 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 di 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, causando l'errore di 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 per tutte le variabili event a cui è assegnata una variabile match. Si tratta di un errore semantico. Affinché un valore della variabile match venga restituito, deve esistere almeno un evento che contenga il valore.

Nota: in caso di utilizzo di una finestra mobile, la variabile evento pivot deve essere coinvolta in almeno una condizione con limiti.

Condizioni di risultato

Elenca qui i predicati della condizione per le variabili di risultato, uniti con la parola chiave and o or oppure preceduti dalla parola chiave not.

Specifica i condizionali di esito in modo diverso a seconda del tipo di variabile di esito:

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

  $risk_score > 10

• float: esegui il confronto con un valore letterale float 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 conditionals>, devi racchiudere l'intera sottosezione tra parentesi. Ad esempio, il seguente è valido: ($e1 or $e2) and $outcome > 0.

Classificazione delle regole

Se specifichi una condizione di esito in una regola che ha una sezione di corrispondenza, la regola verrà classificata come multi-evento per la quota di regole. Per saperne di più sulle classificazioni di eventi singoli e multipli, consulta Regola evento singolo e Regola evento multiplo.

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 è attivata 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, la regola impedirà di escludere implicitamente i valori zero dei segnaposto utilizzati nella sezione delle corrispondenze, come descritto nella sezione Gestione dei valori zero nella sezione delle corrispondenze.

Espressioni booleane

Le espressioni booleane sono espressioni di tipo booleano.

Confronti

Per un'espressione binaria da utilizzare 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 letterali, si tratta di 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 degli elenchi di riferimento

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

Espressioni logiche

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

• $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 dalla più alta alla più bassa è 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.

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

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

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

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

Questo esempio viene interpretato nel seguente modo:

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

Poiché or è definito in modo esplicito, i predicati che lo circondano vengono raggruppati e valutati per primi.or 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 in base alla complessità della regola e alla complessità dei dati nel tuo account Google Security Operations. Contatta il tuo rappresentante di Google Security Operations per informazioni sulle alternative a questo tipo di regola.

Tipi enumerati

Puoi utilizzare gli operatori con tipi elencati. Può essere applicato alle regole per semplificare e ottimizzare (utilizza l'operatore anziché gli elenchi di riferimento) il rendimento.

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 di eventi:

• USER_RESOURCE_DELETION
• USER_RESOURCE_UPDATE_CONTENT
• USER_RESOURCE_UPDATE_PERMISSIONS
• USER_STATS
• USER_UNCATEGORIZED

Modificatore Nocase

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

Questo non può essere utilizzato 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, il che indica 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 sezioni seguenti 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 va a buon fine 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 va a buon fine 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 controlla 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 controlla che nessun indirizzo IP corrisponda a 192.168.12.16.

Limitazioni:

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

Espressioni non modificate

Con le espressioni non modificate, ogni elemento del 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 transitorie e non vengono archiviate.

La regola viene applicata alle seguenti copie:

copia 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 qualsiasi copia dell'evento soddisfa tutte le condizioni non modificate nel campo ripetuto, l'evento nel suo complesso soddisfa tutte le condizioni. Ciò significa che se hai più condizioni per un campo ripetuto, la copia dell'evento deve soddisfarne 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 degli eventi:

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

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

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

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

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

La regola viene applicata alle seguenti copie:

copia 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 complesso corrisponderebbe.

Un altro modo per considerare questi tipi di espressioni è:

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

Campi e segnaposto ripetuti

I campi ripetuti funzionano con le assegnazioni di segnaposto. Come per le espressioni non modificate nei campi ripetuti, viene creata una copia dell'evento per ogni elemento. Utilizzando lo stesso esempio di event_copy, il segnaposto assume il valore del valore del campo ripetuto di 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, possono verificarsi 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 nella regola. I campioni 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. Pertanto, ottieni tre corrispondenze in cui ogni corrispondenza ha un valore diverso per la variabile di corrispondenza $ip. Ogni corrispondenza ha lo stesso sample di eventi: 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 per assegnare un campo ripetuto a una variabile segnaposto o per eseguire l'unione con un campo di un altro evento. Ad esempio, any $e.principal.ip = $ip non è valido.

Risultati utilizzando i segnaposto assegnati ai campi ripetuti

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

Considera la seguente regola:

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

  match:
    $host over 5m

  outcome:
    $o = array_distinct($ip)

  condition:
    $e
}

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

copia 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 escluderà quindi le righe che non corrispondono ai filtri:

copia evento	$ip	$host	$e
event_copy_1	"192.0.2.1"	"host"	event_id
event_copy_2	"192.0.2.2"	"host"	event_id

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

La sezione delle corrispondenze raggruppa in base alle variabili di corrispondenza e la sezione dei risultati esegue l'aggregazione su ciascun gruppo:

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

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

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

$o non contiene tutti gli elementi di $e.principal.ip perché non tutti gli elementi soddisfano tutte le condizioni nella sezione degli eventi. Tuttavia, tutti gli elementi di e.principal.ip verranno visualizzati nel SampleEvent perché il SampleEvent utilizza event_original.

Indicizzazione di array

Puoi eseguire l'indicizzazione dell'array sui campi ripetuti. Per accedere all'elemento del campo ripetuto n-esimo, utilizza la sintassi dell'elenco standard (gli elementi sono indicizzati da 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, il valore restituito è true.

Limitazioni:

• Un indice deve essere un valore letterale intero non negativo. Ad esempio, $e.principal.ip[-1] non è valido.
• I valori di tipo int (ad esempio un segnaposto impostato su int) non vengono conteggiati.
• L'indice dell'array non può essere combinato con any o all. Ad esempio, any $e.intermediary.ip[0] non è valido.
• L'indice dell'array non può essere combinato 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'indice 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 indesiderato è la riduzione della probabilità di una corrispondenza. Questo è illustrato negli esempi che seguono.

Considera il seguente evento:

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

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

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

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

La regola viene applicata alle seguenti copie:

copia 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 di array

Un altro comportamento imprevisto può verificarsi quando si utilizza l'indice dell'array con espressioni non modificate su campi di messaggi ripetuti. Considera la seguente regola di esempio che utilizza l'indice 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 evento	about.ip	about[1].hostname
event_copy_1	"192.0.2.1"	"bob"
event_copy_2	"192.0.2.2"	"bob"
event_copy_3	"192.0.2.3"	"bob"
event_copy_4	""	"bob"

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

Ciò può comportare un comportamento imprevisto perché la regola repeated_message_1 non aveva l'indice dell'array e non ha prodotto corrispondenze, mentre la regola repeated_message_2 utilizzava l'indice dell'array e ha prodotto una corrispondenza.

Commenti

Indica i commenti con due barre (// comment) o i commenti su più righe con barre e asterischi (/* comment */), come faresti in C.

Valori letterali

Sono supportati numeri interi e valori decimali non negativi, stringhe, valori booleani e letterali di espressioni regolari.

Letterali di stringhe ed espressioni regolari

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

1. Virgolette doppie ("): da utilizzare per le stringhe normali. Devono includere i caratteri di escape.
   Ad esempio: "ciao\tmondo" -\t viene interpretato come tabulazione

2. Chiavi basse (`): da utilizzare per interpretare tutti i caratteri in modo letterale.
   Ad esempio: "ciao\tmondo" -\t non viene interpretato come tabulazione

Per le espressioni regolari, hai due opzioni.

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

Quando utilizzi la funzione re.regex(), puoi anche utilizzare i valori letterali di stringa come valori letterali di espressioni regolari. Tieni presente che per i valori letterali stringa con virgolette doppie, devi eseguire l'escape dei caratteri barra rovesciata con altri caratteri barra rovesciata, il che può sembrare spiacevole.

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 facilitare la leggibilità, Google consiglia di utilizzare i caratteri di virgolette inverse per le stringhe nelle espressioni regolari.

Operatori

In YARA-L puoi utilizzare i seguenti operatori:

Operatore	Descrizione
=	uguale/dichiarazione
!=	non uguale
<	minore di
<=	minore o uguale
>	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. Le variabili evento vengono identificate utilizzando un nome, un'origine evento e i campi evento. Le origini consentite sono udm (per gli eventi normalizzati) e graph (per gli eventi delle entità). Se l'origine viene omessa, viene impostata come predefinita udm. I campi evento sono rappresentati come una catena di .<nome campo> (ad esempio $e.field1.field2). Le catene di campi evento iniziano sempre dall'origine di primo livello (UDM o entità).

• Variabili di corrispondenza: da dichiarare 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 delle variabili di corrispondenza. Specifica cosa rappresenta ogni 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 andrà a buon fine perché $var non è associato a una variabile evento: $e.field != $var

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

Parole chiave

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 entrare in conflitto con le parole chiave. Ad esempio, $AND o $outcome non è valido.

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, min, sum, array, array_distinct, count, count_distinct, is e null.

Maps

YARA-L supporta l'accesso alla mappa per Structs e Labels.

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 della mappa standard:

// 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.

Casi supportati

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"])

Assegnare un valore della 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"]

Casi non supportati

Le mappe non sono supportate nei seguenti casi.

Combinare le parole chiave any o all 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 di 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 di altri tipi primitivi, come gli interi.

Gestione dei valori duplicati

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

Questo può accadere in uno dei seguenti casi:

• Un'etichetta ha una chiave duplicata.

  La struttura dell'etichetta rappresenta una mappa, ma non impone l'unicità delle chiavi. Per convenzione, una mappa deve avere chiavi univoche, pertanto Google Security Operations non consiglia di compilare un'etichetta con chiavi duplicate.

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

  // 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 di un antenato.

  Un campo ripetuto potrebbe contenere un'etichetta come campo secondario. Due voci diverse nel campo ripetuto di primo livello potrebbero contenere etichette con 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 che puoi utilizzare nelle regole e nella ricerca dell'engine di rilevamento.

Nota: l'utilizzo della variabile evento $e è facoltativo quando YARA-L viene utilizzato nella ricerca. Sia principal.hostname che $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 una condizione nella sezione Risultato.

arrays.concat

Supportato in:

Regole Ricerca

arrays.concat(string_array, string_array)

Descrizione

Restituisce un nuovo array di stringhe copiando gli elementi dagli array di stringhe originali.

Tipi di dati Param

ARRAY_STRINGS, ARRAY_STRINGS

Tipo restituito

ARRAY_STRINGS

Esempi di codice

Esempio 1

L'esempio seguente concatena due diversi array di stringhe.

arrays.concat(["test1", "test2"], ["test3"]) = ["test1", "test2", "test3"]

Esempio 2

L'esempio seguente concatena gli array con una stringa vuota.

arrays.concat([""], [""]) = ["", ""]

Esempio 3

L'esempio seguente concatena array vuoti.

arrays.concat([], []) = []

arrays.join_string

Supportato in:

Regole Ricerca

arrays.join_string(array_of_strings, optional_delimiter)

Descrizione

Converte un array di stringhe in una singola stringa separata dal parametro facoltativo. Se non viene fornito alcun delimitatore, viene utilizzata la stringa vuota.

Tipi di dati Param

ARRAY_STRINGS, STRING

Tipo restituito

STRING

Esempi di codice

Ecco alcuni esempi di utilizzo della funzione:

Esempio 1

Questo esempio unisce un array con elementi non null e un delimitatore.

arrays.join_string(["foo", "bar"], ",") = "foo,bar"

Esempio 2

Questo esempio unisce un array con un elemento nullo e un delimitatore.

arrays.join_string(["foo", NULL, "bar"], ",") = "foo,bar"

Esempio 3

Questo esempio unisce un array con elementi non null e senza delimitatore.

arrays.join_string(["foo", "bar"]) = "foobar"

arrays.length

Supportato in:

Regole Ricerca

arrays.length(repeatedField)

Descrizione

Restituisce il numero di elementi di campo ripetuti.

Tipi di dati Param

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 nel percorso sono presenti più campi ripetuti, restituisce il numero totale di elementi di campo ripetuti.

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

arrays.max

Supportato in:

Regole Ricerca

arrays.max(array_of_ints_or_floats)

Descrizione

Restituisce l'elemento maggiore in un array o zero se l'array è vuoto.

Tipi di dati Param

ARRAY_INTS|ARRAY_FLOATS

Tipo restituito

FLOAT

Esempi di codice

Ecco alcuni esempi di utilizzo della funzione:

Esempio 1

Questo esempio restituisce l'elemento maggiore in un array di numeri interi.

arrays.max([10, 20]) = 20.000000

Esempio 2

Questo esempio restituisce l'elemento maggiore in un array di valori float.

arrays.max([10.000000, 20.000000]) = 20.000000

arrays.min

Supportato in:

Regole Ricerca

arrays.min(array_of_ints_or_floats[, ignore_zeros=false])

Descrizione

Restituisce l'elemento più piccolo di un array o zero se l'array è vuoto. Se il secondo argomento facoltativo è impostato su true, gli elementi uguali a zero vengono ignorati.

Tipi di dati Param

ARRAY_INTS|ARRAY_FLOATS, BOOL

Tipo restituito

FLOAT

Esempi di codice

Ecco alcuni esempi di utilizzo della funzione:

Esempio 1

Questo esempio restituisce l'elemento più piccolo in un array di numeri interi.

arrays.min([10, 20]) = 10.000000

Esempio 2

Questo esempio restituisce l'elemento più piccolo in un array di valori float.

arrays.min([10.000000, 20.000000]) = 10.000000

Esempio 3

Questo esempio restituisce l'elemento più piccolo in un array di valori float, ignorando gli zeri.

arrays.min([10.000000, 20.000000, 0.0], true) = 10.000000

arrays.size

Supportato in:

Regole Ricerca

arrays.size( array )

Descrizione

Restituisce le dimensioni dell'array. Restituisce 0 per un array vuoto.

Tipi di dati Param

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS

Tipo restituito

INT

Esempi di codice

Esempio 1

Questo esempio utilizza un array di stringhe contenente due elementi.

arrays.size(["test1", "test2"]) = 2

Esempio 2

Questo esempio utilizza un array di interi contenente 3 elementi.

arrays.size([1, 2, 3]) = 3

Esempio 3

Questo esempio utilizza un array di numeri con virgola mobile contenente 1 elemento

arrays.size([1.200000]) = 1

Esempio 4

Questo esempio utilizza un array vuoto.

arrays.size([]) = 0

arrays.index_to_float

Supportato in:

Regole Ricerca

arrays.index_to_float(array, index)

Descrizione

Restituisce l'elemento all'indice specificato di un array. L'elemento in quell'indice viene restituito come numero in virgola mobile.

L'indice è un valore intero che rappresenta la posizione di un elemento nell'array. Per impostazione predefinita, il primo elemento di un array ha un indice 0 e l'ultimo elemento ha un indice n-1, dove n è la dimensione dell'array. L'indice negativo consente di accedere agli elementi dell'array rispetto alla fine dell'array. Ad esempio, un indice di -1 si riferisce all'ultimo elemento dell'array e un indice di -2 si riferisce al penultimo elemento dell'array.

Tipi di dati Param

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

L'esempio seguente recupera un elemento all'indice 1 da un array di valori float.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 1) // 2.1

Esempio 2

L'esempio seguente recupera un elemento all'indice -1 da un array di valori float.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], -1) // 4.6

Esempio 3

L'esempio seguente recupera un elemento per un indice maggiore della dimensione dell'array.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 6) // 0.0

Esempio 4

L'esempio seguente recupera un elemento da un array vuoto.

arrays.index_to_float([], 0) // 0.0

Esempio 5

L'esempio seguente recupera un elemento all'indice 1 da un array di stringhe.

arrays.index_to_float(["1.2", "3.3", "2.4"], 1) // 3.3

Esempio 6

L'esempio seguente recupera un elemento all'indice 2 da un array di numeri interi.

arrays.index_to_float([1, 3, 2], 2) // 2.0

arrays.index_to_int

Supportato in:

Regole Ricerca

arrays.index_to_int(array_of_inputs, index)

Descrizione

Restituisce il valore in un determinato indice di un array come numero intero.

L'indice è un valore intero che rappresenta la posizione di un elemento nell'array. Per impostazione predefinita, il primo elemento di un array ha un indice 0 e l'ultimo elemento ha un indice n-1, dove n è la dimensione dell'array. L'indice negativo consente di accedere agli elementi dell'array rispetto alla fine dell'array. Ad esempio, un indice di -1 si riferisce all'ultimo elemento dell'array e un indice di -2 si riferisce al penultimo elemento dell'array.

Tipi di dati Param

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo restituito

INT

Esempi di codice

Esempio 1

Questa chiamata di funzione restituisce 0 quando il valore all'indice è una stringa non numerica.

arrays.index_to_int(["str0", "str1", "str2"], 1) = 0

Esempio 2

Questa funzione restituisce l'elemento all'indice -1.

arrays.index_to_int(["44", "11", "22", "33"], -1) = 33

Esempio 3

Restituisce 0 per l'elemento fuori intervallo.

arrays.index_to_int(["44", "11", "22", "33"], 5) = 0

Esempio 4

Questa funzione recupera l'elemento dall'array di numeri in virgola mobile all'indice 1.

arrays.index_to_int([1.100000, 1.200000, 1.300000], 1) = 1

Esempio 5

Questa funzione recupera l'elemento dall'array di interi all'indice 0.

arrays.index_to_int([1, 2, 3], 0) = 1

arrays.index_to_str

Supportato in:

Regole Ricerca

arrays.index_to_str(array, index)

Descrizione

Restituisce l'elemento all'indice specificato dell'array come stringa. L'indice è un valore intero che rappresenta la posizione di un elemento nell'array. Per impostazione predefinita, il primo elemento di un array ha un indice 0 e l'ultimo elemento ha un indice n-1, dove n è la dimensione dell'array. L'indice negativo consente di accedere agli elementi dell'array dalla fine dell'array. Ad esempio, un indice di -1 si riferisce all'ultimo elemento dell'array e un indice di -2 si riferisce al penultimo elemento dell'array.

Tipi di dati Param

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente recupera un elemento all'indice 1 da un array di stringhe.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 1) // "test2"

Esempio 2

L'esempio seguente recupera un elemento all'indice -1 (ultimo elemento dell'array) da un array di stringhe.

arrays.index_to_str(["test1", "test2", "test3", "test4"], -1) // "test4"

Esempio 3

L'esempio seguente recupera un elemento per un indice maggiore della dimensione dell'array, che restituisce una stringa vuota.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 6) // ""

Esempio 4

L'esempio seguente recupera un elemento da un array vuoto.

arrays.index_to_str([], 0) // ""

Esempio 5

L'esempio seguente recupera un elemento all'indice 0 da un array di valori float. L'output viene restituito come stringa.

arrays.index_to_str([1.200000, 3.300000, 2.400000], 0) // "1.2"

Esempio 6

L'esempio seguente recupera un elemento all'indice 2 da un array di numeri interi. L'output è sotto forma di stringa.

arrays.index_to_str([1, 3, 2], 2) // "2"

cast.as_bool

Supportato in:

Regole Ricerca

cast.as_bool(string_or_int)

Descrizione

La funzione converte un valore int o stringa in un valore booleano. Le chiamate di funzioni con valori che non possono essere sottoposti a conversione restituiranno FALSE. Restituisce TRUE solo per l'intero 1 e la stringa "true" senza distinzione tra maiuscole e minuscole.

Tipi di dati Param

INT|STRING

Tipo restituito

BOOL

Esempi di codice

Esempio 1

Questo esempio mostra come eseguire il casting di una stringa non booleana

cast.as_bool("123") = false

Esempio 2

Intero vero (1)

cast.as_bool(1) = true

Esempio 3

Stringa vera

cast.as_bool("true") = true

Esempio 4

Stringa vera in maiuscolo

cast.as_bool("TRUE") = true

Esempio 5

Numero intero negativo

cast.as_bool(-1) = false

Esempio 6

Numero intero falso (0)

cast.as_bool(0) = false

Esempio 7

stringa vuota

cast.as_bool("") = false

cast.as_float

Supportato in:

Regole Ricerca

cast.as_float(string_to_cast)

Descrizione

Converte una stringa numerica in un numero in virgola mobile. Eventuali chiamate di funzioni con valori che non possono essere sottoposti a conversione restituiscono 0. I valori float mantengono la precisione fino a 7 cifre decimali.

Tipi di dati Param

STRING

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

Il casting di una stringa non numerica restituisce 0.

cast.as_float("str") = 0.0000000

Esempio 2

Il casting di una stringa vuota restituisce 0.

cast.as_float("") = 0.0000000

Esempio 3

Il casting di una stringa numerica valida restituisce un valore float.

cast.as_float("1.012345678") = 1.0123456

impronta

Supportato in:

Regole

hash.fingerprint2011(byteOrString)

Descrizione

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

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

Tipi di dati Param

BTYE, STRING

Tipo restituito

INT

Esempio di codice

id_fingerprint = hash.fingerprint2011("user123")

gruppo

Supportato in:

Ricerca

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

Descrizione

Raggruppa i campi di un tipo simile in una variabile segnaposto.

Nella ricerca UDM, i campi agrupati vengono utilizzati per eseguire ricerche in più campi di tipo simile. La funzione gruppo è simile ai campi raggruppati, tranne per il fatto che ti consente di selezionare i campi da raggruppare per attivare un rilevamento. Puoi utilizzare la funzione di gruppo per raccogliere informazioni su una determinata entità (ad esempio un nome host, un indirizzo IP o un ID utente) in diversi tipi di sostantivi.

Nota: per la ricerca, puoi utilizzare i campi raggruppati nella sezione Eventi, ma non nelle sezioni Corrispondenza e Risultato.

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

hash.sha256

Supportato in:

Regole

hash.sha256(string)

Descrizione

Restituisce un hash SHA-256 della stringa di input.

Tipi di dati Param

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

Questo esempio mostra l'hash SHA-256 quando l'input è una stringa valida.

hash.sha256("str") = "8c25cb3686462e9a86d2883c5688a22fe738b0bbc85f458d2d2b5f3f667c6d5a"

Esempio 2

Questo esempio mostra l'hash SHA-256 quando l'input è una stringa vuota.

hash.sha256("") = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

math.abs

Supportato in:

Regole Ricerca

math.abs(numericExpression)

Descrizione

Restituisce il valore assoluto di un'espressione di tipo intero o con virgola mobile.

Tipi di dati Param

NUMBER

Tipo restituito

NUMBER

Esempi di codice

Esempio 1

Questo esempio restituisce True se l'evento è avvenuto più di 5 minuti dopo l'ora specificata (in secondi dall'epoca Unix), indipendentemente dal fatto che sia avvenuto 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 di tempo hardcoded 1643687343 nell'esempio seguente con $e2.metadata.event_timestamp.seconds.

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

math.ceil

Supportato in:

Regole Ricerca

math.ceil(number)

Descrizione

Restituisce il numero intero più piccolo non inferiore al numero specificato (arrotondamento per eccesso). Restituisce 0 se l'input è nullo o troppo grande per essere inserito in un int64.

Tipi di dati Param

FLOAT

Tipo restituito

INT

Esempi di codice

Questa sezione contiene esempi di utilizzo di math.ceil.

Esempio 1

Questo esempio restituisce il valore intero superiore o uguale a un numero intero.

math.ceil(2.000000) = 2

Esempio 2

Questo esempio restituisce il valore intero superiore di un numero negativo.

math.ceil(-1.200000) = -1

Esempio 3

Questo esempio restituisce 0 come il valore intero superiore di un numero troppo grande per un numero intero a 64 bit.

math.ceil(184467440737095516160.0) = 0

math.floor

Supportato in:

Regole Ricerca

math.floor(float_val)

Descrizione

Restituisce il valore intero più grande che non è maggiore del valore fornito (arrotondamento per difetto). Restituisce 0 se l'input è nullo o troppo grande per essere inserito in un int64.

Tipi di dati Param

FLOAT

Tipo restituito

INT

Esempi di codice

Esempio 1

Questo esempio mostra un caso di numero positivo.

math.floor(1.234568) = 1

Esempio 2

Questo esempio mostra un caso di numero negativo.

math.floor(-1.234568) = -2

Esempio 3

Questo esempio mostra un caso zero.

math.floor(0.000000) = 0

math.geo_distance

Supportato in:

Regole

math.geo_distance(longitude1, latitude1, longitude2, latitude2))

Descrizione

Restituisce la distanza tra due geolocalizzazioni (coordinate). Restituisce -1 se la coordinata geografica non è valida.

Tipi di dati Param

FLOAT, FLOAT, FLOAT, FLOAT

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

Questo esempio restituisce la distanza quando tutti i parametri sono coordinate valide.

math.geo_distance(-122.020287, 37.407574, -122.021810, 37.407574) = 134.564318

Esempio 2

Questo esempio restituisce la distanza quando uno dei parametri è una coordinata troncata.

math.geo_distance(-122.000000, 37.407574, -122.021810, 37.407574) = 1926.421905

Esempio 3

Questo esempio restituisce -1 quando uno dei parametri è una coordinata non valida.

math.geo_distance(-122.897680, 37.407574, -122.021810, 97.407574) = -1.000000

Esempio 4

Questo esempio restituisce 0 quando le coordinate sono uguali.

math.geo_distance(-122.897680, 37.407574, -122.897680, 37.407574) = 0.000000

math.is_increasing

Supportato in:

Regole Ricerca

math.is_increasing(num1, num2, num3)

Descrizione

Prende un elenco di valori numerici (interi o doppi) e restituisce True se i valori sono in ordine crescente e False in caso contrario.

Tipi di dati Param

INT|FLOAT, INT|FLOAT, INT|FLOAT

Tipo restituito

BOOL

Esempi di codice

Esempio 1

Questo esempio include valori simili a timestamp in secondi.

math.is_increasing(1716769112, 1716769113, 1716769114) = true

Esempio 2

Questo esempio include un valore doppio negativo, un valore INT64 pari a zero e un valore INT64 positivo.

math.is_increasing(-1.200000, 0, 3) = true

Esempio 3

Questo esempio include un valore doppio negativo, un valore INT64 pari a zero e un valore INT64 negativo.

math.is_increasing(-1.200000, 0, -3) = false

Esempio 4

Questo esempio include due numeri doppi negativi e un valore INT64 pari a zero.

math.is_increasing(-1.200000, -1.50000, 0) = false

Esempio 5

Questo esempio include un numero doppio negativo e due valori uguali.

math.is_increasing(-1.200000, 0, 0) = false

math.log

Supportato in:

Regole Ricerca

math.log(numericExpression)

Descrizione

Restituisce il valore del logaritmo naturale di un'espressione di tipo integer o float.

Tipi di dati Param

NUMBER

Tipo restituito

NUMBER

Esempi di codice

Esempio 1

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

math.pow

Supportato in:

Regole Ricerca

math.pow(base, exponent)

Descrizione

Restituisce il valore del primo argomento elevato alla potenza del secondo argomento. Restituisce 0 in caso di overflow.

Tipi di dati Param

base: INT|FLOAT esponente: INT|FLOAT

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

Questo esempio mostra un caso di numero intero.

math.pow(2, 2) // 4.00

Esempio 2

Questo esempio mostra un caso base di frazioni.

math.pow(2.200000, 3) // 10.648

Esempio 3

Questo esempio mostra un caso di base e potenza della frazione.

math.pow(2.200000, 1.200000) // 2.575771

Esempio 4

Questo esempio mostra un caso di potenza negativa.

math.pow(3, -3) // 0.037037

Esempio 5

Questo esempio mostra un caso di potenza di frazione.

math.pow(3, -1.200000) // 0.267581

Esempio 6

Questo esempio mostra un caso base negativo.

math.pow(-3, -3) // -0.037037

Esempio 7

Questo esempio mostra un caso base zero.

math.pow(0, 3) // 0

Esempio 8

Questo esempio mostra un caso di potenza zero.

math.pow(9223372036854775807, 0) // 1

Esempio 9

Questo esempio mostra un caso base di grandi dimensioni.

math.pow(9223372036854775807, 1.200000) // 57262152889751593549824

math.random

Supportato in:

Regole Ricerca

math.random()

Descrizione

Genera un valore pseudo-casuale di tipo DOUBLE nell'intervallo [0, 1), incluso 0 ed escluso 1.

Tipo restituito

FLOAT

Esempi di codice

L'esempio seguente verifica se il valore casuale rientra nell'intervallo [0, 1). none if(math.random() >= 0 and math.random() < 1) = true

math.round

Supportato in:

Ricerca

math.round(numericExpression, decimalPlaces)

Descrizione

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

Tipi di dati Param

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

math.sqrt

Supportato in:

Regole Ricerca

math.sqrt(number)

Descrizione

Restituisce la radice quadrata del numero specificato. Restituisce 0 in caso di numeri negativi.

Tipi di dati Param

INT|FLOAT

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

Questo esempio restituisce la radice quadrata di un argomento int.

math.sqrt(3) = 1.732051

Esempio 2

Questo esempio restituisce la radice quadrata di un argomento int negativo.

math.sqrt(-3) = 0.000000

Esempio 3

Questo esempio restituisce la radice quadrata dell'argomento zero.

math.sqrt(0) = 0.000000

Esempio 4

Questo esempio restituisce la radice quadrata di un argomento float.

math.sqrt(9.223372) = 3.037000

Esempio 5

Questo esempio restituisce la radice quadrata di un argomento float negativo.

math.sqrt(-1.200000) = 0.000000

metriche

Supportato in:

Regole

Le funzioni di metrica possono aggregare grandi quantità di dati storici. Puoi utilizzarla nella regola utilizzando metrics.functionName() nella sezione relativa al risultato.

Per ulteriori informazioni, consulta 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 nella subnet specificata.

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

Per eseguire una ricerca in un intervallo di indirizzi IP, specifica un campo UDM IP e un intervallo CIDR. YARA-L può gestire sia i campi di indirizzi IP singoli che quelli ripetuti.

Per eseguire una ricerca 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 di indirizzi IP singoli che quelli ripetuti.

Tipi di dati Param

STRING, STRING

Tipo restituito

BOOL

Esempi di codice

Esempio 1

Esempio 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 Singolo evento nell'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: relativo agli eventi. Di seguito è riportata una rappresentazione generica di questa sintassi:

  $e.field = /regex/
  

• Utilizzando la sintassi YARA-L: come funzione che accetta 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 trovare una corrispondenza esatta della stringa o solo di un prefisso o suffisso, includi i caratteri di ancoraggio ^ (iniziale) e $ (finale) 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 un (?s) all'espressione regolare. Ad esempio, sostituisci /.*allUDM.*/ con /(?s).*allUDM.*/.
• Puoi utilizzare il modificatore nocase dopo le stringhe per indicare che la ricerca deve ignorare le lettere maiuscole.

Tipi di dati Param

STRING, STRING

Tipi di espressioni param

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 dell'espressione regolare fornito nell'argomento.

Questa funzione accetta due argomenti:

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

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

Tipi di dati Param

STRING, STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

In questo esempio, se $e.principal.hostname contiene "aaa1bbaa2", il seguente valore sarebbe vero, perché la funzione restituisce la prima istanza. Questo esempio non contiene 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 un'ineguaglianza:

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

STRING, STRING, 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. Tieni presente l'utilizzo di funzioni nidificate.

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

Esempio 2

Questo esempio utilizza cifre con interpretazione letterale a barra rovesciata nell'argomento replacementText per fare riferimento alle corrispondenze del 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")

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 Sample.

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 Param

• byteOrString: espressione che restituisce un BYTE o un 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 accetta come argomento una stringa codificata in base64. Se encodedString non è una stringa con codifica base64 valida, la funzione restituisce encodedString invariato.

Tipi di dati Param

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 restituisce una stringa vuota, la chiamata alla funzione restituisce una stringa vuota.

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

Tipi di dati Param

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente include variabili stringa come argomenti. La condizione viene valutata come 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 è lo stesso in cui sono elencati nella condizione della regola:

1. $e.principal.ip viene valutato per primo.
2. Viene valutato $e.src.ip.
3. Viene valutato $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 e dall'evento $e2. Verrà restituito 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, ciascuno dei quali può essere una stringa, un numero intero o un numero decimale.

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

Tipi di dati Param

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 vengono 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 float come argomenti. Quando sono rappresentati come stringhe, i numeri in virgola mobile che sono numeri interi vengono formattati senza la virgola decimale (ad esempio, 1,0 è rappresentato come "1"). Inoltre, gli float che superano sedici cifre decimali vengono troncati alla sedicesima cifra decimale.

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

Esempio 4

L'esempio seguente include una variabile stringa, un valore letterale della stringa, una variabile intera e un valore letterale con virgola mobile come argomenti. Tutte le variabili provengono dall' stessa evento, $e, e vengono 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 dell'evento $e1 con principal.hostname dell'evento $e2. Verrà restituito un errore del compilatore perché gli argomenti sono variabili evento diverse.

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

strings.contains

Supportato in:

Regole Ricerca

strings.contains( str, substr )

Descrizione

Restituisce true se una determinata stringa contiene la sottostringa specificata. In caso contrario, restituisce false.

Tipi di dati Param

STRING, STRING

Tipo restituito

BOOL

Esempi di codice

Esempio 1

Questo esempio restituisce true perché la stringa contiene una sottostringa "è".

strings.contains("thisisastring", "is") = true

Esempio 2

Questo esempio restituisce false perché la stringa non contiene la sottostringa "that".

strings.contains("thisisastring", "that") = false

strings.count_substrings

Supportato in:

Regole Ricerca

strings.count_substrings(string_to_search_in, substring_to_count)

Descrizione

Se vengono fornite una stringa e una sottostringa, restituisce un valore int64 del conteggio delle occorrenze non sovrapposte della sottostringa all'interno della stringa.

Tipi di dati Param

STRING, STRING

Tipo restituito

INT

Esempi di codice

Questa sezione contiene esempi che calcolano il numero di volte in cui una sottostringa compare in una determinata stringa.

Esempio 1

Questo esempio utilizza una stringa non null e un carattere di sottostringa singola non null.

strings.count_substrings("this`string`has`four`backticks", "`") = 4

Esempio 2

Questo esempio utilizza una stringa non null e una sottostringa non null superiore a un carattere.

strings.count_substrings("str", "str") = 1

Esempio 3

Questo esempio utilizza una stringa non null e una sottostringa vuota.

strings.count_substrings("str", "") = 0

Esempio 4

Questo esempio utilizza una stringa vuota e una sottostringa non null maggiore di un carattere.

strings.count_substrings("", "str") = 0

Esempio 5

Questo esempio utilizza una stringa vuota e una sottostringa vuota.

strings.count_substrings("", "") = 0

Esempio 6

Questo esempio utilizza una stringa non null e una sottostringa non null che è maggiore di un carattere e di un'occorrenza.

strings.count_substrings("fooABAbarABAbazABA", "AB") = 3

Esempio 7

Questo esempio utilizza una stringa non null e una sottostringa non null che è maggiore di un carattere e di un'occorrenza. Evidenzia la limitazione con le occorrenze delle sottostringhe sovrapposte

strings.count_substrings("ABABABA", "ABA") = 2

strings.extract_domain

Supportato in:

Regole Ricerca

strings.extract_domain(url_string)

Descrizione

Estrae il dominio da una stringa.

Nota: la funzione non esegue la normalizzazione Unicode.

Nota: i dati sui suffissi pubblici disponibili su publicsuffix.org contengono anche domini privati. Questa funzione non tratta un dominio privato come suffisso pubblico. Ad esempio, se us.com è un dominio privato nei dati del suffisso pubblico, ("foo.us.com") restituisce us.com (il suffisso pubblico com più l'etichetta precedente us) anziché foo.us.com (il dominio privato us.com più l'etichetta precedente foo).

Nota: i dati del suffisso pubblico potrebbero cambiare nel tempo. Di conseguenza, l'input che ora produce un valore predefinito vuoto potrebbe produrre un valore non vuoto in futuro.

Tipi di dati Param

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

Questo esempio mostra una stringa vuota

strings.extract_domain("") = ""

Esempio 2

stringa casuale, non un URL

strings.extract_domain("1234") = ""

Esempio 3

più backslach

strings.extract_domain("\\\\") = ""

Esempio 4

I caratteri non alfabetici vengono gestiti correttamente

strings.extract_domain("http://例子.卷筒纸.中国") = "卷筒纸.中国"

Esempio 5

gestione degli URI

strings.extract_domain("mailto:?to=&subject=&body=") = ""

Esempio 6

più caratteri prima dell'URL effettivo

strings.extract_domain("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "google.com"

Esempio 7

caratteri speciali nell'URI #

strings.extract_domain("test#@google.com") = ""

Esempio 8

caratteri speciali nell'URL #

strings.extract_domain("https://test#@google.com") = ""

Esempio 9

test case positivo

strings.extract_domain("https://google.co.in") = "google.co.in"

strings.extract_hostname

Supportato in:

Regole Ricerca

strings.extract_hostname(string)

Descrizione

Estrae il nome host da una stringa. Questa funzione è sensibile alle maiuscole.

Tipi di dati Param

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

Questo esempio restituisce una stringa vuota.

strings.extract_hostname("") = ""

Esempio 2

stringa casuale, non un URL

strings.extract_hostname("1234") = "1234"

Esempio 3

più barre inverse

strings.extract_hostname("\\\\") = ""

Esempio 4

I caratteri non inglesi vengono gestiti correttamente

strings.extract_hostname("http://例子.卷筒纸.中国") = "例子.卷筒纸.中国"

Esempio 5

gestione degli URI

strings.extract_hostname("mailto:?to=&subject=&body=") = "mailto"

Esempio 6

più caratteri prima dell'URL effettivo

strings.extract_hostname("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "www.google.com"

Esempio 7

caratteri speciali nell'URI #

strings.extract_hostname("test#@google.com") = "test"

Esempio 8

caratteri speciali nell'URL #

strings.extract_hostname("https://test#@google.com") = "test"

strings.from_hex

Supportato in:

Regole Ricerca

strings.from_hex(hex_string)

Descrizione

Restituisce i byte associati alla stringa esadecimale specificata.

Tipi di dati Param

STRING

Tipo restituito

BYTES

Esempi di codice

Recupera i byte associati a una determinata stringa esadecimale.

Esempio 1

Questo esempio mostra le conversioni di caratteri non esadecimali.

strings.from_hex("str") // returns empty bytes

Esempio 2

Questo esempio mostra l'input con una stringa vuota.

strings.from_hex("") // returns empty bytes

Esempio 3

Questo esempio mostra la conversione di stringhe esadecimali.

strings.from_hex("1234") // returns 1234 bytes

Esempio 4

Questo esempio mostra la conversione dei caratteri non ASCII.

strings.from_hex("筒纸.中国") // returns empty bytes

strings.ltrim

Supportato in:

Regole Ricerca

strings.ltrim(string_to_trim, cutset)

Descrizione

Taglia gli spazi bianchi iniziali da una determinata stringa. Questa funzione rimuove i caratteri iniziali presenti nel set di taglio.

Tipi di dati Param

STRING, STRING

Tipo restituito

STRING

Esempi di codice

Di seguito sono riportati alcuni casi d'uso di esempio.

Esempio 1

Questo esempio utilizza lo stesso primo e secondo argomento.

strings.ltrim("str", "str") = ""

Esempio 2

Questo esempio utilizza una stringa vuota come secondo argomento.

strings.ltrim("str", "") = "str"

Esempio 3

Questo esempio utilizza una stringa vuota come primo argomento e una stringa come secondo argomento.

strings.ltrim("", "str") = ""

Esempio 4

Questo esempio utilizza stringhe contenenti spazi bianchi e una stringa come secondo argomento.

strings.ltrim("a aastraa aa ", " a") = "straa aa "

strings.reverse

Supportato in:

Regole Ricerca

strings.reverse(STRING)

Descrizione

Restituisce una stringa che è l'inverso della stringa di input.

Tipi di dati Param

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente passa una stringa breve.

strings.reverse("str") = "rts"  // The function returns 'rts'.

Esempio 2

L'esempio seguente passa una stringa vuota.

strings.reverse("") = ""

Esempio 3

L'esempio seguente passa un palindromo.

strings.reverse("tacocat") = "tacocat"

strings.rtrim

Supportato in:

Regole Ricerca

strings.rtrim(string_to_trim, cutset)

Descrizione

Taglia gli spazi bianchi finali da una determinata stringa. Rimuove i caratteri finali presenti nel set di taglio.

Tipi di dati Param

STRING, STRING

Tipo restituito

STRING

Esempi di codice

Di seguito sono riportati alcuni casi d'uso di esempio.

Esempio 1

Il seguente esempio passa la stessa stringa come primo e secondo argomento.

strings.rtrim("str", "str") = ""

Esempio 2

L'esempio seguente passa una stringa vuota come secondo argomento.

strings.rtrim("str", "") = "str"

Esempio 3

Il seguente esempio passa una stringa vuota come primo argomento e una stringa non vuota come secondo argomento.

strings.rtrim("", "str") = ""

Esempio 4

L'esempio seguente passa una stringa contenente spazi vuoti come primo argomento e una stringa non vuota come secondo argomento.

strings.rtrim("a aastraa aa ", " a") = "a aasstr"

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 Param

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(string_val)

Descrizione

Restituisce la stringa originale con tutti i caratteri alfabetici in maiuscolo.

Tipi di dati Param

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

L'esempio seguente restituisce l'argomento fornito in maiuscolo.

strings.to_upper("example") = "EXAMPLE"

strings.trim

Supportato in:

Regole Ricerca

strings.trim(string_to_trim, cutset)

Descrizione

Rimuove gli spazi vuoti iniziali e finali da una determinata stringa. Inoltre, rimuovi dalla stringa di input i caratteri indesiderati (specificati dall'argomento settaglio).

Tipi di dati Param

STRING, STRING

Tipo restituito

STRING

Esempi di codice

Di seguito sono riportati alcuni casi d'uso di esempio.

Esempio 1

Nell'esempio seguente, la stessa stringa viene passata come stringa di input e come insieme di taglio, il che genera una stringa vuota.

strings.trim("str", "str") // ""

Esempio 2

Nell'esempio seguente, viene passata una stringa vuota come insieme di tagli, che restituisce la stringa originale str perché non sono stati specificati caratteri da rimuovere nell'insieme di tagli.

strings.trim("str", "") = "str"

Esempio 3

Nell'esempio seguente, la funzione restituisce una stringa vuota perché la stringa di input è già vuota e non ci sono caratteri da rimuovere.

strings.trim("", "str") = ""

Esempio 4

Nell'esempio seguente, la funzione restituisce str perché la funzione trim rimuove quanto segue:

• Spazio vuoto finale in "a aastraa aa "
• I caratteri specificati nel set di taglio (spazio, a)

strings.trim("a aastraa aa ", " a") = "str"

strings.url_decode

Supportato in:

Regole Ricerca

strings.url_decode(url_string)

Descrizione

Data una stringa URL, decodifica i caratteri di escape e gestisci i caratteri UTF-8 che sono stati codificati. Restituisce una stringa vuota se la decodifica non riesce.

Tipi di dati Param

STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

Questo esempio mostra un caso di test positivo.

strings.url_decode("three%20nine%20four") = "three nine four"

Esempio 2

Questo esempio mostra una stringa vuota.

strings.url_decode("") // ""

Esempio 3

Questo esempio mostra la gestione dei caratteri non alfabetici.

strings.url_decode("%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B") // "上海+中國"

Esempio 4

Questo esempio mostra una decodifica dell'URL di esempio.

strings.url_decode("http://www.google.com%3Fparam1%3D%22+1+%3E+2+%22%26param2%3D2%3B") // 'http://www.google.com?param1="+1+>+2+"&param2=2;'

timestamp.as_unix_seconds

Supportato in:

Regole Ricerca

timestamp.as_unix_seconds(timestamp [, time_zone])

Descrizione

Questa funzione restituisce un numero intero che rappresenta il numero di secondi trascorsi da un'epoca Unix per la stringa del timestamp specificata.

• timestamp è una stringa che rappresenta un timestamp epoch valido. Il formato deve essere %F %T.
• time_zone è facoltativo ed è una stringa che rappresenta un fuso orario. Se viene omesso, il valore predefinito è GMT. Puoi specificare i fusi orari utilizzando litterali di stringa. Le opzioni sono le seguenti:
  • Il nome del database TZ, ad esempio America/Los_Angeles. Per ulteriori informazioni, consulta l'elenco dei fusi orari del database TZ su Wikipedia.
  • L'offset 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 Param

STRING, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

Timestamp epoch valido

timestamp.as_unix_seconds("2024-02-22 10:43:00") = 1708598580

Esempio 2

Timestamp epoch valido con il fuso orario America/New_York

timestamp.as_unix_seconds("2024-02-22 10:43:00", "America/New_York") = 1708616580

timestamp.current_seconds

Supportato in:

Regole Ricerca

timestamp.current_seconds()

Descrizione

Restituisce un numero intero che rappresenta l'ora corrente in secondi Unix. È approssimativamente uguale al timestamp del rilevamento e si basa sul momento in cui viene eseguita la regola. Questa funzione è un sinonimo della funzione timestamp.now().

Tipi di dati Param

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 poi esegue il confronto utilizzando 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 dopo l'epocha 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 omisso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando litterali di 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
  • L'offset 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 dell'ora:

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

INT, STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

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

$ts = $e.metadata.collected_timestamp.seconds

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

Esempio 2

Questo esempio utilizza un valore letterale di 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 dopo l'epocha 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 viene omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando litterali di 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
  • L'offset 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 Param

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Esempio 2

Questo esempio utilizza un valore letterale di 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 dopo l'epocha 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 omisso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando litterali di 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
  • L'offset 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 Param

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Esempio 2

Questo esempio utilizza un valore letterale di 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 a partire da domenica. Ad esempio, 1 = domenica e 2 = lunedì.

• unix_seconds è un numero intero che rappresenta il numero di secondi dopo l'epocha 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 omisso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando litterali di 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
  • L'offset 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 dell'ora:

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

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6

Esempio 2

Questo esempio utilizza un valore letterale di 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 dopo l'epocha Unix, ad esempio $e.metadata.event_timestamp.seconds, o un segnaposto contenente questo 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 stringhe letterali. 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 viene omesso, il valore predefinito è GMT. Puoi specificare i fusi orari utilizzando litterali di stringa. Le opzioni sono le seguenti:
  • Il nome del database IANA Time Zone (TZ), ad esempio America/Los_Angeles. Per ulteriori informazioni, consulta l'elenco dei fusi orari del database tz su Wikipedia.
  • L'offset 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 Param

INT, STRING, STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

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

$ts = $e.metadata.collected_timestamp.seconds

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

Esempio 2

Questo esempio utilizza un valore letterale di 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

Questo esempio utilizza un valore letterale di 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 di domenica. Le date precedenti la prima domenica dell'anno rientrano nella settimana 0.

• unix_seconds è un numero intero che rappresenta il numero di secondi trascorsi dall'epoch 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 omisso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando litterali di 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
  • L'offset 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 Param

INT, STRING

Tipo restituito

INT

Esempi di codice

Esempio 1

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0

Esempio 2

Questo esempio utilizza un valore letterale di stringa per definire time_zone.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.now

Supportato in:

Regole Ricerca

timestamp.now()

Descrizione

Restituisce il numero di secondi dal giorno 01/01/1970 00:00:00 UTC. È anche noto come ora del periodo Unix.

Tipo restituito

INT

Esempi di codice

Esempio 1

Il seguente esempio restituisce un timestamp per il codice eseguito il 22 maggio 2024 alle ore 18:16:59.

timestamp.now() = 1716401819 // Unix epoch time in seconds for May 22, 2024 at 18:16:59

window.avg

Supportato in:

Regole

window.avg(numeric_values [, should_ignore_zero_values])

Descrizione

Restituisce la media dei valori di input (che possono essere interi o valori in virgola mobile). L'impostazione del secondo argomento facoltativo su true ignora i valori zero.

Tipi di dati Param

INT|FLOAT

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

Questo esempio mostra la media dei numeri interi.

// This rule sets the outcome $size_mode to the average
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 2.5 if the event file size values in the match window are 1, 2, 3 and 4

Esempio 2

Questo esempio mostra la media mobile.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 1.75 if the event file size values in the match window are 1.1 and 2.4

Esempio 3

Media input negativa

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0.6 if the event file size values in the match window are -1.1, 1.1, 0.0 and 2.4

Esempio 4

0 restituisce 0

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0 if the event file size values in the match window is 0

Esempio 5

Ignorare i valori 0

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size, true) // yields 394 if the event file size values in the match window are 0, 0, 0 and 394

window.first

Supportato in:

Regole

window.first(values_to_sort_by, values_to_return)

Descrizione

Questa funzione di aggregazione restituisce un valore di stringa derivato da un evento con il valore int correlato più basso nella finestra di corrispondenza. Un caso d'uso di esempio è l'ottenimento dell'user-id dall'evento con il timestamp più basso nella finestra di corrispondenza (evento più antico).

Tipi di dati Param

INT, STRING

Tipo restituito

STRING

Esempi di codice

Ottieni un valore di stringa derivato da un evento con il valore int correlato più basso nella finestra di corrispondenza.

// This rule sets the outcome $first_event to the lowest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $first_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v1 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.last

Supportato in:

Regole

window.last(values_to_sort_by, values_to_return)

Descrizione

Questa funzione di aggregazione restituisce un valore di stringa derivato da un evento con il valore int correlato più alto nella finestra di corrispondenza. Un caso d'uso di esempio è l'ottenimento dell'user-id dall'evento con il timestamp più basso nella finestra di corrispondenza (timestamp più alto).

Tipi di dati Param

INT, STRING

Tipo restituito

STRING

Esempi di codice

Recupera un valore di stringa derivato da un evento con il valore int correlato più alto nella finestra di corrispondenza.

// This rule sets the outcome $last_event to the highest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $last_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v3 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.median

Supportato in:

Regole

window.median(numeric_values, should_ignore_zero_values)

Descrizione

Restituisce la mediana dei valori di input. Se sono presenti due valori medi, solo uno verrà scelto in modo non deterministico come valore restituito.

Tipi di dati Param

INT|FLOAT, BOOL

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

Questo esempio restituisce la mediana quando i valori di input non sono pari a zero.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 2 if the file sizes in the match window are [1, 2, 3]
  condition:
      $e
}

Esempio 2

Questo esempio restituisce la mediana quando l'input include alcuni valori zero che non devono essere ignorati.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}

Esempio 3

Questo esempio restituisce la mediana quando l'input include alcuni valori zero che devono essere ignorati.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size, true) // returns 2 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}

Esempio 4

Questo esempio restituisce la mediana quando l'input include tutti i valori zero che devono essere ignorati.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 0 if the file sizes in the match window are [0,0]
  condition:
      $e
}

Esempio 5

Questo esempio mostra che, quando sono presenti più mediane, viene restituita una sola mediana.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [1, 2, 3, 4]
  condition:
      $e
}

window.mode

Supportato in:

Regole

window.mode(values)

Descrizione

Restituisce la modalità dei valori di input. In caso di più valori possibili per la modalità, solo uno di questi valori verrà scelto in modo non deterministico come valore restituito.

Tipi di dati Param

INT|FLOAT|STRING

Tipo restituito

STRING

Esempi di codice

Esempio 1

Ottieni la modalità dei valori nella finestra di corrispondenza.

// This rule sets the outcome $size_mode to the most frequently occurring
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.mode($e.file.size) // yields 1.6 if the event file size values in the match window are 1.6, 2, and 1.6

window.stddev

Supportato in:

Regole

window.stddev(numeric_values)

Descrizione

Restituisce la deviazione standard dei valori di input in una finestra di corrispondenza.

Tipi di dati Param

INT|FLOAT

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

Questo esempio restituisce la deviazione standard degli interi in una finestra di corrispondenza.

// This rule creates a detection when the file size stddev in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.0 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 2

Esempio 2

Questo esempio restituisce la deviazione standard dei valori float in una finestra di corrispondenza.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.488686 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 2

Esempio 3

Questo esempio restituisce la deviazione standard in una finestra di corrispondenza contenente numeri negativi.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 48.644972 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 2

Esempio 4

Questo esempio restituisce una deviazione standard pari a zero quando tutti i valori nella finestra di corrispondenza sono uguali.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 2

Esempio 5

Questo esempio restituisce la deviazione standard di una finestra di corrispondenza contenente numeri positivi e negativi.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

window.variance

Supportato in:

Regole

window.variance(values)

Descrizione

Questa funzione restituisce la varianza specificata dei valori di input.

Tipi di dati Param

INT|FLOAT

Tipo restituito

FLOAT

Esempi di codice

Esempio 1

Questo esempio restituisce la varianza di tutti gli interi.

// This rule creates a detection when the file size variance in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 16 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 10

Esempio 2

Questo esempio restituisce la varianza di tutti i valori float.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 20.148300 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 10

Esempio 3

Questo esempio restituisce la varianza dei numeri negativi.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 2366.333333 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 10

Esempio 4

Questo esempio restituisce un valore di varianza ridotto.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [0.000000, 0.000000, 0.000100].
condition:
  $e and #p1 > 10

Esempio 5

Questo esempio restituisce una varianza pari a zero.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 10

Esempio 6

Questo esempio restituisce la varianza di numeri positivi e negativi.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

Assegnazione di una funzione al 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 una funzione a un segnaposto presenta due limitazioni:

1. Ogni segnaposto nell'assegnazione della funzione al 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 uno e un solo evento. Tuttavia, negli argomenti di chiamata delle funzioni è possibile utilizzare più di un campo dello stesso evento. Ad esempio, è valido quanto segue:

   $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 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. 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 gli operatori not e 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 di prestazioni, il motore di rilevamento limita l'utilizzo degli elenchi di riferimento.

• Numero massimo di istruzioni in in una regola, con o senza operatori speciali: 7
• Istruzioni in massime con l'operatore regex: 4
• Istruzioni in massime 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 del tipo visualizzati ti aiutano a rivedere la regola in modo da assicurarti 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 delle regole con più eventi contengono esempi di eventi per fornire il contesto sui relativi eventi che hanno causato il rilevamento. Esiste un limite di massimo 10 campioni di eventi per ogni variabile evento definita nella regola. Ad esempio, se una regola definisce due variabili evento, ogni rilevamento può avere fino a 20 esempi di eventi. Il limite si applica a ogni variabile evento separatamente. Se una variabile evento ha due eventi applicabili in questo rilevamento e l'altra variabile evento ne ha 15 applicabili, il rilevamento risultante contiene 12 campioni di eventi (2 + 10).

Eventuali campioni di eventi superiori al limite vengono omessi dal rilevamento.

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

Se stai visualizzando i rilevamenti nell'interfaccia utente, puoi scaricare tutti i sample di eventi per un rilevamento. Per ulteriori informazioni, vedi Scaricare gli eventi.