Sintassi della sezione Corrispondenza

Supportato in:

Google SecOps SIEM

In YARA-L 2.0, la sezione match fornisce il meccanismo per la correlazione di più eventi. Definisce la logica per raggruppare gli eventi in un'unica rilevazione collegando attributi comuni, come utenti, indirizzi IP o hash dei file, entro un limite temporale specifico.

Utilizzi la sezione match per i seguenti casi d'uso:

Collega due o più eventi distinti all'interno di una regola.
Aggrega i dati in Ricerca e nelle dashboard, ad esempio contando i tentativi di accesso non riusciti in un periodo di tempo specifico.

Definisci i criteri di correlazione

Utilizzalo per definire i criteri per questa correlazione specificando quanto segue:

Campi di raggruppamento (chiavi): variabili (come $user o $ip) che devono avere valori identici negli eventi (definiti nella sezione events) per attivare una corrispondenza.
Vincolo temporale: la finestra di durata in cui devono verificarsi gli eventi raggruppati per soddisfare la regola o l'aggregazione. In Regole, definisce la finestra di rilevamento; in Ricerca e dashboard, definisce la finestra di aggregazione o correlazione.

Confrontare i requisiti delle funzionalità

La tabella seguente descrive in dettaglio i confronti per le regole di ricerca e le dashboard.

Funzionalità	Requisito delle regole	Supporto per la ricerca e le dashboard
Tipi di variabili	Devono essere utilizzati i segnaposto definiti nella sezione `events`.	Supporta sia i segnaposto che i campi UDM diretti.
Finestra temporale	Definisce il confine di rilevamento.	Definisce il bucket di aggregazione o correlazione.
Sintassi	`over <number><m/h/d>` (ad esempio, `10m`, `2h`, `1d`)	`over <number><m/h/d>`
Limiti	Min: `1m` / Max: `48h`	Min: `1m` / Max: `48h`

Tipi di finestre supportati

YARA-L 2.0 utilizza diversi comportamenti di finestra per determinare come viene suddiviso il tempo e come vengono raggruppati gli eventi. Puoi raggruppare i segnaposto e i campi evento nella sezione match in base a una granularità temporale specificata utilizzando una delle seguenti finestre supportate.

Tipo di finestra supportato	Sintassi	Descrizione	Caso d'uso comune
Hop	`$key over <duration>`	Intervalli di tempo sovrapposti (comportamento predefinito).	Correlazione generale di più eventi.
Tumbling	`$key by <duration>`	Intervalli di tempo continui, non sovrapposti e di dimensioni fisse.	Quantificazione dell'attività in blocchi di massimo 1 ora (ad esempio, `$user by 30m`).
Scorrimento	`$key over <duration> [before\|after] $pivot`	Intervalli di tempo ancorati a un evento "pivot" specifico.	Sequenza rigorosa (ad esempio, `File Download after Login`).

Sintassi di esempio:

match:
  $user, $source_ip over 5m  // Groups events by user and IP within a 5-minute window

Finestra di hopping

Una finestra di salto è il comportamento predefinito per le regole multi-evento. Crea intervalli di tempo sovrapposti per assicurarsi che gli eventi che si verificano vicino ai limiti di una finestra non vengano persi.

Sintassi: $key over <duration> (ad esempio, $user over 30m)
Caso d'uso: ideale per il rilevamento quando devi assicurarti che uno scenario specifico venga rilevato indipendentemente da quando inizia o termina esattamente l'intervallo della finestra.
Supporto: supportato per l'aggregazione nella ricerca e nelle dashboard (ad esempio, count).

Per impostazione predefinita, le query YARA-L con una sezione match utilizzano finestre di hop per correlare più eventi nel tempo. L'intervallo di tempo di esecuzione della query è suddiviso in un insieme di finestre di salto fisse e sovrapposte. Mentre la durata di queste finestre è specificata nella sezione match, l'intervallo di sovrapposizione e l'allineamento delle finestre sono definiti dal sistema e non sono configurabili dall'utente. Gli eventi vengono poi correlati all'interno di ciascuna di queste finestre predeterminate.

Esempio: finestre di hop sovrapposte per la correlazione continua

