Syntax des Abschnitts zum Abgleich

Unterstützt in:

Google SecOps SIEM

In YARA-L 2.0 bietet der Abschnitt match den Mechanismus für die Korrelation mehrerer Ereignisse. Sie definiert die Logik für die Gruppierung von Ereignissen in einem einzelnen Fund, indem gemeinsame Attribute wie Nutzer, IP-Adressen oder Dateihashes innerhalb einer bestimmten zeitlichen Begrenzung verknüpft werden.

Sie verwenden den Abschnitt match für die folgenden Anwendungsfälle:

Verknüpfen Sie zwei oder mehr unterschiedliche Ereignisse in einer Regel.
Aggregieren von Daten in der Suche und in Dashboards, z. B. Zählen fehlgeschlagener Anmeldeversuche über einen bestimmten Zeitraum hinweg.

Korrelationskriterien definieren

Damit können Sie die Kriterien für diese Korrelation festlegen, indem Sie Folgendes angeben:

Gruppierungsfelder (Schlüssel): Variablen (z. B. $user oder $ip), die für alle Ereignisse (definiert im Abschnitt events) identische Werte haben müssen, damit eine Übereinstimmung ausgelöst wird.
Zeitbeschränkung: Der Zeitraum, in dem gruppierte Ereignisse auftreten müssen, damit die Regel oder Aggregation erfüllt wird. In Regeln wird damit das Erkennungsfenster definiert, in Suche und Dashboards das Aggregations- oder Korrelationsfenster.

Funktionsanforderungen vergleichen

In der folgenden Tabelle finden Sie einen detaillierten Vergleich von Regeln für die Suche und Dashboards.

Funktion	Regelanforderung	Unterstützung für Suche und Dashboards
Variablentypen	Es müssen Platzhalter verwendet werden, die im Abschnitt `events` definiert sind.	Unterstützt sowohl Platzhalter als auch direkte UDM-Felder.
Zeitfenster	Definiert die Erkennungsgrenze.	Definiert den Bucket für die Aggregation oder Korrelation.
Syntax	`over <number><m/h/d>` (z. B. `10m`, `2h`, `1d`)	`over <number><m/h/d>`
Limits	Min.: `1m` / Max.: `48h`	Min.: `1m` / Max.: `48h`

Unterstützte Fenstertypen

In YARA-L 2.0 werden verschiedene Windowing-Verhaltensweisen verwendet, um zu bestimmen, wie die Zeit unterteilt und wie Ereignisse gruppiert werden. Sie können Ereignisfelder und Platzhalter im Abschnitt match nach einer angegebenen Zeitgranularität gruppieren. Dazu verwenden Sie eines der folgenden unterstützten Zeitfenster.

Unterstützter Fenstertyp	Syntax	Beschreibung	Gängige Anwendungsfälle
Hop	`$key over <duration>`	Sich überschneidende Zeiträume (Standardverhalten).	Allgemeine Korrelation mehrerer Ereignisse.
Tumbling	`$key by <duration> tumbling`	Nicht überlappende, kontinuierliche Zeitintervalle mit fester Größe.	Aktivitäten in Blöcken von bis zu einer Stunde quantifizieren (z. B. `$user by 30m`).
Gleiten	`$key over <duration> [before\|after] $pivot`	Zeitintervalle, die an einem bestimmten „Pivot“-Ereignis verankert sind.	Strikte Sequenzierung (z. B. `File Download after Login`).

Beispielsyntax:

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

Hop-Fenster

Ein Hop-Fenster ist das Standardverhalten für Regeln mit mehreren Ereignissen. Es werden sich überschneidende Zeitintervalle erstellt, damit Ereignisse, die in der Nähe der Grenzen eines Zeitraums stattfinden, nicht übersehen werden.

Syntax: $key over <duration> (z. B. $user over 30m)
Anwendungsfall: Am besten geeignet für die Erkennung, bei der ein bestimmtes Szenario unabhängig davon erfasst werden muss, wann genau das Zeitfenster beginnt oder endet.
Unterstützung: Wird für die Aggregation in der Suche und in Dashboards unterstützt (z. B. count).

