YARA-L 2.0-Sprachsyntax

In diesem Abschnitt werden die wichtigsten Elemente der YARA-L-Syntax beschrieben. Siehe auch Übersicht ü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 dargestellt:

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 Metaabschnitts

Der Meta-Abschnitt besteht aus mehreren Zeilen, wobei jede Zeile ein Schlüssel/Wert-Paar 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
• Joins für Ereignisvariablen

Variablendeklarationen

Verwenden Sie für Variablendeklarationen die folgende Syntax:

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

Beide sind äquivalent, 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 Übereinstimmungsvariable einen beliebigen Wert im Array darstellen. Es ist auch möglich, einer einzigen Abgleich- oder Platzhaltervariablen mehrere Ereignisfelder zuzuweisen. Dies ist eine transitive Join-Bedingung.

Beispiel:

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

entsprechen:

• $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, gilt sie als Kompilierungsfehler.

Filter für Ereignisvariablen

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

Joins für 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 Ereignisfeldern der beiden verknüpften Ereignisvariablen, z. B. $e1.field = $e2.field. Der Ausdruck darf keine Arithmetik enthalten.

• Indirekt durch einen transitiven Join, der nur ein Ereignisfeld umfasst. Eine Definition des Begriffs „transitiver Join“ finden Sie unter Variablendeklaration. Der Ausdruck darf keine Arithmetik enthalten.

Wenn beispielsweise $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 für den 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 für Übereinstimmungsbereich

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

• Geben Sie im Abschnitt events an, wofür jede Übereinstimmungsvariable steht.
• Geben Sie die Zeitdauer an, die für die Korrelation von Ereignissen nach dem Schlüsselwort over verwendet werden soll. Ereignisse außerhalb der Zeitdauer werden ignoriert.

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

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

• Die angegebene Mindestzeit beträgt 1 Minute.

• Sie können maximal 48 Stunden angeben.

Das folgende Beispiel zeigt eine gültige 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, stehen nicht in Beziehung und werden daher von der Regel ignoriert.

Hier 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. Ereignisse, die mehr als eine Stunde auseinanderliegen, stehen nicht zur Verfügung. Die Regel betrachtet sie nicht als Erkennung.

Hier 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. Ereignisse, die mehr als zwei Minuten auseinanderliegen, stehen nicht zur Verfügung. Die Regel betrachtet sie nicht als Erkennung.

Die folgenden Beispiele veranschaulichen ungültige match-Abschnitte:

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

Umgang mit Nullwerten im Übereinstimmungsbereich

Rules Engine filtert implizit die Nullwerte für alle Platzhalter, die im Übereinstimmungsbereich 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 zeigt 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, filtern Regeln die Nullwerte von Platzhaltern, die im Übereinstimmungsbereich verwendet werden, nicht implizit heraus. Das folgende Beispiel zeigt 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
}

Wenn Sie das implizite Filtern von Nullwerten deaktivieren möchten, 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 einen Satz sich überschneidender Hop-Fenster unterteilt, wobei jedes Fenster die im Abschnitt match angegebene Dauer hat. Die Ereignisse werden dann in jedem Hop-Fenster korreliert.

Beispiel: Für eine Regel, die im Zeitraum [1:00, 2:00] mit einem match-Abschnitt über 30m ausgeführt wird, könnte ein möglicher Satz von überlappenden Hop-Fenstern [1:00, 1:30], [1:03, 1:33] und [1:06, 1:36] generiert werden. Diese Fenster werden verwendet, um mehrere Ereignisse in Beziehung zu setzen.

Schiebefenster

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

Eine effektivere Methode, um 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 in jedem gleitenden Fenster korreliert. So kann nach Ereignissen in einer bestimmten Reihenfolge gesucht werden (z. B. tritt e1 innerhalb von 2 Minuten nach e2 auf). Das Ereignis e1 und das Ereignis e2 werden korreliert, wenn das Ereignis e1 innerhalb der gleitenden Fensterdauer nach Ereignis e2 auftritt.

So geben Sie gleitende Fenster im Abschnitt match einer Regel an:

<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. Bei Verwendung des Schlüsselworts after werden gleitende Fenster mit jedem Auftreten des Pivot-Ereignisses generiert.

Im Folgenden finden Sie Beispiele für gültige gleitende Fenster:

• $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 erfahrungsgemäß zu einer langsameren Leistung. Google empfiehlt, gleitende Fenster nur in bestimmten Fällen zu verwenden, z. B. wenn die Ereignisreihenfolge unbedingt erforderlich ist oder wenn nach Ereignissen gesucht werden soll, die nicht vorhanden sind.

Google empfiehlt, bei Einzelereignisregeln keine gleitenden Fenster zu verwenden, da diese so konzipiert sind, dass mehrere Ereignisse erkannt werden. Wenn eine Ihrer Regeln in diese Kategorie fällt, empfiehlt Google eine der folgenden Problemumgehungen:

• Konvertieren Sie die Regel so, dass mehrere Ereignisvariablen verwendet werden, und aktualisieren Sie den Abschnitt mit den Bedingungen, wenn die Regel das Ereignis mehrmals erfordert.
  • Optional können Sie Zeitstempelfilter hinzufügen, anstatt ein gleitendes Fenster zu verwenden. Beispiel: $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
• Entferne das Schiebefenster.

Syntax des Ergebnisabschnitts

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 etwas ganz Besonderes. Sie können optional ein Ergebnis mit diesem Namen definieren. Wenn Sie sich dafür entscheiden, muss es vom Typ "Integer" oder "Float" sein. Wenn das Feld risk_score ausgefüllt ist, wird es in der Enterprise Insights-Ansicht für Benachrichtigungen angezeigt, die von der Regelerkennung stammen.

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

