YARA-L 2.0-Sprachsyntax

In diesem Abschnitt werden die wichtigsten Elemente der YARA-L-Syntax beschrieben. Siehe auch Überblick über die Sprache YARA-L 2.0.

Regelstruktur

Für YARA-L 2.0 müssen Sie Variablendeklarationen, Definitionen und Verwendungen in der folgenden Reihenfolge angeben:

1. Meta
2. Ereignisse
3. Übereinstimmung (optional)
4. Ergebnis (optional)
5. Bedingung
6. Optionen (optional)

Hinweis :Wenn Sie den optionalen Abschnitt match weglassen, kann die Regel mit einem einzelnen Ereignis abgeglichen werden.

Im Folgenden wird die allgemeine Struktur einer Regel veranschaulicht:

rule <rule Name>
{
    meta:
    // Stores arbitrary key-value pairs of rule details, such as who wrote
    // it, what it detects on, version control, etc.

  events:
    // Conditions to filter events and the relationship between events.

  match:
    // Values to return when matches are found.

  outcome:
    // Additional information extracted from each detection.

  condition:
    // Condition to check events and the variables used to find matches.

  options:
    // Options to turn on or off while executing this rule.
}

Syntax des Meta-Abschnitts

Metaabschnitt besteht aus mehreren Zeilen, wobei jede Zeile ein Schlüsselwertpaar definiert. Ein Schlüsselteil muss ein String ohne Anführungszeichen und ein Wertteil ein String in Anführungszeichen sein:

<key> = "<value>"

Das folgende Beispiel zeigt eine gültige meta-Abschnittszeile:

meta:
    author = "Google"
    severity = "HIGH"

Syntax des Abschnitts „Ereignisse“

Listen Sie im Abschnitt events die Prädikate auf, um Folgendes anzugeben:

• Variablendeklarationen
• Filter für Ereignisvariablen
• Zusammenführungen von Ereignisvariablen

Variablendeklarationen

Verwenden Sie für Variablendeklarationen die folgende Syntax:

• <EVENT_FIELD> = <VAR>
• <VAR> = <EVENT_FIELD>

Beide sind gleichwertig, wie in den folgenden Beispielen gezeigt:

• $e.source.hostname = $hostname
• $userid = $e.principal.user.userid

Diese Deklaration gibt an, dass diese Variable das angegebene Feld für die Ereignisvariable darstellt. Wenn das Ereignisfeld ein wiederkehrendes Feld ist, kann die Abgleichvariable einen beliebigen Wert im Array darstellen. Einer Übereinstimmungs- oder Platzhaltervariablen können auch mehrere Ereignisfelder zugewiesen werden. Dies ist eine transitive Join-Bedingung.

Beispiel:

• $e1.source.ip = $ip
• $e2.target.ip = $ip

Entspricht:

• $e1.source.ip = $ip
• $e1.source.ip = $e2.target.ip

Wenn eine Variable verwendet wird, muss sie durch eine Variablendeklaration deklariert werden. Wird eine Variable ohne Deklaration verwendet, wird sie als Kompilierungsfehler betrachtet.

Filter für Ereignisvariablen

Ein boolescher Ausdruck, der auf eine einzelne Ereignisvariable wirkt, wird als Filter betrachtet.

Zusammenführungen von Ereignisvariablen

Alle in der Regel verwendeten Ereignisvariablen müssen mit jeder anderen Ereignisvariablen auf eine der folgenden Arten verknüpft werden:

• Direkt durch einen Gleichheitsvergleich zwischen den Ereignisfeldern der beiden verknüpften Ereignisvariablen, z. B. $e1.field = $e2.field. Der Ausdruck darf keine Arithmetik enthalten.

• Indirekt über einen transitiven Join, der nur ein Ereignisfeld umfasst. Eine Definition von „transitive Join“ finden Sie in der Deklaration von Variablen. Der Ausdruck darf keine Arithmetik enthalten.

Wenn zum Beispiel $e1, $e2 und $e3 in der Regel verwendet werden, sind die folgenden events-Abschnitte gültig.

events:
  $e1.principal.hostname = $e2.src.hostname // $e1 joins with $e2
  $e2.principal.ip = $e3.src.ip // $e2 joins with $e3

events:
  // $e1 joins with $e2 via function to event comparison
  re.capture($e1.src.hostname, ".*") = $e2.target.hostname

events:
  // $e1 joins with $e2 via an `or` expression
  $e1.principal.hostname = $e2.src.hostname
  or $e1.principal.hostname = $e2.target.hostname
  or $e1.principal.hostname = $e2.principal.hostname

events:
  // all of $e1, $e2 and $e3 are transitively joined via the placeholder variable $ip
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = $ip

events:
  // $e1 and $e2 are transitively joined via function to event comparison
  re.capture($e2.principal.application, ".*") = $app
  $e1.principal.hostname = $app

Hinweis: Wenn Ihre einzige Join-Bedingung eine or-Kette, eine Funktion zum Ereignisvergleich oder eine Kombination aus beidem ist, funktioniert die Regel möglicherweise schlecht.

Hier einige Beispiele für ungültige events-Bereiche.

events:
  // Event to arithmetic comparison is an invalid join condition for $e1 and $e2.
  $e1.principal.port = $e2.src.port + 1

events:
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = "192.1.2.0" //$e3 is not joined with $e1 or $e2.

events:
  $e1.src.port = $port

  // Arithmetic to placeholder comparison is an invalid transitive join condition.
  $e2.principal.port + 800 = $port

Syntax des Übereinstimmungsabschnitts

Listen Sie im Abschnitt match die Abgleichsvariablen für Gruppenereignisse auf, bevor Sie nach Übereinstimmungsbedingungen suchen. Diese Felder werden bei jeder Übereinstimmung zurückgegeben.

• Geben Sie im Abschnitt events an, wofür die einzelnen Übereinstimmungsvariablen stehen.
• Geben Sie die Zeitdauer an, die zum Korrelieren von Ereignissen nach dem Keyword over verwendet werden soll. Ereignisse außerhalb der Dauer werden ignoriert.

• Verwenden Sie die folgende Syntax, um die Dauer anzugeben: <number><m/h/d>

  Dabei steht m/h/d für Minuten, Stunden bzw. Tage.

• Sie können mindestens 1 Minute angeben.

• Sie können maximal 48 Stunden angeben.

Hier ein Beispiel für einen gültigen match:

$var1, $var2 over 5m

Diese Anweisung gibt $var1 und $var2 zurück (definiert im Abschnitt events), wenn die Regel eine Übereinstimmung findet. Die angegebene Zeit beträgt 5 Minuten. Ereignisse, die mehr als 5 Minuten auseinanderliegen, sind nicht korreliert und werden daher von der Regel ignoriert.

Hier ist ein weiteres Beispiel für einen gültigen match-Abschnitt:

$user over 1h

Diese Anweisung gibt $user zurück, wenn die Regel eine Übereinstimmung findet. Das angegebene Zeitfenster beträgt 1 Stunde. Zwischen Ereignissen, die mehr als eine Stunde auseinanderliegen, besteht keine Korrelation. Sie werden von der Regel nicht als Erkennung betrachtet.

Hier ist ein weiteres Beispiel für einen gültigen match-Abschnitt:

$source_ip, $target_ip, $hostname over 2m

Diese Anweisung gibt $source_ip, $target_ip und $hostname zurück, wenn die Regel eine Übereinstimmung findet. Das angegebene Zeitfenster beträgt 2 Minuten. Bei Ereignissen, die mehr als 2 Minuten auseinanderliegen, besteht keine Korrelation. Sie werden von der Regel nicht als Erkennung betrachtet.

In den folgenden Beispielen werden ungültige match-Abschnitte veranschaulicht:

• var1, var2 over 5m // invalid variable name
• $user 1h // missing keyword

Umgang mit Nullwerten im Übereinstimmungsbereich

Das Rules Engine filtert implizit die Nullwerte für alle Platzhalter aus, die im Übereinstimmungsabschnitt verwendet werden ("" für String, 0 für Zahlen, false für boolesche Werte, der Wert an Position 0 für Aufzählungstypen). Das folgende Beispiel veranschaulicht Regeln, die Nullwerte herausfiltern.

rule ZeroValuePlaceholderExample {
  meta:
  events:
    // Because $host is used in the match section, the rule 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 section,
    // there is no implicit filtering of zero values for $otherPlaceholder.
    $otherPlaceholder = $e.principal.ip

  match:
    $host over 5m

  condition:
    $e
}

Wenn jedoch einer Funktion ein Platzhalter zugewiesen ist, werden die Nullwerte von Platzhaltern, die im Übereinstimmungsabschnitt verwendet werden, nicht implizit herausgefiltert. Das folgende Beispiel veranschaulicht Regeln, die Nullwerte herausfiltern:

rule ZeroValueFunctionPlaceholder {
  meta:
  events:
    // Even though $ph is used in the match section, there is no
    // implicit filtering of zero values for $ph, because $ph is assigned to a function.
    $ph = re.capture($e.principal.hostname, "some-regex")

  match:
    $ph over 5m

  condition:
    $e
}

Um das implizite Filtern von Nullwerten zu deaktivieren, können Sie die Option allow_zero_values im Abschnitt „Optionen“ verwenden.

Hop-Fenster

Standardmäßig werden YARA-L 2.0-Regeln mit einem Übereinstimmungsbereich mithilfe von Hop-Fenstern ausgewertet. Der Zeitraum für die Ausführung der Regel wird in mehrere sich überschneidende Hop-Fenster unterteilt, von denen jedes die im Abschnitt match angegebene Dauer hat. Die Ereignisse werden dann in jedem Hop-Fenster korreliert.

Für eine Regel, die für den Zeitraum [1:00, 2:00] ausgeführt wird und einen match-Abschnitt über 30m hat, könnten folgende sich überschneidende Hop-Fenster generiert werden: [1:00, 1:30], [1:03, 1:33] und [1:06, 1:36]. Diese Fenster werden verwendet, um mehrere Ereignisse zu korrelieren.

Schiebefenster

Die Verwendung von Hop-Fenstern ist keine effektive Möglichkeit, um nach Ereignissen zu suchen, die in einer bestimmten Reihenfolge stattfinden (z. B. e1 tritt bis zu 2 Minuten nach e2 auf). Ein Auftreten des Ereignisses e1 und das Auftreten des Ereignisses e2 werden nur dann korreliert, wenn sie in dasselbe generierte Hop-Fenster fallen.

Eine effektivere Möglichkeit, nach solchen Ereignissequenzen zu suchen, sind gleitende Fenster. Gleitende Fenster mit der im Abschnitt match angegebenen Dauer werden generiert, wenn sie mit einer angegebenen Pivot-Ereignisvariablen beginnen oder enden. Die Ereignisse werden dann innerhalb der einzelnen gleitenden Fenster in Beziehung gesetzt. So kann nach Ereignissen gesucht werden, die in einer bestimmten Reihenfolge auftreten (z. B. e1 innerhalb von 2 Minuten nach e2). Das Eintreten des Ereignisses e1 und das Ereignis e2 werden korreliert, wenn das Ereignis e1 innerhalb der gleitenden Fensterdauer nach dem Ereignis e2 eintritt.

So legen Sie gleitende Fenster im Abschnitt match einer Regel fest:

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

Die Pivot-Ereignisvariable ist die Ereignisvariable, auf der gleitende Fenster basieren. Wenn Sie das Schlüsselwort before verwenden, werden gleitende Fenster generiert, die mit jedem Auftreten des Pivot-Ereignisses enden. Wenn das Schlüsselwort after verwendet wird, werden gleitende Fenster ab jedem Auftreten des Pivot-Ereignisses generiert.

Im Folgenden finden Sie Beispiele für gültige Verwendungen eines gleitenden Fensters:

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

Beispiel für eine gleitende Fensterregel

Hinweis: Die Verwendung von gleitenden Fenstern anstelle von Hop-Fenstern führt bekanntermaßen zu einer langsameren Leistung. Google empfiehlt, gleitende Fenster nur in bestimmten Fällen zu verwenden, z. B. wenn die Reihenfolge von Ereignissen unbedingt erforderlich ist oder wenn nach dem Nicht-Vorhandensein von Ereignissen gesucht wird.

Google empfiehlt, bei Einzelereignisregeln keine gleitenden Fenster zu verwenden, da mit gleitenden Fenstern mehrere Ereignisse erkannt werden sollen. Wenn eine Ihrer Regeln in diese Kategorie fällt, empfiehlt Google eine der folgenden Behelfslösungen:

