YARA-L 2.0-Sprachsyntax

Unterstützt in:

Google SecOps SIEM

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

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

1. Meta
2. ansehen
3. match (optional)
4. outcome (optional)
5. Bedingung
6. options (optional)

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

Im Folgenden wird die allgemeine Struktur einer Regel veranschaulicht:

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

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

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

  outcome:
    // Additional information extracted from each detection.

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

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

Syntax des Meta-Abschnitts

Der Meta-Abschnitt besteht aus mehreren Zeilen, wobei jede Zeile ein Schlüssel/Wert-Paar definiert. Der Schlüsselteil muss ein String ohne Anführungszeichen sein und der Wertteil ein String in Anführungszeichen:

<key> = "<value>"

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

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

Syntax für den Bereich „Ereignisse“

Geben Sie im Abschnitt events die Prädikate an, um Folgendes anzugeben:

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

Variablendeklarationen

Verwenden Sie für Variablendeklarationen die folgende Syntax:

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

Beide sind gleichwertig, wie in den folgenden Beispielen gezeigt:

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

Diese Deklaration gibt an, dass diese Variable das angegebene Feld für die Ereignisvariable darstellt. Wenn das Ereignisfeld ein wiederkehrendes Feld ist, kann die Abgleichvariable jeden Wert im Array repräsentieren. Es ist auch möglich, einer einzelnen Übereinstimmungs- oder Platzhaltervariablen mehrere Ereignisfelder zuzuweisen. Dies ist eine transitive Join-Bedingung.

Beispiel:

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

sind gleichbedeutend mit:

• $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, wird dies als Kompilierungsfehler betrachtet.

Filter für Ereignisvariablen

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

Zusammenführen von Ereignisvariablen

Alle in der Regel verwendeten Ereignisvariablen müssen auf eine der folgenden Arten mit allen anderen Ereignisvariablen zusammengeführt werden:

• Direkt über einen Gleichheitsvergleich zwischen Ereignisfeldern der beiden zusammengeführten Ereignisvariablen, z. B. $e1.field = $e2.field. Der Ausdruck darf keine arithmetischen Ausdrücke enthalten.

• Indirekt über eine transitive Verbindung, die nur ein Ereignisfeld umfasst (Definition von „transitiver Verbindung“ siehe Variablendeklaration). Der Ausdruck darf keine arithmetischen Ausdrücke enthalten.

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

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

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

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

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

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

Hinweis :Wenn die einzige Join-Bedingung eine or-Kette, eine Funktion zum Ereignisvergleich oder eine Kombination aus beiden ist, kann die Leistung der Regel beeinträchtigt werden.

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 Abgleichsabschnitts

Geben Sie im Bereich match die Abgleichsvariablen für Gruppenereignisse an, bevor Sie nach Abgleichbedingungen suchen. Diese Felder werden bei jeder Übereinstimmung zurückgegeben.

• Geben Sie im Abschnitt events an, was die einzelnen Abgleichsvariablen darstellen.
• Geben Sie die Zeitspanne an, die für die Korrelation 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 steht m/h/d jeweils für Minuten, Stunden und Tage.

• Die Mindestdauer 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

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

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

$user over 1h

Diese Anweisung gibt $user zurück, wenn die Regel eine Übereinstimmung findet. Der angegebene Zeitraum beträgt eine Stunde. Ereignisse, die mehr als eine Stunde auseinanderliegen, werden nicht miteinander in Beziehung gesetzt. Sie werden von der Regel nicht als Erkennung betrachtet.

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

$source_ip, $target_ip, $hostname over 2m

Diese Anweisung gibt $source_ip, $target_ip und $hostname zurück, wenn die Regel eine Übereinstimmung findet. Das angegebene Zeitfenster beträgt 2 Minuten. Ereignisse, die mehr als zwei Minuten auseinanderliegen, werden nicht miteinander in Beziehung gesetzt. Sie werden von der Regel nicht als Erkennung betrachtet.

Die folgenden Beispiele zeigen ungültige match-Abschnitte:

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

Umgang mit Nullwerten im Bereich „Abgleich“

Die Regelmaschine filtert implizit die Nullwerte für alle Platzhalter heraus, die im Abgleichbereich verwendet werden ("" für Strings, 0 für Zahlen, false für boolesche Werte, der Wert an Position 0 für aufzählbare Typen). Das folgende Beispiel zeigt Regeln, mit denen 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 Abgleichbereich verwendet werden, nicht implizit herausgefiltert. Im folgenden Beispiel werden Regeln veranschaulicht, mit denen 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 Options-Bereich verwenden.

Hop-Fenster

Standardmäßig werden YARA-L 2.0-Regeln mit einem Abgleichabschnitt mithilfe von Hop-Fenstern ausgewertet. Der Zeitraum der Ausführung der Regel wird in eine Reihe sich überschneidender Hop-Fenster 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] mit einem match-Abschnitt über 30m ausgeführt wird, könnten beispielsweise die sich überschneidenden Hop-Fenster [1:00, 1:30], [1:03, 1:33] und [1:06, 1:36] generiert werden. Mit diesen Zeiträumen werden mehrere Ereignisse in Beziehung gesetzt.

Schiebefenster

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

Eine effektivere Methode, nach solchen Ereignissequenzen zu suchen, sind gleitende Zeitfenster. Gleitende Zeitfenster mit der im Abschnitt match angegebenen Dauer werden generiert, wenn sie mit einer bestimmten Pivot-Ereignisvariablen beginnen oder enden. Die Ereignisse werden dann innerhalb jedes gleitenden Fensters korreliert. So können Sie nach Ereignissen suchen, die in einer bestimmten Reihenfolge auftreten (z. B. e1 innerhalb von 2 Minuten nach e2). Ein Auftreten von Ereignis e1 und ein Auftreten von Ereignis e2 sind miteinander korreliert, wenn Ereignis e1 innerhalb der Dauer des gleitenden Fensters nach Ereignis e2 auftritt.

Geben Sie gleitende Zeitfenster 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 gleitende Zeitfenster basieren. Wenn Sie das Schlüsselwort before verwenden, werden gleitende Zeitfenster generiert, die mit jedem Auftreten des Pivot-Ereignisses enden. Wenn das Keyword after verwendet wird, werden gleitende Zeitfenster generiert, die mit jedem Auftreten des Pivot-Ereignisses beginnen.

Hier sind einige Beispiele für gültige Verwendungen von Gleitfenstern:

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

Beispiel für eine Gleitfensterregel

Hinweis: Die Verwendung von gleitenden Fenstern anstelle von Hop-Fenstern kann zu einer geringeren Leistung führen. Google empfiehlt, gleitende Zeitfenster nur in bestimmten Fällen zu verwenden, z. B. wenn die Ereignisreihenfolge unbedingt erforderlich ist oder wenn nach dem Nichtvorhandensein von Ereignissen gesucht wird.

Google empfiehlt, Gleitfenster nicht für Regeln mit einzelnen Ereignissen zu verwenden, da sie für die Erkennung mehrerer Ereignisse konzipiert sind. Wenn eine Ihrer Regeln in diese Kategorie fällt, empfiehlt Google eine der folgenden Problemumgehungen:

• Konvertieren Sie die Regel so, dass mehrere Ereignisvariablen verwendet werden, und aktualisieren Sie den Bedingungsabschnitt, wenn für die Regel mehr als ein Ereignis erforderlich ist.
  • Sie können auch Zeitstempelfilter hinzufügen, anstatt ein gleitendes Fenster zu verwenden. Beispiel: $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
• Nehmen Sie das Schiebefenster ab.

Syntax für den Abschnitt „Ergebnisse“

Im Abschnitt outcome können Sie bis zu 20 Ergebnisvariablen mit beliebigen Namen definieren. Diese Ergebnisse werden in den Erkennungen gespeichert, die von der Regel generiert wurden. Für jede Erkennung können unterschiedliche Werte für die Ergebnisse gelten.

Der Name des Ergebnisses, $risk_score, ist etwas Besonderes. Optional können Sie ein Ergebnis mit diesem Namen definieren. In diesem Fall muss es vom Typ „Integer“ oder „Float“ sein. Wenn ein Wert angegeben ist, wird das Symbol risk_score in der Ansicht „Unternehmensstatistiken“ für Benachrichtigungen angezeigt, die auf Regelerkennungen zurückzuführen sind.

Wenn Sie im Ergebnisbereich 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 für Ergebnisvariablen

Jede Ergebnisvariable kann einen anderen Datentyp haben, der vom Ausdruck abhängt, der zur Berechnung verwendet wird. Wir unterstützen die folgenden Datentypen für Ergebnisse:

• integer
• floats
• String
• Listen mit Ganzzahlen
• Listen von Floats
• Listen von Strings

Bedingte Logik

Mit bedingten 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 BOOLESCHE_KLAUSE wahr ist, dann THEN_KLAUSE zurückgeben, andernfalls ELSE_KLAUSE zurückgeben“.

BOOL_CLAUSE muss zu einem booleschen Wert führen. Ein BOOL_CLAUSE-Ausdruck hat eine ähnliche Form wie Ausdrücke im Abschnitt events. Beispiele:

• 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 im Abschnitt outcome definierte Ergebnisvariable, 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)

• Sie können sie beispielsweise in einer Referenzliste nachschlagen:

  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. Es werden Ganzzahlen, Gleitkommazahlen und Strings unterstützt.

Sie können die ELSE_CLAUSE weglassen, wenn der Datentyp ein Ganzzahl- oder ein Gleitkommatyp 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 ELSE_CLAUSE angeben, wenn der Datentyp „String“ ist oder wenn THEN_CLAUSE eine Platzhaltervariable oder eine Ergebnisvariable ist.

Mathematische Vorgänge

Sie können mathematische Vorgänge verwenden, um Ganzzahl- oder Gleitkommadatentypen 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 eine Beispielberechnung im Abschnitt outcome:

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

Mathematische Vorgänge sind für die folgenden Operandentypen zulässig, sofern jeder Operand und der gesamte arithmetische Ausdruck korrekt aggregiert werden (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 Modulus ist bei Gleitkommazahlen nicht zulässig.

Platzhaltervariablen in Ergebnissen

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

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 Ergebniszuweisung

Aus Ergebnisvariablen können andere Ergebnisvariablen abgeleitet werden, ähnlich wie bei Platzhaltervariablen, die im Abschnitt events definiert sind. Sie können in der Zuweisung einer anderen Ergebnisvariablen auf eine Ergebnisvariable verweisen. Verwenden Sie dazu ein $-Token gefolgt vom Variablennamen. Ergebnisvariablen müssen definiert werden, bevor sie im Regeltext referenziert werden können. Wenn Ergebnisvariablen in einem Zuweisungsausdruck verwendet werden, dürfen sie 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 allen Arten von Ausdrücken auf der rechten Seite einer Ergebniszuweisung verwendet werden, mit Ausnahme der folgenden Ausdrücke:

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

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 mehrere IP-Werte haben. Es ist ein nicht skalarer Wert. Die Ereignisfeldvariable $e.principal.hostname ist dagegen kein wiederkehrendes Feld und hat nur einen Wert (d.h. einen Skalarwert).

Ebenso sind sowohl nicht wiederholte Ereignisfelder als auch wiederholte Ereignisfelder, die im Ergebnisbereich einer Regel mit einem Abgleichfenster verwendet werden, nicht skaläre Werte. In der folgenden Regel werden Ereignisse beispielsweise mithilfe eines Abgleichabschnitts gruppiert und im Ergebnisabschnitt auf ein nicht wiederholtes Ereignisfeld verwiesen:

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

Ein 5-Minuten-Fenster, in dem die Regel ausgeführt wird, kann null, ein oder viele Ereignisse enthalten. Der Abschnitt „Ergebnis“ bezieht sich auf alle Ereignisse in einem Spielfenster. Jede Ereignisfeldvariable, auf die im Bereich „Ergebnis“ verwiesen wird, kann auf null, einen oder mehrere Werte des Felds für jedes Ereignis im Abgleichfenster verweisen. Wenn in der vorherigen Regel ein 5-Minuten-Fenster 5 $e-Ereignisse enthält, verweist $e.principal.hostname im Ergebnisbereich auf 5 unterschiedliche Hostnamen. Die Ereignisfeldvariable $e.principal.hostname ist daher ein nicht skalarer Wert im Ergebnisabschnitt dieser Regel.

Da Ergebnisvariablen immer einen einzelnen Skalarwert liefern müssen, müssen alle nicht skalaren Werte, von denen eine Ergebniszuweisung abhängt, zusammengefasst werden, um einen einzelnen Skalarwert zu erhalten. In einem Ergebnisabschnitt sind die folgenden Werte nicht skalar und müssen zusammengefasst werden:

• Ereignisfelder (wiederkehrend oder nicht wiederkehrend), wenn die Regel einen Abgleichsabschnitt verwendet
• Ereignisplatzhalter (wiederholt oder nicht wiederholt), wenn die Regel einen Abgleichsabschnitt verwendet
• Wiederholte Ereignisfelder, wenn die Regel keinen Abgleichsabschnitt verwendet
• Wiederholte Ereignis-Platzhalter, wenn die Regel keinen Abgleichsabschnitt verwendet

Skalare Ereignisfelder, Platzhalter für skalare Ereignisse und Konstanten können in einer Regel, die keinen Abgleichsabschnitt verwendet, in eine Aggregation eingeschlossen werden. Bei den meisten Aggregationen wird jedoch der eingeklammerte Wert verwendet, sodass diese Option nicht erforderlich ist. Eine Ausnahme bildet die array()-Aggregation, mit der ein Skalarwert in ein Array umgewandelt werden kann.

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

Sie können die folgenden Aggregationsfunktionen verwenden:

• max(): gibt das Maximum aller möglichen Werte aus. Funktioniert nur mit Ganzzahl und Gleitkommazahl.
• min(): gibt das Minimum aller möglichen Werte aus. Funktioniert nur mit Ganzzahl und Gleitkommazahl.
• sum(): Gibt die Summe aller möglichen Werte aus. Funktioniert nur mit Ganzzahl und Gleitkommazahl.
• count_distinct(): Hiermit werden alle möglichen Werte erfasst und dann die Anzahl der einzelnen möglichen Werte ausgegeben.
• count(): Funktioniert wie count_distinct(), gibt aber eine nicht eindeutige Anzahl möglicher Werte zurück.
• array_distinct(): Hiermit werden alle möglichen eindeutigen Werte erfasst und dann eine Liste dieser Werte ausgegeben. Die Liste der eindeutigen Werte wird auf 25 zufällige Elemente gekürzt. Zuerst wird die Deduplizierung angewendet, um eine eindeutige Liste zu erhalten, und dann die Kürzung.
• array(): Funktioniert wie array_distinct(), gibt aber eine nicht eindeutige Liste von Werten zurück. Außerdem wird die Liste der Werte auf 25 beliebige Elemente gekürzt.
• period_start_for_max(): Beginn des Zeitraums, in dem der höchste Wert des aufgeführten Werts aufgetreten ist.
• period_start_for_min(): Beginn des Zeitraums, in dem der niedrigste Wert des aufgeführten Werts aufgetreten ist.

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

Angenommen, die Abschnitte outcome und condition enthalten Folgendes:

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

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

condition:
  #event > 1

Da im Abschnitt „Bedingung“ für jede Erkennung mehr als eine event erforderlich ist, werden die Aggregationsfunktionen 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 zum Bereich „Ergebnisse“:

Weitere Hinweise und Einschränkungen:

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

Ein Beispiel für den Abschnitt „Ergebnis“ finden Sie unter Übersicht über die Sprache YARA-L 2.0. Weitere Informationen zur Erkennung und Deduplizierung von Ergebnissen finden Sie im Hilfeartikel Kontextsensitive Analysen erstellen.

Syntax des Bereichs „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: Verwenden Sie das Keyword and, um eine Abgleichbedingung mithilfe von im Abschnitt outcome definierten Ergebnisvariablen anzugeben. Weitere Informationen finden Sie im folgenden Abschnitt Bedingungen für den Ausgang.

Zeichen zählen

Das Zeichen # ist ein Sonderzeichen im Abschnitt condition. Wenn er vor dem Namen einer Ereignis- oder Platzhaltervariablen verwendet wird, entspricht er der Anzahl der einzelnen Ereignisse oder Werte, die alle Bedingungen des Abschnitts events erfüllen.

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

Wertzeichen

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

Wenn er vor dem Namen eines Ereignisses oder einer Platzhaltervariablen (z. B. $event) verwendet wird, steht er für #event > 0.

Ereignis- und Platzhalterbedingungen

Geben Sie hier Bedingungsprädikate für Ereignisse und Platzhaltervariablen an, die mit dem Keyword and oder or verbunden sind. Das Keyword and kann zwischen beliebigen Bedingungen verwendet werden. Das Keyword or kann jedoch nur verwendet werden, wenn die Regel nur eine Ereignisvariable hat.

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

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

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

  match:
    $ph over 5m

  condition:
    $ph2 or $ph3
}

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

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

Begrenzte und unbegrenzte Bedingungen

Die folgenden Bedingungen sind begrenzte Bedingungen. Sie erzwingen das Vorhandensein der zugehörigen Ereignisvariablen. 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 unbegrenzt. Sie ermöglichen, dass die zugehörige Ereignisvariable nicht vorhanden ist. Das bedeutet, dass in einer Erkennung möglicherweise kein Vorkommen des Ereignisses vorhanden ist und jeder Verweis auf Felder in der Ereignisvariablen einen Nullwert ergibt. Mit unbegrenzten Bedingungen können Sie das Fehlen eines Ereignisses über einen bestimmten Zeitraum erkennen. Beispiel: Ein Bedrohungsereignis ohne ein Ereignis zur Risikobewältigung innerhalb eines 10-minütigen Zeitfensters. Regeln mit unbegrenzten Bedingungen werden als Nichtvorhandensein-Regeln bezeichnet.

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

