YARA-L 2.0 – Fensterlogik

Unterstützt in:

In diesem Leitfaden erfahren Security Engineers, wie sie den richtigen Fenstertyp für Abfragen auswählen, um Compilerfehler vom Typ „variable not bounded“ (Variable nicht gebunden) zu vermeiden. Wenn Sie von gleitenden zu rollierenden Fenstern wechseln, können Sie Logik erstellen, die vom Fehlen von Ereignissen abhängt, z. B. von einem fehlenden Heartbeat oder einer fehlgeschlagenen Protokollquelle.

Hinweis

Prüfen Sie, ob Ihrem Konto eine der folgenden Rollen zugewiesen ist, damit Sie YARA-L-Abfragen erstellen und ändern können:

  • Detection Engine-Administrator (roles/chronicle.detectionEngineAdmin)
  • SecOps-Bearbeiter (roles/chronicle.editor)

Unterstützte Fenstertypen

YARA-L 2.0 verwendet unterschiedliche Windowing-Verhaltensweisen, um zu bestimmen, wie die Zeit unterteilt und wie Ereignisse gruppiert werden. Sie können Ereignisfelder und Platzhalter im Abschnitt match mit den folgenden unterstützten Zeiträumen nach einer angegebenen Zeitgranularität gruppieren:

Unterstützter Fenstertyp Syntax Beschreibung Gängige Anwendungsfälle
Hop $key over <duration> Erstellt feste, sich überschneidende Zeitintervalle. Das System definiert die Überschneidung und Ausrichtung, um Ereignisse in der Nähe von Grenzen zu erfassen. Allgemeine Korrelation mehrerer Ereignisse, unabhängig von den genauen Startzeiten.
Tumbling $key by <duration> Segmentiert Daten in kontinuierliche, nicht überlappende Blöcke mit fester Größe. Wird unabhängig vom Eintreffen von Ereignissen ausgewertet. Aktivitäten in festen Zeiträumen quantifizieren (z. B. $user by 30m) oder das Fehlen von Ereignissen erkennen.
Gleiten $key over <duration> [before|after] $pivot Verankert das Fenster an einem bestimmten "pivot"-Ereignis. Erfordert, dass ein Pivot vorhanden ist, um einen Rückblick oder Ausblick auszulösen. Strikte Abfolge, bei der die Reihenfolge der Ereignisse entscheidend ist (z. B. File Download after Login).

window_start- und window_end-Logik verstehen

Google Security Operations bietet zwei universelle, reservierte Keywords, die direkt in GoogleSQL-Zeitstempel aufgelöst werden und in Abfragen verwendet werden können. Mit diesen Keywords können Sie auf die Grenzen Ihrer Zeiträume zugreifen:

  • window_start: Die Anfangsgrenze des Zeit-Buckets.
  • window_end: Die obere Grenze des Zeit-Buckets.

Nutzungsbeschränkungen

  • Anforderung für den Abgleich:Sie müssen im Abschnitt match einen Zeitraum (by oder over) definieren, um diese Keywords verwenden zu können.
  • Abschnittseinschränkung:Verwenden Sie diese Keywords in condition, order oder outcome. Sie sind im Abschnitt „events“ ungültig.
  • Namespace:Verwenden Sie diese nicht als Namen für benutzerdefinierte Variablen (z. B. $window_start).

Fenstertyp und ‑syntax ermitteln

Verwenden Sie diese Tabelle als Kurzübersicht, um zu ermitteln, welchen Fenstertyp und welche Syntax Sie für Ihre Erkennungsregeln verwenden müssen.

Szenario Empfohlenes Fenster Empfohlene Keywords Wichtigster Vorteil
Erkennungen mit hoher Häufigkeit (z. B. Brute-Force-Angriffe) Schiebefenster (over) window_start, window_end Wird sofort ausgelöst, wenn der Schwellenwert in einem rollierenden Zeitraum erreicht wird.
Fehlen/Nichtvorhandensein (z. B. fehlende Herzschläge) Rollierendes Fenster (by) window_start, window_end Feste Zeitblöcke werden auch dann ausgewertet, wenn keine Ereignisse auftreten. So werden Variable Not Bounded-Fehler vermieden.
Chronologisches Reporting Rutschen oder Purzeln order: window_start asc Die Ausgabe von Benachrichtigungen wird standardisiert, um die Analyse der Zeitachse in der Chronicle-Benutzeroberfläche zu erleichtern.
Zeitgebundene Filterung Rutschen oder Purzeln condition: window_start > "2026-01-01 00:00:00Z" Beschränkt die Regelauswertung auf bestimmte Datumsangaben mithilfe der GoogleSQL-Zeitstempelumwandlung.

Zeitstempeltypen und Zeitzonen vergleichen

