YARA-L 2.0-Sprachsyntax

In diesem Abschnitt werden die wichtigsten Elemente der YARA-L-Syntax beschrieben. Weitere Informationen finden Sie unter Übersicht über die Sprache YARA-L 2.0.

Regelstruktur

Bei YARA-L 2.0 müssen Sie Variablendeklarationen, ‑definitionen und ‑verwendungen in der folgenden Reihenfolge angeben:

1. Meta
2. ansehen
3. match (optional)
4. Ergebnis (optional)
5. Bedingung
6. Optionen (optional)

Das folgende Beispiel veranschaulicht die allgemeine Struktur einer Regel:

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

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

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

  outcome:
    // Additional information extracted from each detection.

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

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

Syntax des Meta-Abschnitts

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 mit Anführungszeichen sein:

<key> = "<value>"

Hier ein Beispiel für eine gültige meta-Abschnittszeile:

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

Syntax für den Bereich „Ereignisse“

Listen Sie im Abschnitt events die Bedingungen auf, um Folgendes anzugeben:

• Variablendeklarationen
• Filter für Ereignisvariablen
• Verknüpfungen von Ereignisvariablen

Variablendeklarationen

Verwenden Sie für Variablendeklarationen die folgende Syntax:

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

Beide sind gleichwertig, wie die folgenden Beispiele zeigen:

• $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 wiederholtes Feld ist, kann die Abgleichsvariable einen beliebigen Wert im Array darstellen. Es ist auch möglich, einer einzelnen Abgleichs- 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. Wenn eine Variable ohne Deklaration verwendet wird, gilt dies als Kompilierungsfehler.

Filter für Ereignisvariablen

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

Verknüpfungen von Ereignisvariablen

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

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

• Indirekt über einen transitiven Join, der nur ein Ereignisfeld umfasst (siehe Variablendeklaration für eine Definition von „transitiv“). 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

Hier sind jedoch Beispiele für ungültige events-Abschnitte.

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

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

events:
  $e1.src.port = $port

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

Syntax des Abschnitts zum Abgleich

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

• Geben Sie im Abschnitt events an, wofür die einzelnen Abgleichsvariablen stehen.
• Geben Sie die Zeitdauer an, die zum Korrelieren von Ereignissen nach dem Schlüsselwort over verwendet werden soll. Ereignisse außerhalb des Zeitraums werden ignoriert.

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

  Dabei stehen m/h/d für Minuten, Stunden und Tage.

• Die Mindestzeit, die Sie angeben können, beträgt 1 Minute.

• Die maximale Zeit, die Sie angeben können, beträgt 48 Stunden.

Das folgende Beispiel zeigt ein gültiges match-Objekt:

$var1, $var2 over 5m

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

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

$user over 1h

Mit dieser Anweisung wird $user zurückgegeben, wenn die Regel eine Übereinstimmung findet. Der angegebene Zeitraum beträgt 1 Stunde. Ereignisse, die mehr als eine Stunde auseinanderliegen, werden nicht in Beziehung gesetzt. Die Regel betrachtet sie nicht als Erkennung.

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

$source_ip, $target_ip, $hostname over 2m

Diese Anweisung gibt $source_ip, $target_ip und $hostname zurück, wenn die Regel eine Übereinstimmung findet. Das angegebene Zeitfenster beträgt 2 Minuten. Ereignisse, die mehr als 2 Minuten auseinanderliegen, werden nicht in Beziehung gesetzt. 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 dem Wert „0“ im Abschnitt „Abgleich“

In der Rules Engine werden die Nullwerte für alle Platzhalter, die im Abschnitt „match“ verwendet werden, implizit herausgefiltert ("" für String, 0 für Zahlen, false für boolesche Werte, der Wert an Position 0 für aufgezählte Typen). Das folgende Beispiel zeigt Regeln, mit denen die Nullwerte herausgefiltert werden.

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 einer Funktion jedoch ein Platzhalter zugewiesen ist, werden die Nullwerte von Platzhaltern, die im Abschnitt „Abgleich“ verwendet werden, nicht implizit durch Regeln herausgefiltert. Im folgenden Beispiel werden Regeln veranschaulicht, mit denen die Nullwerte herausgefiltert werden:

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 „match“-Abschnitt mithilfe von Hop-Fenstern ausgewertet. Der Zeitraum für die Ausführung der Regel wird in eine Reihe von sich überschneidenden Hop-Fenstern unterteilt, die jeweils die im Abschnitt match angegebene Dauer haben. Die Ereignisse werden dann innerhalb jedes Hop-Fensters korreliert.

Für eine Regel, die im Zeitraum [1:00, 2:00] ausgeführt wird, mit einem match-Abschnitt über 30m, könnte beispielsweise die folgende Gruppe von sich überschneidenden Sprungfenstern generiert werden: [1:00, 1:30], [1:03, 1:33] und [1:06, 1:36]. Diese Zeiträume werden verwendet, um mehrere Ereignisse in Beziehung zu setzen.

Schiebefenster

Die Verwendung von Hop-Fenstern ist keine effektive Methode, um nach Ereignissen zu suchen, die in einer bestimmten Reihenfolge eintreten (z. B. e1 bis zu 2 Minuten nach e2). Ein Auftreten des Ereignisses e1 und ein Auftreten des Ereignisses e2 sind nur dann korreliert, wenn sie in dasselbe generierte Hop-Fenster fallen.

Eine effektivere Methode zum Suchen nach solchen Ereignissequenzen ist die Verwendung von gleitenden Fenstern. Gleitende Fenster mit der im Abschnitt match angegebenen Dauer werden generiert, wenn sie mit einer angegebenen Pivot-Ereignisvariablen beginnen oder enden. Ereignisse werden dann in jedem gleitenden Fenster in Beziehung gesetzt. So können Sie nach Ereignissen suchen, die in einer bestimmten Reihenfolge eintreten (z. B. e1 innerhalb von 2 Minuten nach e2). Ein Auftreten des Ereignisses e1 und ein Auftreten des Ereignisses e2 sind korreliert, wenn das Ereignis e1 innerhalb des gleitenden Zeitfensters nach dem Ereignis e2 auftritt.

Geben Sie gleitende Fenster im Abschnitt match einer Regel so an:

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

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

Hier sind einige Beispiele für die gültige Verwendung von gleitenden Fenstern:

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

Beispiel für eine Regel für gleitende Fenster

Wir empfehlen, keine gleitenden Fenster für Einzelereignisregeln zu verwenden, da sie für die Erkennung mehrerer Ereignisse konzipiert sind. Wenn eine Ihrer Regeln in diese Kategorie fällt, empfehlen wir eine der folgenden Problemumgehungen:

• Konvertieren Sie die Regel so, dass mehrere Ereignisvariablen verwendet werden, und aktualisieren Sie den Bedingungsabschnitt, wenn für die Regel mehr als ein Ereignis erforderlich ist.
  • 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
• Entfernen Sie das Schiebefenster.

Syntax für Ergebnisabschnitt

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. Jeder Erkennung können unterschiedliche Werte für die Ergebnisse zugewiesen sein.

Der Name des Ergebnisses, $risk_score, ist speziell. Optional können Sie ein Ergebnis mit diesem Namen definieren. Wenn Sie das tun, muss es vom Typ „Ganzzahl“ oder „Gleitkommazahl“ sein. Falls vorhanden, wird risk_score in der Enterprise Insights-Ansicht für Benachrichtigungen angezeigt, die auf Regelerkennungen beruhen.

Wenn Sie im Ergebnisabschnitt einer Regel keine $risk_score-Variable angeben, wird einer der folgenden Standardwerte festgelegt:

• Wenn die Regel so konfiguriert ist, dass eine Benachrichtigung generiert wird, wird $risk_score auf 40 gesetzt.
• Wenn die Regel nicht so konfiguriert ist, dass eine Benachrichtigung generiert wird, wird $risk_score auf 15 gesetzt.

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

Datentypen von Ergebnisvariablen

Jede Ergebnisvariable kann einen anderen Datentyp haben, der durch den Ausdruck bestimmt wird, mit dem sie berechnet wird. Wir unterstützen die folgenden Arten von Ergebnisdaten:

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

Bedingte Logik

Mit bedingter Logik können Sie den Wert eines Ergebnisses berechnen. Bedingungen werden mit dem folgenden Syntaxmuster angegeben:

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

Ein bedingter Ausdruck kann so gelesen werden: „Wenn BOOL_CLAUSE wahr ist, gib THEN_CLAUSE zurück, andernfalls gib ELSE_CLAUSE zurück.“

BOOL_CLAUSE muss als boolescher Wert ausgewertet werden. Ein BOOL_CLAUSE-Ausdruck hat eine ähnliche Form wie Ausdrücke im events-Abschnitt. 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, z. B.:

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

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

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

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

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

• in einer Referenzliste nachschlagen, z. B.:

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

• Vergleich der Aggregation, z. B.:

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

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

Sie können die ELSE_CLAUSE weglassen, wenn der Datentyp „integer“ oder „float“ ist. Wird sie weggelassen, wird ELSE_CLAUSE als 0 ausgewertet. Beispiel:

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

Sie müssen die ELSE_CLAUSE angeben, wenn der Datentyp „String“ ist oder wenn die THEN_CLAUSE eine Platzhaltervariable oder Ergebnisvariable ist.

Mathematische Operationen

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

Das folgende Snippet ist ein Beispiel für eine Berechnung im Abschnitt outcome:

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

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

• Numerische Ereignisfelder
• Numerische Platzhaltervariablen, die im Abschnitt events definiert sind
• Numerische Ergebnisvariablen, die im Abschnitt outcome definiert sind
• Funktionen, die Ganzzahlen oder Gleitkommazahlen zurückgeben
• Aggregationen, die Ganzzahlen oder Gleitkommazahlen zurückgeben

Der Modulo-Operator ist für 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 Abschnitt „Ereignisse“ 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 für mehrere Ereignisse:

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 Ausdrücken für die Ergebniszuteilung

Mit Ergebnisvariablen lassen sich andere Ergebnisvariablen ableiten, ähnlich wie mit Platzhaltervariablen, die im Abschnitt events definiert sind. Sie können in der Zuweisung einer anderen Ergebnisvariablen mit einem $-Token gefolgt vom Variablennamen auf eine Ergebnisvariable verweisen. Ergebnisvariablen müssen definiert werden, bevor auf sie im Regeltext verwiesen werden kann. Wenn sie in einem Zuweisungsausdruck verwendet werden, dürfen Ergebnisvariablen nicht aggregiert werden (siehe Aggregationen).

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

Beispiel für mehrere Ereignisse:

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

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

Zusammenfassungen

Wiederholte Ereignisfelder sind nicht skalare Werte. Das bedeutet, dass eine einzelne Variable auf mehrere Werte verweist. Die Ereignisfeldvariable $e.target.ip ist beispielsweise 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 ist dagegen kein wiederkehrendes Feld und hat nur einen Wert (einen skalaren Wert).

Sowohl nicht wiederholte als auch wiederholte Ereignisfelder, die im Ergebnisbereich einer Regel mit einem Abgleichszeitraum verwendet werden, sind keine skalaren Werte. Die folgende Regel gruppiert Ereignisse beispielsweise mithilfe eines Match-Abschnitts und verweist im Ergebnisabschnitt auf ein nicht wiederholtes Ereignisfeld:

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

In einem 5‑Minuten-Zeitraum, in dem die Regel ausgeführt wird, können null, ein oder mehrere Ereignisse enthalten sein. Der Abschnitt „Ergebnis“ wird für alle Ereignisse in einem Match-Zeitraum ausgeführt. Jede Ereignisfeldvariable, auf die im Ergebnisabschnitt verwiesen wird, kann für jedes Ereignis im Abgleichszeitraum auf null, einen oder mehrere Werte des Felds verweisen. Wenn ein 5-Minuten-Zeitfenster beispielsweise 5 $e-Ereignisse enthält, verweist $e.principal.hostname im Ergebnisbereich auf fünf verschiedene Hostnamen. Die Event-Feldvariable $e.principal.hostname wird im Abschnitt outcome dieser Regel als nicht skalarer Wert behandelt.

Da Ergebnisvariablen immer einen einzelnen skalaren Wert ergeben müssen, muss jeder nicht skalare Wert, von dem eine Ergebniszuweisung abhängt, aggregiert werden, um einen einzelnen skalaren Wert zu erhalten. Im Ergebnisbereich sind die folgenden Werte nicht skalar und müssen aggregiert werden:

• Ereignisfelder (wiederholt oder nicht wiederholt), wenn die Regel einen Abgleichabschnitt verwendet
• Platzhalter für Ereignisse (wiederholt oder nicht wiederholt), wenn in der Regel ein Abgleichabschnitt verwendet wird
• Wiederholte Ereignisfelder, wenn die Regel keinen Match-Abschnitt verwendet
• Wiederholte Ereignisplatzhalter, wenn die Regel keinen Abgleichabschnitt verwendet

Skalare Ereignisfelder, skalare Ereignis-Platzhalter und Konstanten können in Regeln ohne Match-Abschnitt in Aggregationsfunktionen eingeschlossen werden. In den meisten Fällen geben diese Aggregationen jedoch den umschlossenen Wert zurück, sodass sie nicht erforderlich sind. Eine Ausnahme ist die Aggregation array(), mit der Sie einen skalaren Wert explizit in ein Array konvertieren können.

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

Sie können die folgenden Aggregationsfunktionen verwenden:

• max(): Gibt das Maximum aller möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.
• min(): Gibt das Minimum aller möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.
• sum(): Gibt die Summe aller möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.
• count_distinct(): Erfasst alle möglichen Werte und gibt dann die Anzahl der einzelnen möglichen Werte aus.
• count(): Verhält sich wie count_distinct(), gibt aber eine nicht eindeutige Anzahl möglicher Werte zurück.
• array_distinct(): Erfasst alle möglichen eindeutigen Werte und gibt dann eine Liste dieser Werte aus. Die Liste der eindeutigen Werte wird auf 1.000 zufällige Elemente gekürzt. Die Deduplizierung zur Erstellung einer Liste mit eindeutigen Werten wird zuerst angewendet, dann die Kürzung.
• array(): Verhält sich wie array_distinct(), gibt aber eine nicht eindeutige Liste von Werten zurück. Außerdem wird die Liste der Werte auf 1.000 zufällige Elemente gekürzt.
• period_start_for_max(): Beginn des Zeitraums, in dem das Maximum des aufgeführten Werts aufgetreten ist.
• period_start_for_min(): Beginn des Zeitraums, in dem das Minimum des aufgeführten Werts aufgetreten ist.

Die Aggregatfunktion ist wichtig, wenn eine Regel einen condition-Abschnitt enthält, in dem angegeben wird, dass mehrere Ereignisse vorhanden sein müssen. Die Aggregatfunktion wird dann auf alle Ereignisse angewendet, die die Erkennung ausgelöst haben.

Wenn Ihre Abschnitte outcome und condition beispielsweise Folgendes enthalten:

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

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

condition:
  #event > 1

Da im Bedingungsabschnitt mehr als ein event für jeden erkannten Fall vorhanden sein muss, werden die Aggregatfunktionen auf mehrere Ereignisse angewendet. Angenommen, die folgenden Ereignisse haben eine Erkennung ausgelöst:

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

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

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

Die Werte Ihrer Ergebnisse sind dann:

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

Wissenswertes zur Verwendung des Bereichs „Ergebnis“:

Weitere Hinweise und Einschränkungen:

• Im Abschnitt outcome kann nicht auf eine neue Platzhaltervariable verwiesen werden, die nicht bereits im Abschnitt events oder im Abschnitt outcome definiert wurde.
• Im Abschnitt outcome können keine Ereignisvariablen verwendet werden, die nicht im Abschnitt events definiert wurden.
• Im Abschnitt outcome kann ein Ereignisfeld verwendet werden, das nicht im Abschnitt events verwendet wurde, sofern die Ereignisvariable, zu der das Ereignisfeld gehört, bereits im Abschnitt events definiert wurde.
• Im Bereich outcome können nur Ereignisvariablen in Beziehung gesetzt werden, die bereits im Bereich events in Beziehung gesetzt wurden. Korrelationen treten auf, wenn zwei Ereignisfelder aus verschiedenen Ereignisvariablen gleichgesetzt werden.

Ein Beispiel mit dem Ergebnisabschnitt finden Sie unter Übersicht über YARA-L 2.0. Weitere Informationen zum Deduplizieren von Erkennungen mit dem Ergebnisbereich finden Sie unter Kontextsensitive Analysen erstellen.

Syntax des Abschnitts „Bedingungen“

• Geben Sie eine Abgleichsbedingung für Ereignisse und Platzhalter an, die im Abschnitt events definiert sind. Weitere Informationen finden Sie im folgenden Abschnitt Bedingungen für Ereignisse und Platzhalter.
• Optional können Sie mit dem Keyword and eine Abgleichsbedingung mit Ergebnisvariablen angeben, die im Abschnitt outcome definiert sind. Weitere Informationen finden Sie im Abschnitt Bedingungen für Ergebnisse.

Zeichen zählen

Das Zeichen # ist ein Sonderzeichen im Abschnitt condition. Wenn sie vor einem Ereignis- oder Platzhaltervariablennamen verwendet wird, steht sie für die Anzahl der unterschiedlichen Ereignisse oder Werte, die alle Bedingungen im events-Abschnitt erfüllen.

Beispiel: #c > 1 bedeutet, dass die Variable c mehr als einmal vorkommen muss.

Wertzeichen

Das Zeichen $ ist ein Sonderzeichen im Abschnitt condition. Wenn es vor einem Namen einer Ergebnisvariablen verwendet wird, steht es für den Wert dieses Ergebnisses.

Wenn es vor einem Ereignis- oder Platzhaltervariablennamen verwendet wird (z. B. $event), steht es für #event > 0.

Bedingungen für Ereignisse und Platzhalter

Listen Sie Bedingungsprädikate für Ereignisse und Platzhaltervariablen mit den Keywords and oder or auf. Mit and können Sie beliebige Kombinationen von Bedingungen verknüpfen. or ist jedoch nur möglich, wenn sich alle Bedingungen auf dieselbe Ereignisvariable beziehen.

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 für verschiedene Ereignisse:

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

Begrenzte und unbegrenzte Bedingungen

Die folgenden Bedingungen sind gebundene Bedingungen. Sie erzwingen, dass die zugehörige Ereignisvariable vorhanden ist. Das bedeutet, dass bei jeder Erkennung mindestens ein Ereignis auftreten muss.

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

Die folgenden Bedingungen sind ungebundene Bedingungen. Sie ermöglichen, dass die zugehörige Ereignisvariable nicht vorhanden ist. Das bedeutet, dass das Ereignis in einer Erkennung nicht vorkommen kann und jeder Verweis auf Felder in der Ereignisvariablen den Wert „0“ zurückgibt. Mit unbegrenzten Bedingungen kann das Fehlen eines Ereignisses über einen bestimmten Zeitraum hinweg erkannt werden. Beispiel: Ein Bedrohungsereignis ohne ein Ereignis zur Risikominderung innerhalb eines Zeitfensters von 10 Minuten. Regeln mit unbegrenzten Bedingungen werden als „Nicht-Existenz-Regeln“ bezeichnet.

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

Anforderungen für die Nichtexistenz

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

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

Sehen Sie sich die folgende Regel an, bei der der Bedingungsabschnitt weggelassen wurde:

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

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

• $u1 and !$u2 and $e1 and $e2
  • Alle UDM-Ereignisse und ‑Entitäten sind im Bedingungsabschnitt vorhanden.
  • Mindestens ein UDM-Ereignis ist begrenzt.
• $u1 and !$u2 and $e1 and !$e2
  • $e2ist unbegrenzt, was zulässig ist, da es mit $u1 verknüpft ist, das begrenzt ist. Wenn $e2 nicht mit $u1 verknüpft wäre, wäre das ungültig.
• #port > 50 and #ip = 0
  • Im Bedingungsabschnitt sind keine UDM-Ereignisse und ‑Entitäten vorhanden. 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 ungebundene 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 für <condition_section> sind ungültig:

• $u1 and $e1
  • Jedes UDM-Ereignis und jede UDM-Entität, die im Abschnitt „Ereignisse“ angezeigt wird, muss auch im Abschnitt „Bedingung“ angezeigt werden (oder es muss ein Platzhalter dafür zugewiesen sein, der im Abschnitt „Bedingung“ angezeigt wird).
• $u1, $u2, $e1, $u2, #port > 50
  • Kommas sind als Trennzeichen für Bedingungen nicht zulässig.
• !$u1 and !$u2 and $e1 and $e2
  • Verstößt gegen die erste Anforderung, dass mindestens ein UDM-Ereignis begrenzt ist.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • Das or-Keyword wird bei unbegrenzten Bedingungen nicht unterstützt.
• ($u1 or $u2) and $e1 and $e2
  • Das Keyword or wird nicht zwischen verschiedenen Ereignisvariablen unterstützt.
• not $u1 and $u2 and $e1 and $e2
  • Das not-Schlüsselwort 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. Alle Bedingungen sind jedoch unbegrenzt. Das bedeutet, dass keines der UDM-Ereignisse begrenzt ist, was dazu führt, dass die Regel nicht kompiliert werden kann.

Bedingungen für Ergebnisse

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

Die Bedingungen für das Ergebnis müssen je nach Typ der Ergebnisvariablen unterschiedlich angegeben werden:

• integer: Vergleich mit einem Integer-Literal mit Operatoren =, >, >=, <, <=, !=, z. B.:

  $risk_score > 10

• float: Vergleich mit einem Gleitkomma-Literal mit Operatoren =, >, >=, <, <=, !=, z. B.:

  $risk_score <= 5.5

• string: Vergleich mit einem Stringliteral mit = oder !=, z. B.:

  $severity = "HIGH"

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

  arrays.contains($event_ids, "id_1234")

Regelklassifizierung

Wenn Sie eine Ergebnisbedingung in einer Regel mit einem Abgleichsabschnitt angeben, wird die Regel für das Regelkontingent als Regel mit mehreren Ereignissen klassifiziert. Weitere Informationen zu Klassifizierungen für einzelne und mehrere Ereignisse finden Sie unter Regel für einzelne Ereignisse und Regel für mehrere Ereignisse.

Syntax des Abschnitts „Options“

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

rule RuleOptionsExample {
  // Other rule sections

  options:
    allow_zero_values = true
}

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

allow_zero_values

Die gültigen Werte für diese Option sind true und false. Sie legen fest, ob die Option aktiviert ist. Der Standardwert ist false. Diese Option ist deaktiviert, wenn sie in der Regel nicht angegeben ist.

Fügen Sie zum Aktivieren dieser Einstellung Folgendes in den Optionsabschnitt Ihrer Regel ein: allow_zero_values = true. So wird verhindert, dass die Regel die Nullwerte von Platzhaltern, die im Abgleichsabschnitt verwendet werden, implizit herausfiltert. Weitere Informationen finden Sie unter Umgang mit Nullwerten im Abgleichsabschnitt.

suppression_window

Mit der Option suppression_window können Sie festlegen, wie oft eine Regel eine Erkennung auslösen soll. So wird verhindert, dass dieselbe Regel innerhalb eines bestimmten Zeitfensters mehrere Erkennungen generiert, auch wenn die Bedingungen der Regel mehrmals erfüllt sind. Beim Suppression-Windowing wird ein rollierendes Fenster verwendet, mit dem Duplikate in einem nicht überlappenden Fenster mit fester Größe unterdrückt werden.

Optional können Sie einen suppression_key angeben, um genauer festzulegen, welche Instanzen der Regel im Unterdrückungszeitraum unterdrückt werden. Wenn keine Angabe erfolgt, werden alle Instanzen der Regel unterdrückt. Dieser Schlüssel ist als Ergebnisvariable definiert.

Im folgenden Beispiel ist suppression_window auf 5m und suppression_key auf die Variable $hostname festgelegt. Nachdem die Regel eine Erkennung für $hostname ausgelöst hat, werden alle weiteren Erkennungen für $hostname für die nächsten fünf Minuten unterdrückt. Wenn die Regel jedoch durch ein Ereignis mit einem anderen Hostnamen ausgelöst wird, wird eine Erkennung erstellt.

Der Standardwert von suppression_window ist 0. Das bedeutet, dass das Unterdrückungszeitfenster standardmäßig deaktiviert ist. Diese Option funktioniert nur für Regeln für einzelne Ereignisse ohne match-Abschnitt.

Beispiel:

rule SuppressionWindowExample {
  // Other rule sections

  outcome:
    $suppression_key = $hostname

  options:
    suppression_window = 5m
}

Zusammengesetzte Erkennungsregeln

Bei der zusammengesetzten Erkennung in Google SecOps werden mehrere YARA-L-Regeln verknüpft. In diesem Abschnitt wird beschrieben, wie Sie eine zusammengesetzte Regel erstellen. Eine Übersicht über zusammengesetzte Erkennungen finden Sie unter Übersicht über zusammengesetzte Erkennungen.

Regelstruktur

Zusammengesetzte Erkennungsregeln sind immer Mehrfachereignisregeln und folgen derselben Struktur und Syntax. Für zusammengesetzte Erkennungsregeln gelten die folgenden Anforderungen:

• Für zusammengesetzte Regeln muss ein match-Abschnitt verwendet werden, um Bedingungen für den Erkennungstrigger zu definieren.
• Bei Regeln, in denen sowohl Erkennungsfelder als auch UDM-Ereignisse verwendet werden, müssen diese Datenquellen explizit verknüpft werden.

Informationen zu Einschränkungen bei Regeln finden Sie unter Einschränkungen.

Erkennungen als Eingabe für Regeln verwenden

In zusammengesetzten Regeln kann auf Regelerkennungen verwiesen werden, die von benutzerdefinierten oder kuratierten Regeln generiert wurden. Google SecOps bietet dafür zwei Methoden.

Inhalte für die Referenzerkennung mit Ergebnisvariablen, Abgleichsvariablen oder Meta-Labels referenzieren

Wenn Sie auf Daten aus einer Erkennung zugreifen möchten, ohne auf die ursprünglichen UDM-Ereignisse zu verweisen, verwenden Sie outcome-Variablen, match-Variablen oder meta-Labels. Wir empfehlen diesen Ansatz, da er mehr Flexibilität und eine bessere Kompatibilität mit verschiedenen Regeltypen bietet.

Beispielsweise können mit mehreren Regeln ein String (z. B. eine URL, ein Dateiname oder ein Registrierungsschlüssel) in einer gemeinsamen outcome-Variablen gespeichert werden, wenn Sie in verschiedenen Kontexten nach diesem String suchen. Wenn Sie über eine zusammengesetzte Regel auf diesen String zugreifen möchten, beginnen Sie mit detection und suchen Sie die relevanten Informationen mithilfe von Elementen aus der Sammlungsressource.