L'esempio seguente mostra una query eseguita nell'intervallo di tempo [1:00, 2:00], con una sezione match $user over 30m, in cui 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].

rule hop_window_brute_force_example {
meta:
  description = "Detects multiple failed logins within a shifting 30-minute window."
  severity = "Medium"

events:
  $login.metadata.event_type = "USER_LOGIN"
  $login.extensions.auth.auth_status = "FAILURE"
  $login.principal.user.userid = $user

match:
  // This creates the overlapping windows (e.g., 1:00-1:30, 1:03-1:33)
  $user over 30m

condition:
  // This will trigger if 10 or more failures fall into any single 30m hop
  #login >= 10
}

Esempio: correlazione di più eventi utilizzando una finestra di hop

L'esempio seguente rappresenta il valore predefinito per la maggior parte delle regole multi-evento. Acquisisce gli eventi che si verificano nello stesso periodo di tempo generale.

rule hop_window_example {
meta:
  description = "Detect a user with a failed login followed by a success within 30m"

events:
  $e1.metadata.event_type = "USER_LOGIN"
  $e1.extensions.auth.auth_status = "FAILURE"
  $e1.principal.user.userid = $user

  $e2.metadata.event_type = "USER_LOGIN"
  $e2.extensions.auth.auth_status = "SUCCESS"
  $e2.principal.user.userid = $user

match:
  $user over 30m  // This is a hop window

condition:
  $e1 and $e2
}

Esempio: confronto delle finestre di salto