Hinweis: Bei Nichtvorhandensein-Regeln fügt die Erkennungs-Engine der erwarteten Latenz (basierend auf der Ausführungshäufigkeit der Regel) eine Verzögerung von einer Stunde hinzu, um für verspätet eintreffende Daten zu sorgen.

Anforderungen für das Nichtvorhandensein

Damit eine Regel mit Nichtvorhandensein kompiliert werden kann, müssen die folgenden Anforderungen erfüllt sein:

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.

Betrachten Sie die folgende Regel, bei der der Abschnitt mit den Bedingungen 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 sind gültig für die <condition_section>:

• $u1 and !$u2 and $e1 and $e2
  • Alle UDM-Ereignisse und -Entitäten sind im Bereich „Bedingung“ vorhanden.
  • Mindestens ein UDM-Ereignis ist begrenzt.
• $u1 and !$u2 and $e1 and !$e2
  • $e2 ist unbegrenzt, was zulässig ist, da es mit $u1 verknüpft ist, das begrenzt ist. Wenn $e2 nicht mit $u1 verknüpft ist, ist dies ungültig.
• #port > 50 and #ip = 0
  • Im Bereich „Bedingung“ 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 unbegrenzte Bedingung. Begrenzte Bedingungen sind jedoch strenger als unbegrenzte Bedingungen. Da $port $u1 zugewiesen ist und #port > 50 eine begrenzte Bedingung ist, ist $u1 weiterhin begrenzt.

Die folgenden Beispiele sind ungültig:<condition_section>

• $u1 and $e1
  • Alle UDM-Ereignisse und -Entitäten, die im Bereich „Ereignisse“ angezeigt werden, müssen auch im Bereich „Bedingung“ aufgeführt sein oder einen Platzhalter haben, der im Bereich „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 Keyword or wird nicht mit unbegrenzten Bedingungen 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 Keyword not ist für Ereignis- und Platzhalterbedingungen nicht zulässig.
• #port < 50 and #ip = 0
  • Die vorhandenen Platzhalter umfassen alle UDM-Ereignisse und -Entitäten. Alle Bedingungen sind jedoch unbegrenzt. Das bedeutet, dass keines der UDM-Ereignisse begrenzt ist, wodurch die Regel nicht kompiliert werden kann.

Hinweis: Verwenden Sie im Abschnitt condition keine match-Variable. Dies ist ein semantischer Fehler, da Ereignisse nach dem Wert der Variablen match gruppiert werden.

Hinweis :Geben Sie nicht nur unbegrenzte Bedingungen für alle event-Variablen an, denen eine match-Variable zugewiesen ist. Es ist ein semantischer Fehler. Damit ein Wert für die Variable match zurückgegeben werden kann, muss mindestens ein Ereignis vorhanden sein, das den Wert enthält.

Hinweis: Bei Verwendung eines gleitenden Fensters muss die Variable für das Pivot-Ereignis in mindestens einer begrenzten Bedingung enthalten sein.

Bedingte Ergebnisse

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

Geben Sie die Ergebnisbedingungen je nach Art der Ergebnisvariablen unterschiedlich an:

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

  $risk_score > 10

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

  $risk_score <= 5.5

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

  $severity = "HIGH"

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

  arrays.contains($event_ids, "id_1234")

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

Regelklassifizierung

Wenn Sie eine Bedingung für das Ergebnis in einer Regel mit einem Abgleichsabschnitt angeben, wird die Regel für das Regelkontingent als Mehrerereignisregel klassifiziert. Weitere Informationen zur Klassifizierung einzelner und mehrerer Ereignisse finden Sie unter Regel für einzelne Ereignisse und Regel für mehrere Ereignisse.

Syntax des Optionsabschnitts

Im Abschnitt options können Sie die Optionen für die Regel angeben. Hier ist ein Beispiel für die Angabe des Optionsbereichs:

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 Optionenname und value ein gültiger Wert für die Option sein, wie für die folgenden Optionen angegeben:

allow_zero_values

Gültige Werte für diese Option sind true und false. Sie bestimmen, ob diese Option aktiviert ist oder nicht. Der Standardwert ist false. Diese Option ist deaktiviert, wenn sie in der Regel nicht angegeben ist.

Wenn Sie diese Einstellung aktivieren möchten, fügen Sie dem Optionsabschnitt Ihrer Regel Folgendes hinzu: allow_zero_values = true. Andernfalls werden die Nullwerte von Platzhaltern, die im Abgleichabschnitt verwendet werden, von der Regel implizit herausgefiltert, wie unter Nullwertbehandlung im Abgleichabschnitt beschrieben.

Boolesche Ausdrücke

Boolesche Ausdrücke sind Ausdrücke vom Typ „Boolescher Wert“.

Vergleiche

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

• <EXPR> <OP> <EXPR>

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

Beispiel:

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

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

Funktionen

Einige Funktionsausdrücke geben einen booleschen Wert zurück, der im Abschnitt events als individuelles Prädikat 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

Im Bereich „Ereignisse“ können Sie Referenzlisten verwenden. Weitere Informationen finden Sie im Abschnitt Literaturverzeichnisse.

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 oder b und c“ wird als „a oder (b und c)“ ausgewertet, wenn die Operatoren or und and im Ausdruck explizit definiert sind.

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

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

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

$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 herum gruppiert und zuerst ausgewertet. Das letzte Prädikat, $e2.field = "bar", wird implizit mit and zusammengeführt. Das hat zur Folge, dass sich die Reihenfolge der Auswertung ändert.

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

Aufzählungstypen

Sie können die Operatoren mit aufzählbaren Typen verwenden. Sie können auf Regeln angewendet werden, um die Leistung zu vereinfachen und zu optimieren (Bedienelemente anstelle von Referenzlisten verwenden).

Im folgenden Beispiel entsprechen „USER_UNCATEGORIZED“ und „USER_RESOURCE_DELETION“ den Werten 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

Modifikator „nocase“

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

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

Diese Option kann nicht verwendet werden, wenn ein Feldtyp ein enumerierter 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 wiederholt gekennzeichnet. Das bedeutet, dass es sich um Listen von Werten oder anderen Arten von Nachrichten handelt.

Wiederholte Felder und boolesche Ausdrücke

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

1. Geändert
2. Unverändert

Betrachten Sie das folgende Ereignis:

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

    hostname: "host"
  }
}

Modifizierte Ausdrücke

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

Beliebig

Wenn ein beliebiges Element des 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".

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

Wenn Sie eine Bedingung mit any oder all schreiben, beachten Sie, dass die Negierung der Bedingung mit not nicht unbedingt 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. Mit anderen Worten: Die Regel prüft, 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. Mit der Regel wird also geprüft, 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 Skalarfeldern) kompatibel.
• any und all können nicht verwendet werden, um zwei wiederkehrende Felder zusammenzuführen. any $e1.principal.ip = $e2.principal.ip ist beispielsweise ungültig.
• Die Operatoren any und all werden vom Ausdruck für die Referenzliste nicht unterstützt.

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

Ereignistext	principal.ip	principal.hostname
event_copy_1	„192.0.2.1“	„host“
event_copy_2	„192.0.2.2“	„host“
event_copy_3	„192.0.2.3“	„host“

Wenn eine Ereigniskopie alle unveränderten Bedingungen für das wiederholte Feld erfüllt, erfüllt das Ereignis insgesamt alle Bedingungen. Wenn Sie also mehrere Bedingungen für ein wiederholtes Feld haben, muss die Ereigniskopie alle erfüllen. In den folgenden Regelbeispielen wird dieses Verhalten anhand des vorherigen Beispieldatensatzes veranschaulicht.

Die folgende Regel gibt eine Übereinstimmung zurück, wenn sie auf den Beispieldatensatz event_original angewendet wird, da event_copy_1 alle Ereignisprädikate erfüllt:

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

Die folgende Regel gibt bei der Ausführung mit dem Beispieldatensatz event_original keine Übereinstimmung zurück, 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
}

Modifizierte 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. Betrachten Sie die folgende Regel:

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

Die Regel wird auf die folgenden Kopien angewendet:

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

In diesem Fall erfüllen alle Kopien any $e.principal.ip = "192.0.2.1", aber nur event_copy_3 erfüllt $e.principal.ip = "192.0.2.3". Das Ereignis würde also insgesamt übereinstimmen.

Diese Ausdruckstypen können auch so beschrieben werden:

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

Wiederkehrende Felder und Platzhalter

Wiederkehrende Felder funktionieren mit Platzhalterzuweisungen. Ähnlich wie bei unveränderten Ausdrücken in wiederholten Feldern wird für jedes Element eine Kopie des Ereignisses erstellt. Anhand des Beispiels für event_copy wird für jede Ereigniskopie der Wert des wiederholten Felds event_copy_n für den Platzhalter verwendet, wobei n die Ereigniskopiennummer ist. Wenn der Platzhalter im Bereich „Übereinstimmung“ verwendet wird, kann dies zu mehreren Übereinstimmungen führen.