Beispiel:Angenommen, eine Erkennungsregel gibt die folgenden Informationen aus:

• Ergebnisvariable: dest_domain = "cymbal.com"
• UDM-Feld: target.hostname = "cymbal.com"

In der zusammengesetzten Regel können Sie über die folgenden Pfade auf diese Daten zugreifen:

• detection.detection.outcomes["dest_domain"], um auf die Ergebnisvariable dest_domain zuzugreifen.
• detection.collection_elements.references.event.target.hostname, um auf das UDM-Feld target.hostname zuzugreifen.
• detection.time_window.start_time.seconds, um auf den Zeitstempel der Erkennung zuzugreifen.

Die Collection API und die SecurityResult API bieten Zugriff auf beides:

• Metadaten und Ergebniswerte für die Erkennung (detection.detection)
• Zugrunde liegende UDM-Ereignisse aus referenzierten Regeln (collection_elements)

Auf Erkennungsinhalte anhand der Regel-ID oder des Regelnamens verweisen

Sie können auf eine Regel entweder über ihren Namen oder ihre ID verweisen. Wir empfehlen diesen Ansatz, wenn Ihre Erkennungslogik von bestimmten Regeln abhängt. Wenn Sie anhand des Namens oder der ID auf relevante Regeln verweisen, wird die Leistung verbessert und es werden Zeitüberschreitungen verhindert, da weniger Daten analysiert werden. Sie können beispielsweise Felder wie target.url oder principal.ip direkt aus einer bekannten vorherigen Erkennung abfragen.

• Auf eine Regel anhand der Regel-ID verweisen (empfohlen): Verwenden Sie das Feld detection.detection.rule_id, um anhand der ID auf eine Regel zu verweisen. Sie finden die Regel-ID in der URL der Regel in Google SecOps. Nutzergenerierte Regeln haben IDs im Format ru_UUID, kuratierte Erkennungen haben IDs im Format ur_UUID. Beispiel:

  detection.detection.rule_id = "ru_e0d3f371-6832-4d20-b0ad-1f4e234acb2b"

• Auf eine Regel anhand des Namens verweisen:Verwenden Sie das Feld detection.detection.rule_name, um anhand des Namens auf eine Regel zu verweisen. Sie können den genauen Namen der Regel angeben oder einen regulären Ausdruck verwenden, um ihn abzugleichen. Beispiel:

  • detection.detection.rule_name = "My Rule Name"
  • detection.detection.rule_name = "/PartOfName/"

Hinweis:Wir empfehlen, Regel-IDs für Verweise zu verwenden, da IDs eindeutig sind und sich nicht ändern. Regelnamen können geändert werden, was möglicherweise zu Problemen bei der zusammengesetzten Erkennung führt.

Ereignisse und Erkennungen kombinieren

In zusammengesetzten Regeln können verschiedene Datenquellen kombiniert werden, darunter UDM-Ereignisse, Daten aus dem Entity-Diagramm und Erkennungsfelder. Hierfür gelten folgende Richtlinien:

• Unterschiedliche Variablen pro Quelle verwenden: Weisen Sie jeder Datenquelle eindeutige Ereignisvariablen zu (z. B. $e für Ereignisse, $d für Erkennungen), wenn die Datenquelle Ereignisse, Entitäten und Erkennungen enthält.
• Quellen anhand von gemeinsamem Kontext zusammenführen: Verbinden Sie Datenquellen mit gemeinsamen Werten wie Nutzer-IDs, IP-Adressen oder Domainnamen in den Bedingungen Ihrer Regel.
• Zeitfenster für den Abgleich definieren: Fügen Sie immer eine match-Klausel mit einem Zeitfenster von maximal 48 Stunden ein.

Beispiel:

rule CheckCuratedDetection_with_EDR_and_EG {
  meta:
    author = "noone@cymbal.com"
  events:
    $d.detection.detection.rule_name = /SCC: Custom Modules: Configurable Bad Domain/
    $d.detection.collection_elements.references.event.network.dns.questions.name = $domain
    $d.detection.collection_elements.references.event.principal.asset.hostname = $hostname

    $e.metadata.log_type = "LIMACHARLIE_EDR"
    $e.metadata.product_event_type = "NETWORK_CONNECTIONS"
    $domain = re.capture($e.principal.process.command_line, "\\s([a-zA-Z0-9.-]+\\.[a-zA-Z0-9.-]+)$")
    $hostname = re.capture($e.principal.hostname, "([^.]*)")

    $prevalence.graph.metadata.entity_type = "DOMAIN_NAME"
    $prevalence.graph.metadata.source_type = "DERIVED_CONTEXT"
    $prevalence.graph.entity.hostname = $domain
    $prevalence.graph.entity.domain.prevalence.day_count = 10
    $prevalence.graph.entity.domain.prevalence.rolling_max <= 5
    $prevalence.graph.entity.domain.prevalence.rolling_max > 0

  match:
    $hostname over 1h

  outcome:
    $risk_score = 80
    $CL_target = array($domain)

  condition:
    $e and $d and $prevalence
}

Sequenzielle zusammengesetzte Erkennungen erstellen

Bei sequenziellen zusammengesetzten Erkennungen werden Muster von zusammenhängenden Ereignissen erkannt, bei denen die Reihenfolge der Erkennungen wichtig ist, z. B. eine Erkennung eines Brute-Force-Anmeldeversuchs, gefolgt von einer erfolgreichen Anmeldung. Diese Muster können mehrere Basis-Erkennungen, Roh-UDM-Ereignisse oder beides kombinieren.

Wenn Sie eine sequenzielle zusammengesetzte Erkennung erstellen möchten, müssen Sie diese Reihenfolge in Ihrer Regel erzwingen. Verwenden Sie eine der folgenden Methoden, um die erwartete Reihenfolge zu erzwingen:

• Gleitende Fenster:Definieren Sie die Reihenfolge der Erkennungen mit gleitenden Fenstern in Ihren match-Bedingungen.
• Zeitstempelvergleiche:Vergleichen Sie die Zeitstempel von Erkennungen in Ihrer Regel-Logik, um zu prüfen, ob sie in der ausgewählten Reihenfolge erfolgen.

Beispiel:

events:
    $d1.detection.detection.rule_name = "fileEvent_rule"
    $userid = $d1.detection.detection.outcomes["user"]
    $hostname = $d1.detection.detection.outcomes["hostname"]

    $d2.detection.detection.rule_name = "processExecution_rule"
    $userid = $d2.detection.detection.outcomes["user"]
    $hostname = $d2.detection.detection.outcomes["hostname"]

    $d3.detection.detection.rule_name = "networkEvent_rule"
    $userid = $d3.detection.detection.outcomes["user"]
    $hostname = $d3.detection.detection.outcomes["hostname"]

$d3.detection.collection_elements.references.event.metadata.event_timestamp.seconds > $d2.detection.collection_elements.references.event.metadata.event_timestamp.seconds

  match:
    $userid over 24h after $d1

Boolesche Ausdrücke

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

Vergleiche

Verwenden Sie die folgende Syntax für einen binären Ausdruck, der als Bedingung verwendet werden soll:

• <EXPR> <OP> <EXPR>

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

Beispiel:

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

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

Funktionen

Einige Funktionsausdrücke geben einen booleschen Wert zurück, der als einzelnes Prädikat im Abschnitt events verwendet werden kann. Dazu 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 für Referenzlisten

Sie können Referenzlisten im Bereich „Ereignisse“ verwenden. Weitere Informationen finden Sie im Abschnitt 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.

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

Im Abschnitt events werden die Prädikate mit dem Operator and verknüpft, wenn kein Operator explizit definiert ist.

Die Reihenfolge der Auswertung kann sich ändern, wenn der Operator and im Ausdruck impliziert wird.

Betrachten Sie beispielsweise die folgenden Vergleichsausdrücke, in 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 um or gruppiert und zuerst ausgewertet. Das letzte Prädikat, $e2.field = "bar", wird implizit mit and verknüpft. Dadurch ändert sich die Reihenfolge der Auswertung.

Aufzählungstypen

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

Im folgenden Beispiel entsprechen „USER_UNCATEGORIZED“ und „USER_RESOURCE_DELETION“ 15000 und 15014. Die Regel sucht also nach allen aufgeführten Ereignissen:

$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 einen regulären Ausdruck haben, können Sie am Ende des Ausdrucks „nocase“ anhängen, um die Groß-/Kleinschreibung zu ignorieren.

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

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

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

Wiederkehrende Felder

Im Unified Data Model (UDM) sind einige Felder als „repeated“ (wiederholt) gekennzeichnet. Das bedeutet, dass sie Listen mit Werten oder anderen Arten von Nachrichten sind.

Wiederkehrende Felder und boolesche Ausdrücke

Es gibt zwei Arten von booleschen Ausdrücken, die sich auf wiederholte Felder beziehen:

1. Geändert
2. Unverändert

Stellen Sie sich folgendes Ereignis vor:

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

    hostname: "host"
  }
}

Geänderte Ausdrücke

In den folgenden Abschnitten wird der Zweck der Modifikatoren any und all in Ausdrücken beschrieben und es wird erläutert, wie sie verwendet werden.

Beliebig

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

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

Alle

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

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

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

Beispiel:

• Mit not all $e.principal.ip = "192.168.12.16" wird geprüft, ob nicht alle IP-Adressen mit 192.168.12.16 übereinstimmen. Die Regel prüft also, ob mindestens eine IP-Adresse nicht mit 192.168.12.16 übereinstimmt.
• Mit all $e.principal.ip != "192.168.12.16" wird geprüft, ob alle IP-Adressen nicht mit 192.168.12.16 übereinstimmen. Die Regel prüft also, ob keine IP-Adressen mit 192.168.12.16 übereinstimmen.

Einschränkungen:

• Die Operatoren any und all sind nur mit sich wiederholenden Feldern (nicht mit skalaren Feldern) kompatibel.
• any und all können nicht verwendet werden, um zwei wiederkehrende Felder zu verknüpfen. any $e1.principal.ip = $e2.principal.ip ist beispielsweise ungültig.
• Die Operatoren any und all werden mit dem Ausdruck für die Referenzliste nicht unterstützt.

Unveränderte Ausdrücke

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

Die Regel wird auf die folgenden Kopien angewendet:

Wenn eine Ereigniskopie alle unveränderten Bedingungen für das wiederholte Feld erfüllt, erfüllt das Ereignis als Ganzes alle Bedingungen. Wenn Sie also mehrere Bedingungen für ein wiederholtes Feld haben, muss die Ereigniskopie alle Bedingungen erfüllen. In den folgenden Beispielregeln wird dieses Verhalten anhand des oben genannten Beispieldatasets veranschaulicht.

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

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

Die folgende Regel gibt keine Übereinstimmung zurück, wenn sie für das Beispiel-Dataset event_original ausgeführt wird, da es in $e.principal.ip keine Ereigniskopie gibt, 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 für wiederholte Felder sind mit unveränderten Ausdrücken für wiederholte Felder kompatibel, da die Elementliste für jede Ereigniskopie identisch ist. Sehen Sie sich die folgende Regel an:

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:

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". Daher würde das gesamte Ereignis übereinstimmen.

Eine andere Möglichkeit, diese Ausdruckstypen zu betrachten, ist:

• Ausdrücke für wiederholte Felder, die any oder all verwenden, werden für die Liste in event_original ausgeführt.
• Ausdrücke für wiederholte Felder, in denen any oder all nicht verwendet wird, werden für einzelne event_copy_n-Ereignisse ausgeführt.

Wiederkehrende Felder und Platzhalter

Wiederkehrende Felder funktionieren mit Platzhalterzuweisungen. Ähnlich wie bei unveränderten Ausdrücken für wiederholte Felder wird für jedes Element eine Kopie des Ereignisses erstellt. Im Beispiel mit event_copy nimmt der Platzhalter den Wert des wiederholten Felds von event_copy_n für jede der Ereigniskopien an, wobei n die Nummer der Ereigniskopie ist. Wenn der Platzhalter im Abschnitt „Übereinstimmung“ 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 Ereignisstichproben des Abgleichs enthalten ein einzelnes 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 entspricht für jede der verschiedenen event_copy_n-Kopien unterschiedlichen Werten. Die Gruppierung erfolgt auf $ip, da sich diese im Abschnitt „Abstimmung“ befindet. Daher erhalten Sie drei Übereinstimmungen, bei denen die Variable $ip jeweils einen anderen Wert hat. Jede Übereinstimmung hat dasselbe Ereignismuster: 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
}

Ergebnisse mit Platzhaltern, die wiederkehrenden Feldern zugewiesen sind

Platzhalter werden jedem Element jedes wiederholten Felds zugewiesen, nicht der gesamten Liste. Wenn sie also im Ergebnisabschnitt verwendet werden, wird das Ergebnis nur anhand der Elemente berechnet, die die vorherigen Abschnitte erfüllt haben.

Sehen Sie sich die folgende Regel an:

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

  match:
    $host over 5m

  outcome:
    $o = array_distinct($ip)

  condition:
    $e
}

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

Im Abschnitt „Ereignisse“ werden dann Zeilen herausgefiltert, die nicht mit den Filtern übereinstimmen:

event_copy_3 wird herausgefiltert, weil "192.0.2.3" nicht $ip = "192.0.2.1" or $ip = "192.0.2.2" entspricht.

Im Abschnitt „Abgleich“ wird dann nach Abgleichsvariablen gruppiert und im Abschnitt „Ergebnis“ wird eine Aggregation für jede Gruppe durchgeführt:

$o = array_distinct($ip) wird anhand von $ip aus der vorherigen Phase und nicht aus der Phase zum Kopieren von Ereignissen berechnet.

Schließlich wird jede Gruppe nach dem Bedingungsabschnitt gefiltert. Da diese Regel nur das Vorhandensein von $e prüft, wird in der Zeile von oben nur ein einziger Treffer erzielt.

$o enthält nicht alle Elemente aus $e.principal.ip, da nicht alle Elemente alle Bedingungen im Bereich „Ereignisse“ erfüllt haben. Alle Elemente von e.principal.ip werden jedoch im Ereignisbeispiel angezeigt, da im Ereignisbeispiel event_original verwendet wird.

Array-Indexierung

Sie können Array-Indexierung für wiederholte Felder ausführen. Für den Zugriff auf das n-te wiederholte Feldelement verwenden Sie die Standardlistensyntax (Elemente sind 0-indiziert). Bei einem Element außerhalb des gültigen Bereichs wird der Standardwert zurückgegeben.

• $e.principal.ip[0] = "192.168.12.16"
• $e.principal.ip[999] = "" Wenn weniger als 1.000 Elemente vorhanden sind, wird dies als true ausgewertet.

Einschränkungen:

• Ein Index muss ein nicht negatives Ganzzahlliteral sein. $e.principal.ip[-1] ist beispielsweise ungültig.
• Werte vom Typ int (z. B. ein Platzhalter, der auf int festgelegt ist) werden nicht berücksichtigt.
• 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 Map-Syntax kombiniert werden. $e.additional.fields[0]["key"] ist beispielsweise ungültig.
• Wenn der Feldpfad mehrere wiederholte Felder enthält, muss für alle wiederholten Felder die Array-Indexierung verwendet werden. $e.intermediary.ip[0] ist beispielsweise ungültig, da intermediary und ip beides wiederkehrende Felder sind, aber nur für ip ein Index vorhanden ist.

Wiederholte Nachrichten

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

Stellen Sie sich folgendes Ereignis vor:

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

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

Wie bei unveränderten Ausdrücken für wiederholte Felder wird für jedes Element des wiederholten Felds eine temporäre Kopie des Ereignisses erstellt. Sehen Sie sich die folgende Regel an:

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:

Das Ereignis stimmt nicht mit der Regel überein, da keine Ereigniskopie vorhanden ist, die alle Ausdrücke erfüllt.

Wiederholte Nachrichten und Array-Indexierung

Ein weiteres unerwartetes Verhalten kann auftreten, wenn Sie die Array-Indexierung mit unveränderten Ausdrücken für wiederholte Nachrichtenfelder verwenden. Sehen Sie sich die folgende Beispielregel an, in der die Array-Indexierung verwendet wird:

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:

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 in Regel repeated_message_1 keine Array-Indexierung verwendet wurde und keine Übereinstimmungen gefunden wurden, während in Regel repeated_message_2 Array-Indexierung verwendet wurde und eine Übereinstimmung gefunden wurde.

Kommentare

