Logica di finestra di YARA-L 2.0

Supportato in:

Questa guida aiuta gli ingegneri della sicurezza a scegliere il tipo di finestra corretto per le query per evitare errori del compilatore "variabile non associata". La transizione dalle finestre scorrevoli alle finestre temporali consente di creare una logica che dipende dall'assenza di eventi, ad esempio un heartbeat mancante o un'origine log non riuscita.

Prima di iniziare

Verifica che il tuo account disponga di uno dei seguenti ruoli per creare e modificare le query YARA-L:

  • Amministratore Detection Engine (roles/chronicle.detectionEngineAdmin)
  • Editor SecOps (roles/chronicle.editor)

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 campi evento e i segnaposto nella sezione match in base a una granularità temporale specificata utilizzando le seguenti finestre supportate:

Tipo di finestra supportato Sintassi Descrizione Caso d'uso comune
Hop $key over <duration> Crea intervalli di tempo fissi e sovrapposti. Il sistema definisce la sovrapposizione e l'allineamento per rilevare gli eventi vicino ai limiti. Correlazione generale di più eventi, indipendentemente dagli orari di inizio esatti.
Tumbling $key by <duration> Segmenta i dati in blocchi continui, non sovrapposti e di dimensioni fisse. Valuta indipendentemente dall'arrivo dell'evento. Quantificare l'attività in slot fissi (ad esempio, $user by 30m) o rilevare l'assenza di eventi.
Scorrimento $key over <duration> [before|after] $pivot Ancora la finestra a un evento "pivot" specifico. Richiede che esista un punto di rotazione per attivare una ricerca indietro o in avanti. Sequenza rigorosa in cui l'ordine degli eventi è fondamentale (ad esempio, File Download after Login).

Comprendere la logica di window_start e window_end

Google Security Operations fornisce due parole chiave universali riservate che vengono risolte direttamente in timestamp GoogleSQL da utilizzare nelle query. Queste parole chiave ti consentono di accedere ai limiti dei bucket temporali:

  • window_start: il limite iniziale del bucket temporale.
  • window_end: il limite di chiusura del bucket temporale.

Vincoli di utilizzo

  • Requisito di corrispondenza:per utilizzare queste parole chiave, devi definire una finestra (by o over) nella sezione match.
  • Limitazione della sezione:utilizza queste parole chiave in condition, order o outcome. Non sono validi nella sezione events.
  • Spazio dei nomi:non utilizzarli come nomi di variabili personalizzate (ad esempio, $window_start).

Determinare il tipo di finestra e la sintassi

Utilizza questa tabella come riferimento rapido per determinare il tipo di finestra e la sintassi da utilizzare per le regole di rilevamento.

Scenario Finestra consigliata Parole chiave consigliate Vantaggio principale
Rilevamenti ad alta frequenza (ad esempio, attacchi di forza bruta) Finestra scorrevole (over) window_start, window_end Si attiva immediatamente quando la soglia viene raggiunta in un periodo di tempo continuativo.
Assenza/non esistenza (ad esempio, battito cardiaco assente) Finestra a cascata (by) window_start, window_end Valuta i blocchi di tempo fissi anche se non si verificano eventi, evitando errori di tipo Variabile non delimitata.
Report cronologico Scivolamento o caduta order: window_start asc Standardizza l'output degli avvisi per semplificare l'analisi della cronologia nell'interfaccia utente di Chronicle.
Filtro basato sul tempo Scivolamento o caduta condition: window_start > "2026-01-01 00:00:00Z" Limita la valutazione delle regole a date specifiche utilizzando la conversione del timestamp GoogleSQL.

Confrontare i tipi di timestamp e i fusi orari

YARA-L supporta il confronto diretto di window_start e window_end con le stringhe nel formato timestamp GoogleSQL. In questo modo puoi eseguire un filtraggio preciso senza conversione manuale dei tipi.

Nota:specifica sempre il fuso orario UTC utilizzando il suffisso Z (ad esempio, "2026-03-17T17:35:00Z") per allinearti ai timestamp degli eventi UDM.

Utilizza i filtri dei timestamp per il rendimento. Se devi solo confermare che un evento si è verificato dopo un altro, un confronto dei timestamp nella sezione condition è spesso più efficiente: $e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds.

Scopri di più sulla sintassi della sezione match e sulla sintassi della sezione condition.

Esempi: window_end e window_start

  • window_end < "2026-01-01T12:30:00Z" (data, ora e suffisso UTC)
  • window_start != "2026-01-01 15:00:00+00" (con scarto da UTC)

Se il confronto non riesce, verifica che la stringa segua il formato timestamp canonico GoogleSQL.

Hop windows