In YARA-L können window_start und window_end direkt mit Strings im GoogleSQL-Zeitstempelformat verglichen werden. So können Sie präzise filtern, ohne eine manuelle Typumwandlung durchführen zu müssen.

Hinweis:Geben Sie UTC immer mit dem Suffix Z an (z. B. "2026-03-17T17:35:00Z"), damit die Zeitstempel mit denen von UDM-Ereignissen übereinstimmen.

Zeitstempelfilter für die Leistung verwenden Wenn Sie nur bestätigen müssen, dass ein Ereignis nach einem anderen stattgefunden hat, ist ein Zeitstempelvergleich im Abschnitt condition oft effizienter: $e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds.

Weitere Informationen zur Syntax des Abschnitts match und zur Syntax des Abschnitts condition

Beispiele: window_end und window_start

  • window_end < "2026-01-01T12:30:00Z" (Datum, Uhrzeit und UTC-Suffix)
  • window_start != "2026-01-01 15:00:00+00" (mit UTC-Versatz)

Wenn der Vergleich fehlschlägt, prüfen Sie, ob Ihr String dem kanonischen GoogleSQL-Zeitstempelformat entspricht.

Fenster wechseln

Mit einem springenden Fenster werden sich überschneidende Zeitintervalle erstellt, damit Ereignisse, die in der Nähe der Grenzen eines Fensters auftreten, nicht übersehen werden.

  • Anwendungsfall:Am besten für Erkennungen geeignet, bei denen ein bestimmtes Szenario erfasst werden muss, unabhängig davon, wann genau das Zeitfenster beginnt oder endet.
  • Unterstützung:Wird für die Aggregation in Search und Dashboards unterstützt.

Bei YARA-L-Abfragen mit einem match-Abschnitt werden Hop-Fenster verwendet, um mehrere Ereignisse im Zeitverlauf zu korrelieren. Das System unterteilt den Zeitraum der Abfrageausführung in eine Reihe von festen, sich überschneidenden Hop-Fenstern. Die Dauer dieser Fenster geben Sie im Abschnitt match an. Das System definiert das Überschneidungsintervall und die Fensterausrichtung. Ereignisse werden dann innerhalb der einzelnen vorgegebenen Zeiträume in Beziehung gesetzt.

Weitere Informationen zur Syntax des match-Abschnitts

Beispiel: Überlappende Hop-Windows für kontinuierliche Korrelation

Im folgenden Beispiel wird eine Abfrage für den Zeitraum [1:00, 2:00] mit dem match-Abschnitt $user over 30m ausgeführt. Ein möglicher Satz von sich überschneidenden Hop-Fenstern, die das System generiert, ist [1:00, 1:30], [1:03, 1:33] und [1:06, 1:36].

Regel

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

Beispiel: Korrelation mehrerer Ereignisse mit einem Hop-Fenster

Im folgenden Beispiel werden Ereignisse erfasst, die im selben allgemeinen Zeitraum auftreten:

Regel

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
}

Suchen

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

Beispiel: Vergleich von Hop-Fenstern

Um einen Brute-Force-Angriff zu erkennen, werden alle USER_LOGIN-Fehler in einem 10m-Zeitfenster gruppiert. Anschließend wird geprüft, ob die Anzahl (#e) in diesem 10‑Minuten-Bucket Ihren Grenzwert überschreitet.

Regel

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
}

Suchen

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

Rollierende Fenster

Hinweis:Diese Funktion ist nicht für alle Kunden in allen Regionen verfügbar.

Bei einem rollierenden Fenster werden Daten in nicht überlappende, kontinuierliche Zeitintervalle fester Größe segmentiert. Der Zeitstempel jedes Ereignisses fällt in genau ein Fenster. Es gibt keine Überschneidungen zwischen rollierenden Fenstern. Dies steht im Gegensatz zu einem springenden Fenster oder einem gleitenden Fenster, die sich überlappende Zeitintervalle haben können.

Um ein rollierendes Fenster zu implementieren, verwenden Sie den Operator by im Abschnitt match. Bei rollierenden Fenstern wird die Zeit in fortlaufende, aufeinanderfolgende Blöcke unterteilt, z. B.:

  • by 1h: Erstellt Fenster für jede Stunde (z. B. [00:00:00-00:59:59], [01:00:00-01:59:59]).
  • by 10m: Erstellt Fenster für jedes 10‑Minuten-Intervall (z. B. [00:00:00-00:09:59], [00:10:00-00:19:59]).

Gängige Anwendungsfälle

Verwenden Sie gleitende Fenster, wenn Sie Folgendes benötigen:

  • Ereignisse in separaten, nicht überlappenden Zeitblöcken analysieren
  • Es wird nur eine Erkennung für eine bestimmte Einheit (definiert durch die Abgleichsvariablen) innerhalb jedes festen Zeitintervalls erstellt, unabhängig davon, wie oft das Ereignis auftritt.
  • Eindeutige Einheiten über feste Zeiträume hinweg zählen.