• Konvertieren Sie die Regel so, dass mehrere Ereignisvariablen verwendet werden, und aktualisieren Sie den Bedingungsabschnitt, wenn das Ereignis gemäß der Regel mehr als ein Auftreten erfordert.
  • Optional können Sie Zeitstempelfilter hinzufügen, statt ein gleitendes Fenster zu verwenden. Beispiel: $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
• Entfernen Sie das gleitende Fenster.

Syntax des Abschnitts „Ergebnis“

Im Abschnitt outcome können Sie bis zu 20 Ergebnisvariablen mit beliebigen Namen definieren. Diese Ergebnisse werden in den von der Regel generierten Erkennungen gespeichert. Jede Erkennung kann unterschiedliche Werte für die Ergebnisse haben.

Der Ergebnisname $risk_score ist speziell. Optional können Sie ein Ergebnis mit diesem Namen definieren. In diesem Fall muss es sich um eine Ganzzahl oder eine Gleitkommazahl handeln. Wenn das Feld ausgefüllt ist, wird risk_score in der Ansicht „Enterprise Insights“ für Benachrichtigungen angezeigt, die durch Regelerkennungen ausgelöst werden.

Wenn Sie keine $risk_score-Variable in den Ergebnisabschnitt einer Regel einfügen, wird einer der folgenden Standardwerte festgelegt:

• Ist die Regel so konfiguriert, dass eine Benachrichtigung generiert wird, ist $risk_score auf 40 gesetzt.
• Wenn die Regel nicht zum Generieren einer Benachrichtigung konfiguriert ist, wird $risk_score auf „15“ gesetzt.

Der Wert von $risk_score wird im UDM-Feld security_result.risk_score gespeichert.

Datentypen der Ergebnisvariablen

Jede Ergebnisvariable kann einen anderen Datentyp haben, der durch den Ausdruck bestimmt wird, mit dem sie berechnet wird. Die folgenden Ergebnisdatentypen werden unterstützt:

• integer
• Gleitkommazahlen
• String
• Listen mit Ganzzahlen
• Listen von Gleitkommazahlen
• Listen mit Strings

Bedingte Logik

Sie können bedingte Logik verwenden, um den Wert eines Ergebnisses zu berechnen. Bedingungen werden nach dem folgenden Syntaxmuster angegeben:

if(BOOL_CLAUSE, THEN_CLAUSE)
if(BOOL_CLAUSE, THEN_CLAUSE, ELSE_CLAUSE)

Sie können einen bedingten Ausdruck so lesen: „wenn BOOL_CLAUSE wahr ist, dann THEN_CLAUSE zurückgibt, sonst ELSE_CLAUSE zurückgeben“.

BOOL_CLAUSE muss einen booleschen Wert ergeben. Ein BOOL_CLAUSE-Ausdruck nimmt eine ähnliche Form an wie Ausdrücke im events-Abschnitt. Er kann beispielsweise Folgendes enthalten:

• UDM-Feldnamen mit Vergleichsoperator, z. B.:

  if($context.graph.entity.user.title = "Vendor", 100, 0)

• Platzhaltervariable, die im Abschnitt events definiert wurde. Beispiel:

  if($severity = "HIGH", 100, 0)

• Eine weitere Ergebnisvariable, die im Abschnitt outcome definiert ist, z. B.:

  if($risk_score > 20, "HIGH", "LOW")

• Funktionen, die einen booleschen Wert zurückgeben, zum Beispiel:

  if(re.regex($e.network.email.from, `.*altostrat.com`), 100, 0)

• Referenzliste nachschlagen, zum Beispiel:

  if($u.principal.hostname in %my_reference_list_name, 100, 0)

• Aggregationsvergleich, zum Beispiel:

  if(count($login.metadata.event_timestamp.seconds) > 5, 100, 0)

THEN_CLAUSE und ELSE_CLAUSE müssen denselben Datentyp haben. Wir unterstützen Ganzzahlen, Gleitkommazahlen und Strings.

Sie können ELSE_CLAUSE auslassen, wenn der Datentyp eine Ganzzahl oder eine Gleitkommazahl ist. Wenn keine Angabe gemacht wird, wird ELSE_CLAUSE mit 0 ausgewertet. Beispiel:

`if($e.field = "a", 5)` is equivalent to `if($e.field = "a", 5, 0)`

Sie müssen die ELSE_CLAUSE angeben, wenn der Datentyp ein String ist oder wenn THEN_CLAUSE eine Platzhalter- oder Ergebnisvariable ist.

Mathematische Operationen

Sie können mathematische Operationen verwenden, um Ganzzahl- oder Float-Datentypen in den Abschnitten outcome und events einer Regel zu berechnen. Google Security Operations unterstützt Addition, Subtraktion, Multiplikation, Division und Modulus als Operatoren der obersten Ebene in einer Berechnung.

Das folgende Snippet ist eine Beispielberechnung im Abschnitt outcome:

outcome:
  $risk_score = max(100 + if($severity = "HIGH", 10, 5) - if($severity = "LOW", 20, 0))

Mathematische Operationen sind für die folgenden Operandentypen zulässig, sofern jeder Operand und der gesamte arithmetische Ausdruck korrekt aggregiert ist (siehe Aggregationen):

• Numerische Ereignisfelder
• Im Abschnitt events definierte numerische Platzhaltervariablen
• Im Abschnitt outcome definierte numerische Ergebnisvariablen
• Funktionen, die Ganzzahlen oder Gleitkommazahlen zurückgeben
• Aggregationen, die Ganzzahlen oder Gleitkommazahlen zurückgeben

Modulo ist für Gleitkommazahlen nicht zulässig.

Platzhaltervariablen in Ergebnissen

Bei der Berechnung von Ergebnisvariablen können Sie Platzhaltervariablen verwenden, die im Abschnitt „Ereignisse“ der Regel definiert wurden. Nehmen wir in diesem Beispiel an, dass im Abschnitt „Ereignisse“ der Regel $email_sent_bytes definiert wurde:

Beispiel für ein Einzelereignis:

// No match section, so this is a single-event rule.

outcome:
  // Use placeholder directly as an outcome value.
  $my_outcome = $email_sent_bytes

  // Use placeholder in a conditional.
  $other_outcome = if($file_size > 1024, "SEVERE", "MODERATE")

condition:
  $e

Beispiel für Mehrfachereignisse:

match:
  // This is a multi event rule with a match section.
  $hostname over 5m

outcome:
  // Use placeholder directly in an aggregation function.
  $max_email_size = max($email_sent_bytes)

  // Use placeholder in a mathematical computation.
  $total_bytes_exfiltrated = sum(
    1024
    + $email_sent_bytes
    + $file_event.principal.file.size
  )

condition:
  $email_event and $file_event

Ergebnisvariablen in Ergebniszuweisungsausdrücken

Ergebnisvariablen können zum Ableiten anderer Ergebnisvariablen verwendet werden, ähnlich wie mit den im Abschnitt events definierten Platzhaltervariablen. Sie können in der Zuweisung einer anderen Ergebnisvariablen auf eine Ergebnisvariable verweisen. Verwenden Sie dazu ein $-Token, gefolgt vom Variablennamen. Ergebnisvariablen müssen definiert werden, bevor im Regeltext darauf verwiesen werden kann. Bei Verwendung in einem Zuweisungsausdruck dürfen Ergebnisvariablen nicht aggregiert werden (siehe Zusammenfassungen).

Im folgenden Beispiel leitet die Ergebnisvariable $risk_score ihren Wert von der Ergebnisvariablen $event_count ab:

Beispiel für Mehrfachereignisse:

match:
  // This is a multi event rule with a match section.
  $hostname over 5m

outcome:
  // Aggregates all timestamp on login events in the 5 minute match window.
  $event_count = count($login.metadata.event_timestamp.seconds)
  
  // $event_count cannot be aggregated again.
  $risk_score = if($event_count > 5, "SEVERE", "MODERATE")

  // This is the equivalent of the 2 outcomes above combined.
  $risk_score2 = if(count($login.metadata.event_timestamp.seconds) > 5, "SEVERE", "MODERATE")

condition:
  $e

Ergebnisvariablen können in allen Ausdruckstypen auf der rechten Seite einer Ergebniszuweisung verwendet werden, außer in den folgenden Ausdrücken:

• Zusammenfassungen
• Arrays.length()-Funktionsaufrufe
• Mit any- oder all-Modifikatoren

Zusammenfassungen

Felder für wiederkehrende Ereignisse sind nicht skalare Werte. Das heißt, eine einzelne Variable verweist auf mehrere Werte. Die Ereignisfeldvariable $e.target.ip ist beispielsweise ein wiederkehrendes Feld und kann null, einen oder viele IP-Werte enthalten. Dies ist ein nicht skalarer Wert. Die Ereignisfeldvariable $e.principal.hostname ist kein wiederkehrendes Feld und hat nur einen Wert (d.h. einen skalaren Wert).

Ebenso sind sowohl nicht wiederkehrende Ereignisfelder als auch wiederkehrende Ereignisfelder, die im Ergebnisabschnitt einer Regel mit einem Übereinstimmungsfenster verwendet werden, nicht skalare Werte. Die folgende Regel gruppiert beispielsweise Ereignisse mithilfe eines Abgleichsabschnitts und verweist auf ein nicht wiederkehrendes Ereignisfeld im Ergebnisbereich:

rule OutcomeAndMatchWindow{
  ...
  match:
    $userid over 5m
  outcome:
    $hostnames = array($e.principal.hostname)
  ...
}

Jedes 5-Minuten-Fenster, in dem die Regel ausgeführt wird, kann null, ein oder viele Ereignisse enthalten. Der Ergebnisbereich wirkt sich auf alle Ereignisse in einem Abgleichsfenster aus. Jede Ereignisfeldvariable, auf die im Ergebnisabschnitt Bezug genommen wird, kann bei jedem Ereignis im Übereinstimmungsfenster auf null, einen oder mehrere Werte des Felds verweisen. Wenn in der vorherigen Regel ein 5-Minuten-Fenster 5 $e-Ereignisse enthält, verweist $e.principal.hostname im Ergebnisabschnitt auf 5 verschiedene Hostnamen. Die Ereignisfeldvariable $e.principal.hostname ist daher ein nicht skalarer Wert im Ergebnisabschnitt dieser Regel.

Da Ergebnisvariablen immer einen einzelnen Skalarwert liefern müssen, muss jeder nicht skalare Wert, von dem eine Ergebniszuweisung abhängt, aggregiert werden, um einen einzelnen Skalarwert zu erhalten. In einem Ergebnisabschnitt sind die folgenden nicht skalaren Werte und müssen aggregiert werden:

• Ereignisfelder (wiederholt oder nicht wiederholt), wenn die Regel einen Übereinstimmungsbereich verwendet
• Ereignisplatzhalter (wiederholt oder nicht wiederholt), wenn die Regel einen Übereinstimmungsbereich verwendet
• Wiederkehrende Ereignisfelder, wenn für die Regel kein Übereinstimmungsbereich verwendet wird
• Wiederholte Ereignisplatzhalter, wenn für die Regel kein Übereinstimmungsbereich verwendet wird

Skalare Ereignisfelder, skalare Ereignisplatzhalter und Konstanten können in einer Aggregation in einer Regel zusammengefasst werden, die keinen Übereinstimmungsbereich verwendet. Die meisten Aggregationen liefern jedoch den umschlossenen Wert und sind daher nicht erforderlich. Die einzige Ausnahme ist die array()-Aggregation, mit der ein skalarer Wert in ein Array konvertiert werden kann.

Ergebnisvariablen werden wie Aggregationen behandelt: Sie dürfen nicht neu aggregiert werden, wenn in einer anderen Ergebniszuweisung darauf verwiesen wird.

Sie können die folgenden Aggregatfunktionen verwenden:

• max(): Gibt das Maximum an allen möglichen Werten aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.
• min(): Gibt das Minimum aller möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.
• sum(): gibt die Summe über alle möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.
• count_distinct(): Sammelt alle möglichen Werte und gibt dann die eindeutige Anzahl möglicher Werte aus.
• count(): verhält sich wie count_distinct(), gibt jedoch eine nicht eindeutige Anzahl möglicher Werte zurück.
• array_distinct(): Sammelt alle möglichen unterschiedlichen Werte und gibt dann eine Liste dieser Werte aus. Die Liste der unterschiedlichen Werte wird auf 25 zufällig ausgewählte Elemente gekürzt. Die Deduplizierung für eine eindeutige Liste wird zuerst angewendet, dann wird die Kürzung angewendet.
• array(): verhält sich wie array_distinct(), gibt jedoch eine nicht eindeutige Liste von Werten zurück. Außerdem wird die Liste der Werte auf 25 Zufallselemente gekürzt.