Una finestra di salto crea intervalli di tempo sovrapposti in modo che gli eventi che si verificano vicino ai limiti di una finestra non vengano persi.

  • Caso d'uso:ideale per i rilevamenti in cui è necessario acquisire uno scenario specifico indipendentemente da quando inizia o termina esattamente l'intervallo della finestra.
  • Supporto:supportato per l'aggregazione in Ricerca e nelle dashboard.

Le query YARA-L con una sezione match utilizzano finestre di salto per correlare più eventi nel tempo. Il sistema divide l'intervallo di tempo di esecuzione della query in un insieme di finestre hop fisse e sovrapposte. Mentre specifichi la durata di queste finestre nella sezione match, il sistema definisce l'intervallo di sovrapposizione e l'allineamento delle finestre. Gli eventi vengono poi correlati all'interno di ciascuna di queste finestre predeterminate.

Scopri di più sulla sintassi della sezione match.

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. Un possibile insieme di finestre di coincidenza sovrapposte generate dal sistema è [1:00, 1:30], [1:03, 1:33] e [1:06, 1:36].

Regola

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
}

metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user

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

Dashboard

metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user

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

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

Il seguente esempio acquisisce gli eventi che si verificano nello stesso periodo di tempo generale:

Regola

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

events:
  // Event 1: Capture failed login attempts
  $fail.metadata.event_type = "USER_LOGIN"
  $fail.security_result.action = "FAIL"
  $fail.principal.user.userid = $user

  // Event 2: Capture successful login attempts
  $success.metadata.event_type = "USER_LOGIN"
  $success.security_result.action = "ALLOW"
  $success.principal.user.userid = $user

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

condition:
  // Ensure both a failed ($fail) and a successful ($success) login event occurred for the same user within the 30m window.
  $fail and $success
}

Cerca

// Event 1: Capture failed login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user // Assign user ID to a placeholder

// Event 2: Capture successful login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "ALLOW"
principal.user.userid = $user // Link to the same user placeholder

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

Dashboard

// Event 1: Capture failed login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user // Assign user ID to a placeholder

// Event 2: Capture successful login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "ALLOW"
principal.user.userid = $user // Link to the same user placeholder

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

Esempio: confronto della finestra di hop

Per identificare un tentativo di attacco di tipo brute force, una finestra 10m raggruppa tutti gli errori USER_LOGIN. La condizione valuta quindi se il conteggio (#e) all'interno di questo bucket specifico di 10 minuti supera la soglia.

Regola

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
}

Cerca

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

match:
  $user over 10m

Dashboard

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

match:
  $user over 10m

Finestre a cascata

Nota:questa funzionalità non è disponibile per tutti i clienti in tutte le regioni.

Una finestra temporale sequenziale segmenta i 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 hop o una finestra scorrevole, che possono avere intervalli di tempo sovrapposti.

Per implementare una finestra a cascata, utilizza l'operatore by nella sezione match. Le finestre temporali consecutive 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]).
  • by 10m: crea finestre per ogni intervallo di 10 minuti (ad esempio, [00:00:00-00:09:59], [00:10:00-00:19:59]).

Casi d'uso comuni

Utilizza le finestre temporali quando necessario:

  • Analizza gli eventi in blocchi di tempo distinti e non sovrapposti.
  • Genera 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 il motore gestisce i rilevamenti 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), il motore genera al massimo una rilevazione per una singola finestra a cascata.
  • Priorità al primo arrivato: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.
  • Rimozione dei duplicati:gli eventi successivi che corrispondono ai criteri all'interno della stessa istanza della finestra non genereranno ulteriori rilevamenti.

Sintassi

La sintassi nella sezione match è: match: $variable by <duration>

  • $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: raggruppamento a intervallo fisso

Il seguente gruppo di regole raggruppa gli accessi per $userid in finestre non sovrapposte di 1 ora.

Regola

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
}

Cerca

metadata.event_type = "USER_LOGIN"
principal.user.userid = $userid

match:
  $userid by 1h

Dashboard

metadata.event_type = "USER_LOGIN"
principal.user.userid = $userid

match:
  $userid by 1h

Esempio: comportamento di rilevamento (user = "Alex")

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

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

Configura le finestre temporali per i rilevamenti di assenza

Per generare un avviso in caso di conteggio pari a zero ed evitare errori del compilatore, completa i seguenti passaggi:

  1. Identifica l'obiettivo del rilevamento. Determina se stai cercando un'alta frequenza o una mancanza di attività.
  2. Seleziona la windowparola chiave. Utilizza over per la frequenza e by per l'assenza.
  3. Limiti della finestra di riferimento. Utilizza le parole chiave window_start e window_end per fare riferimento a limiti specifici del bucket temporale.

Contesto:utilizza outcome: $ext_window_end = window_end per includere l'ora di fine esatta di un heartbeat mancante nei metadati dell'avviso.

Esempio: rilevare un battito cardiaco mancante con i metadati