Standardmäßig werden in YARA-L-Abfragen mit einem match-Abschnitt Hop-Fenster verwendet, um mehrere Ereignisse im Zeitverlauf zu korrelieren. Der Zeitraum der Abfrageausführung wird in eine Reihe fester, sich überschneidender Hop-Fenster unterteilt. Die Dauer dieser Zeiträume wird im Abschnitt match angegeben. Das Überschneidungsintervall und die Ausrichtung der Zeiträume werden jedoch vom System definiert und können nicht vom Nutzer konfiguriert werden. Ereignisse werden dann innerhalb der einzelnen vordefinierten Zeiträume in Beziehung gesetzt.

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. Eine mögliche Gruppe von sich überschneidenden Hop-Fenstern, die generiert werden könnten, ist [1:00, 1:30], [1:03, 1:33] und [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
}

Beispiel: Korrelation mehrerer Ereignisse mit einem Hop-Fenster

Das folgende Beispiel stellt die Standardeinstellung für die meisten Regeln mit mehreren Ereignissen dar. Damit werden Ereignisse erfasst, die im selben allgemeinen Zeitraum auftreten.

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
}

Beispiel: Vergleich von Hop-Windows

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

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
}

Im Abschnitt match werden Nutzer mit einem fehlgeschlagenen Log-in an einem neuen Standort innerhalb eines 10‑Minuten-Intervalls (10m) ermittelt:

match:
  $user over 10m

Rollierendes Fenster

Bei einem rollierenden Fenster wird ein Datenstrom in nicht überlappende, kontinuierliche Zeitintervalle fester Größe segmentiert. Jedes Datenereignis wird nur einem Fenster zugewiesen. Im Gegensatz dazu können sich Zeitintervalle bei einem gleitenden oder springenden Fenster überlappen.

Syntax: Verwenden Sie den Operator by ($key by <duration>), z. B. $user by 30m.
Anwendungsfall: Am besten geeignet für Berichte und Dashboards, in denen Sie Ereignisse in separaten Blöcken zählen möchten (z. B. "How many alerts per hour?").
Suche und Dashboards: Werden häufig verwendet, um übersichtliche Balkendiagramme zu erstellen, ohne Ereignisse zu deduplizieren.

Beispiel: Zählen mit festen Intervallen und gleitenden Fenstern

Das folgende Beispiel zeigt ein 30‑minütiges gleitendes Fenster, in dem Ereignisse, die zwischen 1:00:00 und 1:29:59 Uhr auftreten, gemeinsam verarbeitet werden. Anschließend wird die nächste Gruppe von Ereignissen (von 1:30:00 bis 1:59:59) separat verarbeitet.

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
}

Schiebefenster

Verwenden Sie ein gleitendes Fenster, wenn Sie nach Ereignissen suchen müssen, die in einer strengen, relativen Reihenfolge auftreten (z. B. e1 tritt bis zu zwei Minuten nach e2 auf). Im Gegensatz zu festen Fenstern wird ein gleitendes Fenster durch jedes Vorkommen des angegebenen $pivot_event ausgelöst. Verwenden Sie dazu die folgende Syntax:

after: Das Fenster beginnt mit dem Zeitstempel des Pivot-Ereignisses und wird nach vorn erweitert.
before: Das Fenster endet am Zeitstempel des Pivot-Ereignisses und wird rückwärts erweitert.

Geben Sie gleitende Fenster im match-Abschnitt einer Abfrage so an:

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

Syntax: $key over <duration> before|after $<pivot_event>
Gruppierungsschlüssel: Gemeinsame Felder (z. B. $user, $ip), die zum Verknüpfen von Ereignissen verwendet werden.
Zeitraum: Zeitlicher Versatz vom Pivot-Ereignis (z. B. 5m, 1h).
Anwendungsfälle:
- Strikte Sequenzierung: Erkennen einer Angriffskette, bei der eine bestimmte Reihenfolge erforderlich ist (z. B. Erstellung eines Nutzers gefolgt von einer Rechteausweitung).
- Relativer Zeitpunkt: Suchen Sie nach einem Ereignis, das innerhalb eines bestimmten Offsets eines „Triggers“ auftritt, z. B. ein Process Start-Ereignis, gefolgt von einem Network Connection-Ereignis innerhalb von 30 Sekunden.
- Erkennung von Abwesenheit: Ermitteln, wann ein erforderliches „Cleanup“- oder „Heartbeat“-Ereignis nach einem Start-Ereignis nicht eintritt, z. B. ein Database Backup Start ohne entsprechendes End-Ereignis.

Gültige Beispiele für gleitende Fenster

Die folgenden Beispiele zeigen gültige gleitende Fenster:

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