Die Aggregatfunktion ist wichtig, wenn eine Regel einen condition-Abschnitt enthält, in dem mehrere Ereignisse vorhanden sein müssen, da die Aggregatfunktion für alle Ereignisse verwendet wird, die die Erkennung generiert haben.

Wenn die Abschnitte outcome und condition beispielsweise Folgendes enthalten:

outcome:
  $asset_id_count = count($event.principal.asset_id)
  $asset_id_distinct_count = count_distinct($event.principal.asset_id)

  $asset_id_list = array($event.principal.asset_id)
  $asset_id_distinct_list = array_distinct($event.principal.asset_id)

condition:
  #event > 1

Da der Bedingungsabschnitt für jede Erkennung mehr als ein event erfordert, werden die Aggregatfunktionen für mehrere Ereignisse ausgeführt. Angenommen, die folgenden Ereignisse haben eine Erkennung generiert:

event:
  // UDM event 1
  asset_id="asset-a"

event:
  // UDM event 2
  asset_id="asset-b"

event:
  // UDM event 3
  asset_id="asset-b"

Dann lauten die Werte Ihrer Ergebnisse wie folgt:

• $asset_id_count = 3
• $asset_id_distinct_count = 2
• $asset_id_list = ["asset-a", "asset-b", "asset-b"]
• $asset_id_distinct_list = ["asset-a", "asset-b"]

Wichtige Hinweise zur Verwendung des Bereichs „Ergebnis“:

Weitere Hinweise und Einschränkungen:

• Der Abschnitt outcome darf nicht auf eine neue Platzhaltervariable verweisen, die noch nicht im Abschnitt events oder outcome definiert wurde.
• Der Abschnitt outcome darf keine Ereignisvariablen verwenden, die nicht im Abschnitt events definiert wurden.
• Für den Abschnitt outcome kann ein Ereignisfeld verwendet werden, das im Abschnitt events nicht verwendet wurde, sofern die Ereignisvariable, zu der das Ereignisfeld gehört, bereits im Abschnitt events definiert wurde.
• Mit dem Abschnitt outcome können nur Ereignisvariablen korreliert werden, die bereits im Abschnitt events korreliert wurden. Korrelationen treten auf, wenn zwei Ereignisfelder aus verschiedenen Ereignisvariablen gleich sind.

Ein Beispiel finden Sie im Abschnitt „Ergebnis“ unter Übersicht über YARA-L 2.0. Weitere Informationen zur Deduplizierung bei der Erkennung mit dem Ergebnisbereich finden Sie unter Kontextsensitive Analysen erstellen.

Syntax des Abschnitts „Bedingung“

• Geben Sie eine Übereinstimmungsbedingung für Ereignisse und Platzhalter an, die im Abschnitt events definiert sind. Weitere Informationen finden Sie im folgenden Abschnitt Ereignis- und Platzhalterbedingungen.
• (Optional) Verwenden Sie das Keyword and, um eine Übereinstimmungsbedingung mithilfe von im Abschnitt outcome definierten Ergebnisvariablen anzugeben. Weitere Informationen finden Sie im folgenden Abschnitt Ergebnisbedingungen.

Anzahl der Zeichen

Das Zeichen # ist ein Sonderzeichen im Abschnitt condition. Wird er vor dem Namen eines Ereignisses oder einer Platzhaltervariablen verwendet, stellt er die Anzahl der unterschiedlichen Ereignisse oder Werte dar, die alle Bedingungen im Abschnitt events erfüllen.

#c > 1 bedeutet beispielsweise, dass die Variable c mehrmals vorkommen muss.

Wertzeichen

Das Zeichen $ ist ein Sonderzeichen im Abschnitt condition. Wenn er vor dem Namen einer Ergebnisvariablen verwendet wird, stellt er den Wert dieses Ergebnisses dar.

Wenn es vor einem Ereignis- oder Platzhaltervariablennamen verwendet wird (z. B. $event), stellt es #event > 0 dar.

Ereignis- und Platzhalterbedingungen

Listen Sie hier Bedingungprädikate für Ereignisse und Platzhaltervariablen auf, verbunden mit dem Schlüsselwort and oder or. Das Schlüsselwort and kann zwischen beliebigen Bedingungen verwendet werden, aber das Keyword or kann nur verwendet werden, wenn die Regel nur eine einzige Ereignisvariable hat.

Ein gültiges Beispiel für die Verwendung von or zwischen zwei Platzhaltern für dasselbe Ereignis:

rule ValidConditionOr {
  meta:
  events:
      $e.metadata.event_type = "NETWORK_CONNECTION"

      // Note that all placeholders use the same event variable.
      $ph = $e.principal.user.userid  // Define a placeholder variable to put in match section.
      $ph2 = $e.principal.ip  // Define a second placeholder variable to put in condition section.
      $ph3 = $e.principal.hostname  // Define a third placeholder variable to put in condition section.

  match:
    $ph over 5m

  condition:
    $ph2 or $ph3
}

Ein ungültiges Beispiel für die Verwendung von or zwischen zwei Bedingungen bei verschiedenen Ereignissen:

rule InvalidConditionOr {
  meta:
  events:
      $e.metadata.event_type = "NETWORK_CONNECTION"
      $e2.graph.metadata.entity_type = "FILE"
      $e2.graph.entity.hostname  = $e.principal.hostname

      $ph = $e.principal.user.userid  // Define a placeholder variable to put in match section.

  match:
    $ph over 5m

  condition:
    $e or $e2 // This line will cause an error because there is an or between events.
}

Hinweis: Verwenden Sie das Keyword not nicht in Ereignis- und Platzhalterbedingungen.

Begrenzte und unbegrenzte Bedingungen

Die folgenden Bedingungen sind begrenzte Bedingungen. Sie erzwingen die Existenz der zugehörigen Ereignisvariablen. Das bedeutet, dass bei jeder Erkennung mindestens ein Auftreten des Ereignisses auftreten muss.

• $var // equivalent to #var > 0
• #var > n // where n >= 0
• #var >= m // where m > 0

Die folgenden Bedingungen sind unbegrenzte Bedingungen. Sie sorgen dafür, dass die zugehörige Ereignisvariable nicht vorhanden ist. Das bedeutet, dass bei einer Erkennung kein Auftreten des Ereignisses auftreten kann und jeder Verweis auf Felder der Ereignisvariablen einen Nullwert ergibt. Unbegrenzte Bedingungen können verwendet werden, um das Fehlen eines Ereignisses über einen bestimmten Zeitraum zu erkennen. Zum Beispiel ein Bedrohungsereignis ohne Eindämmungsereignis innerhalb von 10 Minuten. Regeln mit unbegrenzten Bedingungen werden als Nicht-Vorhandenseinsregeln bezeichnet.

• !$var // equivalent to #var = 0
• #var >= 0
• #var < n // where n > 0
• #var <= m // where m >= 0

Hinweis: Bei nicht vorhandenen Regeln fügt die Erkennungs-Engine der erwarteten Latenz (basierend auf der Ausführungshäufigkeit der Regel) eine Verzögerung von 1 Stunde hinzu, um spät ankommende Daten zu berücksichtigen.

Voraussetzungen für das Nicht-Vorhandensein

Damit eine Regel, die nicht vorhanden ist, kompiliert werden kann, muss sie die folgenden Anforderungen erfüllen:

1. Mindestens ein UDM-Ereignis muss eine begrenzte Bedingung haben (d. h., mindestens ein UDM-Ereignis muss vorhanden sein).
2. Wenn ein Platzhalter eine unbegrenzte Bedingung hat, muss er mit mindestens einem begrenzten UDM-Ereignis verknüpft sein.
3. Wenn eine Entität eine unbegrenzte Bedingung hat, muss sie mindestens einem begrenzten UDM-Ereignis zugeordnet werden.

Betrachten Sie die folgende Regel ohne den Abschnitt „Bedingung“:

rule NonexistenceExample {
  meta:
  events:
      $u1.metadata.event_type = "NETWORK_CONNECTION" // $u1 is a UDM event.
      $u2.metadata.event_type = "NETWORK_CONNECTION" // $u2 is a UDM event.
      $e1.graph.metadata.entity_type = "FILE"        // $e1 is an Entity.
      $e2.graph.metadata.entity_type = "FILE"        // $e2 is an Entity.

      $user = $u1.principal.user.userid // Match variable is required for Multi-Event Rule.

      // Placeholder Associations:
      //   u1        u2 
      //   |  \    /
      // port   ip
      //   |       \
      //   e1        e2
      $u1.target.port = $port
      $e1.graph.entity.port = $port
      $u1.principal.ip = $ip
      $u2.target.ip = $ip
      $e2.graph.entity.ip = $ip

      // UDM-Entity Associations:
      // u1 - u2
      // |  \  |
      // e1   e2
      $u1.metadata.event_type = $u2.metadata.event_type
      $e1.graph.entity.hostname = $u1.principal.hostname
      $e2.graph.entity.hostname = $u1.target.hostname
      $e2.graph.entity.hostname = $u2.principal.hostname

  match:
    $user over 5m

  condition:
      <condition_section>
}

Im Folgenden finden Sie gültige Beispiele für den <condition_section>:

• $u1 and !$u2 and $e1 and $e2
  • Alle UDM-Ereignisse und -Entitäten sind im Abschnitt „Bedingung“ vorhanden.
  • Mindestens ein UDM-Ereignis ist begrenzt.
• $u1 and !$u2 and $e1 and !$e2
  • $e2 ist unbegrenzt, was zulässig ist, weil die Property der begrenzten $u1 zugeordnet ist. Wenn $e2 nicht mit $u1 verknüpft wäre, wäre dies ungültig.
• #port > 50 and #ip = 0
  • Im Abschnitt „Bedingung“ sind keine UDM-Ereignisse und -Entitäten vorhanden. Die vorhandenen Platzhalter decken jedoch alle UDM-Ereignisse und -Entitäten ab.
  • $ip ist $u1 und $u2 zugewiesen und #ip = 0 ist eine unbegrenzte Bedingung. Eingeschränkte Bedingungen sind jedoch stärker als unbegrenzte Bedingungen. Da $port $u1 zugewiesen ist und #port > 50 eine begrenzte Bedingung ist, ist $u1 immer noch begrenzt.

Die folgenden Beispiele für <condition_section> sind ungültig:

• $u1 and $e1
  • Jedes UDM-Ereignis und jede Entität, die im Abschnitt „Ereignisse“ erscheint, muss im Abschnitt „Condition“ (Bedingung) angezeigt werden oder es muss ein Platzhalter im Abschnitt „Condition“ (Bedingung) zugewiesen sein.
• $u1, $u2, $e1, $u2, #port > 50
  • Kommas sind als Trennzeichen für Bedingungen nicht zulässig.
• !$u1 and !$u2 and $e1 and $e2
  • Verstößt gegen die erste Anforderung, dass mindestens ein UDM-Ereignis begrenzt ist.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • Das Keyword or wird mit unbegrenzten Bedingungen nicht unterstützt.
• ($u1 or $u2) and $e1 and $e2
  • Das Keyword „or“ wird mit verschiedenen Ereignisvariablen nicht unterstützt.
• not $u1 and $u2 and $e1 and $e2
  • not Keyword ist für Ereignis- und Platzhalterbedingungen nicht zulässig.
• #port < 50 and #ip = 0
  • Die vorhandenen Platzhalter decken alle UDM-Ereignisse und -Entitäten ab. Allerdings sind alle Bedingungen unbegrenzt. Das bedeutet, dass keines der UDM-Ereignisse begrenzt ist, wodurch die Regel nicht kompiliert werden kann.

Hinweis: Verwenden Sie keine match-Variable im Abschnitt condition. Es handelt sich um einen semantischen Fehler, da Ereignisse anhand des Variablenwerts match gruppiert werden.

Hinweis: Geben Sie nicht für alle event-Variablen, denen eine match-Variable zugewiesen ist, nur unbegrenzte Bedingungen an. Es handelt sich um einen semantischen Fehler. Damit ein match-Variablenwert zurückgegeben wird, muss mindestens ein Ereignis vorhanden sein, das den Wert enthält.

Hinweis: Wenn Sie ein gleitendes Fenster verwenden, muss die Pivot-Ereignisvariable an mindestens einer Begrenzungsbedingung beteiligt sein.

Ergebnisbedingungen

Listen Sie hier Bedingungsprädikate für Ergebnisvariablen auf, die mit dem Schlüsselwort and oder or verknüpft oder dem Schlüsselwort not vorangestellt sind.