Deduplizierungsverhalten

Ein wichtiges Merkmal von gleitenden Fenstern ist, wie die Engine Erkennungen innerhalb jedes Fensters für dieselben Abgleichsvariablen verarbeitet:

  • Eine Erkennung pro Fenster:Für eine bestimmte Gruppe von Werten für die Abgleichsvariablen (z. B. ein bestimmter $userid) wird von der Engine höchstens eine Erkennung für ein einzelnes rollierendes Fenster generiert.
  • Das erste Eintreffen gewinnt:Die ersten erfassten Ereignisse, die die Regelbedingungen für diese Gruppe von Abgleichsvariablen innerhalb eines bestimmten Zeitraums erfüllen, lösen die Erkennung aus.
  • Deduplizierung:Für alle nachfolgenden Ereignisse, die innerhalb derselben Fensterinstanz den Kriterien entsprechen, werden keine zusätzlichen Erkennungen generiert.

Syntax

Die Syntax im Abschnitt match lautet: match: $variable by <duration>

  • $variable ist die Platzhaltervariable, die Sie abgleichen.
  • duration ist eine Zahl, auf die eine Zeiteinheit folgt: m (Minute), h (Stunde), d (Tag).
  • Geben Sie mindestens eine Minute und maximal 72 Stunden oder drei Tage an.

Beispiel: Gruppierung nach festen Intervallen

Die folgenden Regelgruppen gruppieren Logins nach $userid in nicht überlappenden 1-Stunden-Zeiträumen.

Regel

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
}

Suchen

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

Beispiel: Erkennungsverhalten (Nutzer = „Alex“)

  • Ereignis 1:Alex meldet sich um 00:30 Uhr an. Dies fällt in das Zeitfenster [00:00:00-00:59:59]. Die Engine generiert für Alex eine Erkennung für dieses Zeitfenster.
  • Ereignis 2:Ein anderer Nutzer, „Taylor“, meldet sich um 00:45 Uhr an. Das fällt auch unter [00:00:00-00:59:59], aber da sich die $userid unterscheidet, generiert die Engine eine separate Erkennung für Taylor.
  • Ereignis 3:Alex meldet sich um 00:40 Uhr noch einmal an. Das ist noch innerhalb des [00:00:00-00:59:59]-Zeitraums. Da bereits eine Erkennung für Alex vorhanden ist, wird dieses Ereignis dedupliziert. Es wird keine neue Erkennung generiert.
  • Ereignis 4:Alex meldet sich um 01:20 Uhr an. Das fällt in den nächsten Zeitraum, [01:00:00-01:59:59]. Die Engine generiert eine neue Erkennung für Alex.

Obwohl Ereignis 1 und Ereignis 4 für Alex weniger als eine Stunde auseinanderliegen, fallen sie in separate Erkennungen, da Ereignis 4 die Grenze des festen Zeitfensters überschreitet.

Tumbling-Fenster für die Abwesenheitserkennung konfigurieren

Führen Sie die folgenden Schritte aus, um eine Benachrichtigung bei einem Zählwert von null zu erhalten und Compilerfehler zu vermeiden:

  1. Erkennungsziel festlegen: Legen Sie fest, ob Sie nach hoher Häufigkeit oder nach Inaktivität suchen.
  2. Wählen Sie das Keyword window aus. Verwenden Sie over für die Häufigkeit und by für das Fehlen.
  3. Grenzen des Referenzzeitraums: Verwenden Sie die Keywords window_start und window_end, um auf bestimmte Grenzen des Zeitintervalls zu verweisen.

Kontext:Verwenden Sie outcome: $ext_window_end = window_end, um die genaue Endzeit eines verpassten Herzschlags in die Metadaten der Benachrichtigung aufzunehmen.

Beispiel: Fehlenden Herzschlag mit Metadaten erkennen

Mit gleitenden Fenstern können Sie eine Warnung bei einer Anzahl von null ausgeben lassen. So vermeiden Sie Compilerfehler, wenn Sie nach fehlender Aktivität suchen.

Regel

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

Suchen

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

Gleitende Fenster

Ein gleitendes Fenster ist an einem bestimmten Pivot-Ereignis verankert und wird entweder vorwärts (after) oder rückwärts (before) betrachtet.

Gängige Anwendungsfälle

