Sintassi della sezione Corrispondenza

Supportato in:

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> tumbling 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

Finestra a cascata

Una finestra temporale progressiva segmenta un flusso di dati in intervalli di tempo continui, non sovrapposti e di dimensioni fisse. Ogni evento di dati viene assegnato a una sola finestra. Ciò è in contrasto con una finestra scorrevole o a salti, che può avere intervalli di tempo sovrapposti.

  • Sintassi: utilizza l'operatore by ($key by <duration>), ad esempio $user by 30m.
  • Caso d'uso: ideale per generare report e creare dashboard in cui vuoi conteggiare gli eventi in blocchi distinti (ad esempio, "How many alerts per hour?").
  • Ricerca e dashboard: utilizzate spesso per creare grafici a barre puliti senza deduplicare gli eventi.

Esempio: conteggio a intervallo fisso con finestre temporali

L'esempio seguente mostra una finestra temporale di 30 minuti, in cui gli eventi che si verificano tra le 1:00:00 e le 1:29:59 vengono elaborati insieme. Poi, il successivo insieme di eventi, dalle 1:30:00 alle 1:59:59, viene elaborato separatamente.

rule tumbling_window_threshold_example {
meta:
  description = "Detect more than 50 failed logins from a single IP within a fixed 1-hour block."
  severity = "Medium"

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

match:
// This creates distinct, 1-hour blocks (e.g., 1:00-1:59, 2:00-2:59)
  $ip by 1h

condition:
  #login > 50
}

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 ogni volta che si verifica l'$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 assenza: identifica quando un evento "pulizia" o "battito" 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

Gli esempi seguenti 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 delle cause principali 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

Comprendere il 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 corrispondenze 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.