Geben Sie Ergebnisbedingungen je nach Typ der Ergebnisvariablen unterschiedlich an:

• integer: Vergleich mit einem Ganzzahlliteral mit den Operatoren =, >, >=, <, <=, !=. Beispiel:

  $risk_score > 10

• float: Vergleich mit einem Gleitkommazahl-Literal mit den Operatoren =, >, >=, <, <=, !=. Beispiel:

  $risk_score <= 5.5

• string: Vergleich mit einem Stringliteral mit = oder !=. Beispiel:

  $severity = "HIGH"

• Liste mit Ganzzahlen oder Arrays: Geben Sie die Bedingung mit der Funktion arrays.contains an. Beispiel:

  arrays.contains($event_ids, "id_1234")

Hinweis :Wenn Sie das Schlüsselwort or im Unterabschnitt <event/placeholder conditionals> verwenden, müssen Sie den gesamten Unterabschnitt in Klammern setzen. Folgendes ist beispielsweise gültig: ($e1 or $e2) and $outcome > 0.

Regelklassifizierung

Wenn Sie eine Bedingung für das Ergebnis in einer Regel mit einem Übereinstimmungsbereich angeben, wird die Regel für das Regelkontingent als Regel mit mehreren Ereignissen klassifiziert. Weitere Informationen zur Klassifizierung von einzelnen und mehreren Ereignissen finden Sie unter Regeln für einzelne Ereignisse und Regeln für mehrere Ereignisse.

Syntax des Abschnitts „Optionen“

Im Abschnitt options können Sie die Optionen für die Regel festlegen. Hier ein Beispiel dafür, wie Sie den Abschnitt „Optionen“ angeben:

rule RuleOptionsExample {
  // Other rule sections

  options:
    allow_zero_values = true
}

Sie können Optionen mit der Syntax key = value angeben, wobei key ein vordefinierter Optionsname und value ein gültiger Wert für die Option sein muss, wie für die folgenden Optionen angegeben:

allow_zero_values

Die gültigen Werte für diese Option sind true und false. Mit diesen Werten wird festgelegt, ob diese Option aktiviert ist oder nicht. Der Standardwert ist false. Diese Option ist deaktiviert, wenn sie in der Regel nicht angegeben ist.

Um diese Einstellung zu aktivieren, fügen Sie dem Abschnitt „Optionen“ der Regel Folgendes hinzu: allow_zero_values = true. Dadurch wird verhindert, dass die Regel implizit die Nullwerte von Platzhaltern herausfiltert, die im Abgleichsabschnitt verwendet werden, wie unter Umgang mit Nullwerten im Übereinstimmungsabschnitt beschrieben.

Boolesche Ausdrücke

Boolesche Ausdrücke sind Ausdrücke mit einem booleschen Typ.

Vergleiche

Damit ein binärer Ausdruck als Bedingung verwendet werden kann, verwenden Sie die folgende Syntax:

• <EXPR> <OP> <EXPR>

Der Ausdruck kann ein Ereignisfeld, eine Variable, ein Literal oder ein Funktionsausdruck sein.

Beispiel:

• $e.source.hostname = "host1234"
• $e.source.port < 1024
• 1024 < $e.source.port
• $e1.source.hostname != $e2.target.hostname
• $e1.metadata.collected_timestamp.seconds > $e2.metadata.collected_timestamp.seconds
• $port >= 25
• $host = $e2.target.hostname
• "google-test" = strings.concat($e.principal.hostname, "-test")
• "[e-mail]" = re.replace($e.network.email.from, "com", "org")

Wenn beide Seiten Literale sind, wird dies als Kompilierungsfehler betrachtet.

Funktionen

Einige Funktionsausdrücke geben einen booleschen Wert zurück, der als einzelnes Prädikat im events-Abschnitt verwendet werden kann. Diese Funktionen sind:

• re.regex()
• net.ip_in_range_cidr()

Beispiel:

• re.regex($e.principal.hostname, `.*\.google\.com`)
• net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

Ausdrücke der Referenzliste

Du kannst Referenzlisten im Ereignisbereich verwenden. Weitere Informationen finden Sie im Abschnitt zu Referenzlisten.

Logische Ausdrücke

Sie können die logischen and- und logischen or-Operatoren im Abschnitt events verwenden, wie in den folgenden Beispielen gezeigt:

• $e.metadata.event_type = "NETWORK_DNS" or $e.metadata.event_type = "NETWORK_DHCP"
• ($e.metadata.event_type = "NETWORK_DNS" and $e.principal.ip = "192.0.2.12") or ($e.metadata.event_type = "NETWORK_DHCP" and $e.principal.mac = "AB:CD:01:10:EF:22")
• not $e.metadata.event_type = "NETWORK_DNS"

Standardmäßig ist die Reihenfolge von der höchsten zur niedrigsten Priorität not, and, or.

Beispielsweise wird „a oder b und c“ als „a oder (b und c)“ ausgewertet, wenn die Operatoren or und and explizit im Ausdruck definiert sind.

Im Abschnitt events werden Prädikate mit dem Operator and verbunden, wenn nicht explizit ein Operator definiert ist.

Die Reihenfolge der Auswertung kann abweichen, wenn der and-Operator im Ausdruck impliziert ist.

Betrachten Sie beispielsweise die folgenden Vergleichsausdrücke, in denen or explizit definiert ist. Der Operator and ist impliziert.

$e1.field = "bat"
or $e1.field = "baz"
$e2.field = "bar"

Dieses Beispiel wird so interpretiert:

($e1.field = "bat" or $e1.field = "baz")
and ($e2.field = "bar")

Da or explizit definiert ist, werden die Prädikate um or zuerst gruppiert und ausgewertet. Das letzte Prädikat, $e2.field = "bar", wird implizit über and verknüpft. Das Ergebnis ist diese Reihenfolge der Bewertungsänderungen.

Hinweis: Die Anzahl der Werte and und or, die Sie für eine einzelne Regel angeben können, ist begrenzt. Dieses Limit hängt von der Komplexität der Regel und der Komplexität der Daten in Ihrem Google Security Operations-Konto ab. Wenden Sie sich an Ihren Google Security Operations-Vertreter, um Informationen zu Alternativen zu dieser Art von Regel zu erhalten.

Enumerationstypen

Sie können die Operatoren auch mit Enum-Typen verwenden. Sie kann auf Regeln angewendet werden, um die Leistung zu vereinfachen und zu optimieren (Operator anstelle von Referenzlisten verwenden).

Im folgenden Beispiel entsprechen „USER_UNCATEGORIZED“ und „USER_RESOURCE_DELETION“ den Werten 15.000 und 15.014, sodass die Regel nach allen aufgeführten Ereignissen sucht:

$e.metadata.event_type >= "USER_CATEGORIZED" and $e.metadata.event_type <= "USER_RESOURCE_DELETION"

Liste der Ereignisse:

• USER_RESOURCE_DELETION
• USER_RESOURCE_UPDATE_CONTENT
• USER_RESOURCE_UPDATE_PERMISSIONS
• USER_STATS
• USER_UNCATEGORIZED

Nocase-Modifikator

Wenn Sie einen Vergleichsausdruck zwischen Stringwerten oder einem regulären Ausdruck haben, können Sie nocase am Ende des Ausdrucks anhängen, um die Groß- und Kleinschreibung zu ignorieren.

• $e.principal.hostname != "http-server" nocase
• $e1.principal.hostname = $e2.target.hostname nocase
• $e.principal.hostname = /dns-server-[0-9]+/ nocase
• re.regex($e.target.hostname, `client-[0-9]+`) nocase

Dies kann nicht verwendet werden, wenn ein Feldtyp ein Aufzählungswert ist. Die folgenden Beispiele sind ungültig und führen zu Kompilierungsfehlern:

• $e.metadata.event_type = "NETWORK_DNS" nocase
• $e.network.ip_protocol = "TCP" nocase

Wiederkehrende Felder

Im Unified Data Model (UDM) sind einige Felder als wiederholt gekennzeichnet, was darauf hinweist, dass es sich um Listen von Werten oder anderen Nachrichtentypen handelt.

Wiederkehrende Felder und boolesche Ausdrücke

Es gibt zwei Arten von booleschen Ausdrücken, die auf wiederkehrende Felder angewendet werden:

1. Geändert
2. Unverändert

Stellen Sie sich folgendes Ereignis vor:

event_original {
  principal {
    // ip is a repeated field
    ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]

    hostname: "host"
  }
}

Geänderte Ausdrücke

In den folgenden Abschnitten werden der Zweck und die Verwendung der Modifikatoren any und all in Ausdrücken beschrieben.

Beliebig

Wenn ein beliebiges Element des wiederholten Felds die Bedingung erfüllt, erfüllt das Ereignis als Ganzes die Bedingung.

• event_original erfüllt any $e.principal.ip = "192.0.2.1".
• event_original schlägt any $e.repeated_field.field_a = "9.9.9.9 fehl.

alle

Wenn alle Elemente des wiederholten Felds die Bedingung erfüllen, erfüllt das Ereignis als Ganzes die Bedingung.

• event_original erfüllt net.ip_in_range_cidr(all $e.principal.ip, "192.0.2.0/8").
• event_original schlägt all $e.principal.ip = "192.0.2.2" fehl.

Hinweis :Wenn Sie any oder all mit einer Funktion verwenden möchten, muss der Modifikator dem wiederholten Feld und nicht der Funktion vorangestellt werden. re.regex(any $e.about.hostname, `server-[0-9]+`) ist beispielsweise gültig, any re.regex($e.about.hostname, `server-[0-9]+`) jedoch nicht.

Wenn Sie eine Bedingung mit any oder all schreiben, beachten Sie, dass das Negieren der Bedingung mit not möglicherweise nicht die gleiche Bedeutung wie die Verwendung des negierten Operators hat.

Beispiel:

• not all $e.principal.ip = "192.168.12.16" prüft, ob nicht alle IP-Adressen mit 192.168.12.16 übereinstimmen. Das heißt, die Regel prüft, ob mindestens eine IP-Adresse nicht mit 192.168.12.16 übereinstimmt.
• all $e.principal.ip != "192.168.12.16" prüft, ob alle IP-Adressen nicht mit 192.168.12.16 übereinstimmen. Das heißt, die Regel prüft, ob keine IP-Adressen mit 192.168.12.16 übereinstimmen.

Einschränkungen:

• Die Operatoren any und all sind nur mit wiederkehrenden Feldern (keine skalaren Felder) kompatibel.
• any und all können nicht verwendet werden, um zwei wiederkehrende Felder zu verknüpfen. any $e1.principal.ip = $e2.principal.ip ist beispielsweise ungültig.
• Die Operatoren any und all werden zusammen mit dem Referenzlistenausdruck nicht unterstützt.

Nicht geänderte Ausdrücke

Bei unveränderten Ausdrücken wird jedes Element im wiederholten Feld einzeln behandelt. Wenn das wiederkehrende Feld eines Ereignisses n Elemente enthält, wird die Regel auf n Kopien des Ereignisses angewendet, wobei jede Kopie eines der Elemente des wiederholten Felds enthält. Diese Kopien sind vorübergehend und werden nicht gespeichert.

Die Regel wird auf die folgenden Kopien angewendet:

Terminkopie	principal.ip	principal.hostname
event_copy_1	„192.0.2.1“	"Host"
event_copy_2	„192.0.2.2“	"Host"
event_copy_3	„192.0.2.3“	"Host"

Wenn eine beliebige Ereigniskopie alle unveränderten Bedingungen im wiederholten Feld erfüllt, erfüllt das Ereignis als Ganzes alle Bedingungen. Wenn also mehrere Bedingungen für ein wiederkehrendes Feld vorhanden sind, muss die Ereigniskopie alle Bedingungen erfüllen. In den folgenden Regelbeispielen wird das vorherige Beispiel-Dataset verwendet, um dieses Verhalten zu veranschaulichen.

Die folgende Regel gibt eine Übereinstimmung zurück, wenn sie für das Beispiel-Dataset event_original ausgeführt wird, da event_copy_1 alle Ereignisprädikate erfüllt:

rule repeated_field_1 {
  meta:
  events:
    net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/8") // Checks if IP address matches 192.x.x.x
    $e.principal.ip = "192.0.2.1"
  condition:
    $e
}

Die folgende Regel gibt bei der Ausführung für das Beispiel-Dataset event_original keine Übereinstimmung zurück, da in $e.principal.ip keine Ereigniskopie vorhanden ist, die alle Ereignisprädikate erfüllt.

rule repeated_field_2 {
  meta:
  events:
    $e.principal.ip = "192.0.2.1"
    $e.principal.ip = "192.0.2.2"
  condition:
    $e
}