Per identificare un tentativo di attacco di tipo brute force, una finestra 10m raggruppa tutti i USER_LOGINerrori. Il condition valuta quindi se il conteggio (#e) all'interno di quel bucket specifico di 10 minuti supera la soglia.

rule failed_logins
{
meta:
  author = "Security Team"
  description = "Detects multiple failed user logins within 10-minute windows."
  severity = "HIGH"

events:
  $e.metadata.event_type = "USER_LOGIN"
  $e.security_result.action = "FAIL"
  $user = $e.target.user.userid

match:
  $user over 10m

condition:
  #e >= 5
}

La sezione match individua gli utenti con un accesso non riuscito in una nuova posizione in un intervallo di 10 minuti (10m):

match:
  $user over 10m

Finestre temporali fisse (a cascata)

Una finestra temporale suddivide un flusso di dati in intervalli di tempo continui, non sovrapposti e di dimensioni fisse. Il timestamp di ogni evento rientra in una sola finestra. Non c'è sovrapposizione tra le finestre temporali. Ciò è in contrasto con una finestra scorrevole o a salti, che può avere intervalli di tempo sovrapposti.

Per implementare una finestra temporale, utilizza l'operatore by nella sezione match.

Le finestre temporali mobili dividono il tempo in blocchi continui e consecutivi. Ad esempio:

by 1h: crea finestre per ogni ora (ad esempio, [00:00:00-00:59:59], [01:00:00-01:59:59] e così via).
by 10m: crea finestre per ogni intervallo di 10 minuti (ad esempio, [00:00:00-00:09:59], [00:10:00-00:19:59] e così via).

Casi d'uso

Utilizza le finestre temporali quando necessario.

Analizza gli eventi in blocchi di tempo distinti e non sovrapposti.
Assicurati che venga generato un solo rilevamento per una determinata entità (come definita dalle variabili di corrispondenza) all'interno di ogni intervallo di tempo fisso, indipendentemente dal numero di volte in cui si verifica l'evento.
Conteggia le entità uniche in periodi fissi.

Comportamento di deduplicazione

Una caratteristica fondamentale delle finestre temporali è il modo in cui vengono gestite le rilevazioni all'interno di ogni finestra per lo stesso insieme di variabili di corrispondenza:

Una rilevazione per finestra:per un determinato insieme di valori per le variabili di corrispondenza (ad esempio, un $userid specifico), viene generata al massimo una rilevazione per ogni singola finestra temporale.
Priorità al primo evento: gli eventi inseriti per primi che soddisfano le condizioni della regola per quel set di variabili di corrispondenza all'interno di una finestra specifica attivano il rilevamento.
De-duplicazione:gli eventi successivi che corrispondono ai criteri all'interno della stessa istanza della finestra non genereranno rilevamenti aggiuntivi.

Sintassi

La sintassi nella sezione match è:

match:
  $variable by <duration>

dove:

$variable è la variabile segnaposto su cui stai eseguendo la corrispondenza.
<duration> è un numero seguito da un'unità di tempo:
- m: minuto
- h: ora
- d: giorno
Specifica un minimo di un minuto e un massimo di 72 ore o tre giorni.

Esempio

Il seguente gruppo di regole raggruppa gli accessi per $userid in finestre non sovrapposte di 1 ora (ad esempio, [00:00:00-00:59:59], [01:00:00-01:59:59] e così via):

rule TumblingWindowExample {
  meta:
    description = "Example using a 1-hour tumbling window"
  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $userid
  match:
    $userid by 1h
  condition:
    $e
}

Di seguito è riportato un esempio di comportamento di rilevamento per user = "alex":

Evento 1: Alex esegue l'accesso alle 00:30. Rientra nella finestra [00:00:00-00:59:59]. Per questa finestra viene generato un rilevamento per Alex.
Evento 2: un altro utente, "taylor", esegue l'accesso alle 00:45. Anche questo rientra nell'intervallo [00:00:00-00:59:59], ma poiché il $userid è diverso, in questa finestra viene generato un rilevamento separato per Taylor.
Evento 3: Alex esegue di nuovo l'accesso alle 00:40. Rientra ancora nella finestra [00:00:00-00:59:59]. Poiché esiste già un rilevamento per Alex per questa finestra, questo evento viene deduplicato. Non viene generato alcun nuovo rilevamento.
Evento 4: Alex esegue l'accesso alle 01:20. Rientra nella finestra successiva, [01:00:00-01:59:59]. Per questa nuova finestra viene generata una nuova rilevazione per Alex.

Anche se l'evento 1 e l'evento 4 per Alice si sono verificati a meno di un'ora di distanza, rientrano in rilevamenti separati perché l'evento 4 supera il limite della finestra fissa.

Finestra scorrevole

Utilizza una finestra mobile quando devi cercare eventi che si verificano in un ordine relativo rigoroso (ad esempio, e1 si verifica fino a due minuti dopo e2). A differenza delle finestre fisse, una finestra mobile viene attivata da ogni occorrenza di $pivot_event designato utilizzando questa sintassi:

after: la finestra inizia al timestamp dell'evento pivot e si estende in avanti.
before: La finestra termina al timestamp dell'evento pivot e si estende all'indietro.

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

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

Sintassi: $key over <duration> before|after $<pivot_event>
Chiavi di raggruppamento: campi comuni (ad esempio $user, $ip) utilizzati per collegare gli eventi.
Durata: offset temporale rispetto all'evento pivot (ad esempio, 5m, 1h).
Casi d'uso:
- Sequenza rigorosa: rileva una catena di attacchi in cui è richiesto un ordine (ad esempio, la creazione di un utente seguita da un escalation dei privilegi).
- Tempistica relativa: trova un evento che si verifica entro un offset specifico di un "trigger" (ad esempio, un evento Process Start seguito da un evento Network Connection entro 30 secondi).
- Rilevamento dell'assenza: identifica quando un evento "cleanup" o "battito cardiaco" obbligatorio non si verifica dopo un evento di inizio (ad esempio, un Database Backup Start senza un evento End corrispondente).

Esempi validi di finestre scorrevoli

I seguenti esempi mostrano finestre scorrevoli valide:

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

Esempio: correlazione prospettica con finestre scorrevoli (`after`)

L'esempio seguente mostra come rilevare una sequenza di eventi in cui il secondo evento deve verificarsi entro un periodo di tempo specifico dopo un evento "trigger" o pivot principale. Ciò è utile per rilevare movimenti laterali rapidi o azioni successive automatizzate.

rule sliding_window_after_example {
meta:
  description = "Detect a network connection occurring within 1 minute after a suspicious process launch."
  severity = "High"

events:
  $proc.metadata.event_type = "PROCESS_LAUNCH"
  $proc.principal.hostname = $host

  $net.metadata.event_type = "NETWORK_HTTP"
  $net.principal.hostname = $host

match:
  // $proc is the pivot; the 1-minute window starts at the $proc timestamp
  $host over 1m after $proc

condition:
  $proc and $net
}

Esempio: correlazione retrospettiva con finestre scorrevoli (`before`)

Utilizza una finestra scorrevole "before" per esaminare l'attività che ha portato a un avviso specifico. Viene spesso utilizzato nell'analisi della causa principale per identificare cosa è successo immediatamente prima di un rilevamento critico.

rule sliding_window_before_example {
meta:
  description = "Identify file modifications occurring in the 5 minutes before a ransomware alert."
  severity = "Critical"

events:
  $file.metadata.event_type = "FILE_MODIFICATION"
  $file.principal.hostname = $host

  $alert.metadata.event_type = "ANTIVIRUS_DETECTION"
  $alert.metadata.product_name = "Premium_AV"
  $alert.principal.hostname = $host

match:
  // $alert is the pivot; the 5-minute window ends at the $alert timestamp
  $host over 5m before $alert

condition:
  $file and $alert
}

Rendimento e best practice

Le finestre scorrevoli richiedono una maggiore potenza di elaborazione rispetto alle finestre standard (hop) perché vengono calcolate per ogni occorrenza dell'evento pivot e possono comportare prestazioni più lente.

Segui queste linee guida per un rendimento ottimale in regole, ricerca e dashboard:

Dai la priorità alle finestre temporali: utilizza la finestra temporale predefinita, a meno che la sequenza specifica di eventi (ordine A, poi ordine B) non sia necessaria per la logica di rilevamento. Utilizza le finestre scorrevoli solo quando la sequenza degli eventi è fondamentale o quando cerchi eventi mancanti.
Utilizza i filtri timestamp per il rendimento: se devi solo assicurarti che un evento si sia verificato dopo un altro, un confronto dei timestamp nella sezione events o condition è spesso più efficiente di una finestra mobile, ad esempio:

$e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds

Progettazione multi-evento: evita di utilizzare finestre scorrevoli per le query a evento singolo. Le finestre scorrevoli sono progettate per la correlazione di più eventi. Per la logica di un singolo evento, si applicano le seguenti linee guida:
- Utilizza più variabili evento e aggiorna la sezione condition.
- Rimuovi completamente la sezione match se la correlazione non è necessaria.
- Se vuoi, valuta la possibilità di aggiungere filtri per i timestamp anziché utilizzare una finestra mobile, ad esempio:
  $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds

Informazioni sul limite temporale

La sezione match suddivide gli eventi in gruppi in base alle chiavi di raggruppamento. La durata specificata definisce il limite temporale per ogni gruppo:

Inclusione: solo gli eventi all'interno della finestra vengono passati alla valutazione condition per quella corrispondenza specifica.
Esclusione: gli eventi al di fuori della finestra vengono ignorati per quel gruppo di corrispondenza specifico, impedendo che eventi non correlati attivino un falso positivo.

Valori pari a zero nella sezione `match`

Google SecOps filtra implicitamente i valori pari a zero per tutti i segnaposto utilizzati nella sezione match ("" per le stringhe, 0 per i numeri, false per i valori booleani, il valore nella posizione 0 per i tipi enumerati).

Esempio: filtrare i valori pari a zero

Il seguente esempio illustra le query che escludono i valori pari a zero.

rule ZeroValuePlaceholderExample {

events:
  // Because $host is used in the match section, the query 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,
  // 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 query non filtrano implicitamente i valori zero dei segnaposto utilizzati nella sezione match.

Per disattivare il filtro implicito dei valori zero, puoi utilizzare l'opzione allow_zero_values nella sezione delle opzioni. L'opzione allow_zero_values è disponibile solo in Regole.

Esempio: consenti valori zero

Il seguente esempio illustra le query che non filtrano implicitamente i valori zero dei segnaposto utilizzati nella sezione match:

rule AllowZeroValuesExample {

events:
  // Because allow_zero_values is set to true, there is no implicit filtering
  // of zero values for $host.
  $host = $e.principal.hostname

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

match:
  $host over 5m

condition:
  $e

options:
  allow_zero_values = true
}

Passaggi successivi

Esplora le seguenti risorse per continuare la logica YARA-L o approfondire le funzioni di query avanzate:

Sintassi e logica

Riferimenti ed esempi

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