Gleitende Fenster verwenden, wenn die Reihenfolge von Ereignissen wichtig ist:

  • Strikte Sequenzierung:Erkennen einer Angriffskette (z. B. tritt e1 bis zu zwei Minuten nach e2 auf).
  • Relativer Zeitpunkt:Suchen Sie nach einem Ereignis, das innerhalb eines bestimmten Offsets eines Triggers auftritt, z. B. ein Network Connection innerhalb von 30 Sekunden nach einem Process Start.
  • Erkennung von Abwesenheit:Ermitteln, wann ein erforderliches „Cleanup“- oder „Heartbeat“-Ereignis nach einem Start-Ereignis nicht eintritt.

Syntax

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

Komponente Beschreibung Beispiel
Gruppierungsschlüssel Häufig verwendete Felder zum Verknüpfen von Ereignissen. $host, $user
Dauer Der zeitliche Versatz vom Pivot-Ereignis. 5m, 1h, 30s
Richtung Gibt an, ob sich das Fenster nach vorn oder nach hinten erstreckt. after, before
Neuausrichtung Die Ereignisvariable, die das Fenster verankert. $proc, $alert

Hier sind einige Beispiele für gültige gleitende Fenster:

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

Anforderungen und Einschränkungen

  • Leistung: Sliding-Windows erfordern mehr Rechenleistung als Hop-Windows. Verwenden Sie sie nur, wenn die Reihenfolge der Ereignisse unbedingt erforderlich ist, z. B. wenn ein Ereignis innerhalb von fünf Minuten nach einem anderen Ereignis eintreten muss.
  • Abfragen mit einem einzelnen Ereignis: Verwenden Sie keine gleitenden Fenster für die Logik mit einem einzelnen Ereignis. Verwenden Sie stattdessen mehrere Ereignisvariablen im Abschnitt condition.

Beispiel: Zukunftsgerichtete Korrelation (after)

Regel

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
}

Suchen

after wird für die Suche nicht unterstützt.

Dashboard

after wird für Dashboards nicht unterstützt.

Beispiel: Rückblickende Korrelation (before)

Mit einem "before"-Gleitfenster können Sie die Aktivitäten untersuchen, die zu einer bestimmten Benachrichtigung geführt haben. Dies wird häufig bei der Ursachenanalyse verwendet, um zu ermitteln, was unmittelbar vor einer kritischen Erkennung passiert ist.

Regel

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
}

Suchen

before wird für die Suche nicht unterstützt.

Dashboard

before wird für Dashboards nicht unterstützt.

Fehlerbehebung

In diesem Abschnitt erfahren Sie mehr über Latenz, Grenzwerte und Korrekturen für häufige Probleme mit Zeitfenstern in YARA-L.

Latenz und Limits

  • Regeln, die rollierende Fenster (by) verwenden, werden nur am Ende des festen Zeitblocks ausgelöst. Eine Regel mit match: $user by 24h wird beispielsweise erst ausgewertet, wenn das 24-Stunden-Zeitfenster vollständig abgelaufen ist.

  • Benachrichtigungslatenz:Regeln, die by (Tumbling) verwenden, werden erst ausgelöst, nachdem der feste Zeitblock abgelaufen ist. Eine by 24h-Regel löst keine Benachrichtigung während des Fensters aus.

  • Abweichung bei der Benutzeroberfläche:In Search und Dashboards bezieht sich das window_start-Keyword direkt auf das Feld TIME_BUCKET. Wenn Sie nach window_start filtern oder gruppieren, wird in der Benutzeroberfläche TIME_BUCKET als Spaltenüberschrift angezeigt. Das ist eine bekannte Einschränkung der Benutzeroberfläche. Ihre Logik bleibt gültig.

Fehlerbehebung

Fehlercode Beschreibung Korrigieren
Variable Not Bounded (Variable nicht begrenzt) Die Regel verwendet over (gleitendes Fenster) mit einer $count = 0-Bedingung. Ändern Sie das Windowing-Keyword in by (rollierendes Fenster). Für gleitende Fenster ist ein Ereignis erforderlich, um das Fenster zu verankern, für rollierende Fenster nicht.
UI Header Mismatch Der Nutzer sieht in der Benutzeroberfläche TIME_BUCKET anstelle von window_start. Keine Fehlerbehebung erforderlich. Die Filter- und Sortierlogik funktioniert weiterhin korrekt mit den Keywords.
Unbekannte ID: window_start Das Keyword wird verwendet, aber in match ist kein Zeitraum definiert. Fügen Sie Ihrem match-Abschnitt eine Windowing-Anweisung hinzu, z. B. $hostname by 1h.
Ungültige Verwendung von window_start in Ereignissen Das Keyword wird im Abschnitt events referenziert. Verschieben Sie die Logik in den Abschnitt condition oder outcome. Fenstergrenzen werden erst nach dem Gruppieren von Ereignissen in der Abgleichsphase berechnet.

Nächste Schritte

Benötigen Sie weitere Hilfe? Antworten von Community-Mitgliedern und Google SecOps-Experten erhalten