Geänderte Ausdrücke in wiederkehrenden Feldern sind mit unveränderten Ausdrücken in wiederkehrenden Feldern kompatibel, da die Elementliste für jede Ereigniskopie gleich ist. Beachten Sie die folgende Regel:

rule repeated_field_3 {
  meta:
  events:
    any $e.principal.ip = "192.0.2.1" 
    $e.principal.ip = "192.0.2.3"
  condition:
    $e
}

Die Regel wird auf die folgenden Kopien angewendet:

Terminkopie	principal.ip	jede $e.principal.ip
event_copy_1	„192.0.2.1“	["192.0.2.1", "192.0.2.2", "192.0.2.3"]
event_copy_2	„192.0.2.2“	["192.0.2.1", "192.0.2.2", "192.0.2.3"]
event_copy_3	„192.0.2.3“	["192.0.2.1", "192.0.2.2", "192.0.2.3"]

In diesem Fall erfüllen alle Kopien any $e.principal.ip = "192.0.2.1", aber nur event_copy_3 erfüllt $e.principal.ip = "192.0.2.3". Dadurch würde das Ereignis als Ganzes übereinstimmen.

Sie können sich diese Ausdruckstypen auch so vorstellen:

• Ausdrücke für wiederkehrende Felder, die any oder all verwenden, werden auf die Liste in event_original angewendet.
• Ausdrücke für wiederkehrende Felder, die weder any noch all verwenden, wirken sich auf einzelne event_copy_n-Ereignisse aus.

Wiederkehrende Felder und Platzhalter

Wiederkehrende Felder können mit Platzhalterzuweisungen verwendet werden. Ähnlich wie bei unveränderten Ausdrücken für wiederkehrende Felder wird für jedes Element eine Kopie des Ereignisses erstellt. Wie beim Beispiel für event_copy verwendet der Platzhalter den Wert des wiederkehrenden Feldwerts von event_copy_n für jede der Ereigniskopien, wobei n die Nummer der Ereigniskopie ist. Wenn der Platzhalter im Übereinstimmungsbereich verwendet wird, kann dies zu mehreren Übereinstimmungen führen.

Im folgenden Beispiel wird eine Übereinstimmung generiert. Der Platzhalter $ip ist gleich 192.0.2.1 für event_copy_1, wodurch die Prädikate in der Regel erfüllt werden. Die Ereignisbeispiele für die Übereinstimmung enthalten das einzelne Element event_original.

// Generates 1 match.
rule repeated_field_placeholder1 {
  meta:
  events:
    $ip = $e.principal.ip
    $ip = "192.0.2.1"
    $host = $e.principal.hostname

  match:
    $host over 5m

  condition:
    $e
}

Im folgenden Beispiel werden drei Übereinstimmungen generiert. Der Platzhalter $ip hat für jede der verschiedenen event_copy_n-Kopien gleich verschiedene Werte. Die Gruppierung wird anhand von $ip durchgeführt, da diese sich im Übereinstimmungsbereich befindet. Daher erhalten Sie drei Übereinstimmungen, bei denen jede Übereinstimmung einen anderen Wert für die Übereinstimmungsvariable $ip hat. Für jede Übereinstimmung wird das gleiche Ereignisbeispiel verwendet: nur das Element event_original.

// Generates 3 matches.
rule repeated_field_placeholder2 {
  meta:
  events:
    $ip = $e.principal.ip
    net.ip_in_range_cidr($ip, "192.0.2.0/8") // Checks if IP matches 192.x.x.x

  match:
    $ip over 5m

  condition:
    $e
}

Hinweis :any und all können nicht verwendet werden, wenn Sie einer Platzhaltervariablen ein wiederkehrendes Feld zuweisen oder mit einem Feld eines anderen Ereignisses zusammenführen. any $e.principal.ip = $ip ist beispielsweise ungültig.

Ergebnisse mit Platzhaltern, die wiederkehrenden Feldern zugewiesen sind

Platzhalter werden jedem Element jedes wiederkehrenden Felds zugewiesen, nicht der gesamten Liste. Wenn sie also im Abschnitt „Ergebnis“ verwendet werden, wird das Ergebnis nur anhand der Elemente berechnet, die in früheren Abschnitten erfüllt wurden.

Beachten Sie die folgende Regel:

rule outcome_repeated_field_placeholder {
  meta:
  events:
    $ip = $e.principal.ip
    $ip = "192.0.2.1" or $ip = "192.0.2.2"
    $host = $e.principal.hostname

  match:
    $host over 5m

  outcome:
    $o = array_distinct($ip)

  condition:
    $e
}

Diese Regel wird in vier Ausführungsphasen ausgeführt. Die erste Phase ist das Kopieren von Ereignissen:

Terminkopie	$ip	$host	$e
event_copy_1	„192.0.2.1“	"Host"	event_id
event_copy_2	„192.0.2.2“	"Host"	event_id
event_copy_3	„192.0.2.3“	"Host"	event_id

Im Bereich „Ereignisse“ werden dann Zeilen herausgefiltert, die nicht den Filtern entsprechen:

Terminkopie	$ip	$host	$e
event_copy_1	„192.0.2.1“	"Host"	event_id
event_copy_2	„192.0.2.2“	"Host"	event_id

event_copy_3 wurde herausgefiltert, da "192.0.2.3" nicht die Anforderungen von $ip = "192.0.2.1" or $ip = "192.0.2.2" erfüllt.

Im Übereinstimmungsbereich werden dann nach Übereinstimmungsvariablen gruppiert und im Ergebnisbereich wird für jede Gruppe eine Aggregation durchgeführt:

$host	o €	$e
"Host"	["192.0.2.1", "192.0.2.2"]	event_id

$o = array_distinct($ip) wird anhand der $ip aus der vorherigen Phase und nicht anhand der Kopierphase des Ereignisses berechnet.

Schließlich filtert der Bedingungsabschnitt jede Gruppe. Da diese Regel nur prüft, ob $e vorhanden ist, führt die Zeile von vorhin zu einer einzelnen Erkennung.

$o enthält nicht alle Elemente aus $e.principal.ip, da nicht alle Elemente alle Bedingungen im Bereich „Ereignisse“ erfüllen. Allerdings werden alle Elemente von e.principal.ip im Ereignisbeispiel angezeigt, weil dort event_original verwendet wird.

Array-Indexierung

Sie können eine Array-Indexierung für wiederkehrende Felder durchführen. Um auf das n-te wiederkehrende Feldelement zuzugreifen, verwenden Sie die Standardlistensyntax (die Elemente sind 0-indexiert). Ein Element außerhalb des gültigen Bereichs gibt den Standardwert zurück.

• $e.principal.ip[0] = "192.168.12.16"
• $e.principal.ip[999] = "" Bei weniger als 1.000 Elementen wird true ausgewertet.

Einschränkungen:

• Ein Index muss ein nicht negatives Ganzzahlliteral sein. $e.principal.ip[-1] ist beispielsweise ungültig.
• Werte vom Typ int (z. B. Platzhalter, die auf int gesetzt sind) werden nicht gezählt.
• Die Array-Indexierung kann nicht mit any oder all kombiniert werden. any $e.intermediary.ip[0] ist beispielsweise ungültig.
• Die Array-Indexierung kann nicht mit der Kartensyntax kombiniert werden. $e.additional.fields[0]["key"] ist beispielsweise ungültig.
• Wenn der Feldpfad mehrere wiederkehrende Felder enthält, muss für alle wiederkehrenden Felder die Array-Indexierung verwendet werden. $e.intermediary.ip[0] ist beispielsweise nicht gültig, weil intermediary und ip beide wiederkehrende Felder sind, aber nur ein Index für ip vorhanden ist.

Wiederholte Nachrichten

Wenn ein message-Feld wiederholt wird, verringert sich dadurch die Wahrscheinlichkeit einer Übereinstimmung. Dies wird in den folgenden Beispielen veranschaulicht.

Stellen Sie sich folgendes Ereignis vor:

event_repeated_message {
  // about is a repeated message field.
  about {
    // ip is a repeated string field.
    ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]

    hostname: "alice"
  }
  about {
    hostname: "bob"
  }
}

Wie bei unveränderten Ausdrücken für wiederkehrende Felder angegeben, wird für jedes Element des wiederholten Felds eine temporäre Kopie des Ereignisses erstellt. Beachten Sie die folgende Regel:

rule repeated_message_1 {
  meta:
  events:
    $e.about.ip = "192.0.2.1" 
    $e.about.hostname = "bob"
  condition:
    $e
}

Die Regel wird auf die folgenden Kopien angewendet:

Terminkopie	about.ip	about.hostname
event_copy_1	„192.0.2.1“	„Alice“
event_copy_2	„192.0.2.2“	„Alice“
event_copy_3	„192.0.2.3“	„Alice“
event_copy_4	""	„Bernd“

Das Ereignis stimmt nicht mit der Regel überein, weil es keine Ereigniskopie gibt, die alle Ausdrücke erfüllt.

Wiederholte Nachrichten und Array-Indexierung

Wenn die Array-Indexierung mit unveränderten Ausdrücken für wiederholte Nachrichtenfelder verwendet wird, kann ein anderes unerwartetes Verhalten auftreten. Betrachten Sie die folgende Beispielregel, die die Array-Indexierung verwendet:

rule repeated_message_2 {
  meta:
  events:
    $e.about.ip = "192.0.2.1" 
    $e.about[1].hostname = "bob"
  condition:
    $e
}

Die Regel wird auf die folgenden Kopien angewendet:

Terminkopie	about.ip	about[1].hostname
event_copy_1	„192.0.2.1“	„Bernd“
event_copy_2	„192.0.2.2“	„Bernd“
event_copy_3	„192.0.2.3“	„Bernd“
event_copy_4	""	„Bernd“

Da event_copy_1 alle Ausdrücke in repeated_message_2 erfüllt, stimmt das Ereignis mit der Regel überein.

Dies kann zu unerwartetem Verhalten führen, da der Regel repeated_message_1 keine Array-Indexierung fehlte und keine Übereinstimmungen erzeugt wurden, während die Regel repeated_message_2 die Array-Indexierung verwendet und eine Übereinstimmung erzeugt hat.

Kommentare