Kommentare werden mit zwei Schrägstrichen (// comment) oder mehrzeilige Kommentare mit Schrägstrich-Sternchen-Zeichen (/* comment */) gekennzeichnet, wie in C.

Literale

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

String- und reguläre Ausdrucksliterale

Sie können Strings in YARA-L 2.0 mit einem der folgenden Anführungszeichen einschließen. Die Interpretation von zitiertem Text hängt jedoch davon ab, welche der beiden Optionen Sie verwenden.

1. Doppelte Anführungszeichen ("): Für normale Strings. Muss Escapezeichen enthalten.
   Beispiel: „hallo\twelt“ – \t wird als Tabulator interpretiert.

2. Graviszeichen (`): Damit werden alle Zeichen wörtlich interpretiert.
   Beispiel: `hello\tworld` – \t wird nicht als Tabulator interpretiert

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

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

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

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

• 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 Backquotes zu verwenden, um die Lesbarkeit zu verbessern.

Operatoren

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

Variablen

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

Sie können die folgenden Arten von Variablen definieren:

• Ereignisvariablen: Stellen Gruppen von Ereignissen in normalisierter Form (UDM) oder Entitätsereignissen dar. Geben Sie im Bereich events Bedingungen für Ereignisvariablen an. Sie identifizieren Ereignisvariablen anhand eines Namens, einer Ereignisquelle und Ereignisfeldern. Zulässige Quellen sind udm (für normalisierte Ereignisse) und graph (für Entitätsereignisse). Wenn die Quelle weggelassen wird, wird udm als Standardquelle festgelegt. Ereignisfelder werden als Kette von .<field name> dargestellt, z. B. $e.field1.field2. Ereignisfeldketten beginnen immer mit der Quelle der obersten Ebene (UDM oder Entity).

• Abgleichsvariablen: Im Abschnitt match deklarieren. Match-Variablen werden zu Gruppierungsfeldern für die Abfrage, da für jede eindeutige Gruppe von Match-Variablen (und für jedes Zeitfenster) eine Zeile zurückgegeben wird. Wenn die Regel eine Übereinstimmung findet, werden die Werte der Match-Variablen zurückgegeben. Geben Sie im Abschnitt events an, wofür die einzelnen Abgleichsvariablen stehen.

• Platzhaltervariablen: Im Abschnitt events deklarieren und definieren. Platzhaltervariablen ähneln Abgleichsvariablen. Sie können jedoch Platzhaltervariablen im Abschnitt condition verwenden, um Abgleichsbedingungen anzugeben.

Mit Abgleichsvariablen und Platzhaltervariablen können Sie Beziehungen zwischen Ereignisfeldern über transitive Join-Bedingungen deklarieren (weitere Informationen finden Sie unter Syntax für den Abschnitt „Events“).

Keywords

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

Die folgenden Keywords sind für Regeln der Erkennungs-Engine verfügbar: rule, meta, match, over, events, condition, outcome, options, and, or, not, nocase, in, regex, cidr, before, after, all, any, if, max, min, sum, array, array_distinct, count, count_distinct, is und null.

Maps

YARA-L unterstützt den Zugriff auf Maps für Structs und Labels.

Structs und Labels

Für einige UDM-Felder wird entweder der Datentyp Struct oder Label verwendet.

Wenn Sie in „Struct“ und „Label“ nach einem bestimmten Schlüssel/Wert-Paar suchen möchten, verwenden Sie die Standard-Map-Syntax:

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

Der Kartenzugriff gibt immer einen String zurück.

Unterstützte Fälle

Im Folgenden finden Sie Anwendungsfälle für unterstützte Keywords.

Bereich „Ereignisse und Ergebnisse“

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

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

Platzhalter einen Kartenwert zuweisen

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

Kartenfeld in einer Join-Bedingung verwenden

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

Nicht unterstützte Fälle

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

any- oder all-Keywords mit einer Karte kombinieren

Das folgende Beispiel wird nicht unterstützt:

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

Andere Arten von Werten

Die Map-Syntax kann nur einen Stringwert zurückgeben. Bei Struct-Datentypen kann mit der Map-Syntax nur auf Schlüssel zugegriffen werden, 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

Bei Map-Zugriffen wird immer ein einzelner Wert zurückgegeben. In dem seltenen Grenzfall, dass sich der Kartenzugriff auf mehrere Werte beziehen könnte, wird durch den Kartenzugriff deterministisch der erste Wert zurückgegeben.

Das kann in den folgenden Fällen passieren:

• Ein Label hat einen doppelten Schlüssel.

  Die Labelstruktur stellt eine Map dar, erzwingt aber keine eindeutigen Schlüssel. Konventionsgemäß sollte eine Zuordnung eindeutige Schlüssel haben. Daher wird in Google SecOps nicht empfohlen, ein Label mit doppelten Schlüsseln zu füllen.

  Der Regeltext $e.metadata.ingestion_labels["dupe-key"] würde bei Ausführung für das folgende Datenbeispiel 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 übergeordnetes wiederkehrendes Feld.

  Ein wiederholtes Feld kann ein Label als untergeordnetes Feld enthalten. Zwei verschiedene Einträge im wiederholten Feld der obersten Ebene können Labels mit demselben Schlüssel enthalten. Der Regeltext $e.security_result.rule_labels["key"] würde den ersten möglichen Wert, val3, zurückgeben, wenn er für das folgende Datenbeispiel ausgeführt wird:

  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 Regeln und Suchvorgängen der Erkennungs-Engine verwenden können.

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

• Abschnitt events.
• BOOL_CLAUSE einer Bedingung im Ergebnisbereich.

arrays.concat

arrays.concat(string_array, string_array)

Beschreibung

Gibt ein neues String-Array zurück, indem Elemente aus den ursprünglichen String-Arrays kopiert werden.

Parameterdatentypen

ARRAY_STRINGS, ARRAY_STRINGS

Rückgabetyp

ARRAY_STRINGS

Codebeispiele

Beispiel 1

Im folgenden Beispiel werden zwei verschiedene String-Arrays verkettet.

arrays.concat(["test1", "test2"], ["test3"]) = ["test1", "test2", "test3"]

Beispiel 2

Im folgenden Beispiel werden Arrays mit einem leeren String verkettet.

arrays.concat([""], [""]) = ["", ""]

Beispiel 3

Im folgenden Beispiel werden leere Arrays verkettet.

arrays.concat([], []) = []

arrays.join_string

arrays.join_string(array_of_strings, optional_delimiter)

Beschreibung

Konvertiert ein Array von Strings in einen einzelnen String, der durch den optionalen Parameter getrennt ist. Wenn kein Trennzeichen angegeben ist, wird der leere String verwendet.

Parameterdatentypen

ARRAY_STRINGS, STRING

Rückgabetyp

STRING

Codebeispiele

Hier einige Beispiele für die Verwendung der Funktion:

Beispiel 1

In diesem Beispiel wird ein Array mit Elementen, die nicht null sind, mit einem Trennzeichen zusammengeführt.

arrays.join_string(["foo", "bar"], ",") = "foo,bar"

Beispiel 2

In diesem Beispiel wird ein Array mit einem Null-Element und einem Trennzeichen zusammengeführt.

arrays.join_string(["foo", NULL, "bar"], ",") = "foo,bar"

Beispiel 3

In diesem Beispiel wird ein Array mit nicht leeren Elementen ohne Trennzeichen zusammengeführt.

arrays.join_string(["foo", "bar"]) = "foobar"

arrays.length

arrays.length(repeatedField)

Beschreibung

Gibt die Anzahl der Elemente des wiederholten Felds zurück.

Parameterdatentypen

LIST

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

Gibt die Anzahl der Elemente des wiederholten Felds zurück.

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

Beispiel 2

Wenn sich mehrere wiederholte Felder auf dem Pfad befinden, wird die Gesamtzahl der Elemente des wiederholten Felds zurückgegeben.

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

arrays.max

arrays.max(array_of_ints_or_floats)

Beschreibung

Gibt das größte Element in einem Array oder null zurück, wenn das Array leer ist.

Parameterdatentypen

ARRAY_INTS|ARRAY_FLOATS

Rückgabetyp

FLOAT

Codebeispiele

Hier einige Beispiele für die Verwendung der Funktion:

Beispiel 1

In diesem Beispiel wird das größere Element in einem Array von Ganzzahlen zurückgegeben.

arrays.max([10, 20]) = 20.000000

Beispiel 2

In diesem Beispiel wird das größere Element in einem Array von Gleitkommazahlen zurückgegeben.

arrays.max([10.000000, 20.000000]) = 20.000000

arrays.min

arrays.min(array_of_ints_or_floats[, ignore_zeros=false])

Beschreibung

Gibt das kleinste Element in einem Array oder null zurück, wenn das Array leer ist. Wenn das zweite optionale Argument auf „true“ gesetzt ist, werden Elemente, die gleich null sind, ignoriert.

Parameterdatentypen

ARRAY_INTS|ARRAY_FLOATS, BOOL

Rückgabetyp

FLOAT

Codebeispiele

Hier einige Beispiele für die Verwendung der Funktion:

Beispiel 1

In diesem Beispiel wird das kleinste Element in einem Array von Ganzzahlen zurückgegeben.

arrays.min([10, 20]) = 10.000000

Beispiel 2

In diesem Beispiel wird das kleinste Element in einem Array von Gleitkommazahlen zurückgegeben.

arrays.min([10.000000, 20.000000]) = 10.000000

Beispiel 3

In diesem Beispiel wird das kleinste Element in einem Array von Gleitkommazahlen zurückgegeben, wobei die Nullen ignoriert werden.

arrays.min([10.000000, 20.000000, 0.0], true) = 10.000000

arrays.size

arrays.size( array )

Beschreibung

Gibt die Größe des Arrays zurück. Gibt 0 für ein leeres Array zurück.

Parameterdatentypen

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird ein String-Array mit zwei Elementen verwendet.

arrays.size(["test1", "test2"]) = 2

Beispiel 2

In diesem Beispiel wird ein int-Array mit drei Elementen verwendet.

arrays.size([1, 2, 3]) = 3

Beispiel 3

In diesem Beispiel wird ein Float-Array mit einem Element verwendet.

arrays.size([1.200000]) = 1

Beispiel 4

In diesem Beispiel wird ein leeres Array verwendet.

arrays.size([]) = 0

arrays.index_to_float

arrays.index_to_float(array, index)

Beschreibung

Gibt das Element am angegebenen Index eines Arrays zurück. Das Element an diesem Index wird als Gleitkommazahl zurückgegeben.

Der Index ist ein ganzzahliger Wert, der die Position eines Elements im Array darstellt. Standardmäßig hat das erste Element eines Arrays den Index 0 und das letzte Element den Index n–1, wobei n die Größe des Arrays ist. Mit der negativen Indexierung kann auf Arrayelemente relativ zum Ende des Arrays zugegriffen werden. Ein Index von -1 verweist beispielsweise auf das letzte Element im Array und ein Index von -2 auf das vorletzte Element im Array.

Parameterdatentypen

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird ein Element am Index 1 aus einem Array von Gleitkommazahlen abgerufen.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 1) // 2.1

Beispiel 2

Im folgenden Beispiel wird ein Element am Index -1 aus einem Array von Gleitkommazahlen abgerufen.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 0-1) // 4.6

Beispiel 3

Im folgenden Beispiel wird ein Element für einen Index abgerufen, der größer als die Größe des Arrays ist.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 6) // 0.0

Beispiel 4

Im folgenden Beispiel wird ein Element aus einem leeren Array abgerufen.

arrays.index_to_float([], 0) // 0.0

Beispiel 5

Im folgenden Beispiel wird ein Element am Index 1 aus einem String-Array abgerufen.

arrays.index_to_float(["1.2", "3.3", "2.4"], 1) // 3.3

Beispiel 6

Im folgenden Beispiel wird ein Element am Index 2 aus einem Array von Ganzzahlen abgerufen.

arrays.index_to_float([1, 3, 2], 2) // 2.0

arrays.index_to_int

arrays.index_to_int(array_of_inputs, index)

Beschreibung

Gibt den Wert an einem bestimmten Index in einem Array als Ganzzahl zurück.

Der Index ist ein ganzzahliger Wert, der die Position eines Elements im Array darstellt. Standardmäßig hat das erste Element eines Arrays den Index 0 und das letzte Element den Index n–1, wobei n die Größe des Arrays ist. Mit der negativen Indexierung kann auf Arrayelemente relativ zum Ende des Arrays zugegriffen werden. Ein Index von -1 verweist beispielsweise auf das letzte Element im Array und ein Index von -2 auf das vorletzte Element im Array.

Parameterdatentypen

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Rückgabetyp

INT

Codebeispiele

Beispiel 1

Dieser Funktionsaufruf gibt 0 zurück, wenn der Wert am Index ein nicht numerischer String ist.

arrays.index_to_int(["str0", "str1", "str2"], 1) = 0

Beispiel 2

Diese Funktion gibt das Element am Index -1 zurück.

arrays.index_to_int(["44", "11", "22", "33"], 0-1) = 33

Beispiel 3

Gibt 0 für das Element außerhalb des gültigen Bereichs zurück.

arrays.index_to_int(["44", "11", "22", "33"], 5) = 0

Beispiel 4

Diese Funktion ruft das Element aus dem Gleitkomma-Array am Index 1 ab.

arrays.index_to_int([1.100000, 1.200000, 1.300000], 1) = 1

Beispiel 5

Diese Funktion ruft das Element aus dem int-Array am Index 0 ab.

arrays.index_to_int([1, 2, 3], 0) = 1

arrays.index_to_str

arrays.index_to_str(array, index)

Beschreibung

Gibt das Element am angegebenen Index aus dem Array als String zurück. Der Index ist ein ganzzahliger Wert, der die Position eines Elements im Array darstellt. Standardmäßig hat das erste Element eines Arrays den Index 0 und das letzte Element den Index n–1, wobei n die Größe des Arrays ist. Mit der negativen Indexierung kann auf Arrayelemente vom Ende des Arrays aus zugegriffen werden. Ein Index von -1 verweist beispielsweise auf das letzte Element im Array und ein Index von -2 auf das vorletzte Element im Array.

Parameterdatentypen

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird ein Element am Index 1 aus einem Array von Strings abgerufen.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 1) // "test2"

Beispiel 2

Im folgenden Beispiel wird ein Element am Index -1 (letztes Element des Arrays) aus einem Array von Strings abgerufen.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 0-1) // "test4"

Beispiel 3

Im folgenden Beispiel wird ein Element für einen Index abgerufen, der größer als die Größe des Arrays ist. In diesem Fall wird ein leerer String zurückgegeben.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 6) // ""

Beispiel 4

Im folgenden Beispiel wird ein Element aus einem leeren Array abgerufen.

arrays.index_to_str([], 0) // ""

Beispiel 5

Im folgenden Beispiel wird ein Element am Index 0 aus einem Array von Gleitkommazahlen abgerufen. Die Ausgabe wird als String zurückgegeben.

arrays.index_to_str([1.200000, 3.300000, 2.400000], 0) // "1.2"

Beispiel 6

Im folgenden Beispiel wird ein Element am Index 2 aus einem Array von Ganzzahlen abgerufen. Die Ausgabe erfolgt in Form eines Strings.

arrays.index_to_str([1, 3, 2], 2) // "2"

cast.as_bool

cast.as_bool(string_or_int)

Beschreibung

Die Funktion konvertiert einen Ganzzahl- oder Stringwert in einen booleschen Wert. Funktionsaufrufe mit Werten, die nicht umgewandelt werden können, geben FALSE zurück. Gibt nur für die Ganzzahl 1 und den String „true“ (Groß-/Kleinschreibung wird nicht beachtet) TRUE zurück.

Parameterdatentypen

INT|STRING

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

In diesem Beispiel wird gezeigt, wie ein nicht boolescher String umgewandelt wird.

cast.as_bool("123") = false

Beispiel 2

Wahrer Integerwert (1)

cast.as_bool(1) = true

Beispiel 3

Truthy-String

cast.as_bool("true") = true

Beispiel 4

Wahrheitsgemäßer String in Großbuchstaben

cast.as_bool("TRUE") = true

Beispiel 5

Negative Ganzzahl

cast.as_bool(0-1) = false

Beispiel 6

Falsche Ganzzahl (0)

cast.as_bool(0) = false

Beispiel 7

Leerer String

cast.as_bool("") = false

cast.as_float

cast.as_float(string_to_cast)

Beschreibung

Konvertiert einen numerischen String in eine Gleitkommazahl. Bei Funktionsaufrufen mit Werten, die nicht umgewandelt werden können, wird 0 zurückgegeben. Gleitkommazahlen behalten die Genauigkeit von bis zu 7 Dezimalstellen bei.

Parameterdatentypen

STRING

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

Wenn Sie einen nicht numerischen String umwandeln, wird 0 zurückgegeben.

cast.as_float("str") = 0.0000000

Beispiel 2

Wenn Sie einen leeren String umwandeln, wird 0 zurückgegeben.

cast.as_float("") = 0.0000000

Beispiel 3

Beim Umwandeln eines gültigen numerischen Strings wird ein Gleitkommawert zurückgegeben.

cast.as_float("1.012345678") = 1.0123456

cast.as_string

cast.as_string(int_or_bytes_or_bool, optional_default_string)

Beschreibung

Die Funktion cast.as_string wandelt einen INT-, BYTES- oder BOOL-Wert in seine Stringdarstellung um. Sie können ein optionales default_string-Argument angeben, um Fälle zu verarbeiten, in denen die Übertragung fehlschlägt. Wenn Sie das Argument default_string weglassen oder die Eingabe eine ungültige UTF-8- oder BASE64-Bytefolge ist, gibt die Funktion einen leeren String zurück.

Parameterdatentypen

INT|BYTES|BOOL, STRING

Rückgabetyp

STRING

Codebeispiele

Ganzzahl zu String konvertieren

Die Funktion konvertiert die Ganzzahl 123 in den String "123".

cast.as_string(123) = "123"

Float- in Stringkonvertierung

Die Funktion konvertiert die Gleitkommazahl 2.25 in den String "2.25".

cast.as_string(2.25) = "2.25"

Konvertierung von Byte in String

Die Funktion konvertiert den binären Rohwert b'01 in den String "\x01".

cast.as_string(b'01, "") = "\x01"

Boolesche Werte in Strings umwandeln

Die Funktion konvertiert den booleschen Wert true in den String "true".

cast.as_string(true, "") = "true"

Fehler bei der Umwandlung (Standardwert ist der optional angegebene String)

Wenn der angegebene Wert ungültig ist, wird standardmäßig der String "casting error" verwendet.

cast.as_string(9223372036854775808, "casting error") = "casting error"

Fingerprint

hash.fingerprint2011(byteOrString)

Beschreibung

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

Parameterdatentypen

BTYE, STRING

Rückgabetyp

INT

Codebeispiel

id_fingerprint = hash.fingerprint2011("user123")

Gruppe

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. Sie können jedoch auswählen, welche Felder gruppiert werden sollen, um eine Erkennung auszulösen. Mit der Gruppenfunktion können Sie Informationen zu einer bestimmten Einheit (z. B. einem Hostnamen, einer IP-Adresse oder einer Nutzer-ID) für verschiedene Substantivtypen abrufen.

Codebeispiele

Beispiel 1

Fassen Sie alle IP-Adressen zusammen und geben Sie eine absteigende Anzahl der häufigsten IP-Adressen im gescannten Zeitraum an.

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

hash.sha256

hash.sha256(string)

Beschreibung

Gibt einen SHA-256-Hash des Eingabestrings zurück.

Parameterdatentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird der SHA-256-Hashwert angezeigt, wenn die Eingabe ein gültiger String ist.

hash.sha256("str") = "8c25cb3686462e9a86d2883c5688a22fe738b0bbc85f458d2d2b5f3f667c6d5a"

Beispiel 2

In diesem Beispiel wird der SHA-256-Hash angezeigt, wenn die Eingabe ein leerer String ist.

hash.sha256("") = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

math.abs

math.abs(numericExpression)

Beschreibung

Gibt den Absolutwert 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 von der angegebenen Zeit (in Sekunden seit der Unix-Epoche) entfernt war, unabhängig davon, ob das Ereignis vor oder nach der angegebenen Zeit eingetreten ist. Ein Aufruf von math.abs kann nicht von mehreren Variablen oder Platzhaltern abhängen. Sie können beispielsweise 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.ceil

math.ceil(number)

Beschreibung

Gibt die kleinste Ganzzahl zurück, die nicht kleiner als die angegebene Zahl ist (Aufrunden). Gibt 0 zurück, wenn die Eingabe NULL oder zu groß für einen int64-Wert ist.

Parameterdatentypen

FLOAT

Rückgabetyp

INT

Codebeispiele

Dieser Abschnitt enthält Beispiele für die Verwendung von math.ceil.

Beispiel 1

In diesem Beispiel wird die kleinste Ganzzahl zurückgegeben, die größer oder gleich einer ganzen Zahl ist.

math.ceil(2.000000) = 2

Beispiel 2

In diesem Beispiel wird die kleinste Ganzzahl zurückgegeben, die größer oder gleich einer negativen Zahl ist.

math.ceil(0-1.200000) = -1

Beispiel 3

In diesem Beispiel wird 0 als die kleinste Ganzzahl zurückgegeben, die größer oder gleich einer Zahl ist, die zu groß für eine 64-Bit-Ganzzahl ist.

math.ceil(184467440737095516160.0) = 0

math.floor

math.floor(float_val)

Beschreibung

Gibt den größten Ganzzahlwert zurück, der nicht größer als der angegebene Wert ist (Abrunden). Gibt 0 zurück, wenn die Eingabe NULL oder zu groß für einen int64-Wert ist.

Parameterdatentypen

FLOAT

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird ein Fall mit einer positiven Zahl gezeigt.

math.floor(1.234568) = 1

Beispiel 2

In diesem Beispiel wird ein Fall mit einer negativen Zahl gezeigt.

math.floor(0-1.234568) = -2

Beispiel 3

Dieses Beispiel zeigt einen Fall mit dem Wert 0.

math.floor(0.000000) = 0

math.geo_distance

math.geo_distance(longitude1, latitude1, longitude2, latitude2))

Beschreibung

Gibt die Entfernung zwischen zwei geografischen Standorten (Koordinaten) in Metern zurück. Gibt -1 zurück, wenn die Koordinaten ungültig sind.

Parameterdatentypen

FLOAT, FLOAT, FLOAT, FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird die Entfernung zurückgegeben, wenn alle Parameter gültige Koordinaten sind:

math.geo_distance(-122.020287, 37.407574, -122.021810, 37.407574) = 134.564318

Beispiel 2

Im folgenden Beispiel wird die Entfernung zurückgegeben, wenn einer der Parameter eine gekürzte Koordinate ist:

math.geo_distance(-122.000000, 37.407574, -122.021810, 37.407574) = 1926.421905

Beispiel 3

Im folgenden Beispiel wird -1 zurückgegeben, wenn einer der Parameter eine ungültige Koordinate ist:

math.geo_distance(0-122.897680, 37.407574, 0-122.021810, 97.407574) = -1.000000

Beispiel 4

Im folgenden Beispiel wird 0 zurückgegeben, wenn die Koordinaten identisch sind:

math.geo_distance(-122.897680, 37.407574, -122.897680, 37.407574) = 0.000000

math.is_increasing

math.is_increasing(num1, num2, num3)

Beschreibung

Akzeptiert eine Liste numerischer Werte (Ganzzahlen oder Gleitkommazahlen) und gibt True zurück, wenn die Werte in aufsteigender Reihenfolge sind, andernfalls False.

Parameterdatentypen

INT|FLOAT, INT|FLOAT, INT|FLOAT

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

Dieses Beispiel enthält zeitstempelähnliche Werte in Sekunden.

math.is_increasing(1716769112, 1716769113, 1716769114) = true

Beispiel 2

Dieses Beispiel enthält einen negativen Double-Wert, einen INT64-Wert von null und einen positiven INT64-Wert.

math.is_increasing(-1.200000, 0, 3) = true

Beispiel 3

Dieses Beispiel enthält einen negativen Double-Wert, einen INT64-Wert von null und einen negativen INT64-Wert.

math.is_increasing(0-1.200000, 0, 0-3) = false

Beispiel 4

Dieses Beispiel enthält zwei negative Gleitkommazahlen und einen INT64-Wert von null.

math.is_increasing(0-1.200000, 0-1.50000, 0) = false

Beispiel 5

Dieses Beispiel enthält einen negativen Double-Wert und zwei Werte, die identisch sind.

math.is_increasing(0-1.200000, 0, 0) = false

math.log

math.log(numericExpression)

Beschreibung

Gibt den natürlichen Logarithmus eines Ganzzahl- oder Gleitkommaausdrucks zurück.

Parameterdatentypen

NUMBER

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

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

math.pow

math.pow(base, exponent)

Beschreibung

Gibt den Wert des ersten Arguments zurück, potenziert mit dem zweiten Argument. Gibt bei einem Überlauf 0 zurück.

Parameterdatentypen

Basis: INT|FLOAT Exponent: INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem Beispiel wird ein Ganzzahlfall dargestellt.

math.pow(2, 2) // 4.00

Beispiel 2

Dieses Beispiel zeigt einen Bruch als Basisfall.

math.pow(2.200000, 3) // 10.648

Beispiel 3

In diesem Beispiel wird ein Fall mit Bruchbasis und Potenz gezeigt.

math.pow(2.200000, 1.200000) // 2.575771

Beispiel 4

In diesem Beispiel wird ein Fall mit negativer Leistung gezeigt.

math.pow(3, 0-3) // 0.037037

Beispiel 5

In diesem Beispiel wird ein Fall mit Bruchpotenz gezeigt.

math.pow(3, 0-1.200000) // 0.267581

Beispiel 6

In diesem Beispiel wird ein negativer Basiswert gezeigt.

math.pow(0-3, 0-3) // -0.037037

Beispiel 7

In diesem Beispiel wird ein Fall mit null Basiswerten gezeigt.

math.pow(0, 3) // 0

Beispiel 8

In diesem Beispiel wird ein Fall mit null Leistung gezeigt.

math.pow(9223372036854775807, 0) // 1

Beispiel 9

In diesem Beispiel wird ein großer Basisfall dargestellt.

math.pow(9223372036854775807, 1.200000) // 57262152889751593549824

math.random

math.random()

Beschreibung

Erzeugt einen Pseudozufallswert vom Typ DOUBLE im Bereich von [0, 1), einschließlich 0 und exklusiv 1.

Rückgabetyp

FLOAT

Codebeispiele

Im folgenden Beispiel wird geprüft, ob der Zufallswert im Bereich [0, 1) liegt. none if(math.random() >= 0 and math.random() < 1) = true

math.round

math.round(numericExpression, decimalPlaces)

Beschreibung

Gibt einen Wert zurück, der auf die nächste Ganzzahl oder auf die angegebene Anzahl von Dezimalstellen gerundet wurde.

Parameterdatentypen

NUMBER

Rückgabetyp

NUMBER

Codebeispiele

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

math.sqrt

math.sqrt(number)

Beschreibung

Gibt die Quadratwurzel der angegebenen Zahl zurück. Gibt bei negativen Zahlen 0 zurück.

Parameterdatentypen

INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem Beispiel wird die Quadratwurzel eines int-Arguments zurückgegeben.

math.sqrt(3) = 1.732051

Beispiel 2

In diesem Beispiel wird die Quadratwurzel eines negativen int-Arguments zurückgegeben.

math.sqrt(-3) = 0.000000

Beispiel 3

In diesem Beispiel wird die Quadratwurzel des Arguments „Null“ zurückgegeben.

math.sqrt(0) = 0.000000

Beispiel 4

In diesem Beispiel wird die Quadratwurzel eines Gleitkommaarguments zurückgegeben.

math.sqrt(9.223372) = 3.037000

Beispiel 5

In diesem Beispiel wird die Quadratwurzel eines negativen Gleitkommaarguments zurückgegeben.

math.sqrt(0-1.200000) = 0.000000

Messwerte

Mit Messwertfunktionen lassen sich große Mengen an Verlaufsdaten aggregieren. Sie können dies in Ihrer Regel verwenden, indem Sie metrics.functionName() im Abschnitt „Ergebnis“ angeben.

Weitere Informationen finden Sie unter YARA-L-Messwerte.

net.ip_in_range_cidr

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Beschreibung

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

Mit YARA-L können Sie mit der Anweisung net.ip_in_range_cidr() nach UDM-Ereignissen für alle IP-Adressen in einem Subnetzwerk suchen. Sowohl IPv4 als auch IPv6 werden unterstützt.

Wenn Sie in einem Bereich von IP-Adressen suchen möchten, geben Sie ein IP-UDM-Feld und einen CIDR-Bereich an. YARA-L kann sowohl einzelne als auch sich wiederholende IP-Adressfelder verarbeiten.

Wenn Sie in einem Bereich von IP-Adressen suchen möchten, geben Sie ein ip-UDM-Feld und einen CIDR-Bereich (Classless Inter-Domain Routing) an. YARA-L kann sowohl einzelne als auch sich wiederholende 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")

Ein Beispiel für eine Regel mit der net.ip_in_range_cidr()-Anweisung finden Sie unter Einzelnes Ereignis innerhalb eines IP-Adressbereichs.

re.regex

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

• YARA-L-Syntax verwenden – bezieht sich auf Ereignisse. Das ist eine allgemeine Darstellung dieser Syntax:

  $e.field = /regex/
  

• Verwendung der YARA-L-Syntax: Als Funktion mit den folgenden Parametern:

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

  Das ist 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 am Ende des regulären Ausdrucks hinzuzufügen.

Hinweise

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

Parameterdatentypen

STRING, STRING

Typen von Parameterausdrücken

ANY, ANY

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

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

re.capture

re.capture(stringText, regex)

Beschreibung

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

Diese Funktion akzeptiert zwei Argumente:

• stringText: Der ursprüngliche String, in dem gesucht werden soll.
• regex: Der reguläre Ausdruck, der das Suchmuster angibt.

Der reguläre Ausdruck kann 0 oder 1 Erfassungsgruppen in Klammern enthalten. Wenn der reguläre Ausdruck keine 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 $e.principal.hostname in diesem Beispiel „aaa1bbaa2“ enthält, ist Folgendes wahr, da die Funktion die erste Instanz zurückgibt. Dieses Beispiel enthält 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 test@google.com ist, 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 auslassen, indem Sie den leeren String ausschließen. Das 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

re.replace(stringText, replaceRegex, replacementText)

Beschreibung

Führt einen regulären Ausdrucksersatz durch.

Diese Funktion akzeptiert drei Argumente:

• stringText: Der Originalstring.
• replaceRegex: Der reguläre Ausdruck, der das Suchmuster angibt.
• replacementText: Der Text, der in jede Übereinstimmung eingefügt werden soll.

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

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

Parameterdatentypen

STRING, STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

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

"email@google.org" = re.replace($e.network.email.from, "com", "org")

Beispiel 2

In diesem Beispiel werden Escape-Ziffern mit Backslash im replacementText-Argument verwendet, um auf Übereinstimmungen mit dem replaceRegex-Muster zu verweisen.

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

Beispiel 3

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

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

Wenn Sie einen leeren String ersetzen möchten, 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

optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

Beschreibung

Mit dieser Funktion wird anhand einer deterministischen Stichprobenerhebung entschieden, ob ein Ereignis berücksichtigt werden soll. Diese Funktion gibt Folgendes zurück:

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

Diese Funktion ist nützlich für Optimierungsszenarien, in denen Sie nur eine Teilmenge von Ereignissen verarbeiten möchten. Entspricht:

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Parameterdatentypen

• byteOrString: Ausdruck, der entweder 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

strings.base64_decode(encodedString)

Beschreibung

Gibt einen String mit der base64-decodierten Version des codierten Strings zurück.

Diese Funktion akzeptiert 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

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

Beschreibung

Diese Funktion akzeptiert eine unbegrenzte Anzahl von Argumenten und gibt den Wert des ersten Ausdrucks zurück, der nicht zu einem leeren String ausgewertet wird (z. B. „Wert ungleich null“). Wenn alle Argumente als leerer String ausgewertet werden, 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

Im folgenden Beispiel werden Stringvariablen als Argumente verwendet. Die Bedingung wird als „true“ ausgewertet, wenn (1) $e.network.email.from gleich suspicious@gmail.com ist oder (2) $e.network.email.from leer ist und $e.network.email.to gleich suspicious@gmail.com ist.

"suspicious@gmail.com" = 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. Bei dieser Bedingung wird die erste IP-Adresse ungleich null aus dem Ereignis $e mit den Werten in der Referenzliste ip_watchlist verglichen. Die Reihenfolge, in der die Argumente in diesem Aufruf zusammengeführt werden, entspricht der Reihenfolge, in der sie in der Regelbedingung aufgeführt sind:

1. $e.principal.ip wird zuerst ausgewertet.
2. Als Nächstes wird $e.src.ip ausgewertet.
3. Als Nächstes wird $e.target.ip ausgewertet.
4. Schließlich wird der String „No 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 Ereignis $e1 und Ereignis $e2 zusammenzuführen. Es wird ein Compilerfehler zurückgegeben, da die Argumente unterschiedliche Ereignisvariablen sind.

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

strings.concat

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

Beschreibung

Gibt die Verkettung einer unbegrenzten Anzahl von Elementen zurück, die jeweils ein String, eine Ganzzahl oder eine Gleitkommazahl sein können.

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 aus demselben Ereignis, $e, und werden verkettet, um einen String zurückzugeben.

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

Beispiel 2

Im folgenden Beispiel werden eine Stringvariable und ein Stringliteral als Argumente verwendet.

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

Beispiel 3

Im folgenden Beispiel werden eine String-Variable und ein Gleitkomma-Literal als Argumente verwendet. Wenn sie als Strings dargestellt werden, werden Gleitkommazahlen, die ganze Zahlen sind, ohne Dezimalkomma formatiert (z. B. wird 1,0 als „1“ dargestellt). Außerdem werden Gleitkommazahlen, die mehr als 16 Dezimalstellen haben, auf die 16. 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 Compilerfehler zurückgegeben, da die Argumente unterschiedliche Ereignisvariablen sind.

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

strings.contains

strings.contains( str, substr )

Beschreibung

Gibt „true“ zurück, wenn ein bestimmter String den angegebenen Teilstring enthält. Andernfalls wird „false“ zurückgegeben.

Parameterdatentypen

STRING, STRING

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

In diesem Beispiel wird „true“ zurückgegeben, da der String den Teilstring „is“ enthält.

strings.contains("thisisastring", "is") = true

Beispiel 2

In diesem Beispiel wird „false“ zurückgegeben, da der String den Teilstring „that“ nicht enthält.

strings.contains("thisisastring", "that") = false

strings.count_substrings

strings.count_substrings(string_to_search_in, substring_to_count)

Beschreibung

Gibt bei Angabe eines Strings und eines Teilstrings einen int64-Wert zurück, der die Anzahl der sich nicht überschneidenden Vorkommen des Teilstrings im String angibt.

Parameterdatentypen

STRING, STRING

Rückgabetyp

INT

Codebeispiele

Dieser Abschnitt enthält Beispiele, in denen berechnet wird, wie oft ein Teilstring in einem bestimmten String vorkommt.

Beispiel 1

In diesem Beispiel werden ein String, der nicht null ist, und ein einzelnes Teilstringzeichen verwendet, das nicht null ist.

strings.count_substrings("this`string`has`four`backticks", "`") = 4

Beispiel 2

In diesem Beispiel wird ein String verwendet, der nicht null ist, und ein Substring, der nicht null ist und mehr als ein Zeichen enthält.

strings.count_substrings("str", "str") = 1

Beispiel 3

In diesem Beispiel wird ein String verwendet, der nicht null ist, und ein leerer Teilstring.

strings.count_substrings("str", "") = 0

Beispiel 4

In diesem Beispiel wird ein leerer String und ein nicht null-Substring mit mehr als einem Zeichen verwendet.

strings.count_substrings("", "str") = 0

Beispiel 5

In diesem Beispiel werden ein leerer String und ein leerer Substring verwendet.

strings.count_substrings("", "") = 0

Beispiel 6

In diesem Beispiel werden ein String, der nicht null ist, und ein Substring, der nicht null ist und aus mehr als einem Zeichen besteht und mehr als einmal vorkommt, verwendet.

strings.count_substrings("fooABAbarABAbazABA", "AB") = 3

Beispiel 7

In diesem Beispiel werden ein String, der nicht null ist, und ein Substring, der nicht null ist und aus mehr als einem Zeichen besteht und mehr als einmal vorkommt, verwendet. Es wird die Einschränkung bei sich überschneidenden Teilstring-Vorkommen hervorgehoben.

strings.count_substrings("ABABABA", "ABA") = 2

strings.extract_domain

strings.extract_domain(url_string)

Beschreibung

Extrahiert die Domain aus einem String.

Parameterdatentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Dieses Beispiel zeigt einen leeren String.

strings.extract_domain("") = ""

Beispiel 2

Zufälliger String, keine URL

strings.extract_domain("1234") = ""

Beispiel 3

mehrere umgekehrte Schrägstriche

strings.extract_domain("\\\\") = ""

Beispiel 4

Nicht alphabetische Zeichen werden ordnungsgemäß verarbeitet

strings.extract_domain("http://例子.卷筒纸.中国") = "卷筒纸.中国"

Beispiel 5

URIs verarbeiten

strings.extract_domain("mailto:?to=&subject=&body=") = ""

Beispiel 6

Mehrere Zeichen vor der eigentlichen URL

strings.extract_domain("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "google.com"

Beispiel 7

Sonderzeichen im URI #

strings.extract_domain("test#@google.com") = ""

Beispiel 8

Sonderzeichen in URL #

strings.extract_domain("https://test#@google.com") = ""

Beispiel 9

positiver Testlauf

strings.extract_domain("https://google.co.in") = "google.co.in"

strings.extract_hostname

strings.extract_hostname(string)

Beschreibung

Extrahiert den Hostnamen aus einem String. Bei dieser Funktion wird zwischen Groß- und Kleinschreibung unterschieden.

Parameterdatentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird ein leerer String zurückgegeben.

strings.extract_hostname("") = ""

Beispiel 2

Zufälliger String, keine URL

strings.extract_hostname("1234") = "1234"

Beispiel 3

Mehrere umgekehrte Schrägstriche

strings.extract_hostname("\\\\") = ""

Beispiel 4

Nicht zum lateinischen Alphabet gehörige Zeichen werden korrekt verarbeitet

strings.extract_hostname("http://例子.卷筒纸.中国") = "例子.卷筒纸.中国"

Beispiel 5

URIs verarbeiten

strings.extract_hostname("mailto:?to=&subject=&body=") = "mailto"

Beispiel 6

Mehrere Zeichen vor der eigentlichen URL

strings.extract_hostname("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "www.google.com"

Beispiel 7

Sonderzeichen im URI #

strings.extract_hostname("test#@google.com") = "test"

Beispiel 8

Sonderzeichen in URL #

strings.extract_hostname("https://test#@google.com") = "test"

strings.from_base64

strings.from_base64(base64_encoded_string)

Beschreibung

Die Funktion konvertiert einen base64-codierten STRING-Wert in einen binären BYTES-Rohwert. Funktionsaufrufe mit Werten, die nicht umgewandelt werden können, geben standardmäßig ein leeres BYTES zurück.

Parameterdatentypen

STRING

Rückgabetyp

BYTES

Codebeispiele

Umwandlung von Base64-codiertem String in Byte

Die Funktion wandelt einen base64-codierten String in seine binäre Rohdarstellung um.

strings.from_base64("AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA=") = b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000

Fehlgeschlagene Conversion (Standardwert: leere Bytes)

Die Funktion gibt standardmäßig leere Bytes zurück, wenn der angegebene Wert ungültig ist.

strings.from_base64("invalid-value") = b'

strings.from_hex

strings.from_hex(hex_string)

Beschreibung

Gibt die Bytes zurück, die dem angegebenen Hexadezimalstring zugeordnet sind.

Parameterdatentypen

STRING

Rückgabetyp

BYTES

Codebeispiele

Ruft die Bytes ab, die einem bestimmten Hexadezimalstring zugeordnet sind.

Beispiel 1

In diesem Beispiel werden Zeichen konvertiert, die keine Hexadezimalzeichen sind.

strings.from_hex("str") // returns empty bytes

Beispiel 2

Dieses Beispiel zeigt die Eingabe mit einem leeren String.

strings.from_hex("") // returns empty bytes

Beispiel 3

In diesem Beispiel wird die Konvertierung von Hexadezimalstrings gezeigt.

strings.from_hex("1234") // returns 1234 bytes

Beispiel 4

Dieses Beispiel zeigt die Konvertierung von Nicht-ASCII-Zeichen.

strings.from_hex("筒纸.中国") // returns empty bytes

strings.length

strings.length(string_value)

Beschreibung

Gibt die Anzahl der Zeichen im Eingabestring zurück.

Parameterdatentypen

STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

Das folgende Beispiel zeigt einen String-Test.

strings.length("str") = 3

Beispiel 2

Im Folgenden finden Sie ein Beispiel mit einem leeren String als Eingabe.

strings.length("") = 0

Beispiel 3

Im Folgenden finden Sie ein Beispiel mit einer Sonderzeichenfolge.

strings.length("!@#$%^&*()-_") = 12

Beispiel 4

Im Folgenden finden Sie ein Beispiel mit einem String mit Leerzeichen.

strings.length("This is a test string") = 21

strings.ltrim

strings.ltrim(string_to_trim, cutset)

Beschreibung

Entfernt vorangestellte Leerzeichen aus einem bestimmten String. Mit dieser Funktion werden führende Zeichen entfernt, die im Cutset vorhanden sind.

Parameterdatentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Im Folgenden finden Sie einige Anwendungsbeispiele.

Beispiel 1

In diesem Beispiel werden für das erste und zweite Argument dieselben Werte verwendet.

strings.ltrim("str", "str") = ""

Beispiel 2

In diesem Beispiel wird ein leerer String als zweites Argument verwendet.

strings.ltrim("str", "") = "str"

Beispiel 3

In diesem Beispiel wird ein leerer String als erstes Argument und ein String als zweites Argument verwendet.

strings.ltrim("", "str") = ""

Beispiel 4

In diesem Beispiel werden Strings mit Leerzeichen und ein String als zweites Argument verwendet.

strings.ltrim("a aastraa aa ", " a") = "straa aa "

strings.reverse

strings.reverse(STRING)

Beschreibung

Gibt einen String zurück, der die Umkehrung des Eingabestrings ist.

Parameterdatentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird ein kurzer String übergeben.

strings.reverse("str") = "rts"  // The function returns 'rts'.

Beispiel 2

Im folgenden Beispiel wird ein leerer String übergeben.

strings.reverse("") = ""

Beispiel 3

Im folgenden Beispiel wird ein Palindrom übergeben.

strings.reverse("tacocat") = "tacocat"

strings.rtrim

strings.rtrim(string_to_trim, cutset)

Beschreibung

Entfernt nachfolgende Leerzeichen aus einem bestimmten String. Entfernt nachgestellte Zeichen, die in diesem Cutset vorhanden sind.

Parameterdatentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Im Folgenden finden Sie einige Anwendungsbeispiele.

Beispiel 1

Im folgenden Beispiel wird derselbe String als erstes und zweites Argument übergeben.

strings.rtrim("str", "str") = ""

Beispiel 2

Im folgenden Beispiel wird ein leerer String als zweites Argument übergeben.

strings.rtrim("str", "") = "str"

Beispiel 3

Im folgenden Beispiel wird ein leerer String als erstes Argument und ein nicht leerer String als zweites Argument übergeben.

strings.rtrim("", "str") = ""

Beispiel 4

Im folgenden Beispiel wird ein String mit Leerzeichen als erstes Argument und ein nicht leerer String als zweites Argument übergeben.

strings.rtrim("a aastraa aa ", " a") = "a aasstr"

strings.to_lower

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.

"test@google.com" = strings.to_lower($e.network.email.to)

strings.to_upper

strings.to_upper(string_val)

Beschreibung

Gibt den ursprünglichen String mit allen alphabetischen Zeichen in Großbuchstaben zurück.

Parameterdatentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird das angegebene Argument in Großbuchstaben zurückgegeben.

strings.to_upper("example") = "EXAMPLE"

strings.trim

strings.trim(string_to_trim, cutset)

Beschreibung

Entfernt voran- und nachgestellte Leerzeichen aus einem bestimmten String. Außerdem werden unerwünschte Zeichen (die durch das Argument „cutset“ angegeben werden) aus dem Eingabestring entfernt.

Parameterdatentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Im Folgenden finden Sie einige Anwendungsbeispiele.

Beispiel 1

Im folgenden Beispiel wird derselbe String als Eingabestring und als Cutset übergeben, was zu einem leeren String führt.

strings.trim("str", "str") // ""

Beispiel 2

Im folgenden Beispiel wird ein leerer String als „cutset“ übergeben. Das Ergebnis ist der ursprüngliche String „str“, da im „cutset“ keine zu entfernenden Zeichen angegeben sind.

strings.trim("str", "") = "str"

Beispiel 3

Im folgenden Beispiel gibt die Funktion einen leeren String zurück, da der Eingabestring bereits leer ist und keine Zeichen entfernt werden können.

strings.trim("", "str") = ""

Beispiel 4

Im folgenden Beispiel gibt die Funktion „str“ zurück, da durch die Funktion „trim“ Folgendes entfernt wird:

• Nachfolgende Leerzeichen in „a aastraa aa “
• die im Cutset angegebenen Zeichen (Leerzeichen, a)

strings.trim("a aastraa aa ", " a") = "str"

strings.url_decode

strings.url_decode(url_string)

Beschreibung

Entschlüsselt die Escapezeichen in einem URL-String und verarbeitet codierte UTF-8-Zeichen. Gibt einen leeren String zurück, wenn die Decodierung fehlschlägt.

Parameterdatentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Dieses Beispiel zeigt einen positiven Testlauf.

strings.url_decode("three%20nine%20four") = "three nine four"

Beispiel 2

Dieses Beispiel zeigt einen Fall mit einem leeren String.

strings.url_decode("") // ""

Beispiel 3

In diesem Beispiel wird die Verarbeitung von nicht alphabetischen Zeichen gezeigt.

strings.url_decode("%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B") // "上海+中國"

Beispiel 4

In diesem Beispiel wird eine URL dekodiert.

strings.url_decode("http://www.google.com%3Fparam1%3D%22+1+%3E+2+%22%26param2%3D2%3B") // 'http://www.google.com?param1="+1+>+2+"&param2=2;'

timestamp.as_unix_seconds

timestamp.as_unix_seconds(timestamp [, time_zone])

Beschreibung

Diese Funktion gibt eine Ganzzahl zurück, die die Anzahl der Sekunden seit der Unix-Epoche für den angegebenen Zeitstempelstring darstellt.

• timestamp ist ein String, der einen gültigen Epoch-Zeitstempel darstellt. Das Format muss %F %T sein.
• time_zone ist optional und ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, lautet der Standardwert GMT. Sie können Zeitzonen mit Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der Zeitzonendatenbank, z. B. America/Los_Angeles. Weitere Informationen finden Sie in der Liste der Zeitzonen in der tz-Datenbank auf Wikipedia.
  • Der Zeitzonenversatz von UTC im Format(+|-)H[H][:M[M]], z. B. „-08:00“.

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

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

Parameterdatentypen

STRING, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

Gültiger Epoch-Zeitstempel

timestamp.as_unix_seconds("2024-02-22 10:43:00") = 1708598580

Beispiel 2

Gültiger Epoch-Zeitstempel mit der Zeitzone „America/New_York“

timestamp.as_unix_seconds("2024-02-22 10:43:00", "America/New_York") = 1708616580

timestamp.current_seconds

timestamp.current_seconds()

Beschreibung

Gibt eine Ganzzahl zurück, die die aktuelle Zeit in Unix-Sekunden darstellt. Dieser Wert entspricht in etwa dem Zeitstempel der Erkennung und basiert darauf, wann die Regel ausgeführt wird. Diese Funktion ist ein Synonym für die Funktion timestamp.now().

Parameterdatentypen

NONE

Rückgabetyp

INT

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird true zurückgegeben, wenn das Zertifikat seit mehr als 24 Stunden abgelaufen ist. Die Zeitdifferenz wird berechnet, indem die aktuellen Unix-Sekunden subtrahiert und dann mit dem Operator „größer als“ verglichen werden.

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

timestamp.get_date

timestamp.get_date(unix_seconds [, time_zone])

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden seit der Unix-Epoche darstellt, z. B. $e.metadata.event_timestamp.seconds, oder ein Platzhalter, der diesen Wert enthält.
• time_zone ist optional und ein String, der eine time_zone darstellt. Wenn nicht angegeben, ist der Standardwert „GMT“. Sie können Zeitzonen mit Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie auf dieser Seite in der Spalte TZ Database Name.
  • Der Zeitzonenversatz von UTC im Format(+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige time_zone-Spezifizierer, die Sie als zweites Argument an Funktionen zur Zeitausgabe ü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. Der Standardwert ist also „GMT“.

$ts = $e.metadata.collected_timestamp.seconds

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

Beispiel 2

In diesem Beispiel wird ein Stringliteral verwendet, um die time_zone zu definieren.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_minute

timestamp.get_minute(unix_seconds [, time_zone])

Beschreibung

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

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

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

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

Parameterdatentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Beispiel 2

In diesem Beispiel wird ein Stringliteral verwendet, um die time_zone zu definieren.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_hour

timestamp.get_hour(unix_seconds [, time_zone])

Beschreibung

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

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

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

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

Parameterdatentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Beispiel 2

In diesem Beispiel wird ein Stringliteral verwendet, um die time_zone zu definieren.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_day_of_week

timestamp.get_day_of_week(unix_seconds [, time_zone])

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden seit der Unix-Epoche darstellt, z. B. $e.metadata.event_timestamp.seconds, oder ein Platzhalter, der diesen Wert enthält.
• time_zone ist optional und ein String, der eine time_zone darstellt. Wenn nicht angegeben, ist der Standardwert „GMT“. Sie können Zeitzonen mit Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie auf dieser Seite in der Spalte TZ Database Name.
  • Der Zeitzonenversatz von UTC im Format(+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige time_zone-Spezifizierer, die Sie als zweites Argument an Funktionen zur Zeitausgabe ü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. Der Standardwert ist also „GMT“.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6

Beispiel 2

In diesem Beispiel wird ein Stringliteral verwendet, um die time_zone zu definieren.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.get_timestamp

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

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden seit der Unix-Epoche darstellt, z. B. $e.metadata.event_timestamp.seconds, oder ein Platzhalter, der diesen Wert enthält.
• 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 mit einem Datums-/Zeitformatstring oder einer der folgenden Zeitgranularitäten angeben: SECOND, MINUTE, HOUR, DATE, WEEK, MONTH oder YEAR. Weitere Formatierungsoptionen finden Sie unter Elemente für Datums- und Uhrzeitangaben formatieren.
• time_zone ist optional und ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, lautet der Standardwert GMT. Sie können Zeitzonen mit Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der IANA-Zeitzonendatenbank (TZ), z. B. America/Los_Angeles. Weitere Informationen finden Sie in der Liste der Zeitzonen in der tz-Datenbank bei Wikipedia.
  • Der Zeitzonenversatz von UTC im Format (+|-)H[H][:M[M]], z. B. „-08:00“.

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

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

Parameterdatentypen

INT, STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen. Es wird also standardmäßig auf GMT gesetzt.

$ts = $e.metadata.collected_timestamp.seconds

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

Beispiel 2

In diesem Beispiel wird ein Stringliteral verwendet, um die time_zone zu definieren.

$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 verwendet, um die timestamp_format zu definieren.

$ts = $e.metadata.collected_timestamp.seconds

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

Beispiel 4

In diesem Beispiel wird ein Unix-Zeitstempel als String mit einer Granularität von Sekunden formatiert.

timestamp.get_timestamp(1708598631, "SECOND", "GMT") = "2024-02-22 10:43:51"

Beispiel 5

In diesem Beispiel wird ein Unix-Zeitstempel als String mit einer Granularität von einer Minute formatiert.

timestamp.get_timestamp(1708598631, "MINUTE", "GMT") = "2024-02-22 10:43"

Beispiel 6

In diesem Beispiel wird ein Unix-Zeitstempel als String mit einer Granularität von einer Stunde formatiert.

timestamp.get_timestamp(1708598631, "HOUR", "GMT") = "2024-02-22 10"

Beispiel 7

In diesem Beispiel wird ein Unix-Zeitstempel mit dem Detaillierungsgrad „Tag“ als String formatiert.

timestamp.get_timestamp(1708598631, "DATE", "GMT") = "2024-02-22"

Beispiel 8

In diesem Beispiel wird ein UNIX-Zeitstempel als String auf Wochenbasis formatiert.

timestamp.get_timestamp(1708598631, "WEEK", "GMT") = "2024-02-18"

Beispiel 9

In diesem Beispiel wird ein Unix-Zeitstempel als String auf Monatsebene formatiert.

timestamp.get_timestamp(1708598631, "MONTH", "GMT") = "2024-02"

Beispiel 10

In diesem Beispiel wird ein UNIX-Zeitstempel als String auf Jahresebene formatiert.

timestamp.get_timestamp(1708598631, "YEAR", "GMT") = "2024"

timestamp.get_week

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 am Sonntag. Datumsangaben vor dem ersten Sonntag des Jahres liegen in Woche 0.

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

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

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

Parameterdatentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0

Beispiel 2

In diesem Beispiel wird ein Stringliteral verwendet, um die time_zone zu definieren.

$ts = $e.metadata.collected_timestamp.seconds

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

timestamp.now

timestamp.now()

Beschreibung

Gibt die Anzahl der Sekunden seit dem 01.01.1970 00:00:00 UTC zurück. Dies wird auch als Unix-Epochenzeit bezeichnet.

Rückgabetyp

INT

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird ein Zeitstempel für Code zurückgegeben, der am 22. Mai 2024 um 18:16:59 Uhr ausgeführt wurde.

timestamp.now() = 1716401819 // Unix epoch time in seconds for May 22, 2024 at 18:16:59

window.avg

window.avg(numeric_values [, should_ignore_zero_values])

Beschreibung

Gibt den Durchschnitt der Eingabewerte zurück (die Ganzzahlen oder Gleitkommazahlen sein können). Wenn Sie das optionale zweite Argument auf „true“ setzen, werden Nullwerte ignoriert.

Parameterdatentypen

INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem Beispiel wird der durchschnittliche Ganzzahlwert angezeigt.

// This rule sets the outcome $size_mode to the average
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 2.5 if the event file size values in the match window are 1, 2, 3 and 4

Beispiel 2

In diesem Beispiel wird der Gleitkommadurchschnitt gezeigt.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 1.75 if the event file size values in the match window are 1.1 and 2.4

Beispiel 3

Durchschnittlicher negativer Input

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0.6 if the event file size values in the match window are -1.1, 1.1, 0.0 and 2.4

Beispiel 4

0 gibt 0 zurück

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0 if the event file size values in the match window is 0

Beispiel 5

0-Werte ignorieren

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size, true) // yields 394 if the event file size values in the match window are 0, 0, 0 and 394

window.first

window.first(values_to_sort_by, values_to_return)

Beschreibung

Diese Aggregationsfunktion gibt einen Stringwert zurück, der von einem Ereignis mit dem niedrigsten korrelierten Ganzzahlwert im Abgleichszeitraum abgeleitet wird. Ein Beispiel ist das Abrufen der Nutzer-ID aus dem Ereignis mit dem niedrigsten Zeitstempel im Abgleichszeitraum (frühestes Ereignis).

Parameterdatentypen

INT, STRING

Rückgabetyp

STRING

Codebeispiele

Gibt einen Stringwert zurück, der von einem Ereignis mit dem niedrigsten korrelierten Ganzzahlwert im Abgleichszeitraum abgeleitet wird.

// This rule sets the outcome $first_event to the lowest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $first_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v1 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.last

window.last(values_to_sort_by, values_to_return)

Beschreibung

Diese Aggregationsfunktion gibt einen Stringwert zurück, der von einem Ereignis mit dem am stärksten korrelierten Ganzzahlwert im Abgleichszeitraum abgeleitet wird. Ein Beispiel ist das Abrufen der Nutzer-ID aus dem Ereignis mit dem niedrigsten Zeitstempel im Abgleichszeitraum (höchster Zeitstempel).

Parameterdatentypen

INT, STRING

Rückgabetyp

STRING

Codebeispiele

Gibt einen Stringwert zurück, der aus einem Ereignis mit dem höchsten korrelierten Int-Wert im Abgleichszeitraum abgeleitet wurde.

// This rule sets the outcome $last_event to the highest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $last_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v3 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.median

window.median(numeric_values, should_ignore_zero_values)

Beschreibung

Gibt den Median der Eingabewerte zurück. Wenn es zwei Medianwerte gibt, wird nur einer nicht deterministisch als Rückgabewert ausgewählt.

Parameterdatentypen

INT|FLOAT, BOOL

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem Beispiel wird der Median zurückgegeben, wenn die Eingabewerte nicht null sind.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 2 if the file sizes in the match window are [1, 2, 3]
  condition:
      $e
}

Beispiel 2

In diesem Beispiel wird der Median zurückgegeben, wenn die Eingabe einige Nullwerte enthält, die nicht ignoriert werden sollten.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}

Beispiel 3

In diesem Beispiel wird der Median zurückgegeben, wenn die Eingabe einige Nullwerte enthält, die ignoriert werden sollen.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size, true) // returns 2 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}

Beispiel 4

In diesem Beispiel wird der Median zurückgegeben, wenn die Eingabe alle Nullwerte enthält, die ignoriert werden sollen.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 0 if the file sizes in the match window are [0,0]
  condition:
      $e
}

Beispiel 5

Dieses Beispiel zeigt, dass bei mehreren Medianen nur ein Median zurückgegeben wird.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [1, 2, 3, 4]
  condition:
      $e
}

window.mode

window.mode(values)

Beschreibung

Gibt den Modus der Eingabewerte zurück. Wenn mehrere mögliche Moduswerte vorhanden sind, wird nur einer dieser Werte nicht deterministisch als Rückgabewert ausgewählt.

Parameterdatentypen

INT|FLOAT|STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Den Modus der Werte im Abgleichszeitraum abrufen.

// This rule sets the outcome $size_mode to the most frequently occurring
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.mode($e.file.size) // yields 1.6 if the event file size values in the match window are 1.6, 2, and 1.6

window.stddev

window.stddev(numeric_values)

Beschreibung

Gibt die Standardabweichung der Eingabewerte in einem Abgleichszeitraum zurück.

Parameterdatentypen

INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem Beispiel wird die Standardabweichung von Ganzzahlen in einem Abgleichszeitraum zurückgegeben.

// This rule creates a detection when the file size stddev in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.0 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 2

Beispiel 2

In diesem Beispiel wird die Standardabweichung von Gleitkommazahlen in einem Abgleichszeitraum zurückgegeben.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.488686 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 2

Beispiel 3

In diesem Beispiel wird die Standardabweichung in einem Abgleichszeitraum mit negativen Zahlen zurückgegeben.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 48.644972 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 2

Beispiel 4

In diesem Beispiel wird eine Standardabweichung von null zurückgegeben, wenn alle Werte im Abgleichszeitraum gleich sind.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 2

Beispiel 5

In diesem Beispiel wird die Standardabweichung eines Abgleichszeitraums mit positiven und negativen Zahlen zurückgegeben.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

window.variance

window.variance(values)

Beschreibung

Diese Funktion gibt die angegebene Varianz der Eingabewerte zurück.

Parameterdatentypen

INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem Beispiel wird die Varianz aller Ganzzahlen zurückgegeben.

// This rule creates a detection when the file size variance in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 16 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 10

Beispiel 2

In diesem Beispiel wird die Varianz aller Gleitkommazahlen zurückgegeben.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 20.148300 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 10

Beispiel 3

In diesem Beispiel wird die Varianz negativer Zahlen zurückgegeben.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 2366.333333 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 10

Beispiel 4

In diesem Beispiel wird ein kleiner Varianzwert zurückgegeben.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [0.000000, 0.000000, 0.000100].
condition:
  $e and #p1 > 10

Beispiel 5

In diesem Beispiel wird eine Varianz von null zurückgegeben.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 10

Beispiel 6

In diesem Beispiel wird die Varianz von positiven und negativen Zahlen zurückgegeben.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

bytes.to_base64

bytes.to_base64(bytes, optional_default_string)

Beschreibung

Die Funktion konvertiert einen bytes-Wert in einen base64 encoded string-Wert. Funktionsaufrufe mit Werten, die nicht umgewandelt werden können, geben standardmäßig einen leeren String zurück.

Parameterdatentypen

BYTES, STRING

Rückgabetyp

STRING

Codebeispiele

Rohe binäre Bytes in einen base64-codierten String umwandeln

Die Funktion konvertiert die binären Rohbytes in einen base64-codierten String.

bytes.to_base64(b'000000006f8ec5586d026f9ddac56e9f2fe15b8a0000000001000000cd000000) = "AAAAAG+OxVhtAm+d2sVuny/hW4oAAAAAAQAAAM0AAAA="

Fehler bei der Umwandlung (Standardwert ist der optional angegebene String)

Die Funktion verwendet standardmäßig "invalid bytes", wenn der angegebene Byte-Wert ungültig ist.

bytes.to_base64(b'000000006f8ec5586d", "invalid bytes") = "invalid bytes"

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").

Anschließend können Sie die Platzhaltervariablen in den Abschnitten match, condition und outcome verwenden. Es gibt jedoch zwei Einschränkungen bei der Zuweisung von Funktionen zu Platzhaltern:

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

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

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

   Das folgende Beispiel ist jedoch ungültig:

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

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

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

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

   Das Folgende ist jedoch ungültig:

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

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

Syntax für Referenzlisten

Weitere Informationen zum Verhalten und zur Syntax von Referenzlisten finden Sie auf unserer Seite zu Referenzlisten.

Sie können Referenzlisten in den Abschnitten events oder outcome verwenden. Hier finden Sie die Syntax für die Verwendung verschiedener Arten von Referenzlisten in einer Regel:

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

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

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

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

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

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

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

Aus Leistungsgründen wird die Verwendung von Referenzlisten durch die Detection Engine eingeschränkt.

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

Typüberprüfung

Google SecOps führt eine Typüberprüfung für Ihre YARA-L-Syntax durch, während Sie Regeln in der Benutzeroberfläche erstellen. Die angezeigten Fehler bei der Typüberprüfung helfen Ihnen, die Regel so zu überarbeiten, dass sie wie erwartet funktioniert.

Im Folgenden finden Sie 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"

Sampling von Erkennungsereignissen

Erkennungen aus Regeln für mehrere Ereignisse enthalten Ereignisbeispiele, um Kontext zu den Ereignissen zu liefern, die die Erkennung verursacht haben. Für jede in der Regel definierte Ereignisvariable sind maximal 10 Ereignisbeispiele zulässig. Wenn in einer Regel beispielsweise zwei Ereignisvariablen definiert sind, kann jede Erkennung bis zu 20 Ereignisbeispiele enthalten. Das Limit gilt für jede Ereignisvariable separat. Wenn eine Ereignisvariable in dieser Erkennung zwei anwendbare Ereignisse und die andere Ereignisvariable 15 anwendbare Ereignisse hat, enthält die resultierende Erkennung 12 Ereignisstichproben (2 + 10).

Alle Ereignisstichproben, die das Limit überschreiten, werden bei der Erkennung ausgelassen.

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

Wenn Sie sich die erkannten Ereignisse in der Benutzeroberfläche ansehen, können Sie alle Ereignisbeispiele für ein erkanntes Ereignis herunterladen. Weitere Informationen finden Sie unter Ereignisse herunterladen.

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