Le finestre temporali consentono di generare avvisi in caso di conteggio pari a zero, il che ti aiuta a evitare errori del compilatore quando cerchi una mancanza di attività.

Regola

rule missing_heartbeat_detection {
meta:
  description = "Alert when a system fails to check in within a 24h block"

events:
  $e.metadata.event_type = "STATUS_UPDATE"
  $host = $e.principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count($e.metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

condition:
  $event_count = 0 and window_start > "2026-01-01T12:30:00Z"
}

Cerca

metadata.event_type = "STATUS_UPDATE"
$host = principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count(metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

Dashboard

metadata.event_type = "STATUS_UPDATE"
$host = principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count(metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

Finestre scorrevoli

Una finestra mobile è ancorata a un evento pivot specifico e guarda avanti (after) o indietro (before).

Casi d'uso comuni

Utilizza finestre scorrevoli quando la sequenza degli eventi è fondamentale:

  • Sequenza rigorosa:rileva una catena di attacchi (ad esempio, e1 si verifica fino a due minuti dopo e2).
  • Tempistica relativa:trova un evento che si verifica entro un offset specifico di un trigger (ad esempio, un Network Connection entro 30 secondi da un Process Start).
  • Rilevamento dell'assenza:identifica quando un evento "pulizia" o "battito" richiesto non si verifica dopo un evento di inizio.

Sintassi

match: <grouping_keys> over <duration> [before|after] <$pivot_event>

Componente Descrizione Esempio
Chiavi di raggruppamento Campi comuni utilizzati per collegare gli eventi. $host, $user
Durata L'offset temporale rispetto all'evento pivot. 5m, 1h, 30s
Direzione Se la finestra si estende in avanti o indietro. after, before
Evento pivot La variabile evento che ancora la finestra. $proc, $alert

Di seguito sono riportati alcuni esempi di finestre scorrevoli valide:

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

Requisiti e limitazioni

  • Prestazioni: le finestre scorrevoli richiedono più potenza di elaborazione rispetto alle finestre a salto. Utilizzali solo quando l'ordine degli eventi è strettamente necessario (ad esempio, quando un evento deve verificarsi entro cinque minuti da un altro evento).
  • Query su un singolo evento: non utilizzare finestre scorrevoli per la logica di un singolo evento. Utilizza più variabili evento nella sezione condition.

Esempio: correlazione prospettica (after)

Regola

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
}

Cerca

after non è supportato per la Ricerca.

Dashboard

after non è supportato per le dashboard.

Esempio: correlazione retrospettiva (before)

Utilizza una finestra scorrevole di "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.

Regola

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
}

Cerca

before non è supportato per la Ricerca.

Dashboard

before non è supportato per le dashboard.

Risoluzione dei problemi

Utilizza questa sezione per comprendere la latenza, i limiti e le correzioni per i problemi comuni di finestre in YARA-L.

Latenza e limiti

  • Le regole che utilizzano finestre temporali (by) vengono attivate solo alla fine del blocco di tempo fisso. Ad esempio, una regola con match: $user by 24h viene valutata solo dopo che è trascorso l'intero periodo di 24 ore.

  • Latenza degli avvisi:le regole che utilizzano by (a cascata) vengono attivate solo dopo che è trascorso il blocco di tempo fisso. Una regola by 24h non genera avvisi a metà finestra.

  • Mancata corrispondenza della UI:in Ricerca e dashboard, la parola chiave window_start si riferisce direttamente al campo TIME_BUCKET. Quando filtri o raggruppi per window_start, l'intestazione della colonna viene visualizzata come TIME_BUCKET nell'interfaccia utente.Si tratta di una limitazione nota della visualizzazione dell'interfaccia utente; la logica rimane valida.

Correzione degli errori

Codice di errore Descrizione Correggi
Variabile non vincolata La regola utilizza over (finestra scorrevole) con una condizione $count = 0. Modifica la parola chiave di raggruppamento in by (finestra mobile). Le finestre scorrevoli richiedono l'esistenza di un evento per ancorare la finestra, mentre le finestre temporali non lo richiedono.
UI Header Mismatch L'utente vede TIME_BUCKET nell'interfaccia utente anziché window_start. Non è necessaria alcuna correzione. La logica di filtraggio e ordinamento continua a funzionare correttamente utilizzando le parole chiave.
Identificatore sconosciuto: window_start La parola chiave viene utilizzata, ma non è definita alcuna finestra in match. Aggiungi una dichiarazione di windowing alla sezione match (ad esempio, $hostname by 1h).
Utilizzo non valido di window_start negli eventi La parola chiave viene citata nella sezione events. Sposta la logica nella sezione condition o outcome. I limiti della finestra vengono calcolati solo dopo il raggruppamento degli eventi nella fase di corrispondenza.

Passaggi successivi

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