Im folgenden Beispiel wird eine Übereinstimmung generiert. Der Platzhalter $ip ist für event_copy_1 gleich 192.0.2.1, was den Prädikaten in der Regel entspricht. Die Ereignisstichproben der Übereinstimmung 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 hat für jede der verschiedenen event_copy_n-Kopien einen anderen Wert. Die Gruppierung erfolgt nach $ip, da sich dieses im Abgleichsbereich befindet. Daher erhalten Sie drei Übereinstimmungen, wobei jede Übereinstimmung einen anderen Wert für die Abgleichsvariable $ip hat. Jede Übereinstimmung hat dasselbe Ereignisbeispiel: ein einzelnes Element, event_original.

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

  match:
    $ip over 5m

  condition:
    $e
}

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

Ergebnisse mit Platzhaltern, die wiederkehrenden Feldern zugewiesen sind

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

Betrachten Sie die folgende Regel:

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

  match:
    $host over 5m

  outcome:
    $o = array_distinct($ip)

  condition:
    $e
}

Für diese Regel gibt es vier Ausführungsphasen. Die erste Phase ist das Kopieren von Ereignissen:

Ereignistext	$ip	$host	$e
event_copy_1	„192.0.2.1“	„host“	event_id
event_copy_2	„192.0.2.2“	„host“	event_id
event_copy_3	„192.0.2.3“	„host“	event_id

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

Ereignistext	$ip	$host	$e
event_copy_1	„192.0.2.1“	„host“	event_id
event_copy_2	„192.0.2.2“	„host“	event_id

event_copy_3 wird herausgefiltert, weil "192.0.2.3" nicht die Bedingung $ip = "192.0.2.1" or $ip = "192.0.2.2" erfüllt.

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

$host	$o	$e
„host“	["192.0.2.1", "192.0.2.2"]	event_id

$o = array_distinct($ip) wird anhand von $ip aus der vorherigen Phase berechnet, nicht aus der Phase der Ereigniskopie.

Im Bereich „Bedingung“ werden schließlich die einzelnen Gruppen gefiltert. Da diese Regel nur auf das Vorhandensein von $e prüft, wird für die Zeile aus dem Beispiel nur eine einzelne Erkennung ausgegeben.

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

Array-Indexierung

Sie können Arrayindexierung auf wiederkehrende Felder anwenden. Verwenden Sie die Standardlistensyntax, um auf das n-te wiederholte Feldelement zuzugreifen. Die Elemente beginnen mit der Zählung 0. Für ein Element, das außerhalb des zulässigen Bereichs liegt, wird der Standardwert zurückgegeben.

• $e.principal.ip[0] = "192.168.12.16"
• $e.principal.ip[999] = "" Wenn es weniger als 1.000 Elemente gibt, wird true zurückgegeben.

Einschränkungen:

• Ein Index muss ein nicht negatives Ganzzahlliteral sein. $e.principal.ip[-1] ist beispielsweise ungültig.
• Werte vom Typ int (z. B. ein Platzhalter, der auf int festgelegt ist) werden nicht gezählt.
• Die Array-Indexierung kann nicht mit any oder all kombiniert werden. any $e.intermediary.ip[0] ist beispielsweise ungültig.
• Die Arrayindexierung kann nicht mit der Kartensyntax 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 Arrayindexierung verwendet werden. $e.intermediary.ip[0] ist beispielsweise ungültig, da intermediary und ip wiederkehrende Felder sind, aber nur ein Index für ip vorhanden ist.

Wiederholte Nachrichten

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

Betrachten Sie das folgende Ereignis:

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 in wiederkehrenden Feldern wird für jedes Element des wiederkehrenden Felds eine temporäre Kopie des Ereignisses erstellt. Betrachten Sie die folgende Regel:

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

Die Regel wird auf die folgenden Kopien angewendet:

Ereignistext	about.ip	about.hostname
event_copy_1	„192.0.2.1“	„alice“
event_copy_2	„192.0.2.2“	„alice“
event_copy_3	„192.0.2.3“	„alice“
event_copy_4	""	„max“

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

Wiederholte Nachrichten und Array-Indexierung

Ein weiteres unerwartetes Verhalten kann auftreten, wenn Sie die Arrayindexierung mit unveränderten Ausdrücken in wiederholten Nachrichtenfeldern verwenden. Sehen Sie sich die folgende Beispielregel an, in der die Arrayindexierung 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:

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

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

Das kann zu unerwartetem Verhalten führen, da Regel repeated_message_1 keine Arrayindexierung hat und keine Übereinstimmungen liefert, während Regel repeated_message_2 die Arrayindexierung verwendet und eine Übereinstimmung liefert.

Kommentare

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

Literale

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

String- und reguläre Ausdrucksliterale

Sie können einen der folgenden Anführungszeichen verwenden, um Strings in YARA-L 2.0 zu umschließen. Geschützter Text wird jedoch je nach verwendeter Methode unterschiedlich interpretiert.