Kennzeichnen Sie Kommentare mit zwei Schrägstrichen (// comment) oder mehrzeiligen Kommentare, die mit einem Schrägstrich (/* comment */) versehen sind, wie bei C.

Literale

Nicht negative Ganzzahlen und Gleitkommazahlen, String-, boolesche und reguläre Ausdrucksliterale werden unterstützt.

String- und reguläre Ausdrucksliterale

Sie können eines der folgenden Anführungszeichen verwenden, um Zeichenfolgen in YARA-L 2.0 einzuschließen. Zitierter Text wird jedoch je nachdem, welchen Text Sie verwenden, unterschiedlich interpretiert.

1. Doppelte Anführungszeichen (") – wird für normale Zeichenfolgen verwendet. Muss Escape-Zeichen enthalten.
   Beispiel: „hello\tworld“ —\t wird als Tab interpretiert

2. Zurücke Anführungszeichen (`): Hiermit werden alle Zeichen wortgetreu interpretiert.
   Beispiel: „hello\tworld“ —\t wird nicht als Tab interpretiert.

Für reguläre Ausdrücke gibt es zwei Optionen.

Wenn Sie reguläre Ausdrücke direkt ohne die Funktion re.regex() verwenden möchten, verwenden Sie /regex/ für die Literale regulärer Ausdrücke.

Sie können Stringliterale auch als Literale für reguläre Ausdrücke verwenden, wenn Sie die re.regex()-Funktion nutzen. Bei String-Literalen mit doppelten Anführungszeichen müssen umgekehrte Schrägstriche mit umgekehrten Schrägstrichen maskiert werden, was unpassend aussehen kann.

Die folgenden regulären Ausdrücke sind beispielsweise äquivalent:

• re.regex($e.network.email.from, `.*altostrat\.com`)
• re.regex($e.network.email.from, ".*altostrat\\.com")
• $e.network.email.from = /.*altostrat\.com/

Zur besseren Lesbarkeit empfiehlt Google, in regulären Ausdrücken umgekehrte Anführungszeichen für Strings zu verwenden.

Operatoren

In YARA-L können Sie die folgenden Operatoren verwenden:

Operator:	Beschreibung
=	gleich/deklaration
!=	ungleich
<	ist kleiner als
<=	kleiner oder gleich
>	ist größer als
>=	größer als oder gleich

Variablen

In YARA-L 2.0 werden alle Variablen als $<variable name> dargestellt.

Sie können die folgenden Variablentypen definieren:

• Ereignisvariablen: Sie stellen Ereignisgruppen in normalisierter Form (UDM) oder Entitätsereignisse dar. Geben Sie im Bereich events Bedingungen für Ereignisvariablen an. Ereignisvariablen werden anhand der Felder „Name“, „Ereignisquelle“ und „Ereignis“ identifiziert. Zulässige Quellen sind udm (für normalisierte Ereignisse) und graph (für Entitätsereignisse). Wird die Quelle weggelassen, wird udm als Standardquelle festgelegt. Ereignisfelder werden als Kette von .<Feldname> dargestellt (z. B. $e.field1.field2). Ereignisfeldketten beginnen immer mit der Quelle der obersten Ebene (UDM oder Entität).

• Übereinstimmungsvariablen: Deklarieren Sie sie im Abschnitt match. Übereinstimmungsvariablen werden zu Gruppierungsfeldern für die Abfrage, da für jede eindeutige Gruppe von Übereinstimmungsvariablen (und für jedes Zeitfenster) eine Zeile zurückgegeben wird. Wenn durch die Regel eine Übereinstimmung gefunden wird, werden die Werte der Übereinstimmungsvariablen zurückgegeben. Geben Sie im Abschnitt events an, wofür die einzelnen Übereinstimmungsvariablen stehen.

• Platzhaltervariablen: Deklarieren und definieren Sie sie im Abschnitt events. Platzhaltervariablen ähneln Abgleichvariablen. Sie können jedoch mithilfe von Platzhaltervariablen im Abschnitt condition Übereinstimmungsbedingungen angeben.

Hinweis :Jede Platzhaltervariable muss einem Ereignisfeld zugeordnet sein. Wenn Sie beispielsweise in einer einzigen Zeile nur auf den folgenden Platzhalter verweisen, kann diese nicht kompiliert werden, da $var nicht an eine Ereignisvariable gebunden ist: $e.field != $var

Verwenden Sie Abgleichs- und Platzhaltervariablen, um Beziehungen zwischen Ereignisfeldern mithilfe von Transitive Join-Bedingungen zu deklarieren. Weitere Informationen finden Sie im Abschnitt Syntax des Abschnitts „Ereignisse“.

Keywords

Bei Keywords in YARA-L 2.0 wird die Groß-/Kleinschreibung nicht berücksichtigt. Beispiel: and oder AND sind gleichwertig. Variablennamen dürfen nicht mit Keywords in Konflikt stehen. Beispiel: $AND oder $outcome ist ungültig.

Die folgenden Schlüsselwörter für Erkennungs-Engine-Regeln sind: rule, meta, match, over, events, condition, outcome, options, and, or, not, nocase, in, regex, cidr, before, after, all, any, if, max, {2/6, {2/6}, {2/6}, {2/6}, {2/6}, {2/6}, {2/6}, {2/6}, and, or, not, nocase, or, not, nocaseminsumarrayarray_distinctcountcount_distinctisnull

Maps

YARA-L unterstützt den Kartenzugriff für Structs und Labels.

Strukturen und Beschriftungen

Einige UDM-Felder verwenden entweder den Datentyp Struct oder Label.

Um sowohl in der Struktur als auch in der Bezeichnung nach einem bestimmten Schlüssel/Wert-Paar zu suchen, verwenden Sie die Standardzuordnungssyntax:

// A Struct field.
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// A Label field.
$e.metadata.ingestion_labels["MetadataKeyDeletion"] = "startup-script"

Beim Kartenzugriff wird immer ein String zurückgegeben.

Unterstützte Fälle

Bereich „Ereignisse und Ergebnisse“

// Using a Struct field in the events section
events:
  $e.udm.additional.fields["pod_name"] = "kube-scheduler"

// Using a Label field in the outcome section
outcome:
  $value = array_distinct($e.metadata.ingestion_labels["MetadataKeyDeletion"])

Einem Platzhalter einen Kartenwert zuweisen

$placeholder = $u1.metadata.ingestion_labels["MetadataKeyDeletion"]

Kartenfeld in einer Join-Bedingung verwenden

// using a Struct field in a join condition between two udm events $u1 and $u2
$u1.metadata.event_type = $u2.udm.additional.fields["pod_name"]

Nicht unterstützte Fälle

Karten werden in den folgenden Fällen nicht unterstützt.

Keywords vom Typ any oder all mit einer Karte kombinieren

Folgendes wird beispielsweise nicht unterstützt:

all $e.udm.additional.fields["pod_name"] = "kube-scheduler"

Andere Arten von Werten

Von der Kartensyntax kann nur ein Stringwert zurückgegeben werden. Bei Struct-Datentypen kann die Kartensyntax nur auf Schlüssel zugreifen, deren Werte Strings sind. Der Zugriff auf Schlüssel mit anderen primitiven Typen wie Ganzzahlen ist nicht möglich.

Umgang mit doppelten Werten

Bei Kartenzugriffen wird immer ein einzelner Wert zurückgegeben. In dem ungewöhnlichen Grenzfall, dass sich der Kartenzugriff auf mehrere Werte beziehen kann, gibt der Kartenzugriff deterministisch den ersten Wert zurück.

Das kann in folgenden Fällen passieren:

• Ein Label hat einen doppelten Schlüssel.

  Die Labelstruktur stellt eine Karte dar, erzwingt jedoch keine Eindeutigkeit von Schlüsseln. Konventionsgemäß sollte eine Zuordnung eindeutige Schlüssel haben. Google Security Operations rät daher davon ab, ein Label mit doppelten Schlüsseln zu füllen.

  Der Regeltext $e.metadata.ingestion_labels["dupe-key"] würde bei Ausführung des folgenden Datenbeispiels den ersten möglichen Wert val1 zurückgeben:

  // Disrecommended usage of label with a duplicate key:
  event {
    metadata{
      ingestion_labels{
        key: "dupe-key"
        value: "val1" // This is the first possible value for "dupe-key"
      }
      ingestion_labels{
        key: "dupe-key"
        value: "val2"
      }
    }
  }
  

• Ein Label hat ein wiederkehrendes Ancestor-Feld.

  Ein wiederkehrendes Feld kann ein Label als untergeordnetes Feld enthalten. Zwei verschiedene Einträge im wiederkehrenden Feld der obersten Ebene können Labels mit demselben Schlüssel enthalten. Der Regeltext $e.security_result.rule_labels["key"] würde bei Ausführung des folgenden Datenbeispiels den ersten möglichen Wert, val3, zurückgeben:

  event {
    // security_result is a repeated field.
    security_result {
      threat_name: "threat1"
      rule_labels {
        key: "key"
        value: "val3" // This is the first possible value for "key"
      }
    }
    security_result {
      threat_name: "threat2"
      rule_labels {
        key: "key"
        value: "val4"
      }
    }
  }
  

Funktionen

In diesem Abschnitt werden die YARA-L 2.0-Funktionen beschrieben, die Sie in Erkennungs-Engine-Regeln und -Suchen verwenden können.

Hinweis :Die Verwendung der Ereignisvariablen $e ist optional, wenn YARA-L in der Suche verwendet wird. principal.hostname und $e.principal.hostname werden in der Suche unterstützt.

Diese Funktionen können in den folgenden Teilen einer YARA-L-Regel verwendet werden:

• Bereich „events“.
• BOOL_CLAUSE einer Bedingung im Ergebnisbereich.

arrays.length

Unterstützt in:

Regeln Suchen

arrays.length(repeatedField)

Beschreibung

Gibt die Anzahl wiederholter Feldelemente zurück.

Parameter-Datentypen

LIST

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

Gibt die Anzahl wiederholter Feldelemente zurück.

arrays.length($e.principal.ip) = 2

Beispiel 2

Wenn sich mehrere wiederkehrende Felder im Pfad befinden, wird die Gesamtzahl der wiederholten Feldelemente zurückgegeben.

arrays.length($e.intermediary.ip) = 3

Fingerprint

Unterstützt in:

Regeln

hash.fingerprint2011(byteOrString)

Beschreibung

Diese Funktion berechnet den fingerprint2011-Hash einer Eingabebyte-Sequenz oder eines Eingabestrings. Diese Funktion gibt einen vorzeichenlosen INT-Wert im Bereich [2, 0xFFFFFFFFFFFFFFFF] zurück.

Hinweis :Diese Funktion sollte nicht als kryptografischer sicherer Hash verwendet werden.

Parameter-Datentypen

BTYE, STRING

Rückgabetyp

INT

Codebeispiel

id_fingerprint = hash.fingerprint2011("user123")

Gruppe

Unterstützt in:

Suchen

group(field1, field2, field3, ...)

Beschreibung

Gruppieren Sie Felder eines ähnlichen Typs in einer Platzhaltervariablen.

Hinweis: Für die Suche können Sie gruppierte Felder im Ereignisbereich verwenden, aber nicht im Übereinstimmungs- und Ergebnisbereich.

Codebeispiele

Beispiel 1

Gruppieren Sie alle IP-Adressen und geben Sie die Anzahl der am häufigsten verwendeten IP-Adressen im gescannten Zeitraum absteigend an.

$ip = group(principal.ip, about.ip, target.ip)
$ip != ""
match:
  $ip
outcome:
  $count = count_distinct(metadata.id)
order:
  $count desc

math.abs

Unterstützt in:

Regeln Suchen

math.abs(numericExpression)

Beschreibung

Gibt den Absolutwert eines Ganzzahl- oder Float-Ausdrucks zurück.

Parameter-Datentypen

NUMBER

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

In diesem Beispiel wird "True" zurückgegeben, wenn das Ereignis mehr als 5 Minuten nach dem angegebenen Zeitpunkt (in Sekunden ab der Unix-Epoche) lag – unabhängig davon, ob das Ereignis vor oder nach der angegebenen Zeit aufgetreten ist. Ein Aufruf von math.abs darf nicht von mehreren Variablen oder Platzhaltern abhängen. Beispielsweise können Sie den hartcodierten Zeitwert 1643687343 im folgenden Beispiel nicht durch $e2.metadata.event_timestamp.seconds ersetzen.

300 < math.abs($e1.metadata.event_timestamp.seconds - 1643687343)

math.log

Unterstützt in:

Regeln Suchen

math.log(numericExpression)

Beschreibung

Gibt den natürlichen Logwert eines Ganzzahl- oder Float-Ausdrucks zurück.

Parameter-Datentypen

NUMBER

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

math.log($e1.network.sent_bytes) > 20

math.round

Unterstützt in:

Suchen

math.round(numericExpression, decimalPlaces)

Beschreibung

Gibt den Wert eines Float-Ausdrucks zurück, gerundet auf die angegebene Anzahl von Dezimalstellen.

Parameter-Datentypen

NUMBER

Rückgabetyp

NUMBER

Codebeispiele

math.round(10.7) // returns 11
math.round(1.2567, 2) // returns 1.25
math.round(-10.7) // returns -11
math.round(-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer

metrics

Unterstützt in:

Regeln

Messwertfunktionen können große Mengen an Verlaufsdaten aggregieren. Sie können sie in Ihrer Regel mit metrics.functionName() im Ergebnisbereich verwenden.

Weitere Informationen finden Sie unter YARA-L-Messwerte.

net.ip_in_range_cidr

Unterstützt in:

Regeln Suchen

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Beschreibung

Gibt true zurück, wenn sich die angegebene IP-Adresse im angegebenen Subnetzwerk befindet.

Sie können YARA-L verwenden, um mit der Anweisung net.ip_in_range_cidr() in allen IP-Adressen innerhalb eines Subnetzwerks nach UDM-Ereignissen zu suchen. Sowohl IPv4 als auch IPv6 werden unterstützt.

Geben Sie ein UDM-IP-Feld und einen CIDR-Bereich an, um in einem Bereich von IP-Adressen zu suchen. YARA-L kann sowohl einzelne als auch wiederkehrende IP-Adressfelder verarbeiten.

Geben Sie ein UDM-Feld ip und einen CIDR-Bereich (Classless Inter-Domain Routing) an, um in einem Bereich von IP-Adressen zu suchen. YARA-L kann sowohl einzelne als auch wiederkehrende IP-Adressfelder verarbeiten.

Parameter-Datentypen

STRING, STRING

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

IPv4-Beispiel:

net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

Beispiel 2

IPv6-Beispiel:

net.ip_in_range_cidr($e.network.dhcp.yiaddr, "2001:db8::/32")

Eine Beispielregel mit der Anweisung net.ip_in_range_cidr() finden Sie in der Beispielregel unter Einzelnes Ereignis im Bereich der IP-Adressen.

re.regex

Unterstützt in:

Regeln Suchen

Sie können den Abgleich regulärer Ausdrücke in YARA-L 2.0 mithilfe der folgenden Syntax definieren:

• YARA-L-Syntax verwenden: Ereignisse in Bezug auf Ereignisse. Im Folgenden finden Sie eine allgemeine Darstellung dieser Syntax:

  $e.field = /regex/
  

• Verwendung der YARA-L-Syntax – als Funktion, die die folgenden Parameter übernimmt:

  • Feld, auf das der reguläre Ausdruck angewendet wird
  • Regulärer Ausdruck, der als String angegeben wird

  Im Folgenden finden Sie eine allgemeine Darstellung dieser Syntax:

  re.regex($e.field, `regex`)
  

Beschreibung

Diese Funktion gibt true zurück, wenn der String einen Teilstring enthält, der mit dem angegebenen regulären Ausdruck übereinstimmt. Sie müssen .* nicht am Anfang oder Ende des regulären Ausdrucks einfügen.

Notes

• Fügen Sie die Ankerzeichen ^ (Anfang) und $ (Ende) in den regulären Ausdruck ein, um den genauen String oder nur ein Präfix oder Suffix abzugleichen. Beispiel: /^full$/ stimmt genau mit "full" überein, während /full/ mit "fullest", "lawfull" und "joyfully" übereinstimmen könnte.
• Wenn das UDM-Feld Zeilenumbruchzeichen enthält, stimmt regexp nur mit der ersten Zeile des UDM-Felds überein. Fügen Sie dem regulären Ausdruck (?s) hinzu, um einen vollständigen UDM-Feldabgleich zu erzwingen. Ersetzen Sie beispielsweise /.*allUDM.*/ durch /(?s).*allUDM.*/.
• Sie können den nocase-Modifikator nach Strings verwenden, um anzugeben, dass bei der Suche die Groß- und Kleinschreibung ignoriert werden soll.

Parameter-Datentypen

STRING, STRING

Parameterausdrucktypen

ANY, ANY

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

// Equivalent to $e.principal.hostname = /google/
re.regex($e.principal.hostname, "google")

re.capture

Unterstützt in:

Regeln Suchen

re.capture(stringText, regex)

Beschreibung

Erfasst (extrahiert) Daten aus einem String mithilfe des im Argument angegebenen Musters für reguläre Ausdrücke.

Diese Funktion verwendet zwei Argumente:

• stringText: der ursprüngliche String, der gesucht werden soll.
• regex: der reguläre Ausdruck, der das zu suchende Muster angibt.

Der reguläre Ausdruck kann 0 oder 1 Erfassungsgruppen in Klammern enthalten. Wenn der reguläre Ausdruck 0 Erfassungsgruppen enthält, gibt die Funktion den ersten gesamten übereinstimmenden Teilstring zurück. Wenn der reguläre Ausdruck eine Erfassungsgruppe enthält, wird der erste übereinstimmende Teilstring für die Erfassungsgruppe zurückgegeben. Wenn Sie zwei oder mehr Erfassungsgruppen definieren, wird ein Compilerfehler zurückgegeben.

Parameter-Datentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Wenn $e.principal.hostname in diesem Beispiel „aaa1bbaa2“ enthält, wäre Folgendes wahr, da die Funktion die erste Instanz zurückgibt. Dieses Beispiel hat keine Erfassungsgruppen.

"aaa1" = re.capture($e.principal.hostname, "a+[1-9]")

Beispiel 2

In diesem Beispiel wird alles nach dem @-Symbol in einer E-Mail erfasst. Wenn das Feld $e.network.email.from den Wert [e-mail] hat, wird im Beispiel google.com zurückgegeben. Das folgende Beispiel enthält eine Erfassungsgruppe.

"google.com" = re.capture($e.network.email.from , "@(.*)")

Beispiel 3

Wenn der reguläre Ausdruck mit keinem Teilstring im Text übereinstimmt, gibt die Funktion einen leeren String zurück. Sie können Ereignisse weglassen, bei denen keine Übereinstimmung auftritt, indem Sie den leeren String ausschließen. Dies ist besonders wichtig, wenn Sie re.capture() mit einer Ungleichheit verwenden:

// Exclude the empty string to omit events where no match occurs.
"" != re.capture($e.network.email.from , "@(.*)")

// Exclude a specific string with an inequality.
"google.com" != re.capture($e.network.email.from , "@(.*)")

re.replace

Unterstützt in:

Regeln Suchen

re.replace(stringText, replaceRegex, replacementText)

Beschreibung

Führt eine Ersetzung eines regulären Ausdrucks durch.

Diese Funktion verwendet drei Argumente:

• stringText: der ursprüngliche String.
• replaceRegex: der reguläre Ausdruck, der das zu suchende Muster angibt.
• replacementText: Der Text, der in jede Übereinstimmung eingefügt werden soll.

Gibt einen neuen String zurück, der vom ursprünglichen stringText abgeleitet ist, wobei alle Teilstrings, die mit dem Muster in replaceRegex übereinstimmen, durch den Wert in replacementText ersetzt werden. Sie können innerhalb von replacementText Escape-Ziffern mit umgekehrten Schrägstrichen (\1 bis \9) verwenden, um Text einzufügen, der mit der entsprechenden Klammergruppe im replaceRegex-Muster übereinstimmt. Verwenden Sie \0, um auf den gesamten übereinstimmenden Text zu verweisen.

Die Funktion ersetzt nicht überlappende Übereinstimmungen und priorisiert das Ersetzen des ersten gefundenen Vorkommens. re.replace("banana", "ana", "111") gibt beispielsweise den String „b111na“ zurück.

Parameter-Datentypen

STRING, STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird alles nach dem @-Symbol in einer E-Mail erfasst, com durch org ersetzt und dann das Ergebnis zurückgegeben. Beachten Sie die Verwendung verschachtelter Funktionen.

"[e-mail]" = re.replace($e.network.email.from, "com", "org")

Beispiel 2

In diesem Beispiel werden im replacementText-Argument mit umgekehrten Schrägstrichen maskierte Ziffern verwendet, um auf Übereinstimmungen mit dem replaceRegex-Muster zu verweisen.

"test1.com.google" = re.replace(
                       $e.principal.hostname, // holds "test1.test2.google.com"
                       "test2\.([a-z]*)\.([a-z]*)",
                       "\\2.\\1"  // \\1 holds "google", \\2 holds "com"
                     )

Beispiel 3

Beachten Sie die folgenden Fälle, wenn Sie mit leeren Strings und re.replace() umgehen:

Leerer String als replaceRegex verwenden:

// In the function call below, if $e.principal.hostname contains "name",
// the result is: 1n1a1m1e1, because an empty string is found next to
// every character in `stringText`.
re.replace($e.principal.hostname, "", "1")

Um einen leeren String zu ersetzen, können Sie "^$" als replaceRegex verwenden:

// In the function call below, if $e.principal.hostname contains the empty
// string, "", the result is: "none".
re.replace($e.principal.hostname, "^$", "none")

sample_rate

Unterstützt in:

Regeln

optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

Beschreibung

Mit dieser Funktion wird anhand einer deterministischen Stichprobenstrategie bestimmt, ob ein Ereignis einbezogen wird. Diese Funktion gibt Folgendes zurück:

• true für einen Bruchteil der Eingabewerte, entspricht (rateNumerator / rateDenominator) und gibt an, dass das Ereignis in die Stichprobe aufgenommen werden soll.
• false: Das Ereignis sollte nicht in der Stichprobe enthalten sein.

Diese Funktion ist nützlich für Optimierungsszenarien, in denen Sie nur einen Teil der Ereignisse verarbeiten möchten. Entspricht:

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Parameter-Datentypen

• byteOrString: Ausdruck, der entweder BYTE oder STRING ergibt.
• rateNumerator: 'INT'
• rateDenominator: 'INT'

Rückgabetyp

BOOL

Codebeispiel

events:
    $e.metadata.event_type = "NETWORK_CONNECTION"
    $asset_id = $e.principal.asset.asset_id
    optimization.sample_rate($e.metadata.id, 1, 5) // Only 1 out of every 5 events

  match:
    $asset_id over 1h

  outcome:
    $event_count = count_distinct($e.metadata.id)
  // estimate the usage by multiplying by the inverse of the sample rate
    $usage_past_hour = sum(5.0 * $e.network.sent_bytes)

 condition:
  // Requiring a certain number of events after sampling avoids bias (e.g. a
  // device with just 1 connection will still show up 20% of the time and
  // if we multiply that traffic by 5, we'll get an incorrect estimate)
  $e and ($usage_past_hour > 1000000000) and $event_count >= 100

strings.base64_decode

Unterstützt in:

Regeln Suchen

strings.base64_decode(encodedString)

Beschreibung

Gibt einen String zurück, der die base64-decodierte Version des codierten Strings enthält.

Diese Funktion verwendet einen base64-codierten String als Argument. Wenn encodedString kein gültiger base64-codierter String ist, gibt die Funktion encodedString unverändert zurück.

Parameter-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

"test" = strings.base64_decode($e.principal.domain.name)

strings.coalesce

Unterstützt in:

Regeln Suchen

strings.coalesce(a, b, c, ...)

Beschreibung

Diese Funktion verwendet eine unbegrenzte Anzahl von Argumenten und gibt den Wert des ersten Ausdrucks zurück, der nicht als leerer String ausgewertet wird (z. B. "Wert ungleich null"). Wenn alle Argumente einen leeren String ergeben, gibt der Funktionsaufruf einen leeren String zurück.

Die Argumente können Literale, Ereignisfelder oder Funktionsaufrufe sein. Alle Argumente müssen vom Typ STRING sein. Wenn es sich bei den Argumenten um Ereignisfelder handelt, müssen die Attribute zum selben Ereignis gehören.

Parameter-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Das folgende Beispiel enthält Stringvariablen als Argumente. Die Bedingung wird mit „true“ ausgewertet, wenn (1) $e.network.email.from [e-mail] oder (2) $e.network.email.from leer und $e.network.email.to [e-mail] ist.

"[e-mail]" = strings.coalesce($e.network.email.from, $e.network.email.to)

Beispiel 2

Im folgenden Beispiel wird die Funktion coalesce mit mehr als zwei Argumenten aufgerufen. Diese Bedingung vergleicht die erste Nicht-Null-IP-Adresse des Ereignisses $e mit Werten in der Referenzliste ip_watchlist. Die Reihenfolge, in der die Argumente in diesem Aufruf zusammengeführt werden, entspricht der Reihenfolge, in der sie in der Regelbedingung aufgelistet werden:

1. $e.principal.ip wird zuerst ausgewertet.
2. $e.src.ip wird als Nächstes ausgewertet.
3. $e.target.ip wird als Nächstes ausgewertet.
4. Wenn die vorherigen ip-Felder nicht festgelegt sind, wird der String „No IP“ als Standardwert zurückgegeben.

strings.coalesce($e.principal.ip, $e.src.ip, $e.target.ip, "No IP") in %ip_watchlist

Beispiel 3

Im folgenden Beispiel wird versucht, principal.hostname aus den Ereignissen $e1 und $e2 zusammenzuführen. Es wird ein Compiler-Fehler zurückgegeben, da die Argumente verschiedene Ereignisvariablen sind.

// returns a compiler error
"test" = strings.coalesce($e1.principal.hostname, $e2.principal.hostname)

strings.concat

Unterstützt in:

Regeln Suchen

strings.concat(a, b, c, ...)

Beschreibung

Gibt die Verkettung einer unbegrenzten Anzahl von Elementen zurück, von denen jedes ein String, eine Ganzzahl oder eine Gleitkommazahl sein kann.

Wenn es sich bei den Argumenten um Ereignisfelder handelt, müssen die Attribute zum selben Ereignis gehören.

Parameter-Datentypen

STRING, FLOAT, INT

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Das folgende Beispiel enthält eine Stringvariable und eine Ganzzahlvariable als Argumente. principal.hostname und principal.port stammen aus demselben Ereignis, $e, und werden verkettet, um einen String zurückzugeben.

"google:80" = strings.concat($e.principal.hostname, ":", $e.principal.port)

Beispiel 2

Das folgende Beispiel enthält eine Stringvariable und ein Stringliteral als Argumente.

"google-test" = strings.concat($e.principal.hostname, "-test") // Matches the event when $e.principal.hostname = "google"

Beispiel 3

Das folgende Beispiel enthält eine Stringvariable und ein Gleitkommazahlliteral als Argumente. Bei der Darstellung als Strings werden Gleitkommazahlen in ganzen Zahlen ohne Dezimalzeichen formatiert (z. B. wird 1,0 als „1“) dargestellt. Darüber hinaus werden Gleitkommazahlen, die mehr als sechzehn Dezimalstellen überschreiten, auf die sechzehnte Dezimalstelle gekürzt.

"google2.5" = strings.concat($e.principal.hostname, 2.5)

Beispiel 4

Das folgende Beispiel enthält eine Stringvariable, ein Stringliteral, eine Ganzzahlvariable und ein Float-Literal als Argumente. Alle Variablen stammen aus demselben Ereignis ($e) und werden mit den Literalen verkettet, um einen String zurückzugeben.

"google-test802.5" = strings.concat($e.principal.hostname, "-test", $e.principal.port, 2.5)

Beispiel 5

Im folgenden Beispiel wird versucht, „principal.port“ aus dem Ereignis $e1 mit principal.hostname aus dem Ereignis $e2 zu verketten. Es wird ein Compiler-Fehler zurückgegeben, da die Argumente unterschiedliche Ereignisvariablen sind.

// Will not compile
"test" = strings.concat($e1.principal.port, $e2.principal.hostname)

strings.to_lower

Unterstützt in:

Regeln Suchen

strings.to_lower(stringText)

Beschreibung

Diese Funktion verwendet einen Eingabestring und gibt einen String zurück, nachdem alle Zeichen in Kleinbuchstaben geändert wurden

Parameter-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird true zurückgegeben.

"[e-mail]" = strings.to_lower($e.network.email.to)

strings.to_upper

Unterstützt in:

Regeln Suchen

strings.to_upper(stringText)

Beschreibung

Diese Funktion verwendet einen Eingabestring und gibt einen String zurück, nachdem alle Zeichen in Großbuchstaben geändert wurden

Parameter-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird true zurückgegeben.

"[e-mail]" = strings.to_upper($e.network.email.to)

timestamp.current_seconds

Unterstützt in:

Regeln Suchen

timestamp.current_seconds()

Beschreibung

Gibt eine Ganzzahl zurück, die die aktuelle Zeit in Unix-Sekunden darstellt. Dieser Wert entspricht ungefähr dem Erkennungszeitstempel und hängt davon ab, wann die Regel ausgeführt wird.

Parameter-Datentypen

NONE

Rückgabetyp

INT

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird true zurückgegeben, wenn das Zertifikat länger als 24 Stunden abgelaufen ist. Zur Berechnung der Zeitdifferenz werden die aktuellen Unix-Sekunden subtrahiert und dann mit einem Größer-als-Operator verglichen.

86400 < timestamp.current_seconds() - $e.network.tls.certificate.not_after

timestamp.get_date

Unterstützt in:

Regeln Suchen

timestamp.get_date(unix_seconds [, time_zone])

Beschreibung

Diese Funktion gibt einen String im Format YYYY-MM-DD zurück, der den Tag darstellt, in dem sich ein Zeitstempel befindet.

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden nach der Unix-Epoche (z. B. $e.metadata.event_timestamp.seconds) oder einen Platzhalter mit diesem Wert darstellt.
• time_zone ist optional und ist ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, wird der Standardwert „GMT“ verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie auf dieser Seite in der Spalte „Name der TZ-Datenbank“.
  • Der Zeitzonenunterschied zu UTC im Format (+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige Zeitzonenspezifizierer, die Sie als zweites Argument an Zeitextraktionsfunktionen übergeben können:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Parameter-Datentypen

INT, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Der Standardwert ist daher „GMT“.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts) = "2024-02-19"

Beispiel 2

In diesem Beispiel wird ein Stringliteral zur Definition von time_zone verwendet.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts, "America/Los_Angeles") = "2024-02-20"

timestamp.get_minute

Unterstützt in:

Regeln Suchen

timestamp.get_minute(unix_seconds [, time_zone])

Beschreibung

Diese Funktion gibt eine Ganzzahl im Bereich [0, 59] für die Minute zurück.

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden nach der Unix-Epoche (z. B. $e.metadata.event_timestamp.seconds) oder einen Platzhalter mit diesem Wert darstellt.
• time_zone ist optional und ist ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, wird als Standardwert „GMT“ verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie auf dieser Seite in der Spalte „Name der TZ-Datenbank“.
  • Der Zeitzonenunterschied zu UTC im Format (+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige time_zone-Spezifizierer, die Sie als zweites Argument an Funktionen zur Zeitextraktion übergeben können:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Parameter-Datentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Der Standardwert ist daher „GMT“.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Beispiel 2

In diesem Beispiel wird ein Stringliteral zur Definition von time_zone verwendet.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_hour

Unterstützt in:

Regeln Suchen

timestamp.get_hour(unix_seconds [, time_zone])

Beschreibung

Diese Funktion gibt eine Ganzzahl im Bereich [0, 23] für die Stunde zurück.

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden nach der Unix-Epoche (z. B. $e.metadata.event_timestamp.seconds) oder einen Platzhalter mit diesem Wert darstellt.
• time_zone ist optional und ist ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, wird der Standardwert „GMT“ verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie auf dieser Seite in der Spalte „Name der TZ-Datenbank“.
  • Der Zeitzonenunterschied zu UTC im Format (+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige time_zone-Spezifizierer, die Sie als zweites Argument an Funktionen zur Zeitextraktion übergeben können:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Parameter-Datentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Der Standardwert ist daher „GMT“.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Beispiel 2

In diesem Beispiel wird ein Stringliteral zur Definition von time_zone verwendet.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_day_of_week

Unterstützt in:

Regeln Suchen

timestamp.get_day_of_week(unix_seconds [, time_zone])

Beschreibung

Diese Funktion gibt eine Ganzzahl im Bereich [1, 7] zurück, die den Wochentag ab Sonntag darstellt. Beispiel: 1 = Sonntag und 2 = Montag.

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden nach der Unix-Epoche (z. B. $e.metadata.event_timestamp.seconds) oder einen Platzhalter mit diesem Wert darstellt.
• time_zone ist optional und ist ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, wird der Standardwert „GMT“ verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie auf dieser Seite in der Spalte „Name der TZ-Datenbank“.
  • Der Zeitzonenunterschied zu UTC im Format (+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige Zeitzonenspezifizierer, die Sie als zweites Argument an Zeitextraktionsfunktionen übergeben können:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Parameter-Datentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Der Standardwert ist daher „GMT“.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6

Beispiel 2

In diesem Beispiel wird ein Stringliteral zur Definition von time_zone verwendet.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts, "America/Los_Angeles") = 6

timestamp.get_week

Unterstützt in:

Regeln Suchen

timestamp.get_week(unix_seconds [, time_zone])

Beschreibung

Diese Funktion gibt eine Ganzzahl im Bereich [0, 53] für die Woche des Jahres zurück. Wochen beginnen mit Sonntag. Termine vor dem ersten Sonntag des Jahres sind in Woche 0.

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden nach der Unix-Epoche (z. B. $e.metadata.event_timestamp.seconds) oder einen Platzhalter mit diesem Wert darstellt.
• time_zone ist optional und ist ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, wird der Standardwert „GMT“ verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie auf dieser Seite in der Spalte „Name der TZ-Datenbank“.
  • Der Zeitzonenunterschied zu UTC im Format (+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige time_zone-Spezifizierer, die Sie als zweites Argument an Funktionen zur Zeitextraktion übergeben können:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Parameter-Datentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Der Standardwert ist daher „GMT“.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0

Beispiel 2

In diesem Beispiel wird ein Stringliteral zur Definition von time_zone verwendet.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts, "America/Los_Angeles") = 0

Zuweisung von Funktion zu Platzhaltern

Sie können das Ergebnis eines Funktionsaufrufs einem Platzhalter im Abschnitt events zuweisen. Beispiel:

$placeholder = strings.concat($e.principal.hostname, "my-string").

Anschließend können Sie die Platzhaltervariablen in den Abschnitten match, condition und outcome verwenden. Es gibt jedoch zwei Einschränkungen bei der Funktion für die Platzhalterzuweisung:

1. Jeder Platzhalter in der Zuweisung von Funktion zu Platzhalter muss einem Ausdruck zugewiesen werden, der ein Ereignisfeld enthält. Die folgenden Beispiele sind gültig:

   $ph1 = $e.principal.hostname
   $ph2 = $e.src.hostname
   
   // Both $ph1 and $ph2 have been assigned to an expression containing an event field.
   $ph1 = strings.concat($ph2, ".com")
   

   $ph1 = $e.network.email.from
   $ph2 = strings.concat($e.principal.hostname, "@gmail.com")
   
   // Both $ph1 and $ph2 have been assigned to an expression containing an event field.
   $ph1 = strings.to_lower($ph2)
   

   Das folgende Beispiel ist jedoch ungültig:

   $ph1 = strings.concat($e.principal.hostname, "foo")
   $ph2 = strings.concat($ph1, "bar") // $ph2 has NOT been assigned to an expression containing an event field.
   

2. Der Funktionsaufruf sollte von einem und genau einem Ereignis abhängen. In Funktionsaufrufargumenten können jedoch mehrere Felder aus demselben Ereignis verwendet werden. Folgendes ist beispielsweise gültig:

   $ph = strings.concat($event.principal.hostname, "string2")

   $ph = strings.concat($event.principal.hostname, $event.src.hostname)

   Folgendes ist jedoch ungültig:

   $ph = strings.concat("string1", "string2")

   $ph = strings.concat($event.principal.hostname, $anotherEvent.src.hostname)

Syntax von Referenzlisten

Weitere Informationen zur Funktionsweise von Referenzlisten und zur Syntax von Referenzlisten finden Sie auf der Seite zu Referenzlisten.

Du kannst Referenzlisten in den Abschnitten events und outcome verwenden. Hier ist die Syntax für die Verwendung verschiedener Arten von Referenzlisten in einer Regel:

// STRING reference list
$e.principal.hostname in %string_reference_list

// REGEX reference list
$e.principal.hostname in regex %regex_reference_list

// CIDR reference list
$e.principal.ip in cidr %cidr_reference_list

Sie können auch den Operator not und den Operator nocase mit Referenzlisten verwenden, wie im folgenden Beispiel gezeigt:

// Exclude events whose hostnames match substrings in my_regex_list.
not $e.principal.hostname in regex %my_regex_list

// Event hostnames must match at least 1 string in my_string_list (case insensitive).
$e.principal.hostname in %my_string_list nocase

Der Operator nocase ist mit STRING- und REGEX-Listen kompatibel.

Aus Leistungsgründen schränkt die Detection Engine die Verwendung von Referenzlisten ein.

• Maximale in-Anweisungen in einer Regel mit oder ohne spezielle Operatoren: 7
• Maximale in-Anweisungen mit dem regex-Operator: 4
• Maximale in-Anweisungen mit dem cidr-Operator: 2

Typprüfung

Google Security Operations führt beim Erstellen von Regeln innerhalb der Benutzeroberfläche eine Typprüfung anhand Ihrer YARA-L-Syntax durch. Die angezeigten Fehler bei der Typprüfung helfen Ihnen dabei, die Regel so zu überarbeiten, dass sie wie erwartet funktioniert.

Beispiele für ungültige Prädikate:

// $e.target.port is of type integer which cannot be compared to a string.
$e.target.port = "80"

// "LOGIN" is not a valid event_type enum value.
$e.metadata.event_type = "LOGIN"

Erfassung von Erkennungsereignissen

Erkennungen durch Mehrfachereignisregeln enthalten Ereignisbeispiele, die Kontext zu den Ereignissen liefern, die die Erkennung ausgelöst haben. Für jede in der Regel definierte Ereignisvariable sind maximal zehn Ereignisproben zulässig. Wenn durch eine Regel beispielsweise 2 Ereignisvariablen definiert werden, kann jede Erkennung bis zu 20 Ereignisstichproben umfassen. Das Limit gilt für jede Ereignisvariable separat. Wenn eine Ereignisvariable zwei anwendbare Ereignisse bei dieser Erkennung und die andere 15 anwendbare Ereignisse umfasst, umfasst die resultierende Erkennung 12 Ereignisstichproben (2 + 10).

Ereignisstichproben, die das Limit überschreiten, werden bei der Erkennung nicht berücksichtigt.

Wenn Sie weitere Informationen zu den Ereignissen benötigen, die Ihre Erkennung ausgelöst haben, können Sie im Ergebnisbereich Aggregationen verwenden, um zusätzliche Informationen zur Erkennung auszugeben.

Wenn Sie Erkennungen in der UI ansehen, können Sie alle Ereignisbeispiele herunterladen, um sie zu erkennen. Weitere Informationen finden Sie unter Ereignisse herunterladen.