Beispiel: Zukunftsgerichtete Korrelation mit gleitenden Fenstern (`after`)

Im folgenden Beispiel wird gezeigt, wie Sie eine Ereignissequenz erkennen, bei der das zweite Ereignis innerhalb eines bestimmten Zeitraums nach einem primären „Trigger“- oder Pivot-Ereignis eintreten muss. Dies ist nützlich, um schnelle laterale Bewegungen oder automatisierte Folgeaktionen zu erkennen.

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
}

Beispiel: Rückblickende Korrelation mit gleitenden Fenstern (`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.

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
}

Leistung und Best Practices

Für gleitende Fenster ist mehr Rechenleistung erforderlich als für Standardfenster (mit Sprung), da sie für jedes Auftreten des Pivot-Ereignisses berechnet werden. Dies kann zu einer langsameren Leistung führen.

Beachten Sie die folgenden Richtlinien, um eine optimale Leistung bei Regeln, Suchvorgängen und Dashboards zu erzielen:

Hop-Windows priorisieren: Verwenden Sie das Standard-Hop-Window, es sei denn, die spezifische Reihenfolge von Ereignissen (Bestellung A, dann Bestellung B) ist für die Erkennungslogik erforderlich. Verwenden Sie gleitende Fenster nur, wenn die Reihenfolge der Ereignisse wichtig ist oder wenn Sie nach fehlenden Ereignissen suchen.
Zeitstempelfilter für die Leistung verwenden: Wenn Sie nur prüfen müssen, ob ein Ereignis nach einem anderen stattgefunden hat, ist ein Zeitstempelvergleich im events- oder condition-Abschnitt oft effizienter als ein gleitendes Fenster, z. B.:

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

Design mit mehreren Ereignissen: Vermeiden Sie die Verwendung von gleitenden Fenstern für Abfragen mit einem einzelnen Ereignis. Gleitende Fenster sind für die Korrelation mehrerer Ereignisse konzipiert. Für die Logik für einzelne Ereignisse gelten die folgenden Richtlinien:
- Verwenden Sie mehrere Ereignisvariablen und aktualisieren Sie den Bereich condition.
- Entfernen Sie den Abschnitt match vollständig, wenn keine Korrelation erforderlich ist.
- Optional können Sie Zeitstempelfilter anstelle eines gleitenden Fensters verwenden, z. B.
  $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds.

Zeitliche Grenze

Im Bereich match werden Ereignisse anhand Ihrer Gruppierungsschlüssel in Gruppen unterteilt. Die angegebene Dauer definiert die zeitliche Grenze für jede Gruppe:

Einbeziehung: Nur Ereignisse innerhalb des Zeitfensters werden für die entsprechende Übereinstimmung an die condition-Auswertung übergeben.
Ausschluss: Ereignisse außerhalb des Zeitraums werden für diese bestimmte Abgleichsgruppe ignoriert. So wird verhindert, dass nicht zusammenhängende Ereignisse ein fälschlicherweise positives Ergebnis auslösen.

Nullwerte im Abschnitt `match`

Google SecOps filtert implizit Nullwerte für alle Platzhalter heraus, die im Abschnitt match verwendet werden ("" für String, 0 für Zahlen, false für boolesche Werte, der Wert an Position 0 für aufgezählte Typen).

Beispiel: Nullwerte herausfiltern

Im folgenden Beispiel werden Abfragen veranschaulicht, mit denen die Nullwerte herausgefiltert werden.

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
}

Wenn einem Platzhalter jedoch eine Funktion zugewiesen ist, werden die Nullwerte von Platzhaltern, die im Abschnitt match verwendet werden, nicht implizit aus den Abfragen herausgefiltert.

Wenn Sie das implizite Filtern von Nullwerten deaktivieren möchten, können Sie die Option allow_zero_values im Abschnitt „Optionen“ verwenden. Die Option allow_zero_values ist nur in Regeln verfügbar.

Beispiel: Nullwerte zulassen

Im folgenden Beispiel werden Abfragen veranschaulicht, bei denen die Nullwerte von Platzhaltern, die im Abschnitt match verwendet werden, nicht implizit herausgefiltert werden:

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
}

Nächste Schritte

In den folgenden Ressourcen finden Sie weitere Informationen zur YARA-L-Logik oder zu erweiterten Abfragefunktionen:

Syntax und Logik

Referenzen und Beispiele

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