1. Doppelte Anführungszeichen ("): Verwenden Sie diese für normale Strings. Muss Escape-Zeichen enthalten.
   Beispiel: „hallo\twelt“ – \t wird als Tabulatorzeichen interpretiert

2. Graviszeichen (`): Damit werden alle Zeichen wörtlich interpretiert.
   Beispiel: „hallo\twelt“ – \t wird nicht als Tabulatorzeichen 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 regulären Ausdrucksliterale.

Sie können Stringliterale auch als reguläre Ausdrucksliterale verwenden, wenn Sie die Funktion re.regex() verwenden. Bei Stringliteralen mit doppelten Anführungszeichen müssen Sie umgekehrte Schrägstriche mit umgekehrten Schrägsstrichen maskieren, was etwas unübersichtlich 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 umgekehrte Anführungszeichen zu verwenden, um die Lesbarkeit zu verbessern.

Operatoren

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

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

Variablen

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

Sie können die folgenden Arten von Variablen definieren:

• Ereignisvariablen: Stellt Gruppen von Ereignissen in normalisierter Form (UDM) oder Entitätsereignisse dar. Geben Sie im Bereich events Bedingungen für Ereignisvariablen an. Ereignisvariablen werden anhand eines Namens, einer Ereignisquelle und Ereignisfelder identifiziert. Zulässige Quellen sind udm (für normalisierte Ereignisse) und graph (für Ereignise vom Typ „Entität“). Wenn die Quelle weggelassen wird, wird udm als Standardquelle festgelegt. Ereignisfelder werden als Kette von .<Feldname> dargestellt, z. B. $e.Feld1.Feld2. Ereignisfeldketten beginnen immer bei der obersten Quelle (UDM oder Entität).

• Abgleichvariablen: Deklarieren Sie sie im Abschnitt match. Abgleichsvariablen werden zu Gruppierungsfeldern für die Abfrage, da für jeden eindeutigen Satz von Abgleichsvariablen (und für jedes Zeitfenster) eine Zeile zurückgegeben wird. Wenn die Regel eine Übereinstimmung findet, werden die Werte der Übereinstimmungsvariablen zurückgegeben. Geben Sie im Abschnitt events an, was die einzelnen Abgleichsvariablen darstellen.

• Platzhaltervariablen: Deklarieren und definieren Sie sie im Abschnitt events. Platzhaltervariablen ähneln Abgleichsvariablen. Sie können jedoch Platzhaltervariablen im Abschnitt condition verwenden, um Abgleichbedingungen anzugeben.

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

Verwenden Sie Abgleichsvariablen und Platzhaltervariablen, um Beziehungen zwischen Ereignisfeldern über transitive Join-Bedingungen zu deklarieren. Weitere Informationen finden Sie unter Syntax des Bereichs „Ereignisse“.

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.

Folgende Keywords sind für Regeln der Erkennungs-Engine zulässig: 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 Kartenzugriff für Structs und Labels.

Strukturen und Labels

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

Wenn Sie sowohl in „Struct“ als auch in „Label“ nach einem bestimmten Schlüssel/Wert-Paar suchen möchten, verwenden Sie die Standardzuordnungssyntax:

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

Der Kartenzugriff gibt immer einen String zurück.

Unterstützte Fälle

Abschnitt „Ereignisse und Ergebnisse“

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

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

Platzhaltern 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

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

any- oder all-Keywords mit einer Karte kombinieren

Folgendes wird beispielsweise 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 die Map-Syntax nur auf Schlüssel zugreifen, deren Werte Strings sind. Der Zugriff auf Schlüssel, deren Werte andere primitive Typen wie Ganzzahlen sind, ist nicht möglich.

Umgang mit doppelten Werten

Kartenzugriffe geben immer einen einzelnen Wert zurück. Im seltenen Sonderfall, dass der Zugriff auf die Zuordnung sich auf mehrere Werte beziehen könnte, gibt der Zugriff auf die Zuordnung deterministisch den ersten Wert zurück.

Das kann in den folgenden Fällen passieren:

• Ein Label hat einen doppelten Schlüssel.

  Die Labelstruktur stellt eine Karte dar, erzwingt aber nicht die Eindeutigkeit von Schlüsseln. Eine Zuordnung sollte nach Konvention eindeutige Schlüssel haben. Daher empfiehlt Google Security Operations, ein Label nicht mit doppelten Schlüsseln zu belegen.

  Der Regeltext $e.metadata.ingestion_labels["dupe-key"] würde den ersten möglichen Wert, val1, zurückgeben, wenn er auf das folgende Datenbeispiel angewendet wird:

  // 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 wiederkehrendes Feld kann ein Label als untergeordnetes Feld enthalten. Zwei verschiedene Einträge im wiederkehrenden Feld der obersten Ebene können Labels mit demselben Schlüssel enthalten. Der Regeltext $e.security_result.rule_labels["key"] würde den ersten möglichen Wert, val3, zurückgeben, wenn er auf das folgende Datenbeispiel angewendet 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 der Erkennungs-Engine und in Suchanfragen verwenden können.

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

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

• events.
• BOOL_CLAUSE einer Bedingung im Abschnitt „Ergebnis“.

arrays.concat

Unterstützt in:

Regeln Suche

arrays.concat(string_array, string_array)

Beschreibung

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

Param-Datentypen

ARRAY_STRINGS, ARRAY_STRINGS

Rückgabetyp

ARRAY_STRINGS

Codebeispiele

Beispiel 1

Im folgenden Beispiel werden zwei verschiedene Stringarrays zusammengefügt.

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

Beispiel 2

Im folgenden Beispiel werden Arrays mit einem leeren String verknüpft.

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

Beispiel 3

Im folgenden Beispiel werden leere Arrays zusammengefügt.

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

arrays.join_string

Unterstützt in:

Regeln Suche

arrays.join_string(array_of_strings, optional_delimiter)

Beschreibung

Wandelt ein String-Array in einen einzelnen String um, der durch den optionalen Parameter getrennt ist. Wenn kein Trennzeichen angegeben ist, wird der leere String verwendet.

Param-Datentypen

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 nicht nullwertigen Elementen und einem Trennzeichen zusammengeführt.

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

Beispiel 2

In diesem Beispiel wird ein Array mit einem Nullelement und einem Trennzeichen zusammengeführt.

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

Beispiel 3

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

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

arrays.length

Unterstützt in:

Regeln Suche

arrays.length(repeatedField)

Beschreibung

Gibt die Anzahl der wiederholten Feldelemente zurück.

Param-Datentypen

LIST

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

Gibt die Anzahl der wiederholten Feldelemente zurück.

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

Beispiel 2

Wenn sich mehrere wiederholte Felder entlang des Pfads befinden, wird die Gesamtzahl der wiederholten Feldelemente zurückgegeben.

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

arrays.max

Unterstützt in:

Regeln Suche

arrays.max(array_of_ints_or_floats)

Beschreibung

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

Param-Datentypen

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

Unterstützt in:

Regeln Suche

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

Beschreibung

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

Param-Datentypen

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 Nullen ignoriert werden.

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

arrays.size

Unterstützt in:

Regeln Suche

arrays.size( array )

Beschreibung

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

Param-Datentypen

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird ein Strings-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

Unterstützt in:

Regeln Suche

arrays.index_to_float(array, index)

Beschreibung

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

Der Index ist ein Ganzzahlwert, 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 negativer Indexierung können Sie auf Arrayelemente relativ zum Ende des Arrays zugreifen. Ein Index von -1 bezieht sich beispielsweise auf das letzte Element im Array und ein Index von -2 auf das vorletzte Element im Array.

Param-Datentypen

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird ein Element mit dem 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 mit dem Index -1 aus einem Array von Gleitkommazahlen abgerufen.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], -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 mit dem 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 mit dem Index 2 aus einem Array von Ganzzahlen abgerufen.

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

arrays.index_to_int

Unterstützt in:

Regeln Suche

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 Ganzzahlwert, 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 negativer Indexierung können Sie auf Arrayelemente relativ zum Ende des Arrays zugreifen. Ein Index von -1 bezieht sich beispielsweise auf das letzte Element im Array und ein Index von -2 auf das vorletzte Element im Array.

Param-Datentypen

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 mit dem Index -1 zurück.

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

Beispiel 3

Für ein Element, das außerhalb des Bereichs liegt, wird 0 zurückgegeben.

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

Beispiel 4

Diese Funktion ruft das Element aus dem Float-Array mit dem 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 mit dem Index 0 ab.

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

arrays.index_to_str

Unterstützt in:

Regeln Suche

arrays.index_to_str(array, index)

Beschreibung

Gibt das Element am angegebenen Index aus dem Array als String zurück. Der Index ist ein Ganzzahlwert, 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 negativer Indexierung können Sie vom Ende des Arrays aus auf Arrayelemente zugreifen. Ein Index von -1 bezieht sich beispielsweise auf das letzte Element im Array und ein Index von -2 auf das vorletzte Element im Array.

Param-Datentypen

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

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

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

Beispiel 2

Im folgenden Beispiel wird ein Element mit dem Index -1 (das letzte Element des Arrays) aus einem String-Array abgerufen.

arrays.index_to_str(["test1", "test2", "test3", "test4"], -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. Dies führt dazu, dass ein leerer String zurückgegeben wird.

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 mit dem 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 mit dem 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

Unterstützt in:

Regeln Suche

cast.as_bool(string_or_int)

Beschreibung

Die Funktion wandelt einen Ganzzahl- oder Stringwert in einen Booleschen Wert um. Bei Funktionsaufrufen mit Werten, die nicht gecastet werden können, wird FALSE zurückgegeben. Gibt nur für die Ganzzahl 1 und den String „wahr“ (ohne Berücksichtigung der Groß- und Kleinschreibung) „TRUE“ zurück.

Param-Datentypen

INT|STRING

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

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

cast.as_bool("123") = false

Beispiel 2

Wahrheitsgemäße Ganzzahl (1)

cast.as_bool(1) = true

Beispiel 3

Wahrer String

cast.as_bool("true") = true

Beispiel 4

Großgeschriebener wahrer String

cast.as_bool("TRUE") = true

Beispiel 5

Negative Ganzzahl

cast.as_bool(-1) = false

Beispiel 6

Falsche Ganzzahl (0)

cast.as_bool(0) = false

Beispiel 7

Leerer String

cast.as_bool("") = false

cast.as_float

Unterstützt in:

Regeln Suche

cast.as_float(string_to_cast)

Beschreibung

Wandelt einen numerischen String in eine Gleitkommazahl um. Bei Funktionsaufrufen mit Werten, die nicht gecastet werden können, wird 0 zurückgegeben. Bei Gleitkommazahlen wird eine Genauigkeit von bis zu sieben Dezimalstellen beibehalten.

Param-Datentypen

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 Float-Wert zurückgegeben.

cast.as_float("1.012345678") = 1.0123456

Fingerprint

Unterstützt in:

Regeln

hash.fingerprint2011(byteOrString)

Beschreibung

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

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

Param-Datentypen

BTYE, STRING

Rückgabetyp

INT

Codebeispiel

id_fingerprint = hash.fingerprint2011("user123")

Gruppe

Unterstützt in:

Suche

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

Beschreibung

Gruppieren Sie Felder eines ähnlichen Typs in einer Platzhaltervariablen.

Bei der UDM-Suche werden gruppierte Felder verwendet, um in mehreren Feldern eines ähnlichen Typs zu suchen. Die Gruppenfunktion ähnelt gruppierten Feldern, mit der Ausnahme, dass Sie auswählen können, welche Felder Sie gruppieren möchten, um eine Erkennung auszulösen. Mit der Gruppenfunktion können Sie Informationen zu einer bestimmten Entität (z. B. einem Hostnamen, einer IP-Adresse oder einer Nutzer-ID) aus verschiedenen Nomen-Typen erfassen.

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

Codebeispiele

Beispiel 1

Gruppieren Sie alle IP-Adressen und geben Sie eine absteigende Anzahl der häufigsten IP-Adresse 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

Unterstützt in:

Regeln

hash.sha256(string)

Beschreibung

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

Param-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird der SHA-256-Hash 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

Unterstützt in:

Regeln Suche

math.abs(numericExpression)

Beschreibung

Gibt den Absolutwert eines Ganzzahl- oder Gleitkommaausdrucks zurück.

Param-Datentypen

NUMBER

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

In diesem Beispiel wird „wahr“ zurückgegeben, wenn das Ereignis mehr als 5 Minuten nach der angegebenen Zeit (in Sekunden seit der Unix-Epoche) eingetreten ist, unabhängig davon, ob es vor oder nach der angegebenen Zeit eingetreten ist. Ein Aufruf von math.abs kann nicht von mehreren Variablen oder Platzhaltern abhängen. Im folgenden Beispiel können Sie den hartcodierten Zeitwert 1643687343 beispielsweise nicht durch $e2.metadata.event_timestamp.seconds ersetzen.

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

math.ceil

Unterstützt in:

Regeln Suche

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 ist oder zu groß, um in eine int64-Zahl zu passen.

Param-Datentypen

FLOAT

Rückgabetyp

INT

Codebeispiele

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

Beispiel 1

In diesem Beispiel wird die Obergrenze einer ganzen Zahl zurückgegeben.

math.ceil(2.000000) = 2

Beispiel 2

In diesem Beispiel wird der größte Ganzzahlwert einer negativen Zahl zurückgegeben.

math.ceil(-1.200000) = -1

Beispiel 3

In diesem Beispiel wird 0 als Obergrenze einer Zahl zurückgegeben, die zu groß für eine 64-Bit-Ganzzahl ist.

math.ceil(184467440737095516160.0) = 0

math.floor

Unterstützt in:

Regeln Suche

math.floor(float_val)

Beschreibung

Gibt die größte Ganzzahl zurück, die nicht größer als der angegebene Wert ist (Abrunden). Gibt 0 zurück, wenn die Eingabe null ist oder zu groß, um in eine int64-Zahl zu passen.

Param-Datentypen

FLOAT

Rückgabetyp

INT

Codebeispiele

Beispiel 1

In diesem Beispiel wird eine positive Zahl verwendet.

math.floor(1.234568) = 1

Beispiel 2

In diesem Beispiel wird eine negative Zahl verwendet.

math.floor(-1.234568) = -2

Beispiel 3

Dieses Beispiel zeigt einen Nullfall.

math.floor(0.000000) = 0

math.geo_distance

Unterstützt in:

Regeln

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

Beschreibung

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

Param-Datentypen

FLOAT, FLOAT, FLOAT, FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem 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

In diesem 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

In diesem Beispiel wird -1 zurückgegeben, wenn einer der Parameter eine ungültige Koordinate ist.

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

Beispiel 4

In diesem Beispiel wird 0 zurückgegeben, wenn die Koordinaten übereinstimmen.

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

math.is_increasing

Unterstützt in:

Regeln Suche

math.is_increasing(num1, num2, num3)

Beschreibung

Nimmt eine Liste von numerischen Werten (Ganzzahlen oder Doppeltpräzisionszahlen) als Argument und gibt True zurück, wenn die Werte in aufsteigender Reihenfolge sind, andernfalls False.

Param-Datentypen

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 Null-INT64-Wert und einen positiven INT64-Wert.

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

Beispiel 3

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

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

Beispiel 4

Dieses Beispiel enthält zwei negative Doppelwerte und einen Nullwert vom Typ INT64.

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

Beispiel 5

Dieses Beispiel enthält einen negativen Doppel- und zwei identische Werte.

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

math.log

Unterstützt in:

Regeln Suche

math.log(numericExpression)

Beschreibung

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

Param-Datentypen

NUMBER

Rückgabetyp

NUMBER

Codebeispiele

Beispiel 1

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

math.pow

Unterstützt in:

Regeln Suche

math.pow(base, exponent)

Beschreibung

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

Param-Datentypen

Basis: INT|FLOAT Exponent: INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

Dieses Beispiel zeigt einen Ganzzahlfall.

math.pow(2, 2) // 4.00

Beispiel 2

Dieses Beispiel zeigt einen Basisfall für Brüche.

math.pow(2.200000, 3) // 10.648

Beispiel 3

Dieses Beispiel zeigt eine Bruchgrundzahl und eine Potenz.

math.pow(2.200000, 1.200000) // 2.575771

Beispiel 4

Dieses Beispiel zeigt einen negativen Leistungsfall.

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

Beispiel 5

Dieses Beispiel zeigt einen Fall mit einer Bruchpotenz.

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

Beispiel 6

Dieses Beispiel zeigt einen negativen Basisfall.

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

Beispiel 7

Dieses Beispiel zeigt einen Null-Basisfall.

math.pow(0, 3) // 0

Beispiel 8

Dieses Beispiel zeigt einen Fall ohne Stromversorgung.

math.pow(9223372036854775807, 0) // 1

Beispiel 9

Dieses Beispiel zeigt einen großen Basisfall.

math.pow(9223372036854775807, 1.200000) // 57262152889751593549824

math.random

Unterstützt in:

Regeln Suche

math.random()

Beschreibung

Erzeugt einen Pseudozufallswert vom Typ DOUBLE im Bereich von [0, 1), einschließlich 0 und exklusive 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

Unterstützt in:

Suche

math.round(numericExpression, decimalPlaces)

Beschreibung

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

Param-Datentypen

NUMBER

Rückgabetyp

NUMBER

Codebeispiele

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

math.sqrt

Unterstützt in:

Regeln Suche

math.sqrt(number)

Beschreibung

Gibt die Quadratwurzel der angegebenen Zahl zurück. Bei negativen Zahlen wird 0 zurückgegeben.

Param-Datentypen

INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

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

math.sqrt(3) = 1.732051

Beispiel 2

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

math.sqrt(-3) = 0.000000

Beispiel 3

In diesem Beispiel wird die Quadratwurzel von Null zurückgegeben.

math.sqrt(0) = 0.000000

Beispiel 4

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

math.sqrt(9.223372) = 3.037000

Beispiel 5

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

math.sqrt(-1.200000) = 0.000000

Messwerte

Unterstützt in:

Regeln

Mit Messwertfunktionen können große Mengen an Verlaufsdaten zusammengefasst werden. Sie können dies in Ihrer Regel mit metrics.functionName() im Abschnitt „Ergebnis“ verwenden.

Weitere Informationen finden Sie unter YARA-L-Messwerte.

net.ip_in_range_cidr

Unterstützt in:

Regeln Suche

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Beschreibung

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

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

Wenn Sie in einem IP-Adressbereich 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 IP-Adressbereich 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.

Param-Datentypen

STRING, STRING

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

IPv4-Beispiel:

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

Beispiel 2

IPv6-Beispiel:

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

Eine Beispielregel mit der net.ip_in_range_cidr()-Anweisung finden Sie unter Einzelnes Ereignis innerhalb eines IP-Adressbereichs.

re.regex

Unterstützt in:

Regeln Suche

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

• Verwendung der YARA-L-Syntax – bezieht sich auf Ereignisse. Hier eine allgemeine Darstellung dieser Syntax:

  $e.field = /regex/
  

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

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

  Hier 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 einzufügen.

Hinweise

• Wenn Sie nach dem genauen String oder nur nach einem Präfix oder Suffix suchen möchten, fügen Sie die Ankerzeichen ^ (Anfang) und $ (Ende) in den regulären Ausdruck ein. Beispielsweise stimmt /^full$/ genau mit "full" überein, während /full/ mit "fullest", "lawfull" und "joyfully" übereinstimmen könnte.
• Wenn das UDM-Feld Zeilenumbruchzeichen enthält, wird regexp nur mit der ersten Zeile des UDM-Felds abgeglichen. Wenn Sie einen vollständigen Abgleich der UDM-Felder erzwingen möchten, 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 die Groß-/Kleinschreibung bei der Suche ignoriert werden soll.

Param-Datentypen

STRING, STRING

Parameterausdruckstypen

ANY, ANY

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

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

re.capture

Unterstützt in:

Regeln Suche

re.capture(stringText, regex)

Beschreibung

Erfasst (extrahiert) Daten aus einem String mit dem im Argument angegebenen regulären Ausdrucksmuster.

Diese Funktion nimmt zwei Argumente an:

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

Der reguläre Ausdruck kann 0 oder 1 Erfassungsgruppen in Klammern enthalten. Wenn der reguläre Ausdruck keine Erfassungsgruppen enthält, gibt die Funktion den ersten ü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.

Param-Datentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel würde Folgendes wahr sein, wenn $e.principal.hostname „aaa1bbaa2“ enthält, da die Funktion die erste Instanz zurückgibt. In diesem Beispiel gibt es 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 [e-mail] lautet, 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, bei denen keine Übereinstimmung gefunden wird, ausschließen, indem Sie den leeren String ausschließen. Das ist besonders wichtig, wenn Sie re.capture() mit einer Ungleichheit verwenden:

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

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

re.replace

Unterstützt in:

Regeln Suche

re.replace(stringText, replaceRegex, replacementText)

Beschreibung

Führt einen regulären Ausdrucksersatz durch.

Diese Funktion akzeptiert drei Argumente:

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

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

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

Param-Datentypen

STRING, STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

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

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

Beispiel 2

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

"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 bei leeren Strings und re.replace() Folgendes:

Leerer String als replaceRegex verwenden:

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

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

Unterstützt in:

Regeln

optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

Beschreibung

Mit dieser Funktion wird anhand einer deterministischen Stichprobenstrategie festgelegt, ob ein Ereignis eingeschlossen werden soll. Diese Funktion gibt Folgendes zurück:

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

Diese Funktion ist für Optimierungsszenarien nützlich, in denen nur eine Teilmenge von Ereignissen verarbeitet werden soll. Entspricht:

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Param-Datentypen

• byteOrString: Ausdruck, der zu BYTE oder STRING ausgewertet wird.
• rateNumerator: 'INT'
• rateDenominator: 'INT'

Rückgabetyp

BOOL

Codebeispiel

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

  match:
    $asset_id over 1h

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

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

strings.base64_decode

Unterstützt in:

Regeln Suche

strings.base64_decode(encodedString)

Beschreibung

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

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

Param-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

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

strings.coalesce

Unterstützt in:

Regeln Suche

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

Beschreibung

Diese Funktion nimmt eine unbegrenzte Anzahl von Argumenten an und gibt den Wert des ersten Ausdrucks zurück, der nicht zu einem leeren String führt (z. B. „Wert ungleich Null“). Wenn alle Argumente zu einem leeren String führen, 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.

Param-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Im folgenden Beispiel werden Stringvariablen als Argumente verwendet. Die Bedingung wird als wahr ausgewertet, wenn (1) $e.network.email.from = [e-mail] oder (2) $e.network.email.from leer ist und $e.network.email.to = [e-mail].

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

Beispiel 2

Im folgenden Beispiel wird die Funktion coalesce mit mehr als zwei Argumenten aufgerufen. Bei dieser Bedingung wird die erste nicht nullwertige IP-Adresse aus dem Ereignis $e mit den Werten in der Referenzliste ip_watchlist verglichen. Die Argumente werden in diesem Aufruf in der Reihenfolge zusammengeführt, in der sie in der Regelbedingung aufgezählt 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. Wenn die vorherigen ip-Felder nicht festgelegt sind, wird der String „Kein IP“ als Standardwert zurückgegeben.

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

Beispiel 3

Im folgenden Beispiel wird versucht, principal.hostname aus 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

Unterstützt in:

Regeln Suche

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

Beschreibung

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

Wenn Argumente Ereignisfelder sind, müssen die Attribute aus demselben Ereignis stammen.

Param-Datentypen

STRING, FLOAT, INT

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Im folgenden Beispiel werden eine Stringvariable und eine Ganzzahlvariable als Argumente verwendet. Sowohl principal.hostname als auch principal.port stammen aus demselben Ereignis, $e, und werden zu einem String zusammengefügt.

"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 Stringvariable und ein Floatliteral als Argumente verwendet. Wenn Gleitkommazahlen als Strings dargestellt werden, werden ganze Zahlen ohne Dezimalpunkt formatiert.Beispiel: 1, 0 wird als „1“ dargestellt. Außerdem werden Gleitkommazahlen, die mehr als 16 Dezimalziffern haben, auf die 16. Dezimalziffer abgeschnitten.

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

Beispiel 4

Im folgenden Beispiel werden als Argumente eine Stringvariable, ein Stringliteral, eine Ganzzahlvariable und ein Gleitkommaliteral verwendet. Alle Variablen stammen aus demselben Ereignis, $e, und werden mit den Literalen zusammengefügt, 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 Ereignis $e1 mit „principal.hostname“ aus Ereignis $e2 zu konkatenieren. 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

Unterstützt in:

Regeln Suche

strings.contains( str, substr )

Beschreibung

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

Param-Datentypen

STRING, STRING

Rückgabetyp

BOOL

Codebeispiele

Beispiel 1

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

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

Beispiel 2

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

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

strings.count_substrings

Unterstützt in:

Regeln Suche

strings.count_substrings(string_to_search_in, substring_to_count)

Beschreibung

Gibt bei Angabe eines Strings und eines Teilstrings ein INT64 mit der Anzahl der sich nicht überschneidenden Vorkommen des Teilstrings im String zurück.

Param-Datentypen

STRING, STRING

Rückgabetyp

INT

Codebeispiele

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

Beispiel 1

In diesem Beispiel wird ein nicht nullwertiger String und ein nicht nullwertiges einzelnes Teilstringzeichen verwendet.

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

Beispiel 2

In diesem Beispiel werden ein nicht nullwertiger String und ein nicht nullwertiger Teilstring mit mehr als einem Zeichen verwendet.

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

Beispiel 3

In diesem Beispiel wird ein nicht nullwertiger String und ein leerer Teilstring verwendet.

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

Beispiel 4

In diesem Beispiel wird ein leerer String und ein nicht nullwertiger Teilstring mit mehr als einem Zeichen verwendet.

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

Beispiel 5

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

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

Beispiel 6

In diesem Beispiel werden ein nicht nullwertiger String und ein nicht nullwertiger Teilstring verwendet, der mehr als ein Zeichen und mehr als ein Vorkommen hat.

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

Beispiel 7

In diesem Beispiel werden ein nicht nullwertiger String und ein nicht nullwertiger Teilstring verwendet, der mehr als ein Zeichen und mehr als ein Vorkommen hat. Hier wird die Einschränkung bei sich überschneidenden Teilstring-Vorkommen verdeutlicht.

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

strings.extract_domain

Unterstützt in:

Regeln Suche

strings.extract_domain(url_string)

Beschreibung

Extrahiert die Domain aus einem String.

Hinweis:Die Funktion führt keine Unicode-Normalisierung durch.

Hinweis:Die Daten zu öffentlichen Suffixen bei publicsuffix.org enthalten auch private Domains. Diese Funktion behandelt eine private Domain nicht als öffentliches Suffix. Wenn „us.com“ beispielsweise eine private Domain in den Daten zu öffentlichen Suffixen ist, wird für „foo.us.com“ „us.com“ (das öffentliche Suffix „com“ plus das vorhergehende Label „us“) zurückgegeben, anstatt „foo.us.com“ (die private Domain „us.com“ plus das vorhergehende Label „foo“).

Hinweis :Die Daten zu öffentlichen Suffixen können sich im Laufe der Zeit ändern. Folglich kann die Eingabe, die derzeit einen leeren Standardwert erzeugt, in Zukunft einen nicht leeren Wert erzeugen.

Param-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Dieses Beispiel zeigt einen leeren String.

strings.extract_domain("") = ""

Beispiel 2

Zufallsstring, keine URL

strings.extract_domain("1234") = ""

Beispiel 3

mehrere Backslashes

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

Beispiel 4

Nicht alphabetische Zeichen werden korrekt behandelt

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 der URL #

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

Beispiel 9

Positiver Testfall

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

strings.extract_hostname

Unterstützt in:

Regeln Suche

strings.extract_hostname(string)

Beschreibung

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

Param-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird ein leerer String zurückgegeben.

strings.extract_hostname("") = ""

Beispiel 2

Zufallsstring, keine URL

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

Beispiel 3

mehrere umgekehrte Schrägstriche

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

Beispiel 4

Nicht lateinische Zeichen werden korrekt behandelt

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 der URL #

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

strings.from_hex

Unterstützt in:

Regeln Suche

strings.from_hex(hex_string)

Beschreibung

Gibt die mit dem angegebenen Hexadezimalstring verknüpften Bytes zurück.

Param-Datentypen

STRING

Rückgabetyp

BYTES

Codebeispiele

Bytes abrufen, die mit einem bestimmten Hexadezimalstring verknüpft sind.

Beispiel 1

In diesem Beispiel werden keine Hexadezimalzeichen umgewandelt.

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

Beispiel 2

Dieses Beispiel zeigt eine Eingabe mit einem leeren String.

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

Beispiel 3

Dieses Beispiel zeigt die Konvertierung von Hexadezimalstrings.

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

Beispiel 4

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

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

strings.ltrim

Unterstützt in:

Regeln Suche

strings.ltrim(string_to_trim, cutset)

Beschreibung

Entfernt vorangestellte Leerzeichen aus einem bestimmten String. Mit dieser Funktion werden führende Zeichen in diesem Cutset entfernt.

Param-Datentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Im Folgenden finden Sie einige Anwendungsfälle.

Beispiel 1

In diesem Beispiel werden dasselbe erste und zweite Argument 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

Unterstützt in:

Regeln Suche

strings.reverse(STRING)

Beschreibung

Gibt den umgekehrten String zurück.

Param-Datentypen

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

Unterstützt in:

Regeln Suche

strings.rtrim(string_to_trim, cutset)

Beschreibung

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

Param-Datentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Im Folgenden finden Sie einige Anwendungsfälle.

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

Unterstützt in:

Regeln Suche

strings.to_lower(stringText)

Beschreibung

Diese Funktion nimmt einen Eingabestring entgegen und gibt einen String zurück, nachdem alle Zeichen in Kleinbuchstaben umgewandelt wurden.

Param-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Im folgenden Beispiel wird true zurückgegeben.

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

strings.to_upper

Unterstützt in:

Regeln Suche

strings.to_upper(string_val)

Beschreibung

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

Param-Datentypen

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

Unterstützt in:

Regeln Suche

strings.trim(string_to_trim, cutset)

Beschreibung

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

Param-Datentypen

STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Im Folgenden finden Sie einige Anwendungsfälle.

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, was zum ursprünglichen String „str“ führt, da im Cutset keine Zeichen zum Entfernen 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 es keine Zeichen zum Entfernen gibt.

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

Beispiel 4

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

• Leerzeichen am Ende von „a aastraa aa“
• die im Cutset angegebenen Zeichen (Leerzeichen, a)

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

strings.url_decode

Unterstützt in:

Regeln Suche

strings.url_decode(url_string)

Beschreibung

Entschlüsseln Sie die Escape-Zeichen und verarbeiten Sie codierte UTF-8-Zeichen in einem URL-String. Gibt einen leeren String zurück, wenn die Dekodierung fehlschlägt.

Param-Datentypen

STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Dieses Beispiel zeigt einen positiven Testfall.

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

Beispiel 2

Dieses Beispiel zeigt einen leeren String.

strings.url_decode("") // ""

Beispiel 3

In diesem Beispiel wird die Verarbeitung von Zeichen dargestellt, die nicht zum Alphabet gehören.

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

Beispiel 4

Dieses Beispiel zeigt eine Beispiel-URL-Dekodierung.

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

Unterstützt in:

Regeln Suche

timestamp.as_unix_seconds(timestamp [, time_zone])

Beschreibung

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

• timestamp ist ein String, der einen gültigen Epochenzeitstempel 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 mithilfe von Stringliteralen angeben. Es gibt folgende Optionen:
  • Der Name der TZ-Datenbank, 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"

Param-Datentypen

STRING, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

Gültiger Zeitstempel der Epoche

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

Beispiel 2

Gültiger Epochenzeitstempel mit der Zeitzone „America/New_York“

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

timestamp.current_seconds

Unterstützt in:

Regeln Suche

timestamp.current_seconds()

Beschreibung

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

Param-Datentypen

NONE

Rückgabetyp

INT

Codebeispiele

Beispiel 1

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

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

timestamp.get_date

Unterstützt in:

Regeln Suche

timestamp.get_date(unix_seconds [, time_zone])

Beschreibung

Diese Funktion gibt einen String im Format YYYY-MM-DD zurück, der den Tag eines Zeitstempels angibt.

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden seit der Unix-Epoche angibt, 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 Sie diesen Parameter weglassen, wird „GMT“ als Standard verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte Name der Zeitzonendatenbank auf dieser Seite.
  • Der Zeitzonenversatz von UTC im Format(+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige Zeitzonen-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"

Param-Datentypen

INT, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

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

$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

Unterstützt in:

Regeln Suche

timestamp.get_minute(unix_seconds [, time_zone])

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden seit der Unix-Epoche angibt, 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 mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte Name der Zeitzonendatenbank auf dieser Seite.
  • 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"

Param-Datentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

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

$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

Unterstützt in:

Regeln Suche

timestamp.get_hour(unix_seconds [, time_zone])

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden seit der Unix-Epoche angibt, 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 Sie diesen Parameter weglassen, wird „GMT“ als Standard verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte Name der Zeitzonendatenbank auf dieser Seite.
  • 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"

Param-Datentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

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

$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

Unterstützt in:

Regeln Suche

timestamp.get_day_of_week(unix_seconds [, time_zone])

Beschreibung

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

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden seit der Unix-Epoche angibt, 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 Sie diesen Parameter weglassen, wird „GMT“ als Standard verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte Name der Zeitzonendatenbank auf dieser Seite.
  • Der Zeitzonenversatz von UTC im Format(+|-)H[H][:M[M]], z. B. „-08:00“.

Hier sind Beispiele für gültige Zeitzonen-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"

Param-Datentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

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

$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

Unterstützt in:

Regeln Suche

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

Beschreibung

Diese Funktion gibt einen String im Format YYYY-MM-DD zurück, der den Tag eines Zeitstempels angibt.

• unix_seconds ist eine Ganzzahl, die die Anzahl der Sekunden seit der Unix-Epoche angibt, 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 mithilfe von Stringliteralen angeben. Optionen 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 mithilfe von Stringliteralen angeben. Es gibt folgende Optionen:
  • Der Name der IANA-Zeitzonendatenbank (TZ), 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"

Param-Datentypen

INT, STRING, STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

In diesem Beispiel wird das Argument time_zone weggelassen, sodass standardmäßig GMT verwendet wird.

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

timestamp.get_week

Unterstützt in:

Regeln Suche

timestamp.get_week(unix_seconds [, time_zone])

Beschreibung

Diese Funktion gibt eine Ganzzahl im Bereich [0, 53] zurück, die die Woche des Jahres angibt. 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 angibt, 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 Sie diesen Parameter weglassen, wird „GMT“ als Standard verwendet. Sie können Zeitzonen mithilfe von Stringliteralen angeben. Folgende Optionen sind verfügbar:
  • Der Name der TZ-Datenbank, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte Name der Zeitzonendatenbank auf dieser Seite.
  • 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"

Param-Datentypen

INT, STRING

Rückgabetyp

INT

Codebeispiele

Beispiel 1

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

$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

Unterstützt in:

Regeln Suche

timestamp.now()

Beschreibung

Gibt die Anzahl der Sekunden seit 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

Unterstützt in:

Regeln

window.avg(numeric_values [, should_ignore_zero_values])

Beschreibung

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

Param-Datentypen

INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem Beispiel wird der Ganzzahldurchschnitt 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 Mittelwert mit Nachkommastellen dargestellt.

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

Negativer Mittelwert der Eingabe

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 ergibt 0

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

Nullwerte 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

Unterstützt in:

Regeln

window.first(values_to_sort_by, values_to_return)

Beschreibung

Diese Aggregationsfunktion gibt einen Stringwert zurück, der von einem Ereignis mit dem niedrigsten korrespondierenden Ganzzahlwert im Abgleichszeitraum abgeleitet wurde. Ein Beispiel für einen Anwendungsfall ist das Abrufen der User-ID aus dem Ereignis mit dem niedrigsten Zeitstempel im Abgleichszeitraum (das früheste Ereignis).

Param-Datentypen

INT, STRING

Rückgabetyp

STRING

Codebeispiele

Stringwert, der von einem Ereignis mit dem niedrigsten korrespondierenden 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

Unterstützt in:

Regeln

window.last(values_to_sort_by, values_to_return)

Beschreibung

Diese Aggregationsfunktion gibt einen Stringwert zurück, der von einem Ereignis mit dem höchsten korrespondierenden Ganzzahlwert im Abgleichszeitraum abgeleitet wurde. Ein Beispiel für einen Anwendungsfall ist das Abrufen der User-ID aus dem Ereignis mit dem niedrigsten Zeitstempel im Abgleichszeitraum (höchster Zeitstempel).

Param-Datentypen

INT, STRING

Rückgabetyp

STRING

Codebeispiele

Stringwert abrufen, der aus einem Ereignis mit dem höchsten korrespondierenden Ganzzahlwert 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

Unterstützt in:

Regeln

window.median(numeric_values, should_ignore_zero_values)

Beschreibung

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

Param-Datentypen

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 Nullwerte enthält, die nicht 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 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 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

Unterstützt in:

Regeln

window.mode(values)

Beschreibung

Gibt den Modus der Eingabewerte zurück. Bei mehreren möglichen Moduswerten wird nur einer dieser Werte nicht deterministisch als Rückgabewert ausgewählt.

Param-Datentypen

INT|FLOAT|STRING

Rückgabetyp

STRING

Codebeispiele

Beispiel 1

Der Modus der Werte im Abgleichfenster wird abgerufen.

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

Unterstützt in:

Regeln

window.stddev(numeric_values)

Beschreibung

Gibt die Standardabweichung der Eingabewerte in einem Übereinstimmungsfenster zurück.

Param-Datentypen

INT|FLOAT

Rückgabetyp

FLOAT

Codebeispiele

Beispiel 1

In diesem Beispiel wird die Standardabweichung von Ganzzahlen in einem Übereinstimmungsfenster 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 Abgleichfenster 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 Übereinstimmungsfenster zurückgegeben, das negative Zahlen enthält.

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 Abgleichfenster 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 Übereinstimmungsfensters 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

Unterstützt in:

Regeln

window.variance(values)

Beschreibung

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

Param-Datentypen

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 Wert für die Varianz 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 Nullvarianz 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 positiver und negativer 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

Zuweisung von Funktionen zu Platzhaltern

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

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

Sie können die Platzhaltervariablen dann 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 einer Zuweisung von Funktionen zu Platzhaltern 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 einem und nur einem Ereignis abhängen. In Funktionsaufrufargumenten können jedoch mehrere Felder aus demselben Ereignis verwendet werden. Folgendes ist beispielsweise gültig:

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

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

   Folgendes ist jedoch ungültig:

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

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

Syntax von Referenzlisten

Weitere Informationen 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 ist die Syntax für die Verwendung verschiedener Arten von Referenzlisten in einer Regel:

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

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

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

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

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

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

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

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

• 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

Typprüfung

Google Security Operations führt eine Typprüfung anhand Ihrer YARA-L-Syntax durch, wenn Sie Regeln in der Benutzeroberfläche erstellen. Anhand der angezeigten Fehler bei der Typprüfung können Sie die Regel so überarbeiten, dass sie wie erwartet funktioniert.

Die folgenden Prädikate sind ungültig:

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

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

Stichprobenerhebung von Erkennungsereignissen

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

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

Wenn Sie mehr Informationen zu den Ereignissen benötigen, die zur Erkennung geführt haben, können Sie im Abschnitt „Ergebnis“ Aggregationen verwenden, um zusätzliche Informationen in der Erkennung auszugeben.

Wenn Sie sich Erkennungen in der Benutzeroberfläche ansehen, können Sie alle Ereignis-Samples für eine Erkennung herunterladen. Weitere Informationen finden Sie unter Downloadereignisse.