• Wenn die Regel so konfiguriert ist, 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, der für die Berechnung verwendet wird. Die folgenden Ergebnisdatentypen werden unterstützt:

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

Bedingte Logik

Sie können bedingte Logik verwenden, um den Wert eines Ergebnisses zu berechnen. Bedingungen werden mit 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, sonst ELSE_CLAUSE zurückgeben“.

BOOL_CLAUSE muss einen booleschen Wert ergeben. Ein BOOL_CLAUSE-Ausdruck hat eine ähnliche Form wie Ausdrücke im Abschnitt events. Sie 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 andere Ergebnisvariable, die im Abschnitt outcome definiert ist, z. B.:

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

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

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

• in einer Referenzliste nachschlagen. Beispiel:

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

• Aggregationsvergleich, z. B.:

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

THEN_CLAUSE und ELSE_CLAUSE müssen vom selben Datentyp sein. Wir unterstützen Ganzzahlen, Gleitkommazahlen und Strings.

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

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

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

Mathematische Operationen

Sie können mathematische Operationen verwenden, um den Datentyp "Ganzzahl" oder "Gleitkommazahl" in den Abschnitten outcome und events einer Regel zu berechnen. Google Security Operations unterstützt Addition, Subtraktion, Multiplikation, Division und Modulus als Top-Level-Operatoren 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, solange jeder Operand und der gesamte arithmetische Ausdruck ordnungsgemäß aggregiert wurden (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 bei Gleitkommazahlen nicht zulässig.

Platzhaltervariablen in Ergebnissen

Beim Berechnen von Ergebnisvariablen können Sie Platzhaltervariablen verwenden, die im Ereignisbereich Ihrer Regel definiert wurden. In diesem Beispiel wird davon ausgegangen, dass $email_sent_bytes im Ereignisbereich der Regel definiert wurde:

Beispiel für ein einzelnes Ereignis:

// 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 mit mehreren Ereignissen:

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 Platzhaltervariablen, die im Abschnitt events definiert wurden. Sie können sich in der Zuweisung einer weiteren Ergebnisvariablen auf eine Ergebnisvariable mit einem $-Token beziehen, gefolgt vom Variablennamen. Ergebnisvariablen müssen definiert werden, bevor im Regeltext auf sie verwiesen werden kann. Bei der Verwendung in einem Zuweisungsausdruck dürfen Ergebnisvariablen nicht aggregiert werden (siehe Aggregationen).

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

Beispiel mit mehreren Ereignissen:

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 jedem Ausdruckstyp auf der rechten Seite einer Ergebniszuweisung verwendet werden, mit Ausnahme der folgenden Ausdrücke:

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

Zusammenfassungen

Wiederkehrende Ereignisfelder sind nicht skalare Werte. Eine Variable verweist also auf mehrere Werte. Beispielsweise ist die Ereignisfeldvariable $e.target.ip ein wiederkehrendes Feld und kann null, einen oder viele IP-Werte haben. Es handelt sich um einen nicht skalaren Wert. Die Ereignisfeldvariable $e.principal.hostname hingegen ist kein wiederkehrendes Feld und hat nur einen Wert (d.h. einen skalaren Wert).

In ähnlicher Weise 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 Übereinstimmungsbereichs und verweist im Ergebnisbereich auf ein nicht wiederkehrendes Ereignisfeld:

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

Jedes 5-Minuten-Fenster, für das die Regel ausgeführt wird, kann null, ein oder viele Ereignisse enthalten. Der Ergebnisabschnitt bezieht sich auf alle Ereignisse in einem Übereinstimmungsfenster. Jede Ereignisfeldvariable, auf die im Ergebnisabschnitt verwiesen wird, kann für jedes Ereignis im Übereinstimmungsfenster auf null, einen oder viele Werte des Feldes verweisen. Wenn in der vorherigen Regel ein 5-Minuten-Fenster 5 $e-Ereignisse enthält, verweist $e.principal.hostname im Ergebnisbereich auf 5 verschiedene Hostnamen. Die Ereignisfeldvariable $e.principal.hostname ist somit ein nicht skalarer Wert im Ergebnisbereich dieser Regel.

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

• Ereignisfelder (wiederkehrend oder nicht wiederholt), wenn die Regel einen Übereinstimmungsbereich verwendet
• Ereignisplatzhalter (wiederholt oder nicht wiederholt), wenn die Regel einen Übereinstimmungsbereich verwendet
• Felder für wiederkehrende Ereignisse, wenn für die Regel kein Übereinstimmungsbereich verwendet wird
• Platzhalter für wiederkehrende Ereignisse, wenn für die Regel kein Übereinstimmungsbereich verwendet wird

Skalare Ereignisfelder, Platzhalter für skalare Ereignisse und Konstanten können in einer Aggregation in einer Regel ohne Übereinstimmungsbereich zusammengefasst werden. Die meisten Aggregationen ergeben jedoch den umschlossenen Wert und sind daher nicht erforderlich. Eine Ausnahme ist die array()-Aggregation, mit der ein skalarer Wert in ein Array umgewandelt werden kann.

Ergebnisvariablen werden wie Aggregationen behandelt: Sie dürfen nicht erneut aggregiert werden, wenn sie in einer anderen Ergebniszuweisung referenziert werden.

Sie können die folgenden Aggregationsfunktionen verwenden:

• max(): gibt den Maximalwert für alle möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.
• min(): gibt den Mindestwert für alle möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.
• sum(): Gibt die Summe für 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 zufällige Elemente gekürzt.

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

Angenommen, die Abschnitte outcome und condition enthalten Folgendes:

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 für den Bedingungsabschnitt mehr als ein event für jede Erkennung erforderlich ist, werden die Aggregatfunktionen auf mehrere Ereignisse angewendet. 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 sind die Werte Ihrer Ergebnisse:

• $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"]

Beachten Sie bei der Verwendung des Ergebnisabschnitts Folgendes:

Weitere Hinweise und Einschränkungen:

• Der Abschnitt outcome darf nicht auf eine neue Platzhaltervariable verweisen, die nicht bereits im Abschnitt events oder outcome definiert wurde.
• Im Bereich outcome können keine Ereignisvariablen verwendet werden, die nicht im Bereich events definiert wurden.
• Für den Abschnitt outcome kann ein Ereignisfeld verwendet werden, das im Abschnitt events nicht verwendet wurde. Voraussetzung dafür ist, dass die Ereignisvariable, zu der das Ereignisfeld gehört, bereits im Abschnitt events definiert wurde.
• Im Abschnitt outcome können nur Ereignisvariablen korreliert werden, die bereits im Abschnitt events korreliert wurden. Korrelationen treten auf, wenn zwei Ereignisfelder aus verschiedenen Ereignisvariablen gleichgesetzt werden.

Ein Beispiel finden Sie im Ergebnisabschnitt unter YARA-L 2.0 – Übersicht. Weitere Informationen zum Deduplizieren der Erkennung mit dem Ergebnisabschnitt finden Sie unter Kontextsensitive Analysen erstellen.

Syntax des Bedingungsabschnitts

• eine Übereinstimmungsbedingung für Ereignisse und Platzhalter angeben, die im Bereich events definiert sind. Weitere Informationen finden Sie unten im Abschnitt Bedingungen für Ereignisse und Platzhalter.
• (Optional) Verwenden Sie das Keyword and, um eine Übereinstimmungsbedingung mithilfe von Ergebnisvariablen anzugeben, die im Abschnitt outcome definiert sind. Weitere Informationen finden Sie im folgenden Abschnitt Ergebnisbedingungen.

Anzahl Zeichen

Das Zeichen # ist ein Sonderzeichen im Abschnitt condition. Wird es vor einem Ereignis- oder Platzhaltervariablennamen verwendet, stellt es die Anzahl der einzelnen Ereignisse oder Werte dar, die alle Bedingungen des Abschnitts events erfüllen.

Zum Beispiel bedeutet #c > 1, dass die Variable c öfter als einmal auftreten muss.

Wertzeichen

Das Zeichen $ ist ein Sonderzeichen im Abschnitt condition. Wenn sie vor einem Ergebnisvariablennamen verwendet wird, stellt sie den Wert dieses Ergebnisses dar.

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

Ereignis- und Platzhalterbedingungen

Listen Sie hier Bedingungsprädikate für Ereignisse und Platzhaltervariablen auf, die mit dem Keyword and oder or verbunden sind. Das Keyword and kann zwischen allen Bedingungen verwendet werden, das Keyword or kann jedoch 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 das Vorhandensein der zugehörigen Ereignisvariablen, was bedeutet, dass mindestens ein Ereignis des Ereignisses in einer Erkennung angezeigt werden 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 es möglich ist, dass das Ereignis in einer Erkennung nicht vorkommt und jeder Verweis auf Felder in der Ereignisvariablen den Wert Null ergibt. Unbegrenzte Bedingungen können verwendet werden, um das Fehlen eines Ereignisses über einen bestimmten Zeitraum zu erkennen. Beispiel: ein Bedrohungsereignis ohne ein solches Ereignis innerhalb eines Zeitfensters von 10 Minuten. Regeln, die unbegrenzte Bedingungen verwenden, werden als nicht vorhandene Regeln 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 das Erkennungsmodul eine Verzögerung von einer Stunde zur erwarteten Latenz hinzu (basierend auf der Ausführungshäufigkeit der Regel), um spät ankommende Daten zu berücksichtigen.

Anforderungen für Nicht-existenz

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

1. Mindestens ein UDM-Ereignis muss eine begrenzte Bedingung haben. Es muss also mindestens ein UDM-Ereignis vorhanden sein.
2. Wenn ein Platzhalter eine unbegrenzte Bedingung hat, muss er mindestens einem begrenzten UDM-Ereignis zugeordnet werden.
3. Wenn eine Entität eine unbegrenzte Bedingung hat, muss sie mindestens einem begrenzten UDM-Ereignis zugeordnet sein.

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 <condition_section>:

• $u1 and !$u2 and $e1 and $e2
  • Alle UDM-Ereignisse und -Entitäten sind im Bereich „Bedingung“ vorhanden.
  • Mindestens ein UDM-Ereignis ist begrenzt.
• $u1 and !$u2 and $e1 and !$e2
  • $e2 ist unbegrenzt. Dies ist zulässig, da es der begrenzten $u1 zugeordnet ist. Wenn $e2 nicht mit $u1 verknüpft wäre, wäre dies ungültig.
• #port > 50 and #ip = 0
  • Der Bereich „Bedingung“ enthält keine UDM-Ereignisse und ‐Entitäten. Die vorhandenen Platzhalter decken jedoch alle UDM-Ereignisse und ‐Entitäten ab.
  • $ip ist sowohl $u1 als auch $u2 zugewiesen, und #ip = 0 ist eine unbegrenzte Bedingung. Begrenzte Bedingungen sind jedoch stärker als unbegrenzte Bedingungen. Da $port $u1 zugewiesen ist und #port > 50 eine begrenzte Bedingung ist, ist $u1 weiterhin begrenzt.

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

• $u1 and $e1
  • Jedes UDM-Ereignis und jede Entität, die im Abschnitt „Ereignisse“ angezeigt wird, muss im Abschnitt „Bedingung“ aufgeführt sein. Sie können ihm auch einen Platzhalter zuweisen, der im Bereich „Bedingung“ angezeigt wird.
• $u1, $u2, $e1, $u2, #port > 50
  • Kommas sind als Bedingungstrennzeichen 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 zwischen verschiedenen Ereignisvariablen nicht unterstützt.
• not $u1 and $u2 and $e1 and $e2
  • Das Keyword „not“ 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, sodass die Regel nicht kompiliert werden kann.

Hinweis :Verwenden Sie im Abschnitt condition keine Variable match. Es handelt sich um einen semantischen Fehler, da Ereignisse nach dem Wert der match-Variable gruppiert werden.

Hinweis: Geben Sie nicht nur unbegrenzte Bedingungen für alle event-Variablen an, denen eine match-Variable zugewiesen ist. 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: Bei Verwendung eines gleitenden Fensters muss die Pivot-Ereignisvariable an mindestens einer begrenzten Bedingung beteiligt sein.

Bedingungen für Ergebnisse

Listen Sie Bedingungsprädikate für Ergebnisvariablen hier auf, die mit dem Keyword and oder or verbunden sind oder dem Keyword not vorangestellt sind.

Geben Sie Ergebnisbedingungen je nach Typ der Ergebnisvariablen unterschiedlich an:

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

  $risk_score > 10

• float: Vergleich mit einem Float-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 Keyword 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 Ergebnisbedingung in einer Regel mit einem Übereinstimmungsbereich angeben, wird die Regel für das Regelkontingent als Multi-Ereignis-Regel klassifiziert. Weitere Informationen finden Sie unter Regel für einzelne Ereignisse und Regel für mehrere Ereignisse.

Syntax des Optionsabschnitts

Im Abschnitt options können Sie die Optionen für die Regel angeben. Hier ist 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. Durch sie wird bestimmt, ob diese Option aktiviert ist oder nicht. Der Standardwert ist false. Diese Option ist deaktiviert, wenn sie nicht in der Regel angegeben ist.

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

Boolesche Ausdrücke

Boolesche Ausdrücke sind Ausdrücke eines booleschen Typs.

Vergleiche

Verwenden Sie die folgende Syntax, um einen binären Ausdruck als Bedingung zu verwenden:

• <EXPR> <OP> <EXPR>

Der Ausdruck kann entweder 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, gilt das als Kompilierungsfehler.

Funktionen

Einige Funktionsausdrücke geben einen booleschen Wert zurück, der als einzelnes Prädikat im Abschnitt events verwendet werden kann. Zu diesen Funktionen gehören:

• 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 Bereich „Ereignisse“ 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.

Zum Beispiel 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 and-Operator verknüpft, wenn kein Operator explizit definiert ist.

Die Reihenfolge der Auswertung kann unterschiedlich sein, wenn der and-Operator im Ausdruck impliziert wird.

Betrachten Sie beispielsweise die folgenden Vergleichsausdrücke, bei denen or explizit definiert ist. Der Operator and wird 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, die or umgeben, zuerst gruppiert und ausgewertet. Das letzte Prädikat $e2.field = "bar" wird implizit mit and verknüpft. Das Ergebnis ist, dass sich die Reihenfolge der Bewertungen ändert.

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. Weitere Informationen zu Alternativen zu diesem Regeltyp erhalten Sie von Ihrem Google Security Operations-Ansprechpartner.

Aufgezählte Typen

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

Im folgenden Beispiel entsprechen 'USER_UNCATEGORIZED' und 'USER_RESOURCE_DELETION' dem Wert 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 am Ende des Ausdrucks nocase anhängen, um die Großschreibung 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

Diese Option kann nicht verwendet werden, wenn der Feldtyp ein Aufzählungswert ist. Die folgenden Beispiele sind ungültig und verursachen Kompilierungsfehler:

• $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 hindeutet, dass es sich um Listen von Werten oder andere Arten von Nachrichten 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

Sehen Sie sich folgendes Ereignis an:

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 wird der Zweck und die Verwendung der Modifikatoren any und all in Ausdrücken beschrieben.

Beliebig

Wenn ein beliebiges Element des wiederkehrenden 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 wiederkehrenden 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. Beispielsweise ist re.regex(any $e.about.hostname, `server-[0-9]+`) gültig, any re.regex($e.about.hostname, `server-[0-9]+`) jedoch nicht.

Beachten Sie beim Schreiben einer Bedingung mit any oder all, dass das Negieren der Bedingung mit not möglicherweise nicht dieselbe 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 bedeutet, 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 kompatibel (nicht mit skalaren Feldern).
• any und all können nicht verwendet werden, um zwei wiederkehrende Felder zu verbinden. any $e1.principal.ip = $e2.principal.ip ist beispielsweise ungültig.
• Die Operatoren any und all werden für den Ausdruck mit der Referenzliste nicht unterstützt.

Unveränderte Ausdrücke

Bei unveränderten Ausdrücken wird jedes Element im wiederkehrenden 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 wiederkehrenden 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 für das wiederkehrende Feld erfüllt, erfüllt das Ereignis als Ganzes alle Bedingungen. Wenn also für ein wiederkehrendes Feld mehrere Bedingungen vorliegen, muss die Ereigniskopie alle Bedingungen erfüllen. In den folgenden Regelbeispielen wird dieses Verhalten anhand des vorherigen Beispiel-Datasets veranschaulicht.

Die folgende Regel gibt bei der Ausführung für das Beispiel-Dataset event_original eine Übereinstimmung zurück, 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 für wiederkehrende Felder kompatibel, da die Elementliste für jede Ereigniskopie identisch ist. Betrachten 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	beliebige $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". Infolgedessen würde das Ereignis als Ganzes übereinstimmen.

Anders ausgedrückt:

• Ausdrücke in wiederkehrenden Feldern, die any oder all verwenden, werden auf die Liste in event_original angewendet.
• Ausdrücke in wiederkehrenden Feldern, die weder any noch all enthalten, werden auf einzelne event_copy_n-Ereignisse angewendet.

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. Im selben Beispiel für event_copy verwendet der Platzhalter für jede Ereigniskopie den Wert des wiederkehrenden Feldwerts von event_copy_n, wobei n die Ereigniskopie-Nummer 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 entspricht 192.0.2.1 für event_copy_1, was die Prädikate in der Regel erfüllt. Die Ereignisbeispiele für die Übereinstimmung enthalten nur das 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 jedes der verschiedenen event_copy_n-Kopien verschiedene Werte. Die Gruppierung erfolgt am $ip, da es sich im Bereich „Übereinstimmung“ befindet. Daher erhalten Sie drei Übereinstimmungen, bei denen jede Übereinstimmung einen anderen Wert für die $ip-Übereinstimmungsvariable hat. Jede Übereinstimmung hat dasselbe Ereignisbeispiel: ein einzelnes 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 ein wiederkehrendes Feld einer Platzhaltervariablen zugewiesen oder mit dem Feld eines anderen Ereignisses zusammengeführt wird. 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 Ergebnisabschnitt verwendet werden, wird das Ergebnis nur mit den Elementen berechnet, die den vorherigen Abschnitten entsprechen.

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

Die Ausführung dieser Regel erfolgt in vier Phasen. 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 mit den Filtern übereinstimmen:

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 wird herausgefiltert, weil "192.0.2.3" nicht die Kriterien für $ip = "192.0.2.1" or $ip = "192.0.2.2" erfüllt.

Im Übereinstimmungsbereich wird 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 mit $ip aus der vorherigen Phase und nicht mit dem Kopiervorgang für das Ereignis berechnet.

Im Bereich „Condition“ (Bedingung) werden alle Gruppen gefiltert. Da diese Regel nur prüft, ob $e vorhanden ist, erzeugt die Zeile von zuvor eine einzelne Erkennung.

$o enthält nicht alle Elemente aus $e.principal.ip, weil nicht alle Elemente alle Bedingungen im Ereignisbereich erfüllen. Es werden jedoch alle Elemente von e.principal.ip im Ereignisbeispiel angezeigt, weil im Ereignisbeispiel event_original verwendet wird.

Array-Indexierung

Sie können für wiederkehrende Felder eine Array-Indexierung durchführen. Verwenden Sie die Standardlistensyntax, um auf das n-te wiederholte Feldelement zuzugreifen (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] = "" Wenn weniger als 1.000 Elemente vorhanden sind, wird true zurückgegeben.

Einschränkungen:

• Ein Index muss ein nicht negatives Ganzzahlliteral sein. $e.principal.ip[-1] ist beispielsweise ungültig.
• Werte vom Typ int (z. B. ein Platzhalter, der auf int gesetzt ist) 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 ungültig, da intermediary und ip wiederkehrende Felder sind, aber nur ein Index für ip vorhanden ist.

Wiederholte Nachrichten

Wenn sich ein message-Feld wiederholt, hat das eine unbeabsichtigte Auswirkung darin, die Wahrscheinlichkeit einer Übereinstimmung zu verringern. Dies wird in den folgenden Beispielen veranschaulicht.

Sehen Sie sich folgendes Ereignis an:

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 wiederkehrenden Felds eine temporäre Kopie des Ereignisses erstellt. Betrachten 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, da keine Ereigniskopie vorhanden ist, die allen Ausdrücken entspricht.

Wiederholte Nachrichten und Array-Indexierung

Ein weiteres unerwartetes Verhalten kann auftreten, wenn die Array-Indexierung mit unveränderten Ausdrücken für wiederkehrende Nachrichtenfelder verwendet wird. Betrachten Sie die folgende Beispielregel mit Array-Indexierung:

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 Regel repeated_message_1 keine Array-Indexierung hat und keine Übereinstimmungen erzeugt hat, während Regel repeated_message_2 die Array-Indexierung verwendet und eine Übereinstimmung erzeugt hat.

Kommentare

Wie bei C können Sie Kommentare mit zwei Schrägstrichen (// comment) oder mehrzeilige Kommentare mit einem Schrägstrich (/* comment */) kennzeichnen.

Literale

Nicht negative Ganzzahlen und Gleitkommazahlen, Strings, boolesche Ausdrücke und Literale für reguläre Ausdrücke werden unterstützt.

String- und reguläre Ausdruckliterale

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

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

2. Anführungszeichen (`): Wird verwendet, um alle Zeichen wortgetreu zu interpretieren.
   Beispiel: „hello\tworld“ —\t wird nicht als Tab interpretiert

Für reguläre Ausdrücke haben Sie zwei Möglichkeiten.

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

Wenn Sie die Funktion re.regex() nutzen, können Sie auch Stringliterale als Literale für reguläre Ausdrücke verwenden. Beachten Sie, dass Sie bei Stringliteralen mit doppelten Anführungszeichen umgekehrte Schrägstriche mit umgekehrten Schrägstrichen maskieren müssen. Dies kann umständlich aussehen.

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/

Google empfiehlt, für Strings in regulären Ausdrücken Anführungszeichen zu verwenden, um die Lesbarkeit zu verbessern.

Operatoren

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

Operator:	Beschreibung
=	Gleichheit/Deklaration
!=	Ungleich
<	ist kleiner als
<=	kleiner als 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). Wenn keine Quelle angegeben wird, wird udm als Standardquelle festgelegt. Ereignisfelder werden als Kette von .<field name> dargestellt (z. B. $e.field1.field2). Ereignisfeldketten beginnen immer bei der Quelle auf oberster Ebene (UDM oder Entität).

• Abgleichvariablen: Deklarieren Sie diese im Abschnitt match. Übereinstimmungsvariablen werden zu Gruppierungsfeldern für die Abfrage, da für jeden eindeutigen Satz von Übereinstimmungsvariablen (und für jedes Zeitfenster) eine Zeile zurückgegeben wird. Findet die Regel eine Übereinstimmung, werden die entsprechenden Variablenwerte zurückgegeben. Geben Sie im Abschnitt events an, wofür jede Übereinstimmungsvariable steht.

• Platzhaltervariablen: Deklarieren und definieren Sie diese im Abschnitt events. Platzhaltervariablen ähneln Abgleichvariablen. Sie können jedoch im Bereich condition Platzhaltervariablen verwenden, um Übereinstimmungsbedingungen anzugeben.

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

Verwenden Sie Übereinstimmungsvariablen und Platzhaltervariablen, um Beziehungen zwischen Ereignisfeldern über Transitive Join-Bedingungen zu deklarieren. Weitere Informationen finden Sie unter Syntax des Ereignisabschnitts.

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.minsumarrayarray_distinctcountcount_distinctisnull

Maps

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

Strukturen und Labels

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

Um sowohl in Struct als auch in Label 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

Abschnitt „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"])

Platzhalter einen Kartenwert zuweisen

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

Zuordnungsfeld 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 für 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

Die Kartensyntax kann nur einen Stringwert zurückgeben. Bei Struct-Datentypen kann die Kartensyntax nur auf Schlüssel zugreifen, deren Werte Strings sind. Der Zugriff auf Schlüssel, deren Werte andere primitive Typen wie Ganzzahlen sind, ist nicht möglich.

Umgang mit doppelten Werten

Beim Kartenzugriff wird immer ein einzelner Wert zurückgegeben. In dem ungewöhnlichen Grenzfall, dass der Kartenzugriff auf mehrere Werte verweisen kann, wird beim Kartenzugriff deterministisch der erste Wert zurückgegeben.

Das kann in folgenden Fällen passieren:

• Ein Label hat einen doppelten Schlüssel.

  Die Labelstruktur stellt eine Zuordnung dar, erzwingt jedoch nicht die Eindeutigkeit des Schlüssels. Konventionsgemäß sollte eine Zuordnung eindeutige Schlüssel haben. Daher rät Google Security Operations 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 enthalten, die denselben Schlüssel haben. 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 -Suchvorgängen verwenden können.

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

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

• events Abschnitt.
• BOOL_CLAUSE einer Bedingung im Ergebnisbereich.

arrays.length

Unterstützt in:

Regeln Suche

arrays.length(repeatedField)

Beschreibung

Gibt die Anzahl der wiederkehrenden Feldelemente zurück.

Parameterdatentypen

LIST

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

Gibt die Anzahl der wiederkehrenden Feldelemente zurück.

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

Beispiel 2

Befinden sich mehrere wiederkehrende Felder entlang des Pfads, wird die Gesamtzahl der wiederkehrenden 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 Eingabe-Bytestrings. Diese Funktion gibt einen vorzeichenlosen INT-Wert im Bereich [2, 0xFFFFFFFFFFFFFFFF] zurück.

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

Parameterdatentypen

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.

Bei der UDM-Suche werden gruppierte Felder verwendet, um in mehreren Feldern eines ähnlichen Typs zu suchen. Die Gruppenfunktion ähnelt gruppierten Feldern, mit der Ausnahme, dass Sie auswählen können, welche Felder gruppiert werden sollen, um eine Erkennung auszulösen. Sie können die Funktion group verwenden, um Informationen über eine bestimmte Entität (z. B. Hostnamen, IP-Adressen oder Nutzer-IDs) für verschiedene Substantivtypen zu erfassen.

Hinweis :Für die Suche können Sie gruppierte Felder im Bereich „Ereignisse“ verwenden, aber nicht in den Abschnitten „Übereinstimmung“ und „Ergebnis“.

Codebeispiele

Beispiel 1

Gruppieren Sie alle IP-Adressen und geben Sie die im gescannten Zeitraum am häufigsten verwendeten IP-Adressen in absteigender Reihenfolge 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 Suche

math.abs(numericExpression)

Beschreibung

Gibt den absoluten Wert eines Ganzzahl- oder Gleitkommaausdrucks zurück.

Parameterdatentypen

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) liegt, unabhängig davon, ob das Ereignis vor oder nach dem angegebenen Zeitpunkt stattgefunden hat. 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 Suche

math.log(numericExpression)

Beschreibung

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

Parameterdatentypen

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 einen Wert zurück, gerundet auf die nächste Ganzzahl oder auf die angegebene Anzahl von Dezimalstellen.

Parameterdatentypen

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 diese in Ihrer Regel verwenden, indem Sie im Ergebnisabschnitt metrics.functionName() verwenden.

Weitere Informationen finden Sie unter YARA-L-Messwerte.

net.ip_in_range_cidr

Unterstützt in:

Regeln Suche

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Beschreibung

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

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

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

Wenn Sie in einem IP-Adressbereich suchen möchten, geben Sie ein UDM-Feld ip und einen CIDR-Bereich (Classless Inter-Domain Routing) an. YARA-L kann sowohl einzelne als auch wiederkehrende IP-Adressfelder verarbeiten.

Parameterdatentypen

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 von IP-Adressen.

re.regex

Unterstützt in:

Regeln Suche

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

• Verwendung der YARA-L-Syntax – Bezieht sich auf Ereignisse. Im Folgenden finden Sie eine allgemeine Darstellung dieser Syntax:

  $e.field = /regex/
  

• Verwendung der YARA-L-Syntax: Eine 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. Es ist nicht erforderlich, .* am Anfang oder Ende des regulären Ausdrucks hinzuzufügen.

Notes

• Wenn Sie nach dem genauen String oder nur mit einem Präfix oder Suffix suchen möchten, fügen Sie in den regulären Ausdruck die Ankerzeichen ^ (Anfang) und $ (Ende) ein. Zum Beispiel stimmt /^full$/ 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 eine (?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 die Großschreibung bei der Suche ignoriert werden soll.

Parameterdatentypen

STRING, STRING

Parameterausdruckstypen

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 Suche

re.capture(stringText, regex)

Beschreibung

Erfasst (extrahiert) Daten aus einem String unter Verwendung des Musters für reguläre Ausdrücke, das im Argument angegeben ist.

Diese Funktion verwendet zwei Argumente:

• stringText: Ursprünglicher String, in dem gesucht werden soll
• regex: Der reguläre Ausdruck, der das Muster angibt, nach dem gesucht werden soll.

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.

Parameterdatentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Wenn in diesem Beispiel $e.principal.hostname "aaa1bbaa2" enthält, gilt Folgendes, 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 ohne Übereinstimmung weglassen, indem Sie den leeren String ausschließen. Dies ist besonders wichtig, wenn Sie re.capture() mit einer Ungleichung 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 Suche

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 Muster angibt, nach dem gesucht werden soll.
• 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 in replacementText Escape-Ziffern mit umgekehrten Schrägstrichen (\1 bis \9) verwenden, um Text einzufügen, der mit der entsprechenden Klammergruppe im Muster replaceRegex übereinstimmt. Mit \0 können Sie auf den gesamten übereinstimmenden Text verweisen.

Die Funktion ersetzt nicht überlappende Übereinstimmungen und priorisiert das erste gefundene Vorkommen. Beispielsweise gibt re.replace("banana", "ana", "111") den String „b111na“ zurück.

Parameterdatentypen

STRING, STRING und 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 Argument replacementText Ziffern mit umgekehrten Schrägstrichen verwendet, um auf Übereinstimmungen mit dem Muster replaceRegex 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 beim Umgang mit leeren Strings und re.replace() die folgenden Fälle:

Leeren 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

Diese Funktion bestimmt anhand einer deterministischen Stichprobenstrategie, ob ein Ereignis einbezogen werden soll. Diese Funktion gibt Folgendes zurück:

• true für einen Bruchteil der Eingabewerte, entspricht (rateNumerator / rateDenominator). Dies bedeutet, dass das Ereignis in die Stichprobe einbezogen werden soll.
• false gibt an, dass das Ereignis nicht in die Stichprobe aufgenommen werden soll.

Diese Funktion ist nützlich für Optimierungsszenarien, bei denen nur ein Teil der Ereignisse verarbeitet werden soll. Entspricht:

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Parameterdatentypen

• byteOrString: Ausdruck, der als BYTE oder STRING ausgewertet wird.
• 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 Suche

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.

Parameterdatentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

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

strings.coalesce

Unterstützt in:

Regeln Suche

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 Argumente Ereignisfelder sind, müssen die Attribute aus demselben Ereignis stammen.

Parameterdatentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Das folgende Beispiel enthält Stringvariablen als Argumente. Die Bedingung wird als "true" ausgewertet, wenn (1) $e.network.email.from gleich [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 IP-Adresse, die nicht null ist, aus Ereignis $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. Schließlich wird der String „Keine IP“ als Standardwert zurückgegeben, wenn die vorherigen ip-Felder nicht festgelegt sind.

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 dem Ereignis $e1 und dem Ereignis $e2 zusammenzuführen. Es wird ein Compiler-Fehler zurückgegeben, da die Argumente unterschiedliche Ereignisvariablen sind.

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

strings.concat

Unterstützt in:

Regeln Suche

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 Argumente Ereignisfelder sind, müssen die Attribute aus demselben Ereignis stammen.

Parameterdatentypen

STRING, FLOAT, INT

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Das folgende Beispiel enthält eine String- und eine Ganzzahlvariable als Argumente. Sowohl principal.hostname als auch principal.port stammen vom selben Ereignis $e und werden so verkettet, dass ein String zurückgegeben wird.

"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 Float-Literal als Argumente. Wenn Gleitkommazahlen als ganze Zahlen dargestellt werden, werden sie ohne Dezimalzeichen formatiert (z. B. wird 1, 0 als „1“ dargestellt). Darüber hinaus werden Gleitkommazahlen mit mehr als sechzehn Dezimalstellen 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 Gleitkommaliteral 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 Suche

strings.to_lower(stringText)

Beschreibung

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

Parameterdatentypen

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 Suche

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

Parameterdatentypen

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 Suche

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.

Parameterdatentypen

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 des Zeitunterschieds werden die aktuellen Unix-Sekunden subtrahiert und dann mit dem Operator „Größer als“ verglichen.

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

timestamp.get_date

Unterstützt in:

Regeln Suche

timestamp.get_date(unix_seconds [, time_zone])

Beschreibung

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

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

Im Folgenden finden Sie Beispiele für gültige Zeitzonenbezeichner, 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"

Parameterdatentypen

INT, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Standardmäßig wird „GMT“ verwendet.

$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 Suche

timestamp.get_minute(unix_seconds [, time_zone])

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden nach der Unix-Epoche darstellt, z. B. $e.metadata.event_timestamp.seconds oder ein Platzhalter mit diesem Wert.
• time_zone ist optional und ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, wird standardmäßig "GMT" verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der TZ-Datenbankname, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte „TZ-Datenbankname“ auf dieser Seite.
  • Die Zeitzonenverschiebung gegenüber 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 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"

Parameterdatentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Standardmäßig wird „GMT“ verwendet.

$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 Suche

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 darstellt, z. B. $e.metadata.event_timestamp.seconds oder ein Platzhalter mit diesem Wert.
• time_zone ist optional und ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, wird die Standardeinstellung "GMT" verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der TZ-Datenbankname, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte „TZ-Datenbankname“ auf dieser Seite.
  • Die Zeitzonenverschiebung gegenüber 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 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"

Parameterdatentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Standardmäßig wird „GMT“ verwendet.

$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 Suche

timestamp.get_day_of_week(unix_seconds [, time_zone])

Beschreibung

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

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

Im Folgenden finden Sie Beispiele für gültige Zeitzonenbezeichner, 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"

Parameterdatentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Standardmäßig wird „GMT“ verwendet.

$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_timestamp

Unterstützt in:

Regeln Suche

timestamp.get_timestamp(unix_seconds, optional timestamp_format, optional timezone)

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden nach der Unix-Epoche darstellt, z. B. $e.metadata.event_timestamp.seconds oder ein Platzhalter mit diesem Wert.
• timestamp_format ist optional und ein String, der das Format für den Zeitstempel darstellt. Wenn keine Angabe gemacht wird, lautet der Standardwert %F %T. Sie können das Format mithilfe von Stringliteralen angeben. Informationen zu Optionen finden Sie unter Formatelemente für Datums- und Uhrzeitangaben.
• time_zone ist optional und 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 IANA-Zeitzone (TZ), z. B. America/Los_Angeles. Weitere Informationen finden Sie in der Liste der Zeitzonen in der tz-Datenbank auf Wikipedia.
  • Die Zeitzonenverschiebung gegenüber 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 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"

Parameterdatentypen

INT, STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts) = "2024-02-22 10:43:51"

Beispiel 2

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%F %T", "America/Los_Angeles") = "2024-02-22 10:43:51"

Beispiel 3

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%Y-%m", "GMT") = "2024-02"

timestamp.get_week

Unterstützt in:

Regeln Suche

timestamp.get_week(unix_seconds [, time_zone])

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden nach der Unix-Epoche darstellt, z. B. $e.metadata.event_timestamp.seconds oder ein Platzhalter mit diesem Wert.
• time_zone ist optional und ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, wird die Standardeinstellung "GMT" verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der TZ-Datenbankname, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte „TZ-Datenbankname“ auf dieser Seite.
  • Die Zeitzonenverschiebung gegenüber 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 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"

Parameterdatentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Standardmäßig wird „GMT“ verwendet.

$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 Platzhalter

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

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

Sie können dann die Platzhaltervariablen in den Bereichen match, condition und outcome verwenden. Es gibt jedoch zwei Einschränkungen in Bezug auf die Zuweisung von Funktionen zu Platzhaltern:

1. Jeder Platzhalter in einer Funktion zur Platzhalterzuweisung muss einem Ausdruck zugewiesen werden, der ein Ereignisfeld enthält. Hier einige Beispiele:

   $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. Es kann jedoch mehr als ein Feld aus demselben Ereignis in Argumenten von Funktionsaufrufen 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 zum Verhalten von Referenzlisten und zur Syntax von Referenzlisten finden Sie auf unserer 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 die Operatoren not und 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 eine Typprüfung anhand Ihrer YARA-L-Syntax durch, während Sie Regeln in der Benutzeroberfläche erstellen. Die angezeigten Fehler bei der Typprüfung helfen Ihnen, 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"

Stichprobenerhebung für Erkennungsereignisse

Erkennungen aus Multi-Ereignisregeln enthalten Ereignisbeispiele, um Kontext zu den Ereignissen bereitzustellen, die die Erkennung ausgelöst haben. Für jede in der Regel definierte Ereignisvariable sind maximal zehn Ereignisbeispiele zulässig. Wenn in einer Regel beispielsweise 2 Ereignisvariablen definiert werden, kann jede Erkennung bis zu 20 Ereignisstichproben enthalten. Das Limit gilt für jede Ereignisvariable separat. Wenn eine Ereignisvariable zwei anwendbare Ereignisse in dieser Erkennung und die andere 15 entsprechende Ereignisse enthält, enthält die resultierende Erkennung 12 Ereignisbeispiele (2 + 10).

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

Wenn Sie weitere Informationen zu den Ereignissen benötigen, die zu Ihrer Erkennung geführt haben, können Sie Aggregationen im Ergebnisbereich verwenden, um zusätzliche Informationen für die Erkennung auszugeben.

Wenn Sie Erkennungen in der UI ansehen, können Sie alle Ereignisbeispiele für eine Erkennung herunterladen. Weitere Informationen finden Sie unter Ereignisse herunterladen.