Sintassi del linguaggio YARA-L 2.0
Questa sezione descrive gli elementi principali della sintassi YARA-L. Vedi anche Panoramica del linguaggio YARA-L 2.0.
Struttura della regola
Per YARA-L 2.0, devi specificare dichiarazioni, definizioni e utilizzi delle variabili nel seguente ordine:
- meta
- eventi
- match (facoltativo)
- outcome (facoltativo)
- condizione
- opzioni (facoltativo)
Il seguente esempio illustra 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, ognuna delle quali 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 di 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 unione 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 di variabile. 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 viene 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.Indirettamente tramite un join transitivo che coinvolge solo un campo evento (vedi dichiarazione di variabile per una definizione di "join transitivo"). 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
Tuttavia, ecco alcuni esempi di sezioni events
non valide.
events:
// Event to arithmetic comparison is an invalid join condition for $e1 and $e2.
$e1.principal.port = $e2.src.port + 1
events:
$e1.src.ip = $ip
$e2.target.ip = $ip
$e3.about.ip = "192.1.2.0" //$e3 is not joined with $e1 or $e2.
events:
$e1.src.port = $port
// Arithmetic to placeholder comparison is an invalid transitive join condition.
$e2.principal.port + 800 = $port
Sintassi della sezione 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 di tempo da utilizzare per correlare gli eventi dopo la parola chiave
over
. Gli eventi al di fuori della durata vengono ignorati. Utilizza la seguente sintassi per specificare la durata del tempo:
<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 vengono correlati e pertanto vengono ignorati dalla regola.
Ecco un altro esempio di sezione match
valida:
$user over 1h
Questa istruzione restituisce $user
quando la regola trova una corrispondenza. La finestra temporale specificata è di 1 ora. Gli eventi 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 vengono correlati. La regola non li considera un rilevamento.
Gli esempi seguenti illustrano sezioni non valide match
:
var1, var2 over 5m // invalid variable name
$user 1h // missing keyword
Gestione del valore zero nella sezione Corrispondenza
Rules Engine filtra implicitamente i valori pari a 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).
Il seguente esempio illustra le regole che filtrano i valori zero.
rule ZeroValuePlaceholderExample {
meta:
events:
// Because $host is used in the match section, the rule behaves
// as if the following predicate was added to the events section:
// $host != ""
$host = $e.principal.hostname
// Because $otherPlaceholder was not used in the match section,
// there is no implicit filtering of zero values for $otherPlaceholder.
$otherPlaceholder = $e.principal.ip
match:
$host over 5m
condition:
$e
}
Tuttavia, se un segnaposto viene assegnato a una funzione, le regole non filtrano implicitamente i valori zero dei segnaposto utilizzati nella sezione di corrispondenza. Il seguente esempio illustra le regole che filtrano i valori pari a zero:
rule ZeroValueFunctionPlaceholder {
meta:
events:
// Even though $ph is used in the match section, there is no
// implicit filtering of zero values for $ph, because $ph is assigned to a function.
$ph = re.capture($e.principal.hostname, "some-regex")
match:
$ph over 5m
condition:
$e
}
Per disattivare il filtro implicito dei valori zero,
puoi utilizzare l'opzione allow_zero_values
nella sezione delle opzioni.
Finestra di hopping
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 di 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
su 30m
, un possibile insieme di finestre di hop sovrapposte
che potrebbero 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 di finestre di salto 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 salto 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 di 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 mobile dopo
l'evento e2
.
Specifica le finestre scorrevoli nella sezione match
di una regola nel seguente modo:
<match-var-1>, <match-var-2>, ... over <duration> before|after <pivot-event-var>
La variabile dell'evento pivot è la variabile dell'evento su cui si basano le finestre mobili. 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 scorrevole:
$var1, $var2 over 5m after $e1
$user over 1h before $e2
Vedi un esempio di regola della finestra a scorrimento.
Ti consigliamo di non utilizzare finestre scorrevoli per le regole a evento singolo, perché sono progettate per rilevare più eventi. Se una delle tue regole rientra in questa categoria, ti consigliamo una delle seguenti soluzioni alternative:
- Converti la regola in modo che utilizzi più variabili evento e aggiorna la sezione delle condizioni se la regola richiede più di un'occorrenza dell'evento.
- Se vuoi, valuta la possibilità di aggiungere filtri per timestamp anziché utilizzare una finestra mobile.
Ad esempio,
$permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
- Se vuoi, valuta la possibilità di aggiungere filtri per timestamp anziché utilizzare una finestra mobile.
Ad esempio,
- Rimuovi la finestra scorrevole.
Sintassi della sezione Risultato
Nella sezione outcome
, puoi definire fino a 20 variabili di risultato con
nomi arbitrari. Questi risultati verranno memorizzati nei rilevamenti generati dalla regola. Ogni rilevamento può avere valori diversi per i risultati.
Il nome del risultato, $risk_score
, è speciale. Puoi definire facoltativamente un
risultato con questo nome e, se lo fai, deve essere di tipo intero o float. Se compilato,
risk_score
verrà mostrato nella
visualizzazione Enterprise Insights per
gli avvisi provenienti dal rilevamento delle regole.
Se non includi una variabile $risk_score
nella sezione 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
è impostato su 15.
Il valore di $risk_score
è 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, determinato dall'espressione utilizzata per calcolarla. Sono supportati i seguenti tipi di dati sugli esiti:
- integer
- float
- 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. Le condizioni vengono specificate 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, restituisci THEN_CLAUSE, altrimenti restituisci ELSE_CLAUSE".
BOOL_CLAUSE deve restituire un valore booleano. Un'espressione BOOL_CLAUSE assume una
forma simile alle espressioni nella sezione events
. Ad esempio, può
contenere:
Nomi dei campi UDM con operatore di confronto, ad esempio:
if($context.graph.entity.user.title = "Vendor", 100, 0)
variabile segnaposto definita nella sezione
events
, ad esempio:if($severity = "HIGH", 100, 0)
un'altra variabile di risultato definita nella sezione
outcome
, ad esempio:if($risk_score > 20, "HIGH", "LOW")
funzioni che restituiscono un valore booleano, ad esempio:
if(re.regex($e.network.email.from, `.*altostrat.com`), 100, 0)
cercare in un elenco di riferimento, ad esempio:
if($u.principal.hostname in %my_reference_list_name, 100, 0)
confronto dell'aggregazione, ad esempio:
if(count($login.metadata.event_timestamp.seconds) > 5, 100, 0)
THEN_CLAUSE ed ELSE_CLAUSE devono essere dello stesso tipo di dati. Supportiamo numeri interi, numeri in virgola mobile e stringhe.
Puoi omettere ELSE_CLAUSE se il tipo di dati è un numero intero o un numero in virgola mobile. Se omessa, la ELSE_CLAUSE restituisce 0. Ad esempio:
`if($e.field = "a", 5)` is equivalent to `if($e.field = "a", 5, 0)`
Devi fornire ELSE_CLAUSE se il tipo di dati è stringa o se THEN_CLAUSE è una variabile segnaposto o una variabile di risultato.
Operazioni matematiche
Puoi utilizzare le operazioni matematiche per calcolare il tipo di dati integer o float nelle sezioni outcome
e events
di una regola. Google Security Operations supporta addizione, sottrazione, moltiplicazione, divisione e modulo come operatori di primo livello in un calcolo.
Il seguente snippet è un esempio di calcolo nella sezione outcome
:
outcome:
$risk_score = max(100 + if($severity = "HIGH", 10, 5) - if($severity = "LOW", 20, 0))
Le operazioni matematiche sono consentite sui seguenti tipi di operandi, a condizione che ogni operando e l'intera espressione aritmetica siano aggregati correttamente (vedi Aggregazioni):
- Campi evento numerici
- Variabili segnaposto numeriche definite nella sezione
events
- Variabili di risultato numeriche definite nella sezione
outcome
- Funzioni che restituiscono numeri interi o numeri in virgola mobile
- Aggregazioni che restituiscono numeri interi o numeri in virgola mobile
Il modulo non è consentito per i numeri in virgola mobile.
Variabili segnaposto nei risultati
Quando calcoli le variabili di risultato, 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 risultato nelle espressioni di assegnazione del risultato
Le variabili risultato possono essere utilizzate per derivare altre variabili risultato, in modo simile alle variabili segnaposto definite nella sezione events
. Puoi fare riferimento a una variabile
di risultato nell'assegnazione di un'altra variabile di risultato con un token $
seguito
dal nome della variabile. Le variabili di risultato devono essere definite prima di poter essere utilizzate
nel testo della regola. Se utilizzate in un'espressione di assegnazione, le variabili di risultato non devono essere aggregate (vedi Aggregazioni).
Nell'esempio seguente, la variabile di risultato $risk_score
deriva il suo
valore dalla variabile di risultato $event_count
:
Esempio di più eventi:
match:
// This is a multi event rule with a match section.
$hostname over 5m
outcome:
// Aggregates all timestamp on login events in the 5 minute match window.
$event_count = count($login.metadata.event_timestamp.seconds)
// $event_count cannot be aggregated again.
$risk_score = if($event_count > 5, "SEVERE", "MODERATE")
// This is the equivalent of the 2 outcomes above combined.
$risk_score2 = if(count($login.metadata.event_timestamp.seconds) > 5, "SEVERE", "MODERATE")
condition:
$e
Le variabili risultato possono essere utilizzate in qualsiasi tipo di espressione sul lato destro di un'assegnazione del risultato, tranne nelle seguenti espressioni:
- Aggregazioni
Arrays.length()
chiamate di funzione- Con i modificatori
any
oall
Aggregazioni
I campi evento ripetuti sono valori non scalari. ovvero 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 molti 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).
Allo stesso modo, sia i campi evento non ripetuti sia quelli ripetuti utilizzati nella sezione dei risultati di una regola con una finestra di corrispondenza sono valori non scalari. Ad esempio, il seguente gruppo di regole raggruppa gli eventi utilizzando una sezione di corrispondenza e fa riferimento a un campo evento non ripetuto nella sezione dei risultati:
rule OutcomeAndMatchWindow{
...
match:
$userid over 5m
outcome:
$hostnames = array($e.principal.hostname)
...
}
Qualsiasi finestra di 5 minuti in cui viene eseguita la regola può contenere zero, uno o più eventi. La sezione Risultato
opera su tutti gli eventi in una finestra di corrispondenza. Qualsiasi variabile di campo evento a cui viene fatto riferimento nella sezione
risultato può puntare a zero, uno o più valori del campo in ogni evento nella finestra di corrispondenza.
Ad esempio, se una finestra di 5 minuti contiene 5 eventi $e
, $e.principal.hostname
nella sezione dei risultati indica cinque nomi host diversi. La variabile del campo evento
$e.principal.hostname
viene trattata come un valore non scalare nella sezione outcome
di questa regola.
Poiché le variabili di risultato devono sempre produrre un singolo valore scalare, qualsiasi valore non scalare da cui dipende un'assegnazione del risultato deve essere aggregato per produrre un singolo valore scalare. In una sezione dei risultati, i seguenti sono valori non scalari e devono essere aggregati:
- Campi evento (ripetuti o non ripetuti) quando la regola utilizza una sezione di corrispondenza
- Segnaposto evento (ripetuti o non ripetuti) quando la regola utilizza una sezione di corrispondenza
- Campi evento ripetuti quando la regola non utilizza una sezione di corrispondenza
- Segnaposto per eventi 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
funzioni di aggregazione nelle regole che non includono una sezione di corrispondenza. Tuttavia, nella maggior parte dei casi, queste aggregazioni restituiscono il valore sottoposto a wrapping, rendendole non necessarie.
Un'eccezione è l'aggregazione array()
, che puoi utilizzare per convertire esplicitamente un valore scalare in un array.
Le variabili di risultato vengono trattate come aggregazioni: non devono essere riaggregate quando vengono menzionate in un'altra assegnazione di risultato.
Puoi utilizzare le seguenti funzioni di aggregazione:
max()
: restituisce il valore massimo tra tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.min()
: restituisce il valore minimo tra tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.sum()
: restituisce la somma di tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.count_distinct()
: raccoglie tutti i valori possibili, quindi restituisce il conteggio distinto dei valori possibili.count()
: si comporta comecount_distinct()
, ma restituisce un conteggio non distinto dei valori possibili.array_distinct()
: raccoglie tutti i possibili valori distinti, quindi restituisce un elenco di questi valori. L'elenco dei valori distinti verrà troncato a 1000 elementi casuali. La deduplicazione per ottenere un elenco distinto viene applicata per prima, poi viene applicata la troncamento.array()
: si comporta comearray_distinct()
, ma restituisce un elenco non distinto di valori. Inoltre,tronca l'elenco dei valori a 1000 elementi casuali.period_start_for_max()
: inizio del periodo di tempo in cui si è verificato il massimo del valore elencato.period_start_for_min()
: inizio del periodo di tempo in cui si è verificato il minimo del valore elencato.
La funzione di aggregazione è importante quando una regola include una sezione condition
che specifica che devono esistere più eventi, perché la funzione di aggregazione 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 di aggregazione operano su più eventi. Supponiamo che i seguenti eventi abbiano generato un rilevamento:
event:
// UDM event 1
asset_id="asset-a"
event:
// UDM event 2
asset_id="asset-b"
event:
// UDM event 3
asset_id="asset-b"
I valori dei risultati saranno:
- $asset_id_count =
3
- $asset_id_distinct_count =
2
- $asset_id_list =
["asset-a", "asset-b", "asset-b"]
- $asset_id_distinct_list =
["asset-a", "asset-b"]
Cose da sapere quando utilizzi la sezione Risultato:
Altre note e limitazioni:
- La sezione
outcome
non può fare riferimento a una nuova variabile segnaposto che non è già stata definita nella sezioneevents
o nella sezioneoutcome
. - La sezione
outcome
non può utilizzare variabili evento che non sono state definite nella sezioneevents
. - La sezione
outcome
può utilizzare un campo evento che non è stato utilizzato nella sezioneevents
, a condizione che la variabile evento a cui appartiene il campo evento sia già stata definita nella sezioneevents
. - La sezione
outcome
può correlare solo le variabili evento che sono già state correlate nella sezioneevents
. Le correlazioni si verificano quando due campi evento di variabili evento diverse vengono equiparati.
Puoi trovare un esempio che utilizza la sezione dei risultati in Panoramica di YARA-L 2.0. Consulta Creare analisi sensibili al contesto per informazioni dettagliate sulla deduplicazione del rilevamento con la sezione dei risultati.
Sintassi della sezione Condizione
- specifica una condizione di corrispondenza per eventi e segnaposto definiti nella sezione
events
. Per ulteriori dettagli, consulta la sezione seguente, Condizioni per eventi e segnaposto. - (facoltativo) utilizza la parola chiave
and
per specificare una condizione di corrispondenza utilizzando le variabili di risultato definite nella sezioneoutcome
. Per ulteriori dettagli, consulta la sezione Condizioni di risultato.
Conteggio caratteri
Il carattere #
è un carattere speciale nella sezione condition
. Se viene utilizzato prima di qualsiasi 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
significa che la variabile c
deve verificarsi più di una volta.
Carattere valore
Il carattere $
è un carattere speciale nella sezione condition
. Se viene
utilizzato prima del nome di una variabile di risultato, rappresenta il valore di quel risultato.
Se viene utilizzato prima di qualsiasi nome di variabile segnaposto o evento (ad esempio,
$event
), rappresenta #event > 0
.
Istruzioni condizionali per eventi e segnaposto
Elenca i predicati delle condizioni per gli eventi e le variabili segnaposto utilizzando le parole chiave
and
o or
. Puoi utilizzare and
per unire qualsiasi combinazione di condizioni;
tuttavia, puoi utilizzare or
solo quando tutte le condizioni fanno riferimento alla stessa 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.
}
Condizioni con limiti e senza limiti
Le seguenti condizioni sono condizioni vincolate. Forzano l'esistenza della variabile evento associata, il che significa che almeno un'occorrenza dell'evento deve essere presente in qualsiasi rilevamento.
$var // equivalent to #var > 0
#var > n // where n >= 0
#var >= m // where m > 0
Le seguenti condizioni sono condizioni senza limiti. Consentono alla variabile evento associata di non esistere, il che significa che è possibile che non venga visualizzata alcuna occorrenza dell'evento in un rilevamento e qualsiasi riferimento ai campi della variabile evento restituirà un valore pari a zero. Le condizioni senza limiti possono essere utilizzate per rilevare l'assenza di un evento per un 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
Requisiti per l'inesistenza
Affinché una regola con non esistenza venga compilata, deve soddisfare i seguenti requisiti:
- Almeno un evento UDM deve avere una condizione delimitata (ovvero deve esistere almeno un evento UDM).
- Se un segnaposto ha una condizione senza limiti, deve essere associato ad almeno un evento UDM con limiti.
- Se un'entità ha una condizione senza limiti, deve essere associata ad almeno un evento UDM con limiti.
Considera la seguente regola con la sezione delle condizioni omessa:
rule NonexistenceExample {
meta:
events:
$u1.metadata.event_type = "NETWORK_CONNECTION" // $u1 is a UDM event.
$u2.metadata.event_type = "NETWORK_CONNECTION" // $u2 is a UDM event.
$e1.graph.metadata.entity_type = "FILE" // $e1 is an Entity.
$e2.graph.metadata.entity_type = "FILE" // $e2 is an Entity.
$user = $u1.principal.user.userid // Match variable is required for Multi-Event Rule.
// Placeholder Associations:
// u1 u2
// | \ /
// port ip
// | \
// e1 e2
$u1.target.port = $port
$e1.graph.entity.port = $port
$u1.principal.ip = $ip
$u2.target.ip = $ip
$e2.graph.entity.ip = $ip
// UDM-Entity Associations:
// u1 - u2
// | \ |
// e1 e2
$u1.metadata.event_type = $u2.metadata.event_type
$e1.graph.entity.hostname = $u1.principal.hostname
$e2.graph.entity.hostname = $u1.target.hostname
$e2.graph.entity.hostname = $u2.principal.hostname
match:
$user over 5m
condition:
<condition_section>
}
Di seguito sono riportati alcuni esempi validi per <condition_section>
:
$u1 and !$u2 and $e1 and $e2
- Tutti gli eventi e le entità UDM sono presenti nella sezione delle condizioni.
- Almeno un evento UDM è delimitato.
$u1 and !$u2 and $e1 and !$e2
$e2
non è limitato, il che è consentito perché è associato a$u1
, che è limitato. Se$e2
non era associato a$u1
, questo valore non è valido.
#port > 50 and #ip = 0
- Nella sezione della condizione non sono presenti eventi ed entità UDM, ma i segnaposto presenti coprono tutti gli eventi e le entità UDM.
$ip
è assegnato sia a$u1
che a$u2
e#ip = 0
è una condizione senza limiti. Tuttavia, le condizioni delimitate sono più forti di quelle illimitate. Poiché$port
è assegnato a$u1
e#port > 50
è una condizione limitata,$u1
è ancora limitato.
Di seguito sono riportati esempi non validi per <condition_section>
:
$u1 and $e1
- Ogni evento ed entità UDM visualizzato nella sezione Eventi deve essere visualizzato 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 secondo cui almeno un evento UDM è delimitato.
($u1 or #port < 50) and $u2 and $e1 and $e2
- La parola chiave
or
non è supportata con condizioni illimitate.
- La parola chiave
($u1 or $u2) and $e1 and $e2
- La parola chiave
or
non è supportata tra diverse variabili evento.
- La parola chiave
not $u1 and $u2 and $e1 and $e2
- La parola chiave
not
non è consentita per le condizioni di evento e segnaposto.
- La parola chiave
#port < 50 and #ip = 0
- I segnaposto presenti coprono tutti gli eventi e le entità UDM, ma tutte le condizioni sono illimitate. Ciò significa che nessuno degli eventi UDM è delimitato, pertanto la compilazione della regola non va a buon fine.
Condizionali del risultato
Elenca qui i predicati delle condizioni per le variabili di risultato, uniti alla parola chiave and
o or
oppure preceduti dalla parola chiave not
.
Specifica le condizioni del risultato in modo diverso a seconda del tipo di variabile del risultato:
integer: confronta con un valore letterale intero con gli operatori
=, >, >=, <, <=, !=
, ad esempio:$risk_score > 10
float: confronta 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")
Classificazione delle regole
Se specifichi un risultato condizionale in una regola con una sezione di corrispondenza, la regola verrà classificata come regola multievento ai fini della quota delle regole. Per saperne di più sulle classificazioni di eventi singoli e multipli, consulta Regola per evento singolo e Regola per più eventi.
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 questa opzione è abilitata o meno. Il valore predefinito è false
. Questa opzione è
disattivata 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 non filtrerà implicitamente i
valori zero dei segnaposto utilizzati nella sezione Corrispondenza, come
descritto in Gestione dei valori zero nella sezione Corrispondenza.
suppression_window
L'opzione suppression_window
ti consente di controllare la frequenza con cui una regola attiva un rilevamento. Impedisce alla stessa regola di generare più rilevamenti entro un intervallo di tempo specificato, anche se le condizioni della regola vengono soddisfatte più volte.
Il raggruppamento in finestre di eliminazione utilizza un approccio a finestra mobile, che elimina
i duplicati in una finestra di dimensioni fisse e non sovrapposte.
Facoltativamente, puoi fornire un suppression_key
per perfezionare ulteriormente le istanze
della regola che vengono eliminate nella finestra di eliminazione. Se non specificato, tutte le
istanze della regola vengono eliminate. Questa chiave è definita come variabile di risultato.
Nel seguente esempio, suppression_window
è impostato su 5m
e suppression_key
è
impostato sulla variabile $hostname
. Dopo che la regola attiva un rilevamento per
$hostname
, tutti gli ulteriori rilevamenti per $hostname
vengono soppressi per i successivi
cinque minuti. Tuttavia, se la regola viene attivata per un evento con un nome host diverso,
viene creata una rilevazione.
Il valore predefinito di suppression_window
è 0
, ovvero la finestra di soppressione
è disattivata per impostazione predefinita. Questa opzione funziona solo per le regole per singolo evento
che non hanno una sezione match
.
Esempio:
rule SuppressionWindowExample {
// Other rule sections
outcome:
$suppression_key = $hostname
options:
suppression_window = 5m
}
Regole di rilevamento composito
Il rilevamento composito in Google SecOps prevede il collegamento di più regole YARA-L. Questa sezione spiega come creare una regola composita. Per una panoramica dei rilevamenti compositi, vedi Panoramica dei rilevamenti compositi.
Struttura della regola
Le regole di rilevamento composite sono sempre regole a più eventi e seguono la stessa struttura e sintassi. Ai regole di rilevamento composite si applicano i seguenti requisiti:
- Le regole composite devono utilizzare una sezione
match
per definire le condizioni di attivazione del rilevamento. - Le regole che utilizzano sia i campi di rilevamento sia gli eventi UDM devono unire esplicitamente queste origini dati.
Per informazioni sulle limitazioni delle regole, vedi Limitazioni.
Utilizzare i rilevamenti come input per le regole
Le regole composite possono fare riferimento ai rilevamenti delle regole generati da qualsiasi regola personalizzata o curata. Google SecOps offre due metodi per farlo.
Contenuti di rilevamento dei riferimenti utilizzando variabili di risultato, variabili di corrispondenza o metaetichette
Per accedere ai dati di un rilevamento senza fare riferimento agli eventi UDM originali,
utilizza le variabili outcome
, le variabili match
o le etichette meta
. Consigliamo questo approccio perché offre una maggiore flessibilità e una migliore compatibilità tra i diversi tipi di regole.
Ad esempio, più regole possono memorizzare una stringa (come un URL, un nome file o
una chiave del registro) in una variabile outcome
comune se stai cercando quella stringa
in contesti diversi. Per accedere a questa stringa da una regola composita, inizia
con detection
e individua le informazioni pertinenti utilizzando gli elementi della
risorsa Raccolta.
Esempio: Supponiamo che una regola di rilevamento produca le seguenti informazioni:
- Variabile di risultato:
dest_domain = "cymbal.com"
- Campo UDM:
target.hostname = "cymbal.com"
Nella regola composita, puoi accedere a questi dati utilizzando i seguenti percorsi:
detection.detection.outcomes["dest_domain"]
per accedere alladest_domain
variabile di risultato.detection.collection_elements.references.event.target.hostname
per accedere al campo UDMtarget.hostname
.detection.time_window.start_time.seconds
per accedere al timestamp di rilevamento.
L'API Collection e l'API SecurityResult
forniscono l'accesso a entrambe:
- Valori dei metadati e dei risultati del rilevamento (
detection.detection
) - Eventi UDM sottostanti delle regole a cui viene fatto riferimento (
collection_elements
)
Fai riferimento ai contenuti di rilevamento utilizzando l'ID regola o il nome della regola
Puoi fare riferimento a una regola in base al nome o all'ID. Ti consigliamo questo
approccio quando la logica di rilevamento dipende da regole specifiche. Il riferimento
a regole pertinenti per nome o ID migliora il rendimento ed evita i timeout
riducendo i dati analizzati. Ad esempio, puoi eseguire query direttamente sui campi come
target.url
o principal.ip
da un rilevamento precedente noto.
Fai riferimento a una regola in base all'ID regola (consigliato): utilizza il campo
detection.detection.rule_id
per fare riferimento a una regola in base all'ID. Puoi trovare l'ID regola nell'URL della regola in Google SecOps. Le regole generate dagli utenti hanno ID nel formatoru_UUID
, mentre i rilevamenti curati hanno ID nel formatour_UUID
. Ad esempio:detection.detection.rule_id = "ru_e0d3f371-6832-4d20-b0ad-1f4e234acb2b"
Fai riferimento a una regola in base al nome:utilizza il campo
detection.detection.rule_name
per fare riferimento a una regola in base al nome. Puoi specificare il nome esatto della regola o utilizzare un'espressione regolare per trovarla. Ad esempio:detection.detection.rule_name = "My Rule Name"
detection.detection.rule_name = "/PartOfName/"
Nota:ti consigliamo di utilizzare gli ID regola per i riferimenti perché sono univoci e non cambiano. I nomi delle regole possono essere modificati, il che potrebbe potenzialmente interrompere il rilevamento composito.
Combinare eventi e rilevamenti
Le regole composite possono combinare diverse origini dati, inclusi eventi UDM, dati del grafico delle entità e campi di rilevamento. Si applicano le seguenti linee guida:
- Utilizza variabili distinte per origine: assegna variabili evento uniche a ogni origine dati (ad esempio,
$e
per gli eventi,$d
per i rilevamenti), dove l'origine dati include eventi, entità e rilevamenti. - Unire le origini in base al contesto condiviso: collega le origini dati utilizzando valori comuni, come ID utente, indirizzi IP o nomi di dominio nelle condizioni della regola.
- Definisci una finestra di corrispondenza: includi sempre una clausola
match
con una finestra temporale non superiore a 48 ore.
Ad esempio:
rule CheckCuratedDetection_with_EDR_and_EG {
meta:
author = "noone@cymbal.com"
events:
$d.detection.detection.rule_name = /SCC: Custom Modules: Configurable Bad Domain/
$d.detection.collection_elements.references.event.network.dns.questions.name = $domain
$d.detection.collection_elements.references.event.principal.asset.hostname = $hostname
$e.metadata.log_type = "LIMACHARLIE_EDR"
$e.metadata.product_event_type = "NETWORK_CONNECTIONS"
$domain = re.capture($e.principal.process.command_line, "\\s([a-zA-Z0-9.-]+\\.[a-zA-Z0-9.-]+)$")
$hostname = re.capture($e.principal.hostname, "([^.]*)")
$prevalence.graph.metadata.entity_type = "DOMAIN_NAME"
$prevalence.graph.metadata.source_type = "DERIVED_CONTEXT"
$prevalence.graph.entity.hostname = $domain
$prevalence.graph.entity.domain.prevalence.day_count = 10
$prevalence.graph.entity.domain.prevalence.rolling_max <= 5
$prevalence.graph.entity.domain.prevalence.rolling_max > 0
match:
$hostname over 1h
outcome:
$risk_score = 80
$CL_target = array($domain)
condition:
$e and $d and $prevalence
}
Creare rilevamenti compositi sequenziali
I rilevamenti compositi sequenziali identificano pattern di eventi correlati in cui la sequenza di rilevamenti è importante, ad esempio un rilevamento di un tentativo di accesso con attacco di tipo brute force, seguito da un accesso riuscito. Questi pattern possono combinare più rilevamenti di base, eventi UDM non elaborati o entrambi.
Per creare un rilevamento composito sequenziale, devi applicare l'ordine all'interno della regola. Per applicare la sequenza prevista, utilizza uno dei seguenti metodi:
- Finestre scorrevoli:definisci la sequenza di rilevamenti utilizzando le finestre scorrevoli
nelle condizioni
match
. - Confronti dei timestamp:confronta i timestamp dei rilevamenti all'interno della logica della regola per verificare che si verifichino nell'ordine selezionato.
Ad esempio:
events:
$d1.detection.detection.rule_name = "fileEvent_rule"
$userid = $d1.detection.detection.outcomes["user"]
$hostname = $d1.detection.detection.outcomes["hostname"]
$d2.detection.detection.rule_name = "processExecution_rule"
$userid = $d2.detection.detection.outcomes["user"]
$hostname = $d2.detection.detection.outcomes["hostname"]
$d3.detection.detection.rule_name = "networkEvent_rule"
$userid = $d3.detection.detection.outcomes["user"]
$hostname = $d3.detection.detection.outcomes["hostname"]
$d3.detection.collection_elements.references.event.metadata.event_timestamp.seconds > $d2.detection.collection_elements.references.event.metadata.event_timestamp.seconds
match:
$userid over 24h after $d1
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")
"email@google.org" = re.replace($e.network.email.from, "com", "org")
Se entrambi i lati sono valori letterali, viene considerato un errore di compilazione.
Funzioni
Alcune espressioni di funzione restituiscono un valore booleano, che può essere utilizzato come predicato individuale 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 degli eventi. Per ulteriori dettagli, consulta la sezione Elenchi di riferimenti.
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 dal più alto al più basso è not
, and
, or
.
Ad esempio, "a or b and c" viene valutato come "a or (b and c)" quando gli operatori or
e and
sono definiti in modo esplicito nell'espressione.
Nella sezione events
, i predicati vengono uniti utilizzando l'operatore and
se non è definito esplicitamente un operatore.
L'ordine di valutazione potrebbe essere diverso se l'operatore and
è implicito nell'espressione.
Ad esempio, considera le seguenti espressioni di confronto in cui or
è definito in modo esplicito. 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
. Il risultato è che l'ordine di valutazione cambia.
Tipi enumerati
Puoi utilizzare gli operatori con i tipi enumerati. Può essere applicato alle regole per semplificare e ottimizzare (utilizzare l'operatore anziché gli elenchi di riferimento) il rendimento.
Nell'esempio seguente, "USER_UNCATEGORIZED" e "USER_RESOURCE_DELETION" corrispondono a 15000 e 15014, quindi la regola cercherà tutti gli eventi elencati:
$e.metadata.event_type >= "USER_CATEGORIZED" and $e.metadata.event_type <= "USER_RESOURCE_DELETION"
Elenco 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 stringa o un'espressione regolare, puoi aggiungere nocase alla fine dell'espressione per ignorare la distinzione tra maiuscole e minuscole.
$e.principal.hostname != "http-server" nocase
$e1.principal.hostname = $e2.target.hostname nocase
$e.principal.hostname = /dns-server-[0-9]+/ nocase
re.regex($e.target.hostname, `client-[0-9]+`) nocase
Non può essere utilizzato 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 Unified Data Model (UDM), alcuni campi sono etichettati come ripetuti, il che indica che sono elenchi di valori o altri tipi di messaggi.
Campi ripetuti ed espressioni booleane
Esistono due tipi di espressioni booleane che agiscono sui campi ripetuti:
- Modificato
- 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 l'utilizzo dei modificatori any
e all
nelle espressioni.
tutte
Se un qualsiasi elemento del campo ripetuto soddisfa la condizione, l'evento nel suo complesso soddisfa la condizione.
event_original
soddisfaany $e.principal.ip = "192.0.2.1"
.event_original
non riesce aany $e.repeated_field.field_a = "9.9.9.9
.
tutti
Se tutti gli elementi del campo ripetuto soddisfano la condizione, l'evento nel suo complesso soddisfa la condizione.
event_original
soddisfanet.ip_in_range_cidr(all $e.principal.ip, "192.0.2.0/8")
.event_original
non riesce aall $e.principal.ip = "192.0.2.2"
.
Quando scrivi una condizione con any
o all
, tieni presente che la negazione della condizione
con not
potrebbe non avere lo stesso significato dell'utilizzo dell'operatore negato.
Ad esempio:
not all $e.principal.ip = "192.168.12.16"
verifica se non tutti gli indirizzi IP corrispondono a192.168.12.16
, il che significa che la regola verifica se almeno un indirizzo IP non corrisponde a192.168.12.16
.all $e.principal.ip != "192.168.12.16"
verifica che tutti gli indirizzi IP non corrispondano a192.168.12.16
, il che significa che la regola verifica che nessun indirizzo IP corrisponda a192.168.12.16
.
Limitazioni:
- Gli operatori
any
eall
sono compatibili solo con i campi ripetuti (non scalari). any
eall
non possono essere utilizzati per unire due campi ripetuti. Ad esempio,any $e1.principal.ip = $e2.principal.ip
non è valido.- Gli operatori
any
eall
non sono supportati con l'espressione dell'elenco di riferimento.
Espressioni non modificate
Con le espressioni non modificate, ogni elemento nel campo ripetuto viene trattato singolarmente. Se il campo ripetuto di un evento contiene n elementi, la regola viene applicata a n copie dell'evento, in cui ogni copia ha uno degli elementi del campo ripetuto. Queste copie sono temporanee e non vengono archiviate.
La regola viene applicata alle seguenti copie:
copia dell'evento | principal.ip | principal.hostname |
---|---|---|
event_copy_1 | "192.0.2.1" | "host" |
event_copy_2 | "192.0.2.2" | "host" |
event_copy_3 | "192.0.2.3" | "host" |
Se la copia di un evento 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 in un campo ripetuto, la copia dell'evento deve soddisfarle tutte. I seguenti esempi di regole utilizzano il set di dati di esempio precedente per dimostrare questo comportamento.
La seguente regola restituisce una corrispondenza quando viene eseguita sul set di dati di esempio event_original
, perché event_copy_1
soddisfa tutti i predicati 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 se eseguita sul set di dati di esempio event_original
, perché non esiste una copia dell'evento in $e.principal.ip
che soddisfi tutti i predicati dell'evento.
rule repeated_field_2 {
meta:
events:
$e.principal.ip = "192.0.2.1"
$e.principal.ip = "192.0.2.2"
condition:
$e
}
Le espressioni modificate nei campi ripetuti sono compatibili con le espressioni non modificate nei campi ripetuti perché l'elenco degli elementi è lo stesso per ogni copia dell'evento. Considera la seguente regola:
rule repeated_field_3 {
meta:
events:
any $e.principal.ip = "192.0.2.1"
$e.principal.ip = "192.0.2.3"
condition:
$e
}
La regola viene applicata alle seguenti copie:
copia dell'evento | principal.ip | any $e.principal.ip |
---|---|---|
event_copy_1 | "192.0.2.1" | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
event_copy_2 | "192.0.2.2" | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
event_copy_3 | "192.0.2.3" | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
In questo caso, tutte le copie soddisfano any $e.principal.ip = "192.0.2.1"
, ma solo event_copy_3
soddisfa $e.principal.ip = "192.0.2.3". Di conseguenza, l'evento nel suo complesso corrisponderà.
Un altro modo per pensare a questi tipi di espressioni è:
- Le espressioni nei campi ripetuti che utilizzano
any
oall
operano sull'elenco inevent_original
. - Le espressioni nei campi ripetuti che non utilizzano
any
oall
operano su singoli eventievent_copy_n
.
Campi ripetuti e segnaposto
I campi ripetuti funzionano con le assegnazioni dei segnaposto. Analogamente alle espressioni non modificate nei campi ripetuti, viene creata una copia dell'evento per ogni elemento. Utilizzando lo stesso esempio di event_copy
, il segnaposto assume il valore del campo ripetuto di event_copy_n
per ciascuna delle copie dell'evento in cui n è il numero di copia dell'evento. Se il segnaposto viene utilizzato nella sezione della corrispondenza, 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.
Gli esempi di eventi della corrispondenza contengono un singolo elemento, event_original
.
// Generates 1 match.
rule repeated_field_placeholder1 {
meta:
events:
$ip = $e.principal.ip
$ip = "192.0.2.1"
$host = $e.principal.hostname
match:
$host over 5m
condition:
$e
}
L'esempio seguente genera tre corrispondenze. Il segnaposto $ip
è uguale
a valori diversi per ciascuna delle diverse copie di event_copy_n
.
Il raggruppamento viene eseguito su $ip
perché si trova nella sezione della corrispondenza. Pertanto, ottieni tre corrispondenze
in cui ogni corrispondenza ha un valore diverso per la variabile di corrispondenza $ip
. Ogni corrispondenza ha lo stesso
esempio di evento: un singolo elemento, event_original
.
// Generates 3 matches.
rule repeated_field_placeholder2 {
meta:
events:
$ip = $e.principal.ip
net.ip_in_range_cidr($ip, "192.0.2.0/8") // Checks if IP matches 192.x.x.x
match:
$ip over 5m
condition:
$e
}
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 dei risultati, il risultato viene calcolato utilizzando solo gli elementi che hanno soddisfatto le sezioni precedenti.
Considera la seguente regola:
rule outcome_repeated_field_placeholder {
meta:
events:
$ip = $e.principal.ip
$ip = "192.0.2.1" or $ip = "192.0.2.2"
$host = $e.principal.hostname
match:
$host over 5m
outcome:
$o = array_distinct($ip)
condition:
$e
}
L'esecuzione di questa regola prevede 4 fasi. La prima fase è la copia dell'evento:
copia dell'evento | $ip | $host | $e |
---|---|---|---|
event_copy_1 | "192.0.2.1" | "host" | event_id |
event_copy_2 | "192.0.2.2" | "host" | event_id |
event_copy_3 | "192.0.2.3" | "host" | event_id |
La sezione degli eventi filtrerà quindi le righe che non corrispondono ai filtri:
copia dell'evento | $ip | $host | $e |
---|---|---|---|
event_copy_1 | "192.0.2.1" | "host" | event_id |
event_copy_2 | "192.0.2.2" | "host" | event_id |
event_copy_3
viene filtrato perché "192.0.2.3"
non soddisfa $ip = "192.0.2.1" or $ip = "192.0.2.2"
.
La sezione della partita verrà quindi raggruppata in base alle variabili della partita e la sezione del risultato eseguirà l'aggregazione di ogni gruppo:
$host | $o | $e |
---|---|---|
"host" | ["192.0.2.1", "192.0.2.2"] | event_id |
$o = array_distinct($ip)
viene calcolato utilizzando $ip
della fase precedente e non della fase di copia dell'evento.
Infine, la sezione delle condizioni filtrerà ogni gruppo. Poiché questa regola verifica solo l'esistenza di $e, la riga precedente produrrà un singolo rilevamento.
$o
non contiene tutti gli elementi di $e.principal.ip
perché non tutti gli elementi soddisfano tutte le condizioni nella sezione degli eventi. Tuttavia, tutti gli elementi di e.principal.ip
verranno visualizzati nell'esempio di evento perché l'esempio di evento utilizza event_original
.
Indicizzazione degli array
Puoi eseguire l'indicizzazione degli array sui campi ripetuti. Per accedere all'ennesimo elemento del campo ripetuto, utilizza la sintassi dell'elenco standard (gli elementi sono indicizzati a partire da 0). Un elemento fuori dai limiti restituisce il valore predefinito.
$e.principal.ip[0] = "192.168.12.16"
$e.principal.ip[999] = ""
Se ci sono meno di 1000 elementi, il risultato ètrue
.
Limitazioni:
- Un indice deve essere un valore letterale intero non negativo. Ad esempio,
$e.principal.ip[-1]
non è valido. - I valori di tipo
int
(ad esempio, un segnaposto impostato suint
) non vengono conteggiati. - L'indicizzazione degli array non può essere combinata con
any
oall
. Ad esempio,any $e.intermediary.ip[0]
non è valido. - L'indicizzazione degli array non può essere combinata con la sintassi della mappa. Ad esempio,
$e.additional.fields[0]["key"]
non è valido. - Se il percorso del campo contiene più campi ripetuti, tutti i campi ripetuti devono utilizzare l'indicizzazione degli array. Ad esempio,
$e.intermediary.ip[0]
non è valido perchéintermediary
eip
sono entrambi campi ripetuti, ma esiste un solo indice perip
.
Messaggi ripetuti
Quando un campo message
viene ripetuto, l'effetto indesiderato è quello di ridurre la probabilità di una corrispondenza. Ciò è illustrato negli esempi seguenti.
Considera il seguente evento:
event_repeated_message {
// about is a repeated message field.
about {
// ip is a repeated string field.
ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]
hostname: "alice"
}
about {
hostname: "bob"
}
}
Come indicato per le espressioni non modificate nei campi ripetuti, viene creata una copia temporanea dell'evento per ogni elemento del campo ripetuto. Considera la seguente regola:
rule repeated_message_1 {
meta:
events:
$e.about.ip = "192.0.2.1"
$e.about.hostname = "bob"
condition:
$e
}
La regola viene applicata alle seguenti copie:
copia dell'evento | about.ip | about.hostname |
---|---|---|
event_copy_1 | "192.0.2.1" | "alice" |
event_copy_2 | "192.0.2.2" | "alice" |
event_copy_3 | "192.0.2.3" | "alice" |
event_copy_4 | "" | "bob" |
L'evento non corrisponde alla regola perché non esiste una copia dell'evento che soddisfi tutte le espressioni.
Messaggi ripetuti e indicizzazione degli array
Un altro comportamento imprevisto può verificarsi quando si utilizza l'indicizzazione degli array con espressioni non modificate nei campi dei messaggi ripetuti. Considera la seguente regola di esempio che utilizza l'indicizzazione degli array:
rule repeated_message_2 {
meta:
events:
$e.about.ip = "192.0.2.1"
$e.about[1].hostname = "bob"
condition:
$e
}
La regola viene applicata alle seguenti copie:
copia dell'evento | about.ip | about[1].hostname |
---|---|---|
event_copy_1 | "192.0.2.1" | "bob" |
event_copy_2 | "192.0.2.2" | "bob" |
event_copy_3 | "192.0.2.3" | "bob" |
event_copy_4 | "" | "bob" |
Poiché event_copy_1
soddisfa tutte le espressioni in repeated_message_2
, l'evento corrisponde alla regola.
Ciò può portare a un comportamento imprevisto perché la regola repeated_message_1
non aveva l'indicizzazione degli array e non ha prodotto corrispondenze, mentre la regola repeated_message_2
utilizzava l'indicizzazione degli array e ha prodotto una corrispondenza.
Commenti
Indica i commenti con due caratteri barra (// comment
) o i commenti su più righe delimitati da caratteri barra asterisco (/* comment */
), come in C.
Valori letterali
Sono supportati numeri interi e valori in virgola mobile non negativi, stringhe, valori booleani e valori letterali di espressioni regolari.
Stringhe e valori letterali di 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.
Virgolette doppie (") - Utilizzale per le stringhe normali. Devono includere caratteri di escape.
Ad esempio: "hello\tworld" —\t viene interpretato come una tabulazioneApici inversi (`) - Utilizzali per interpretare tutti i caratteri letteralmente.
Ad esempio: `hello\tworld` —\t non viene interpretato come tabulazione
Per le espressioni regolari, hai due opzioni.
Se vuoi utilizzare le espressioni regolari direttamente senza la funzione re.regex()
, utilizza /regex/
per i valori letterali delle espressioni regolari.
Puoi anche utilizzare i valori letterali stringa come valori letterali di espressioni regolari quando utilizzi la funzione re.regex()
. Tieni presente che per i valori letterali stringa tra virgolette doppie, devi eseguire l'escape dei caratteri barra rovesciata con caratteri barra rovesciata, il che può sembrare strano.
Ad esempio, le seguenti espressioni regolari sono equivalenti:
re.regex($e.network.email.from, `.*altostrat\.com`)
re.regex($e.network.email.from, ".*altostrat\\.com")
$e.network.email.from = /.*altostrat\.com/
Google consiglia di utilizzare i caratteri di apice inverso per le stringhe nelle espressioni regolari per facilitarne la leggibilità.
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 entità. Specifica le condizioni per le variabili evento nella sezione
events
. Identifichi le variabili evento utilizzando un nome, l'origine evento e i campi evento. Le origini consentite sonoudm
(per gli eventi normalizzati) egraph
(per gli eventi entità). Se la sorgente viene omessa,udm
viene impostata come sorgente predefinita. I campi evento sono rappresentati come una catena di .<field name> (ad esempio, $e.field1.field2). Le catene di campi evento iniziano sempre dalla sorgente di primo livello (UDM o entità).Variabili di corrispondenza: dichiarale nella sezione
match
. Le variabili di corrispondenza diventano campi di raggruppamento per la query, in quanto 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 sezioneevents
.Variabili segnaposto: dichiarale e definiscile nella sezione
events
. Le variabili segnaposto sono simili alle variabili di corrispondenza. Tuttavia, puoi utilizzare le variabili segnaposto nella sezionecondition
per specificare le condizioni di corrispondenza.
Utilizza le variabili di corrispondenza e le variabili segnaposto per dichiarare le relazioni tra i campi evento tramite condizioni di unione transitive (per maggiori dettagli, consulta la sintassi della sezione Eventi).
Parole chiave
Le parole chiave in YARA-L 2.0 non distinguono tra maiuscole e minuscole. Ad esempio, and
o AND
sono
equivalenti. I nomi delle variabili non devono essere in conflitto con le parole chiave. Ad esempio,
$AND
o $outcome
non è 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 alle mappe per struct ed etichette.
Strutture ed etichette
Alcuni campi UDM utilizzano il tipo di dati Struct o Label.
Per cercare una coppia chiave-valore specifica sia in Struct che in Label, utilizza la sintassi standard della mappa:
// A Struct field.
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// A Label field.
$e.metadata.ingestion_labels["MetadataKeyDeletion"] = "startup-script"
L'accesso alla mappa restituisce sempre una stringa.
Richieste supportate
Di seguito sono riportati i casi d'uso delle parole chiave supportate.
Sezione Eventi e risultati
// Using a Struct field in the events section
events:
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// Using a Label field in the outcome section
outcome:
$value = array_distinct($e.metadata.ingestion_labels["MetadataKeyDeletion"])
Assegnare un valore della mappa a un segnaposto
$placeholder = $u1.metadata.ingestion_labels["MetadataKeyDeletion"]
Utilizzo di un campo mappa in una condizione di unione
// using a Struct field in a join condition between two udm events $u1 and $u2
$u1.metadata.event_type = $u2.udm.additional.fields["pod_name"]
Richieste non supportate
Le mappe non sono supportate nei seguenti casi.
Combinazione di 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 stringa. Nel caso di tipi di dati Struct, la sintassi della mappa può accedere solo alle chiavi i cui valori sono stringhe. Non è possibile accedere alle chiavi i cui valori sono altri tipi primitivi come gli interi.
Gestione dei valori duplicati
Gli accessi alla 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.
Ciò può verificarsi in uno dei seguenti casi:
Un'etichetta ha una chiave duplicata.
La struttura dell'etichetta rappresenta una mappa, ma non impone l'unicità della chiave. Per convenzione, una mappa deve avere chiavi univoche, pertanto Google SecOps 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 padre.
Un campo ripetuto può contenere un'etichetta come campo secondario. Due voci diverse nel campo ripetuto di primo livello potrebbero contenere etichette che hanno la stessa chiave. Il testo della regola
$e.security_result.rule_labels["key"]
restituirebbe il primo valore possibile,val3
, se eseguito sull'esempio di dati seguente: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 del motore di rilevamento.
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
arrays.concat(string_array, string_array)
Descrizione
Restituisce un nuovo array di stringhe copiando gli elementi dagli array di stringhe originali.
Tipi di dati dei parametri
ARRAY_STRINGS
, ARRAY_STRINGS
Tipo restituito
ARRAY_STRINGS
Esempi di codice
Esempio 1
L'esempio seguente concatena due array di stringhe diversi.
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
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 dei parametri
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 nulli 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 nulli e nessun delimitatore.
arrays.join_string(["foo", "bar"]) = "foobar"
arrays.length
arrays.length(repeatedField)
Descrizione
Restituisce il numero di elementi del campo ripetuto.
Tipi di dati dei parametri
LIST
Tipo restituito
NUMBER
Esempi di codice
Esempio 1
Restituisce il numero di elementi del campo ripetuto.
arrays.length($e.principal.ip) = 2
Esempio 2
Se lungo il percorso sono presenti più campi ripetuti, restituisce il numero totale di elementi del campo ripetuto.
arrays.length($e.intermediary.ip) = 3
arrays.max
arrays.max(array_of_ints_or_floats)
Descrizione
Restituisce l'elemento più grande di una matrice o zero se la matrice è vuota.
Tipi di dati dei parametri
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 numeri in virgola mobile.
arrays.max([10.000000, 20.000000]) = 20.000000
arrays.min
arrays.min(array_of_ints_or_floats[, ignore_zeros=false])
Descrizione
Restituisce l'elemento più piccolo di una matrice o zero se la matrice è vuota. Se il secondo argomento facoltativo è impostato su true, gli elementi uguali a zero vengono ignorati.
Tipi di dati dei parametri
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 numeri in virgola mobile.
arrays.min([10.000000, 20.000000]) = 10.000000
Esempio 3
Questo esempio restituisce l'elemento più piccolo in un array di numeri in virgola mobile, ignorando gli zeri.
arrays.min([10.000000, 20.000000, 0.0], true) = 10.000000
arrays.size
arrays.size( array )
Descrizione
Restituisce la dimensione dell'array. Restituisce 0 per una matrice vuota.
Tipi di dati dei parametri
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 numeri interi contenente tre elementi.
arrays.size([1, 2, 3]) = 3
Esempio 3
Questo esempio utilizza un array di numeri in virgola mobile che contiene un elemento.
arrays.size([1.200000]) = 1
Esempio 4
Questo esempio utilizza un array vuoto.
arrays.size([]) = 0
arrays.index_to_float
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 pari a 0 e l'ultimo elemento ha un indice pari a n-1, dove n è la dimensione dell'array. L'indicizzazione negativa 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 dei parametri
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 numeri in virgola mobile.
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 numeri in virgola mobile.
arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 0-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
arrays.index_to_int(array_of_inputs, index)
Descrizione
Restituisce il valore in un dato 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 pari a 0 e l'ultimo elemento ha un indice pari a n-1, dove n è la dimensione dell'array. L'indicizzazione negativa 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 dei parametri
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"], 0-1) = 33
Esempio 3
Restituisce 0 per l'elemento fuori dai limiti.
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 int all'indice 0.
arrays.index_to_int([1, 2, 3], 0) = 1
arrays.index_to_str
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 pari a 0 e l'ultimo elemento ha un indice pari a n-1, dove n è la dimensione dell'array. L'indicizzazione negativa 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 dei parametri
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 (l'ultimo elemento dell'array) da un array di stringhe.
arrays.index_to_str(["test1", "test2", "test3", "test4"], 0-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 numeri in virgola mobile. 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
cast.as_bool(string_or_int)
Descrizione
La funzione converte un valore int o stringa in un valore booleano. Le chiamate di funzione con valori che non possono essere convertiti restituiranno FALSE. Restituisce TRUE solo per l'intero 1 e la stringa "true" senza distinzione tra maiuscole e minuscole.
Tipi di dati dei parametri
INT|STRING
Tipo restituito
BOOL
Esempi di codice
Esempio 1
Questo esempio mostra come trasmettere una stringa non booleana
cast.as_bool("123") = false
Esempio 2
Intero vero (1)
cast.as_bool(1) = true
Esempio 3
Stringa truthy
cast.as_bool("true") = true
Esempio 4
Stringa truthy in maiuscolo
cast.as_bool("TRUE") = true
Esempio 5
Numero intero negativo
cast.as_bool(0-1) = false
Esempio 6
Numero intero falso (0)
cast.as_bool(0) = false
Esempio 7
stringa vuota
cast.as_bool("") = false
cast.as_float
cast.as_float(string_to_cast)
Descrizione
Converte una stringa numerica in un numero in virgola mobile. Qualsiasi chiamata di funzione con valori che non possono essere convertiti restituisce 0. I valori float mantengono la precisione fino a 7 cifre decimali.
Tipi di dati dei parametri
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
cast.as_string
cast.as_string(int_or_bytes_or_bool, optional_default_string)
Descrizione
La funzione cast.as_string
trasforma un valore INT
, BYTES
o BOOL
nella sua rappresentazione stringa. Puoi fornire un argomento default_string
facoltativo per gestire i casi in cui la trasmissione non va a buon fine. Se ometti l'argomento default_string
o se l'input è una sequenza di byte UTF-8
o BASE64
non valida, la funzione restituisce una stringa vuota.
Tipi di dati dei parametri
INT|BYTES|BOOL
, STRING
Tipo restituito
STRING
Esempi di codice
Conversione da numero intero a stringa
La funzione converte l'intero 123
nella stringa "123"
.
cast.as_string(123) = "123"
Conversione da float a stringa
La funzione converte il numero in virgola mobile 2.25
nella stringa "2.25"
.
cast.as_string(2.25) = "2.25"
Conversione da byte a stringa
La funzione converte il valore binario non elaborato b'01
nella stringa "\x01"
.
cast.as_string(b'01, "") = "\x01"
Conversione da booleano a stringa
La funzione converte il valore booleano true
nella stringa "true"
.
cast.as_string(true, "") = "true"
Conversione non riuscita (valore predefinito della stringa fornita facoltativamente)
La funzione utilizza per impostazione predefinita la stringa "casting error"
quando il valore fornito non è valido.
cast.as_string(9223372036854775808, "casting error") = "casting error"
impronta
hash.fingerprint2011(byteOrString)
Descrizione
Questa funzione calcola l'hash fingerprint2011
di una sequenza di byte
o di una stringa di input. Questa funzione restituisce un valore INT
senza segno nell'intervallo [2, 0xFFFFFFFFFFFFFFFF]
.
Tipi di dati dei parametri
BTYE
, STRING
Tipo restituito
INT
Esempio di codice
id_fingerprint = hash.fingerprint2011("user123")
gruppo
group(field1, field2, field3, ...)
Descrizione
Raggruppa i campi di tipo simile in una variabile segnaposto.
Nella ricerca UDM, i campi raggruppati vengono utilizzati per eseguire ricerche in più campi di un tipo simile. La funzione Group è simile ai campi raggruppati, ma ti consente di selezionare i campi che vuoi raggruppare per attivare un rilevamento. Puoi utilizzare la funzione di raggruppamento per raccogliere informazioni su una specifica entità (ad esempio un nome host, un indirizzo IP o un ID utente) in diversi tipi di sostantivo.
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
hash.sha256(string)
Descrizione
Restituisce un hash SHA-256 della stringa di input.
Tipi di dati dei parametri
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
math.abs(numericExpression)
Descrizione
Restituisce il valore assoluto di un'espressione intera o mobile.
Tipi di dati dei parametri
NUMBER
Tipo restituito
NUMBER
Esempi di codice
Esempio 1
Questo esempio restituisce True se l'evento si è verificato più di 5 minuti dopo l'ora
specificata (in secondi dall'epoca Unix), indipendentemente dal fatto che l'evento si sia verificato
prima o dopo l'ora specificata. Una chiamata a math.abs
non può dipendere da
più variabili o segnaposto. Ad esempio, non puoi sostituire il valore
dell'ora hardcoded 1643687343 nell'esempio seguente con
$e2.metadata.event_timestamp.seconds
.
300 < math.abs($e1.metadata.event_timestamp.seconds - 1643687343)
math.ceil
math.ceil(number)
Descrizione
Restituisce il numero intero più piccolo non inferiore al numero specificato (arrotondamento per eccesso). Restituisce 0 se l'input è null o troppo grande per essere contenuto in un int64.
Tipi di dati dei parametri
FLOAT
Tipo restituito
INT
Esempi di codice
Questa sezione contiene esempi di utilizzo di math.ceil
.
Esempio 1
Questo esempio restituisce il valore di ceil di un numero intero.
math.ceil(2.000000) = 2
Esempio 2
Questo esempio restituisce il valore di ceil di un numero negativo.
math.ceil(0-1.200000) = -1
Esempio 3
Questo esempio restituisce 0 come valore di ceil di un numero troppo grande per un intero a 64 bit.
math.ceil(184467440737095516160.0) = 0
math.floor
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 è null o troppo grande per essere inserito in un int64.
Tipi di dati dei parametri
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(0-1.234568) = -2
Esempio 3
Questo esempio mostra un caso di zero.
math.floor(0.000000) = 0
math.geo_distance
math.geo_distance(longitude1, latitude1, longitude2, latitude2))
Descrizione
Restituisce la distanza tra due posizioni geografiche (coordinate) in metri. Restituisce -1 se le coordinate non sono valide.
Tipi di dati dei parametri
FLOAT
, FLOAT
, FLOAT
, FLOAT
Tipo restituito
FLOAT
Esempi di codice
Esempio 1
L'esempio seguente 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
Il seguente 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
Il seguente esempio restituisce -1
quando uno dei parametri è una coordinata non valida:
math.geo_distance(0-122.897680, 37.407574, 0-122.021810, 97.407574) = -1.000000
Esempio 4
Il seguente esempio restituisce 0
quando le coordinate sono le stesse:
math.geo_distance(-122.897680, 37.407574, -122.897680, 37.407574) = 0.000000
math.is_increasing
math.is_increasing(num1, num2, num3)
Descrizione
Accetta 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 dei parametri
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 double 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 double negativo, un valore INT64 pari a zero e un valore INT64 negativo.
math.is_increasing(0-1.200000, 0, 0-3) = false
Esempio 4
Questo esempio include due numeri doppi negativi e un valore INT64 pari a zero.
math.is_increasing(0-1.200000, 0-1.50000, 0) = false
Esempio 5
Questo esempio include un numero negativo e due valori uguali.
math.is_increasing(0-1.200000, 0, 0) = false
math.log
math.log(numericExpression)
Descrizione
Restituisce il valore del logaritmo naturale di un'espressione intera o mobile.
Tipi di dati dei parametri
NUMBER
Tipo restituito
NUMBER
Esempi di codice
Esempio 1
math.log($e1.network.sent_bytes) > 20
math.pow
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 dei parametri
base: INT|FLOAT
esponente: INT|FLOAT
Tipo restituito
FLOAT
Esempi di codice
Esempio 1
Questo esempio mostra un caso di numeri interi.
math.pow(2, 2) // 4.00
Esempio 2
Questo esempio mostra un caso base di frazione.
math.pow(2.200000, 3) // 10.648
Esempio 3
Questo esempio mostra un caso di base e di potenza di una frazione.
math.pow(2.200000, 1.200000) // 2.575771
Esempio 4
Questo esempio mostra un caso di potenza negativa.
math.pow(3, 0-3) // 0.037037
Esempio 5
Questo esempio mostra un caso di potenza frazionaria.
math.pow(3, 0-1.200000) // 0.267581
Esempio 6
Questo esempio mostra un caso base negativo.
math.pow(0-3, 0-3) // -0.037037
Esempio 7
Questo esempio mostra un caso base pari a zero.
math.pow(0, 3) // 0
Esempio 8
Questo esempio mostra un caso di consumo energetico pari a 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
math.random()
Descrizione
Genera un valore pseudocasuale di tipo DOUBLE nell'intervallo di [0, 1)
, inclusi 0 ed escluso 1.
Tipo restituito
FLOAT
Esempi di codice
Il seguente esempio verifica se il valore casuale rientra nell'intervallo [0, 1)
.
none
if(math.random() >= 0 and math.random() < 1) = true
math.round
math.round(numericExpression, decimalPlaces)
Descrizione
Restituisce un valore arrotondato al numero intero più vicino o al numero specificato di cifre decimali.
Tipi di dati dei parametri
NUMBER
Tipo restituito
NUMBER
Esempi di codice
math.round(10.7) // returns 11
math.round(1.2567, 2) // returns 1.25
math.round(0-10.7) // returns -11
math.round(0-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer
math.sqrt
math.sqrt(number)
Descrizione
Restituisce la radice quadrata del numero specificato. Restituisce 0 in caso di numeri negativi.
Tipi di dati dei parametri
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(0-1.200000) = 0.000000
metriche
Le funzioni delle metriche possono aggregare grandi quantità di dati storici. Puoi utilizzare
questo valore nella regola utilizzando metrics.functionName()
nella sezione
Risultato.
Per ulteriori informazioni, consulta Metriche YARA-L.
net.ip_in_range_cidr
net.ip_in_range_cidr(ipAddress, subnetworkRange)
Descrizione
Restituisce true
quando l'indirizzo IP specificato si trova all'interno della subnet specificata.
Puoi utilizzare YARA-L per cercare eventi UDM in tutti gli indirizzi IP
all'interno di una subnet utilizzando l'istruzione net.ip_in_range_cidr()
.
Sono supportati sia IPv4 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 campi di indirizzi IP singoli e ripetuti.
Per eseguire una ricerca in un intervallo di indirizzi IP, specifica un campo ip
UDM e un intervallo CIDR (Classless Inter-Domain Routing). YARA-L può gestire campi di indirizzi IP singoli e ripetuti.
Tipi di dati dei parametri
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 un esempio di regola che utilizza l'istruzione net.ip_in_range_cidr()
, consulta la regola di esempio in Singolo evento all'interno dell'intervallo di indirizzi IP.
re.regex
Puoi definire la corrispondenza con espressioni regolari in YARA-L 2.0 utilizzando una delle seguenti sintassi:
Utilizzo della sintassi YARA-L: correlata agli eventi. Di seguito è riportata una rappresentazione generica di questa sintassi:
$e.field = /regex/
Utilizzo della 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 la 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 forzare la corrispondenza completa dei campi UDM, aggiungi(?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 maiuscole.
Tipi di dati dei parametri
STRING
, STRING
Tipi di espressioni dei parametri
ANY
, ANY
Tipo restituito
BOOL
Esempi di codice
Esempio 1
// Equivalent to $e.principal.hostname = /google/
re.regex($e.principal.hostname, "google")
re.capture
re.capture(stringText, regex)
Descrizione
Acquisisce (estrae) i dati da una stringa utilizzando il pattern di 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 acquisizione tra parentesi. Se l'espressione regolare contiene 0 gruppi di acquisizione, la funzione restituisce la prima sottostringa corrispondente intera. Se l'espressione regolare contiene un gruppo Capture, restituisce la prima sottostringa corrispondente per il gruppo Capture. La definizione di due o più gruppi di acquisizione restituisce un errore del compilatore.
Tipi di dati dei parametri
STRING
, STRING
Tipo restituito
STRING
Esempi di codice
Esempio 1
In questo esempio, se $e.principal.hostname
contiene "aaa1bbaa2", la seguente condizione è vera perché la funzione
restituisce la prima istanza. Questo esempio non ha gruppi di acquisizione.
"aaa1" = re.capture($e.principal.hostname, "a+[1-9]")
Esempio 2
Questo esempio acquisisce tutto ciò che segue il simbolo @ in un'email. Se il
campo $e.network.email.from
è test@google.com
, 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 ad alcuna sottostringa nel testo, la funzione restituisce una stringa vuota. Puoi omettere gli eventi in cui non si verifica alcuna corrispondenza
escludendo la stringa vuota, il che è particolarmente importante quando
utilizzi re.capture()
con una disuguaglianza:
// Exclude the empty string to omit events where no match occurs.
"" != re.capture($e.network.email.from , "@(.*)")
// Exclude a specific string with an inequality.
"google.com" != re.capture($e.network.email.from , "@(.*)")
re.replace
re.replace(stringText, replaceRegex, replacementText)
Descrizione
Esegue una sostituzione di espressioni regolari.
Questa funzione accetta tre argomenti:
stringText
: la stringa originale.replaceRegex
: l'espressione regolare che indica il pattern da cercare.replacementText
: il testo da inserire in ogni corrispondenza.
Restituisce una nuova stringa derivata dalla stringa 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 dà la priorità alla sostituzione della
prima occorrenza trovata. Ad esempio, re.replace("banana", "ana", "111")
restituisce la stringa "b111na".
Tipi di dati dei parametri
STRING
, STRING
, 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 poi restituisce il risultato. Nota l'utilizzo di funzioni nidificate.
"email@google.org" = re.replace($e.network.email.from, "com", "org")
Esempio 2
Questo esempio utilizza cifre con interpretazione letterale a una barra rovesciata nell'argomento replacementText
per
fare riferimento alle corrispondenze con il pattern replaceRegex
.
"test1.com.google" = re.replace(
$e.principal.hostname, // holds "test1.test2.google.com"
"test2\.([a-z]*)\.([a-z]*)",
"\\2.\\1" // \\1 holds "google", \\2 holds "com"
)
Esempio 3
Tieni presente i seguenti casi quando gestisci stringhe vuote e re.replace()
:
Utilizzo della 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
optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)
Descrizione
Questa funzione determina se includere un evento in base a una strategia di campionamento deterministico. Questa funzione restituisce:
true
per una frazione dei valori di input, equivalente a (rateNumerator
/rateDenominator
), che indica che l'evento deve essere incluso nel campione.false
che indica che l'evento non deve essere incluso nel campione.
Questa funzione è utile per gli scenari di ottimizzazione in cui vuoi elaborare solo un sottoinsieme di eventi. Equivalente a:
hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator
Tipi di dati dei parametri
- byteOrString: espressione che restituisce un valore
BYTE
oSTRING
. - 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
strings.base64_decode(encodedString)
Descrizione
Restituisce una stringa contenente la versione decodificata in base64 della stringa codificata.
Questa funzione accetta una stringa con codifica base64 come argomento. Se encodedString
non è una stringa con codifica base64 valida, la funzione restituisce encodedString
invariato.
Tipi di dati dei parametri
STRING
Tipo restituito
STRING
Esempi di codice
Esempio 1
"test" = strings.base64_decode($e.principal.domain.name)
strings.coalesce
strings.coalesce(a, b, c, ...)
Descrizione
Questa funzione accetta un numero illimitato di argomenti e restituisce il valore della prima espressione che non restituisce una stringa vuota (ad esempio "valore diverso da zero"). Se tutti gli argomenti restituiscono una stringa vuota, la chiamata di funzione restituisce una stringa vuota.
Gli argomenti possono essere valori letterali, campi evento o chiamate di funzioni. Tutti gli argomenti devono essere di tipo STRING
. Se alcuni argomenti sono campi evento, gli attributi devono provenire dallo stesso evento.
Tipi di dati dei parametri
STRING
Tipo restituito
STRING
Esempi di codice
Esempio 1
Il seguente esempio include variabili stringa come argomenti. La condizione
restituisce true quando (1) $e.network.email.from
è suspicious@gmail.com
o
(2) $e.network.email.from
è vuoto e $e.network.email.to
è
suspicious@gmail.com
.
"suspicious@gmail.com" = strings.coalesce($e.network.email.from, $e.network.email.to)
Esempio 2
Il seguente esempio 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 vengono
enumerati nella condizione della regola:
$e.principal.ip
viene valutato per primo.$e.src.ip
viene valutato successivamente.$e.target.ip
viene valutato successivamente.- Infine, la stringa "No 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
. Restituirà un errore del compilatore perché gli argomenti sono
variabili evento diverse.
// returns a compiler error
"test" = strings.coalesce($e1.principal.hostname, $e2.principal.hostname)
strings.concat
strings.concat(a, b, c, ...)
Descrizione
Restituisce la concatenazione di un numero illimitato di elementi, ognuno dei quali può essere una stringa, un numero intero o un numero in virgola mobile.
Se alcuni argomenti sono campi evento, gli attributi devono provenire dallo stesso evento.
Tipi di dati dei parametri
STRING
, FLOAT
, INT
Tipo restituito
STRING
Esempi di codice
Esempio 1
L'esempio seguente include una variabile 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
Il seguente esempio include una variabile stringa e un valore letterale stringa come argomenti.
"google-test" = strings.concat($e.principal.hostname, "-test") // Matches the event when $e.principal.hostname = "google"
Esempio 3
Il seguente esempio 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, i numeri in virgola mobile che superano le 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 stringa,
una variabile intera e un valore letterale float come argomenti. Tutte le variabili provengono dallo stesso 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 dall'evento $e1
,
con principal.hostname
dall'evento $e2
. Restituirà 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
strings.contains( str, substr )
Descrizione
Restituisce true se una determinata stringa contiene la sottostringa specificata. In caso contrario, restituisce false.
Tipi di dati dei parametri
STRING
, STRING
Tipo restituito
BOOL
Esempi di codice
Esempio 1
Questo esempio restituisce true perché la stringa contiene la sottostringa "is".
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
strings.count_substrings(string_to_search_in, substring_to_count)
Descrizione
Data una stringa e una sottostringa, restituisce un int64 del conteggio delle occorrenze non sovrapposte della sottostringa all'interno della stringa.
Tipi di dati dei parametri
STRING
, STRING
Tipo restituito
INT
Esempi di codice
Questa sezione contiene esempi che calcolano il numero di volte in cui una sottostringa viene visualizzata in una determinata stringa.
Esempio 1
Questo esempio utilizza una stringa non nulla e un carattere di sottostringa singola non nullo.
strings.count_substrings("this`string`has`four`backticks", "`") = 4
Esempio 2
Questo esempio utilizza una stringa non nulla e una sottostringa non nulla di più di un carattere.
strings.count_substrings("str", "str") = 1
Esempio 3
Questo esempio utilizza una stringa non nulla e una sottostringa vuota.
strings.count_substrings("str", "") = 0
Esempio 4
Questo esempio utilizza una stringa vuota e una sottostringa non nulla di più 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 nulla e una sottostringa non nulla con più di un carattere e più di un'occorrenza.
strings.count_substrings("fooABAbarABAbazABA", "AB") = 3
Esempio 7
Questo esempio utilizza una stringa non nulla e una sottostringa non nulla con più di un carattere e più di un'occorrenza. Evidenzia la limitazione con le occorrenze di sottostringhe sovrapposte
strings.count_substrings("ABABABA", "ABA") = 2
strings.extract_domain
strings.extract_domain(url_string)
Descrizione
Estrae il dominio da una stringa.
Tipi di dati dei parametri
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ù barre rovesciate
strings.extract_domain("\\\\") = ""
Esempio 4
gestione corretta dei caratteri non alfabetici
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
scenario di test positivo
strings.extract_domain("https://google.co.in") = "google.co.in"
strings.extract_hostname
strings.extract_hostname(string)
Descrizione
Estrae il nome host da una stringa. Questa funzione è sensibile alle maiuscole.
Tipi di dati dei parametri
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
gestione corretta dei caratteri non inglesi
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_base64
strings.from_base64(base64_encoded_string)
Descrizione
La funzione converte un valore STRING
con codifica Base64 in un valore BYTES
binario non elaborato. Le chiamate di funzione con valori che non possono essere convertiti restituiscono un BYTES
vuoto per impostazione predefinita.
Tipi di dati dei parametri
STRING
Tipo restituito
BYTES
Esempi di codice
Conversione da stringa con codifica Base64 a byte
La funzione converte una stringa codificata in base64 nella sua rappresentazione binaria non elaborata.
strings.from_base64("AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA=") = b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000
Conversione non riuscita (valore predefinito: byte vuoti)
Se il valore fornito non è valido, la funzione utilizza per impostazione predefinita byte vuoti.
strings.from_base64("invalid-value") = b'
strings.from_hex
strings.from_hex(hex_string)
Descrizione
Restituisce i byte associati alla stringa esadecimale specificata.
Tipi di dati dei parametri
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 una stringa esadecimale.
strings.from_hex("1234") // returns 1234 bytes
Esempio 4
Questo esempio mostra la conversione di caratteri non ASCII.
strings.from_hex("筒纸.中国") // returns empty bytes
strings.length
strings.length(string_value)
Descrizione
Restituisce il numero di caratteri nella stringa di input.
Tipi di dati dei parametri
STRING
Tipo restituito
INT
Esempi di codice
Esempio 1
Di seguito è riportato un esempio con un test della stringa.
strings.length("str") = 3
Esempio 2
Di seguito è riportato un esempio con una stringa vuota come input.
strings.length("") = 0
Esempio 3
Di seguito è riportato un esempio con una stringa di caratteri speciali.
strings.length("!@#$%^&*()-_") = 12
Esempio 4
Di seguito è riportato un esempio con una stringa con spazi.
strings.length("This is a test string") = 21
strings.ltrim
strings.ltrim(string_to_trim, cutset)
Descrizione
Taglia gli spazi bianchi iniziali da una determinata stringa. Questa funzione rimuove i caratteri iniziali presenti nel cutset.
Tipi di dati dei parametri
STRING
, STRING
Tipo restituito
STRING
Esempi di codice
Di seguito sono riportati alcuni esempi di casi d'uso.
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
strings.reverse(STRING)
Descrizione
Restituisce una stringa che è l'inverso della stringa di input.
Tipi di dati dei parametri
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 supera un palindromo.
strings.reverse("tacocat") = "tacocat"
strings.rtrim
strings.rtrim(string_to_trim, cutset)
Descrizione
Taglia gli spazi vuoti finali da una determinata stringa. Rimuove i caratteri finali presenti nel cutset.
Tipi di dati dei parametri
STRING
, STRING
Tipo restituito
STRING
Esempi di codice
Di seguito sono riportati alcuni esempi di casi d'uso.
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
Il seguente esempio 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
strings.to_lower(stringText)
Descrizione
Questa funzione accetta una stringa di input e restituisce una stringa dopo aver convertito tutti i caratteri in minuscolo.
Tipi di dati dei parametri
STRING
Tipo restituito
STRING
Esempi di codice
Esempio 1
Il seguente esempio restituisce true
.
"test@google.com" = strings.to_lower($e.network.email.to)
strings.to_upper
strings.to_upper(string_val)
Descrizione
Restituisce la stringa originale con tutti i caratteri alfabetici in maiuscolo.
Tipi di dati dei parametri
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
strings.trim(string_to_trim, cutset)
Descrizione
Taglia gli spazi vuoti iniziali e finali di una determinata stringa. Inoltre, rimuove i caratteri indesiderati (specificati dall'argomento cutset) dalla stringa di input.
Tipi di dati dei parametri
STRING
, STRING
Tipo restituito
STRING
Esempi di codice
Di seguito sono riportati alcuni esempi di casi d'uso.
Esempio 1
Nell'esempio seguente, la stessa stringa viene passata come stringa di input e cutset, il che comporta una stringa vuota.
strings.trim("str", "str") // ""
Esempio 2
Nell'esempio seguente, una stringa vuota viene passata come cutset, il che comporta la restituzione della stringa originale str perché non sono stati specificati caratteri da rimuovere nel cutset.
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
Nel seguente esempio, la funzione restituisce str perché la funzione trim rimuove quanto segue:
- spazio vuoto finale in "a aastraa aa "
- i caratteri specificati nel cutset (spazio, a)
strings.trim("a aastraa aa ", " a") = "str"
strings.url_decode
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 va a buon fine.
Tipi di dati dei parametri
STRING
Tipo restituito
STRING
Esempi di codice
Esempio 1
Questo esempio mostra uno scenario di test positivo.
strings.url_decode("three%20nine%20four") = "three nine four"
Esempio 2
Questo esempio mostra un caso di 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+"¶m2=2;'
timestamp.as_unix_seconds
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 omesso, il valore predefinito èGMT
. Puoi specificare i fusi orari utilizzando i valori letterali 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 all'UTC, nel formato
(+|-)H[H][:M[M]]
, ad esempio: "-08:00".
- Il nome del database TZ, ad esempio
Ecco 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 dei parametri
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 Unix 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
timestamp.current_seconds()
Descrizione
Restituisce un numero intero che rappresenta l'ora corrente in secondi Unix. Questo valore è
approssimativamente uguale al timestamp di rilevamento e si basa sul momento in cui viene
eseguita la regola. Questa funzione è un sinonimo della funzione timestamp.now()
.
Tipi di dati dei parametri
NONE
Tipo restituito
INT
Esempi di codice
Esempio 1
Il seguente esempio restituisce true
se il certificato è scaduto da più di 24 ore. Calcola la differenza di tempo sottraendo i secondi Unix attuali e poi confrontando il risultato utilizzando l'operatore maggiore di.
86400 < timestamp.current_seconds() - $e.network.tls.certificate.not_after
timestamp.get_date
timestamp.get_date(unix_seconds [, time_zone])
Descrizione
Questa funzione restituisce una stringa nel formato YYYY-MM-DD
, che rappresenta il giorno in cui si trova un timestamp.
unix_seconds
è un numero intero che rappresenta il numero di secondi trascorsi dall'epoca Unix, ad esempio$e.metadata.event_timestamp.seconds
, o un segnaposto contenente questo valore.time_zone
è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando i valori letterali stringa. Le opzioni sono:- Il nome del database TZ, ad esempio "America/Los_Angeles". Per saperne di più, consulta la colonna "Nome database TZ" di questa pagina.
- L'offset del fuso orario rispetto all'UTC, nel formato
(+|-)H[H][:M[M]]
, ad esempio: "-08:00".
Di seguito sono riportati alcuni esempi di identificatori time_zone validi, che puoi trasmettere 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 dei parametri
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 stringa per definire time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_date($ts, "America/Los_Angeles") = "2024-02-20"
timestamp.get_minute
timestamp.get_minute(unix_seconds [, time_zone])
Descrizione
Questa funzione restituisce un numero intero compreso nell'intervallo [0, 59]
che rappresenta il minuto.
unix_seconds
è un numero intero che rappresenta il numero di secondi trascorsi dall'epoca Unix, ad esempio$e.metadata.event_timestamp.seconds
, o un segnaposto contenente questo valore.time_zone
è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando i valori letterali stringa. Le opzioni sono:- Il nome del database TZ, ad esempio "America/Los_Angeles". Per saperne di più, consulta la colonna "Nome database TZ" di questa pagina.
- L'offset del fuso orario rispetto all'UTC, nel formato
(+|-)H[H][:M[M]]
, ad esempio: "-08:00".
Ecco 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 dei parametri
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 stringa per definire time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts, "America/Los_Angeles") = 15
timestamp.get_hour
timestamp.get_hour(unix_seconds [, time_zone])
Descrizione
Questa funzione restituisce un numero intero compreso nell'intervallo [0, 23]
che rappresenta l'ora.
unix_seconds
è un numero intero che rappresenta il numero di secondi trascorsi dall'epoca Unix, ad esempio$e.metadata.event_timestamp.seconds
, o un segnaposto contenente questo valore.time_zone
è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando i valori letterali stringa. Le opzioni sono:- Il nome del database TZ, ad esempio "America/Los_Angeles". Per saperne di più, consulta la colonna "Nome database TZ" di questa pagina.
- L'offset del fuso orario rispetto all'UTC, nel formato
(+|-)H[H][:M[M]]
, ad esempio: "-08:00".
Ecco 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 dei parametri
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 stringa per definire time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts, "America/Los_Angeles") = 15
timestamp.get_day_of_week
timestamp.get_day_of_week(unix_seconds [, time_zone])
Descrizione
Questa funzione restituisce un numero intero compreso 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 trascorsi dall'epoca Unix, ad esempio$e.metadata.event_timestamp.seconds
, o un segnaposto contenente questo valore.time_zone
è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando i valori letterali stringa. Le opzioni sono:- Il nome del database TZ, ad esempio "America/Los_Angeles". Per saperne di più, consulta la colonna "Nome database TZ" di questa pagina.
- L'offset del fuso orario rispetto all'UTC, nel formato
(+|-)H[H][:M[M]]
, ad esempio: "-08:00".
Di seguito sono riportati alcuni esempi di identificatori time_zone validi, che puoi trasmettere 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 dei parametri
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 stringa per definire time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_day_of_week($ts, "America/Los_Angeles") = 6
timestamp.get_timestamp
timestamp.get_timestamp(unix_seconds, optional timestamp_format/time_granularity, 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 trascorsi dall'epoca 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 una stringa di formato data/ora o una delle seguenti granularità temporali:SECOND
,MINUTE
,HOUR
,DATE
,WEEK
,MONTH
oYEAR
. Per altre opzioni di formattazione, vedi Elementi di formato per le parti di data e ora.time_zone
è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito èGMT
. Puoi specificare i fusi orari utilizzando i valori letterali 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 al fuso orario UTC, nel formato
(+|-)H[H][:M[M]]
, ad esempio: "-08:00".
- Il nome del database IANA Time Zone (TZ), ad esempio
Ecco 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 dei parametri
INT
, STRING
, 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_timestamp($ts) = "2024-02-22 10:43:51"
Esempio 2
Questo esempio utilizza un valore letterale stringa per definire time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_timestamp($ts, "%F %T", "America/Los_Angeles") = "2024-02-22 10:43:51"
Esempio 3
Questo esempio utilizza un valore letterale stringa per definire timestamp_format
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_timestamp($ts, "%Y-%m", "GMT") = "2024-02"
Esempio 4
Questo esempio formatta un timestamp Unix come stringa con una granularità di un secondo.
timestamp.get_timestamp(1708598631, "SECOND", "GMT") = "2024-02-22 10:43:51"
Esempio 5
Questo esempio formatta un timestamp Unix come stringa con granularità al minuto.
timestamp.get_timestamp(1708598631, "MINUTE", "GMT") = "2024-02-22 10:43"
Esempio 6
Questo esempio formatta un timestamp Unix come stringa con granularità oraria.
timestamp.get_timestamp(1708598631, "HOUR", "GMT") = "2024-02-22 10"
Esempio 7
Questo esempio formatta un timestamp Unix come stringa con granularità giornaliera.
timestamp.get_timestamp(1708598631, "DATE", "GMT") = "2024-02-22"
Esempio 8
Questo esempio formatta un timestamp Unix come stringa con granularità settimanale.
timestamp.get_timestamp(1708598631, "WEEK", "GMT") = "2024-02-18"
Esempio 9
Questo esempio formatta un timestamp Unix come stringa con granularità mensile.
timestamp.get_timestamp(1708598631, "MONTH", "GMT") = "2024-02"
Esempio 10
Questo esempio formatta un timestamp Unix come stringa con granularità annuale.
timestamp.get_timestamp(1708598631, "YEAR", "GMT") = "2024"
timestamp.get_week
timestamp.get_week(unix_seconds [, time_zone])
Descrizione
Questa funzione restituisce un numero intero nell'intervallo [0, 53]
che rappresenta la settimana dell'anno. Le settimane iniziano di domenica. Le date antecedenti la prima domenica dell'anno rientrano nella settimana 0.
unix_seconds
è un numero intero che rappresenta il numero di secondi trascorsi dall'epoca Unix, ad esempio$e.metadata.event_timestamp.seconds
, o un segnaposto contenente questo valore.time_zone
è facoltativo ed è una stringa che rappresenta un fuso orario. Se omesso, il valore predefinito è "GMT". Puoi specificare i fusi orari utilizzando i valori letterali stringa. Le opzioni sono:- Il nome del database TZ, ad esempio "America/Los_Angeles". Per saperne di più, consulta la colonna "Nome database TZ" di questa pagina.
- L'offset del fuso orario rispetto all'UTC, nel formato
(+|-)H[H][:M[M]]
, ad esempio: "-08:00".
Ecco 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 dei parametri
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 stringa per definire time_zone
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_week($ts, "America/Los_Angeles") = 0
timestamp.now
timestamp.now()
Descrizione
Restituisce il numero di secondi a partire dal 1° gennaio 1970 00:00:00 UTC. Questo valore è noto anche come tempo Unix.
Tipo restituito
INT
Esempi di codice
Esempio 1
L'esempio seguente 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
window.avg(numeric_values [, should_ignore_zero_values])
Descrizione
Restituisce la media dei valori di input (che possono essere numeri interi o numeri in virgola mobile). Se imposti il secondo argomento facoltativo su true, i valori zero vengono ignorati.
Tipi di dati dei parametri
INT|FLOAT
Tipo restituito
FLOAT
Esempi di codice
Esempio 1
Questo esempio mostra la media intera.
// 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 negativi
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 resi 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 pari a 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
window.first(values_to_sort_by, values_to_return)
Descrizione
Questa funzione di aggregazione restituisce un valore 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'ID utente dall'evento con il timestamp più basso nella finestra di corrispondenza (evento meno recente).
Tipi di dati dei parametri
INT
, STRING
Tipo restituito
STRING
Esempi di codice
Ottieni un valore stringa derivato da un evento con il valore int più basso correlato 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
window.last(values_to_sort_by, values_to_return)
Descrizione
Questa funzione di aggregazione restituisce un valore 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'ID utente dall'evento con il timestamp più basso nella finestra di corrispondenza (timestamp più alto).
Tipi di dati dei parametri
INT
, STRING
Tipo restituito
STRING
Esempi di codice
Ottieni un valore stringa derivato da un evento con il valore int più correlato 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
window.median(numeric_values, should_ignore_zero_values)
Descrizione
Restituisce la mediana dei valori di input. Se sono presenti due valori mediani, ne verrà scelto uno solo in modo non deterministico come valore restituito.
Tipi di dati dei parametri
INT|FLOAT
, BOOL
Tipo restituito
FLOAT
Esempi di codice
Esempio 1
Questo esempio restituisce la mediana quando i valori di input non sono 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 solo una 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
window.mode(values)
Descrizione
Restituisce la moda dei valori di input. In caso di più valori di modalità possibili, solo uno di questi valori verrà scelto in modo non deterministico come valore restituito.
Tipi di dati dei parametri
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
window.stddev(numeric_values)
Descrizione
Restituisce la deviazione standard dei valori di input in una finestra di corrispondenza.
Tipi di dati dei parametri
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 numeri in virgola mobile 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 che contiene 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
window.variance(values)
Descrizione
Questa funzione restituisce la varianza specificata dei valori di input.
Tipi di dati dei parametri
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 numeri in virgola mobile.
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 piccolo valore di varianza.
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 dei 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
bytes.to_base64
bytes.to_base64(bytes, optional_default_string)
Descrizione
La funzione converte un valore bytes
in un valore base64 encoded string
. Le chiamate di funzioni con valori che non possono essere convertiti restituiscono una stringa vuota per impostazione predefinita.
Tipi di dati dei parametri
BYTES
, STRING
Tipo restituito
STRING
Esempi di codice
Byte binari non elaborati in stringa con codifica Base64
La funzione converte i byte binari non elaborati in una stringa con codifica base64.
bytes.to_base64(b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000) = "AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA="
Conversione non riuscita (valore predefinito della stringa fornita facoltativamente)
La funzione utilizza per impostazione predefinita "invalid bytes"
quando il valore dei byte fornito non è valido.
bytes.to_base64(b'000000006f8ec5586d", "invalid bytes") = "invalid bytes"
Assegnazione della 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, esistono due limitazioni per l'assegnazione di funzioni ai segnaposto:
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.
La chiamata di funzione deve dipendere da uno e un solo evento. Tuttavia, è possibile utilizzare più di un campo dello stesso evento negli argomenti della chiamata di funzione. Ad esempio, quanto segue è valido:
$ph = strings.concat($event.principal.hostname, "string2")
$ph = strings.concat($event.principal.hostname, $event.src.hostname)
Tuttavia, quanto segue non è valido:
$ph = strings.concat("string1", "string2")
$ph = strings.concat($event.principal.hostname, $anotherEvent.src.hostname)
Sintassi degli elenchi di riferimento
Per ulteriori informazioni sul comportamento e sulla sintassi degli elenchi di riferimenti, consulta la nostra pagina sugli elenchi di riferimenti.
Puoi utilizzare gli elenchi di riferimenti nelle sezioni events
o outcome
. Ecco la sintassi per utilizzare vari tipi di elenchi di riferimento in una regola:
// STRING reference list
$e.principal.hostname in %string_reference_list
// REGEX reference list
$e.principal.hostname in regex %regex_reference_list
// CIDR reference list
$e.principal.ip in cidr %cidr_reference_list
Puoi anche utilizzare l'operatore not
e l'operatore nocase
con gli elenchi di riferimento, come mostrato nell'esempio seguente:
// Exclude events whose hostnames match substrings in my_regex_list.
not $e.principal.hostname in regex %my_regex_list
// Event hostnames must match at least 1 string in my_string_list (case insensitive).
$e.principal.hostname in %my_string_list nocase
L'operatore nocase
è compatibile con gli elenchi STRING
e REGEX
.
Per motivi 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 - Massimo
in
istruzioni con l'operatoreregex
: 4 - Massimo
in
istruzioni con l'operatorecidr
: 2
Controllo dei tipi
Google SecOps esegue il controllo dei tipi sulla sintassi YARA-L mentre crei regole all'interno dell'interfaccia. Gli errori di controllo del tipo visualizzati ti aiutano a rivedere la regola in modo da verificare 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 multi-evento contengono campioni di eventi per fornire contesto sugli eventi che hanno causato il rilevamento. Esiste un limite di 10 campioni di eventi per ogni variabile evento definita nella regola. Ad esempio, se una regola definisce 2 variabili evento, ogni rilevamento può avere fino a 20 campioni di eventi. Il limite si applica a ogni variabile evento separatamente. Se una variabile evento ha 2 eventi applicabili in questo rilevamento e l'altra variabile evento ha 15 eventi applicabili, il rilevamento risultante contiene 12 campioni di eventi (2 + 10).
Tutti i campioni di eventi che superano il limite vengono omessi dal rilevamento.
Se vuoi maggiori informazioni sugli eventi che hanno causato il rilevamento, puoi utilizzare le aggregazioni nella sezione Risultato per visualizzare informazioni aggiuntive nel rilevamento.
Se visualizzi i rilevamenti nell'interfaccia utente, puoi scaricare tutti i campioni di eventi per un rilevamento. Per maggiori informazioni, vedi Eventi di download.
Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.