YARA-L 2.0-Sprachsyntax

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

Regelstruktur

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

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

Hinweis: Wenn Sie den optionalen Abschnitt match weglassen, wird die Regel nur mit einem Ereignis abgeglichen.

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

Kommentare

Kennzeichne Kommentare mit zwei Schrägstrichen (// comment) oder mehrzeiligen Kommentaren mit Schrägstrich (/* comment */) wie in C.

Literale

Nicht negative Ganzzahlen (ohne Dezimalstellen), String-, boolesche und Regex-Literale werden unterstützt.

String- und Regex-Literale

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

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

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

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

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

Sie können Stringliterale auch als Regex-Literale verwenden, wenn Sie die Funktion re.regex() verwenden. Beachten Sie, dass Sie bei Stringliteralen in doppelten Anführungszeichen umgekehrte Schrägstriche mit umgekehrten Schrägstrichen maskieren müssen.

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

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

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

Operatoren

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

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

Variablen

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

Sie können die folgenden Variablentypen definieren:

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

• Übereinstimmungsvariablen – Deklarieren Sie im Abschnitt match. Übereinstimmungsvariablen werden zu Gruppierungsfeldern für die Abfrage, da für jeden eindeutigen Satz von Übereinstimmungsvariablen (und für jedes Zeitfenster) eine Zeile zurückgegeben wird. Wenn die Regel eine Übereinstimmung findet, werden die Werte der Übereinstimmungsvariablen zurückgegeben. Geben Sie im Abschnitt events an, wofür jede Keyword-Variable steht.

• Platzhaltervariablen – Im Abschnitt events deklarieren und definieren. Platzhaltervariablen ähneln Übereinstimmungsvariablen. Sie können jedoch Platzhaltervariablen im Abschnitt condition verwenden, um Übereinstimmungsbedingungen anzugeben.

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

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

Karten

Structs und Labels

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

Wenn Sie sowohl in Struct als auch in Label nach einem bestimmten Schlüssel/Wert-Paar suchen möchten, verwenden Sie die Standardsyntax für die Zuordnung:

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

Unterstützte Fälle

Ereignisse und Ergebnisse

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

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

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

any- oder all-Keywords mit einer Karte kombinieren

Folgendes wird derzeit beispielsweise nicht unterstützt: all $e.udm.additional.fields["pod_name"] = "kube-scheduler"

Functions

In diesem Abschnitt werden die YARA-L 2.0-Funktionen beschrieben, die Chronicle in der Erkennungs-Engine unterstützt.

Diese Funktionen können in den folgenden Bereichen einer Regel verwendet werden:

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

Stringfunktionen

Chronicle unterstützt die folgenden Funktionen zur Stringbearbeitung:

• string.concat(a, b)
• Strings.coalesce(a, b)
• string.to_lower(stringText)
• string.to_upper(stringText)
• string.base64_decode(encodedString)

In den folgenden Abschnitten wird die Verwendung beschrieben.

Verkettete Strings oder Ganzzahlen

Gibt die Verkettung von zwei Strings, zwei Ganzzahlen oder einer Kombination aus beiden zurück.

strings.concat(a, b)

Diese Funktion verwendet zwei Argumente, die entweder Strings oder Ganzzahlen sein können, und gibt die beiden als String verketteten Werte zurück. Ganzzahlen werden vor der Verkettung in einen String umgewandelt. Die Argumente können Literale oder Ereignisfelder sein. Wenn beide Argumente Felder sind, müssen die beiden Attribute aus demselben Ereignis stammen.

Das folgende Beispiel enthält eine Stringvariable und ein String-Literal als Argumente.

"google-test" = strings.concat($e.principal.hostname, "-test")

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

"google80" = strings.concat($e.principal.hostname, $e.principal.port)

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

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

Stringwerte verketten

Gibt den Wert des ersten Ausdrucks zurück, der keinen leeren String ergibt (z. B. „Wert ungleich null“). Wenn beide Argumente einen leeren String ergeben, gibt der Funktionsaufruf einen leeren String zurück.

strings.coalesce(a, b)

Die Argumente können Literale, Ereignisfelder oder Funktionsaufrufe sein. Beide Argumente müssen vom Typ STRING sein. Wenn beide Argumente Felder sind, müssen die beiden Attribute aus demselben Ereignis stammen.

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

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

Das folgende Beispiel enthält verschachtelte Coalesce-Aufrufe. Diese Bedingung vergleicht die erste Nicht-Null-IP-Adresse aus Ereignis $e mit Werten in der Referenzliste ip_watchlist. Die Reihenfolge, in der die Argumente in diesem Aufruf zusammengeführt werden, entspricht der Reihenfolge, in der sie in der Regelbedingung aufgeführt sind:

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

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

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

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

String in Großbuchstaben umwandeln

Diese Funktionen geben Stringtext zurück, nachdem alle Zeichen in Groß- oder Kleinschreibung geändert wurden.

• string.to_lower(stringText)
• string.to_upper(stringText)

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

Base64-Decodierung eines Strings

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

strings.base64_decode(encodedString)

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

In diesem Beispiel wird „True“ zurückgegeben, wenn „main.domain.name“ „dGVzdA==" ist. Das ist die base64-Codierung für den String „test“.

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

RegExp-Funktionen

Chronicle unterstützt die folgenden Funktionen für reguläre Ausdrücke:

• re.regex(stringText, Regex)
• re.capture(stringText, Regex)
• re.replace(stringText, replaceRegex, ErsatzText)

Übereinstimmung mit regulärem Ausdruck

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

• YARA-Syntax verwenden – Diese bezieht sich auf Ereignisse. Im Folgenden finden Sie eine allgemeine Darstellung dieser Syntax: $e.field = /regex/
• Verwendung der YARA-L-Syntax: Diese Funktion übernimmt folgende Parameter:
  • Das Feld, auf das der reguläre Ausdruck angewendet wird.
  • Regulärer Ausdruck als String. Sie können den nocase-Modifikator nach Strings verwenden, um anzugeben, dass die Suche die Groß- und Kleinschreibung ignorieren soll. Im Folgenden finden Sie eine allgemeine Darstellung dieser Syntax: re.regex($e.field, `regex`)

Beachten Sie beim Definieren regulärer Ausdrücke in YARA-L 2.0 Folgendes:

• In beiden Fällen ist das Prädikat wahr, wenn der String einen Teilstring enthält, der dem angegebenen regulären Ausdruck entspricht. Es ist nicht nötig, .* am Anfang oder Ende des regulären Ausdrucks hinzuzufügen.
• Für den genauen String oder nur ein Präfix oder Suffix fügen Sie die Ankerzeichen ^ (Anfang) und $ (Ende) in den regulären Ausdruck ein. Beispielsweise entspricht /^full$/ genau "full", während /full/ mit "fullest", "lawfull" und "joyfully" übereinstimmen kann.
• Wenn das UDM-Feld Zeilenumbruchzeichen enthält, stimmt regexp nur mit der ersten Zeile des UDM-Felds überein. Fügen Sie dem regulären Ausdruck ein (?s) hinzu, um den vollständigen UDM-Feldabgleich zu erzwingen. Ersetzen Sie beispielsweise /.*allUDM.*/ durch /(?s).*allUDM.*/.

Regex-Erfassung

Erfasst (extrahiert) Daten aus einem String mit dem Muster für reguläre Ausdrücke, das im Argument angegeben wird.

re.capture(stringText, regex)

Diese Funktion verwendet zwei Argumente:

• stringText: der ursprüngliche String, nach dem gesucht werden soll.
• Regulärer Ausdruck: der reguläre Ausdruck, der das Muster angibt, nach dem gesucht werden soll

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

Wenn in diesem Beispiel $e.prinzip.hostname „aaa1bbaa2“ enthält, ist Folgendes „True“, da die Funktion die erste Instanz zurückgibt. In diesem Beispiel gibt es keine Erfassungsgruppen.

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

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

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

Wenn der reguläre Ausdruck mit keinem Teilstring im Text übereinstimmt, gibt die Funktion einen leeren String zurück. Sie können Ereignisse auslassen, bei denen keine Übereinstimmung auftritt, indem Sie den leeren String ausschließen. Dies ist besonders wichtig, wenn Sie re.capture() mit 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 , "@(.*)")

Regulärer Ersatz

Ersetzt einen regulären Ausdruck.

re.replace(stringText, replaceRegex, replacementText)

Diese Funktion verwendet drei Argumente:

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

Gibt einen neuen String aus dem ursprünglichen StringText zurück, in dem alle Teilstrings, die mit dem Muster in replaceRegex übereinstimmen, durch den Wert in replacementText ersetzt werden. Sie können in Ersatztext Ziffern mit umgekehrtem Schrägstrich (\1 bis \9) verwenden, um Text einzufügen, der mit der entsprechenden Klammergruppe im Ersatz-Regex-Muster übereinstimmt. Verwenden Sie \0, um auf den gesamten übereinstimmenden Text zu verweisen.

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

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

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

In diesem Beispiel werden im Ersatztext-Argument Ziffern mit umgekehrtem Schrägstrich 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"
                     )

Beachten Sie die folgenden Fälle bei leeren Strings und re.replace():

Leerer String als replaceRegex verwendet:

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

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

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

Datumsfunktionen

Chronicle unterstützt die folgenden datumsbezogenen Funktionen:

• timestamp.get_minute(unix_seconds [, time_zone])
• timestamp.get_hour(unix_seconds [, time_zone])
• timestamp.get_day_of_week(unix_seconds [, time_zone])
• timestamp.get_week(unix_seconds [, time_zone])
• timestamp.current_seconds()

Chronicle unterstützt negative Ganzzahlen als Argument „unix_seconds“. Negative Ganzzahlen stehen für Zeiten vor der Unix-Epoche. Wenn Sie eine ungültige Ganzzahl angeben, z. B. einen Wert, der zu einem Überlauf führt, gibt die Funktion „-1“ zurück. Das ist ein ungewöhnliches Szenario.

Da YARA-L 2 keine negativen Ganzzahlliterale unterstützt, sollten Sie prüfen, ob diese Bedingung mit dem Operator „Kleiner als“ oder „Kleiner als“ verwendet wird. Beispiel:

0 > timestamp.get_hour(123)

Zeitextraktion

Gibt eine Ganzzahl im Bereich [0, 59] zurück.

timestamp.get_minute(unix_seconds [, time_zone])

Die folgende Funktion gibt eine Ganzzahl im Bereich [0, 23] zurück, die die Tageszeit darstellt.

timestamp.get_hour(unix_seconds [, time_zone])

Die folgende Funktion gibt eine Ganzzahl im Bereich [1, 7] zurück, die den Wochentag beginnt, beginnend mit Sonntag. Beispiel: 1 = Sonntag; 2 = Montag usw.

timestamp.get_day_of_week(unix_seconds [, time_zone])

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

timestamp.get_week(unix_seconds [, time_zone])

Diese Funktionen zur Zeitextraktion haben die gleichen Argumente.

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

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

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

In diesem Beispiel wird ein String-Literal verwendet, um die Zeitzone zu definieren.

$ts = $e.metadata.collected_timestamp.seconds

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

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

• "America/Los_Angeles" oder "-08:00". ("PST" wird nicht unterstützt)
• "America/New_York" oder "-05:00". ("EST" wird nicht unterstützt)
• "Europe/London"
• "UTC"
• "GMT"

Aktueller Zeitstempel

Gibt eine Ganzzahl zurück, die die aktuelle Zeit in Unix-Sekunden darstellt. Dieser Wert entspricht etwa dem Erkennungszeitstempel und basiert auf der Ausführung der Regel.

timestamp.current_seconds()

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

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

Mathematische Funktionen:

Absoluter Wert

Gibt den absoluten Wert eines ganzzahligen Ausdrucks zurück.

math.abs(intExpression)

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

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

NET-Funktionen

IP-Subnetzwerksuche

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

net.ip_in_range_cidr(ipAddress, subnetworkRange)

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

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

Beispiel für IPv4:

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

Beispiel für IPv6:

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

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

Funktion für Platzhalterzuweisung

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

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

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

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

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

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

   Das folgende Beispiel ist jedoch ungültig:

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

2. Der Funktionsaufruf sollte von einem und genau einem Ereignis abhängen. Allerdings können mehrere Felder desselben Ereignisses in Argumenten für Funktionsaufrufe verwendet werden. Beispiel:

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

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

   Folgendes ist jedoch ungültig:

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

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

Syntax von Referenzlisten

Weitere Informationen zum Verhalten von Referenzlisten und zur Referenzlistensyntax 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

Du kannst auch den Operator not mit Referenzlisten verwenden, wie hier gezeigt: not $e.principal.hostname in regex %my_regex_list.

Aus Leistungsgründen schränkt die Erkennungs-Engine die Nutzung von Referenzlisten ein. Sie können in einer Regel bis zu sieben in-Anweisungen und in derselben Regel mehrere Typen von in-Anweisungen verwenden. Für maximal zwei der sieben in-Anweisungen können die speziellen Operatoren regex oder cidr verwendet werden.

Der Operator nocase funktioniert nicht mit Referenzlisten. Das Einfügen von nocase nach einem Referenzlistenaufruf hat keine Auswirkungen und wird nicht empfohlen.

Syntax des Metabereichs

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

<key> = "<value>"

Das folgende Beispiel zeigt eine gültige Zeile im Abschnitt meta: meta: author = "Chronicle" severity = "HIGH"

Syntax des Ereignisbereichs

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

• Bedeutung der einzelnen Übereinstimmungen oder Platzhaltervariablen
• Einfache binäre Ausdrücke als Bedingungen
• Funktionsausdrücke als Bedingungen
• Verweise auf Listenlisten als Bedingungen
• Logische Operatoren

Variablendeklarationen

Für Variablendeklarationen verwenden Sie die folgende Syntax:

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

Beide sind äquivalent, wie in den folgenden Beispielen gezeigt:

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

Diese Deklaration gibt an, dass diese Variable das angegebene Feld für die Ereignisvariable darstellt. Wenn das Ereignisfeld ein wiederkehrendes Feld ist, kann die Übereinstimmungsvariable einen beliebigen Wert im Array darstellen. Es ist auch möglich, einer einzelnen Übereinstimmungs- oder Platzhaltervariable mehrere Ereignisfelder zuzuweisen. Dies ist eine vorübergehende Join-Bedingung.

Beispiel:

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

Entspricht:

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

Wenn eine Variable verwendet wird, muss sie über die Variablendeklaration deklariert werden. Wenn eine Variable ohne Deklaration verwendet wird, wird sie als Kompilierungsfehler betrachtet.

Einfache binäre Ausdrücke als Bedingungen

Verwenden Sie die folgende Syntax, um einen einfachen Binärausdruck als Bedingung zu verwenden:

• <EXPR> <OP> <EXPR>

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

Beispiel:

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

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

Funktionsausdrücke als Bedingungen

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

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

Beispiel:

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

Verweise auf Listenlisten als Bedingungen

Im Ereignisbereich können Sie Referenzlisten verwenden. Weitere Informationen finden Sie im Abschnitt Referenzlisten.

Logische Operatoren

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

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

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

Beispiel: "a or b and c" wird als "a or (b and c)" ausgewertet. Bei Bedarf können Sie Klammern verwenden, um die Priorität zu ändern.

Im Abschnitt events werden alle Prädikate standardmäßig als and angesehen.

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

Operatoren in Ereignissen

Sie können die Operatoren mit Aufzählungstypen verwenden. Er kann auf Regeln angewendet werden, um die Leistung zu vereinfachen und zu optimieren (Operator statt Referenzlisten verwenden).

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

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

Liste der Ereignisse:

• NUTZER_RESOURCE_DELETION
• NUTZER-RESOURCE_UPDATE_CONTENT
• USER_RESOURCE_UPDATE_PERMISSIONS
• NUTZERSTATISTIKEN
• USER_UNCATEGORIZED (Vom Nutzer nicht zugeordnet)

Modifikatoren

Nocase

Wenn Sie einen Vergleichsausdruck zwischen Stringwerten oder einem Regex-Ausdruck verwenden, können Sie am Ende des Ausdrucks die Groß-/Kleinschreibung 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

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

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

Wiederkehrende Felder

alle, alle

In UDM und Entität sind einige Felder als wiederholt gekennzeichnet. Das bedeutet, dass es sich um Listen mit Werten oder anderen Arten von Nachrichten handelt. In YARA-L wird jedes Element im wiederkehrenden Feld einzeln behandelt. Das bedeutet, dass die Regel für jedes Element im Feld ausgewertet wird, wenn das wiederkehrende Feld in der Regel verwendet wird. Das kann zu einem unerwarteten Verhalten führen. Wenn eine Regel beispielsweise im Abschnitt events sowohl $e.principal.ip = "1.2.3.4" als auch $e.principal.ip = "5.6.7.8" enthält, generiert die Regel nie Übereinstimmungen, auch wenn sich "1.2.3.4" und "5.6.7.8" in principal.ip befinden.

Um das wiederkehrende Feld als Ganzes auszuwerten, können Sie die Operatoren any und all verwenden. Bei Verwendung von any wird das Prädikat als wahr ausgewertet, wenn ein Wert im wiederkehrenden Feld die Bedingung erfüllt. Bei Verwendung von all wird das Prädikat als wahr ausgewertet, wenn alle Werte im wiederkehrenden Feld die Bedingung erfüllen.

• any $e.target.ip = "127.0.0.1"
• all $e.target.ip != "127.0.0.1"
• re.regex(any $e.about.hostname, `server-[0-9]+`)
• net.ip_in_range_cidr(all $e.principal.ip, "10.0.0.0/8")

Die Operatoren any und all können nur mit wiederkehrenden Feldern verwendet werden. Außerdem können sie nicht verwendet werden, wenn einer Platzhaltervariablen ein wiederkehrendes Feld zugewiesen oder es mit einem Feld eines anderen Ereignisses verknüpft wird.

any $e.principal.ip = $ip und any $e1.principal.ip = $e2.principal.ip sind beispielsweise keine gültige Syntax. Verwenden Sie $e.principal.ip = $ip, um ein wiederkehrendes Feld abzugleichen oder zu verknüpfen. Für jedes Element des wiederkehrenden Felds wird ein Wert oder Join für eine Variable angegeben.

Beachten Sie beim Schreiben einer Bedingung mit any oder all, dass die Negation der Bedingung mit not nicht dieselbe Bedeutung hat wie die Verwendung des negierten Operators.

Beispiel:

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

Hinweis: Die Operatoren any und all werden im Ausdruck der Referenzliste noch nicht unterstützt.

Voraussetzungen für das Verknüpfen von Ereignisvariablen

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

• direkt über einen Gleichheitsvergleich zwischen den Ereignisfeldern der beiden verknüpften Ereignisvariablen. Beispiel: $e1.field = $e2.field. Der Ausdruck darf keine arithmetischen oder Funktionsaufrufe enthalten.

• indirekt über einen vorübergehenden Join, der nur ein Ereignisfeld umfasst. Eine Definition von "transitive Join" finden Sie in der Variablendeklaration. Der Ausdruck darf keine arithmetischen oder Funktionsaufrufe enthalten.

Angenommen, in der Regel werden $e1, $e2 und $e3 verwendet, dann 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:
  // 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.principal.hostname = $e2.src.hostname // $e1 joins with $e2

  // Function to event comparison is not a valid join condition for $e1 and $e2,
  // but the whole events section is valid because we have a valid join condition in the first line.
  re.capture($e1.src.hostname, ".*") = $e2.target.hostname

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

events:
  // Event to function comparison is an invalid join condition for $e1 and $e2.
  $e1.principal.hostname = re.capture($e2.principal.application, ".*")

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.ip = $ip

  // Function to placeholder comparison is an invalid transitive join condition.
  re.capture($e2.target.ip, ".*") = $ip

events:
  $e1.src.port = $port

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

Syntax des Abschnitts „Übereinstimmung“

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

• Geben Sie im Abschnitt events an, wofür jede Keyword-Variable steht.
• Geben Sie den Zeitraum an, der verwendet werden soll, um Ereignisse nach dem Keyword over zu korrelieren. Ereignisse außerhalb des Zeitraums werden ignoriert.
• Verwenden Sie die folgende Syntax, um den Zeitraum anzugeben: <number><s/m/h/d> Dabei steht s/m/h/d für Sekunden, Minuten, Stunden bzw. Tage.
• Die Mindestdauer beträgt 1 Minute.
• Sie können maximal 48 Stunden angeben.

Das folgende Beispiel zeigt eine gültige match:

$var1, $var2 over 5m

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

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

$user over 1h

Diese Anweisung gibt $user zurück, wenn die Regel eine Übereinstimmung findet. Das angegebene Zeitfenster beträgt 1 Stunde. Ereignisse, die mehr als eine Stunde auseinanderliegen, werden nicht berücksichtigt. Die Regel betrachtet sie nicht als Erkennung.

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

$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 berücksichtigt. Die Regel betrachtet sie nicht als Erkennung.

Die folgenden Beispiele zeigen ungültige match-Abschnitte:

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

Schiebefenster

YARA-L 2.0-Regeln werden standardmäßig mithilfe von Hop-Fenstern ausgewertet. Ein Zeitraum von Unternehmensereignisdaten ist in eine Reihe von sich überschneidenden Hop-Fenstern unterteilt, die jeweils die im Abschnitt match angegebene Dauer enthalten. Die Ereignisse werden dann in jedem Hop-Fenster korreliert. Mit Hop-Fenstern ist es nicht möglich, nach Ereignissen zu suchen, die in einer bestimmten Reihenfolge auftreten (z. B. e1 findet bis zu 2 Minuten nach e2 statt). Das Ereignis e1 und das Ereignis e2 korrelieren, solange sie sich innerhalb der Hop-Fensterdauer befinden.

Regeln können auch mithilfe von Schiebefenstern ausgewertet werden. Bei gleitenden Fenstern werden gleitende Fenster mit der im Abschnitt match angegebenen Dauer zu Beginn oder am Ende mit einer angegebenen Pivot-Ereignisvariablen generiert. Die Ereignisse werden dann in jedem gleitenden Fenster in Beziehung gesetzt. Dadurch können Sie nach Ereignissen suchen, die in einer bestimmten Reihenfolge auftreten (z. B. e1 findet innerhalb von 2 Minuten nach e2 statt). Das Ereignis e1 und das Ereignis e2 korrelieren, wenn das Ereignis e1 innerhalb der Dauer des gleitenden Fensters nach dem Ereignis e2 auftritt.

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

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

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

Die folgenden Beispiele zeigen gültige Verwendungen für fließende Fenster:

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

Hinweis: Die Verwendung von gleitenden Fenstern anstelle von Hop-Fenstern hat bekanntermaßen eine geringere Leistung. Google empfiehlt, Schiebefenster nur für bestimmte Fälle zu verwenden, z. B. wenn die Reihenfolge von Ereignissen absolut notwendig ist oder wenn Sie nach Ereignissen suchen, die nicht vorhanden sind.

Syntax des Ergebnisabschnitts

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

Der Ergebnisname $risk_score ist etwas Besonderes. Sie können optional ein Ergebnis mit diesem Namen definieren. In diesem Fall muss es sich um einen Ganzzahltyp handeln. Wenn die Daten befüllt sind, wird die risk_score in der Enterprise Insights-Ansicht für Benachrichtigungen angezeigt, die durch Regelerkennungen ausgelöst werden.

Datentypen von Ergebnisvariablen

Jede Ergebnisvariable kann einen anderen Datentyp haben, der durch den für die Berechnung verwendeten Ausdruck bestimmt wird. Wir unterstützen die folgenden Ergebnisdatentypen:

• integer
• String
• Listen ganzer Zahlen
• Stringlisten

Bedingte Logik

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

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

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

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

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

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

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

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

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

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

• in einer Referenzliste nachschlagen. Beispiel:

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

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

Sie können ELSE_CLAUSE weglassen, wenn der Datentyp eine Ganzzahl ist. Wenn nicht angegeben, wird ELSE_CLAUSE mit 0 ausgewertet. Beispiel:

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

Sie müssen den ELSE_CLAUSE angeben, wenn der Datentyp String ist.

Mathematische Operationen

Sie können mathematische Vorgänge verwenden, um ganzzahlige Datentypergebnisse zu berechnen. Wir unterstützen Addition und Subtraktion (aber keine Multiplikation, Division oder Modulo) als Operatoren der obersten Ebene in einer Ergebnisberechnung. Beispiel:

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

Platzhaltervariablen in Ergebnissen

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

Beispiel für ein 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

Zusammenfassungen

Der Ergebnisbereich kann in Regeln für mehrere Ereignisse (Regeln mit Übereinstimmung) und in Einzelereignisregeln (Regeln ohne Abgleich) verwendet werden. Für Aggregationen gelten folgende Anforderungen:

• Regeln für mehrere Ereignisse (mit Übereinstimmung)

  • Der Ausdruck zur Berechnung der Ergebnisse wird für alle Ereignisse ausgewertet, die eine bestimmte Erkennung generiert haben.
  • Der Ausdruck muss in eine Aggregatfunktion eingeschlossen werden
    • Beispiel: $max_email_size = max($e.network.sent_bytes)
    • Wenn der Ausdruck ein wiederkehrendes Feld enthält, wird der Aggregatvorgang auf alle Elemente im wiederkehrenden Feld angewendet, und zwar auf alle Ereignisse, die die Erkennung generiert haben.

• Regeln für einzelne Ereignisse (ohne Übereinstimmung)

  • Der Ausdruck zur Berechnung der Ergebnisse wird anhand des einzelnen Ereignisses ausgewertet, das eine bestimmte Erkennung generiert hat.
  • Aggregatfunktion muss für Ausdrücke verwendet werden, die mindestens ein wiederkehrendes Feld enthalten
    • Beispiel: $suspicious_ips = array($e.principal.ip)
    • Das Aggregat wird auf alle Elemente im wiederkehrenden Feld angewendet.
  • Aggregierte Funktion kann nicht für Ausdrücke verwendet werden, die kein wiederkehrendes Feld enthalten.
    • Beispiel: $threat_status = if($e.principal.file.size > 1024, "SEVERE", "MODERATE")

Sie können die folgenden Aggregationsfunktionen verwenden:

• max(): Gibt das Maximum über alle möglichen Werte aus. Funktioniert nur mit Ganzzahl.
• min(): Gibt das Minimum über alle möglichen Werte aus. Funktioniert nur mit Ganzzahl.
• sum(): Gibt die Summe aller möglichen Werte aus. Funktioniert nur mit Ganzzahl.
• count_distinct(): erfasst alle möglichen Werte und gibt dann die eindeutige Anzahl der möglichen Werte aus.
• count(): verhält sich wie count_distinct(), gibt jedoch eine unbestimmte Anzahl möglicher Werte zurück.
• array_distinct(): erfasst alle möglichen Werte und gibt dann eine Liste dieser Werte aus. Die Liste der Werte wird auf 25 zufällige Elemente gekürzt.
• array(): verhält sich wie array_distinct(), gibt jedoch eine nicht eindeutige Liste von Werten zurück. Außerdem wird die Liste der Werte auf 25 zufällige Elemente gekürzt.

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

Beispiel: Ihre Abschnitte outcome und condition enthalten Folgendes:

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

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

condition:
  #event > 1

Da für die Bedingung mehr als ein event pro Erkennung erforderlich ist, werden die Aggregatfunktionen für mehrere Ereignisse ausgeführt. Angenommen, die folgenden Ereignisse haben eine Erkennung generiert:

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

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

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

Dann ergeben sich die Ergebnisse:

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

Hinweise zur Verwendung des Ergebnisbereichs:

Weitere Hinweise und Einschränkungen:

• Der Abschnitt outcome kann nicht auf eine neue Platzhaltervariable verweisen, die im Abschnitt events noch nicht definiert ist.
• Im Abschnitt outcome können keine Ereignisvariablen verwendet werden, die im Abschnitt events nicht 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 ist.
• Im Abschnitt outcome können nur Ereignisvariablen korreliert werden, die bereits im Abschnitt events korreliert wurden. Korrelationen treten auf, wenn zwei Ereignisfelder aus verschiedenen Ereignisvariablen abgeglichen werden.

Ein Beispiel finden Sie im Abschnitt mit den Ergebnissen unter YARA-L 2.0 – Übersicht. Weitere Informationen zur Erkennung von Duplikaten mit dem Ergebnisbereich finden Sie unter Kontextsensitive Analysen erstellen.

Syntax des Bedingungsabschnitts

Im Abschnitt condition können Sie Folgendes tun:

• Legen Sie eine Abgleichsbedingung für Ereignisse und Platzhalter fest, 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 Abgleichsbedingung mit den im outcome-Bereich definierten Ergebnisvariablen anzugeben. Weitere Informationen finden Sie im folgenden Abschnitt Ergebnisbedingungen.

Die folgenden Bedingungsmuster sind gültig:

condition:
  <event/placeholder conditionals>

condition:
  <event/placeholder conditionals> and <outcome conditionals>

Bedingungen für Ereignisse und Platzhalter

Hier werden Bedingungsprädikate für Ereignisse und Platzhaltervariablen aufgeführt, die mit dem Keyword and oder or verknüpft sind.

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

Die folgenden Bedingungen sind Begrenzungsrahmenbedingungen. Sie erzwingen, dass die zugehörige Ereignisvariable vorhanden ist, d. h., mindestens ein Ereignis muss in einer Erkennung auftreten.

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

Die folgenden Bedingungen sind nicht bindend. Sie ermöglichen die Existenz der zugehörigen Ereignisvariablen, was bedeutet, dass das Ereignis möglicherweise nicht in einer Erkennung angezeigt wird. Dies ermöglicht das Erstellen von Nichtvorhandenseinregeln, die das Fehlen einer Variablen anstelle des Vorhandenseins einer Variablen suchen.

Hinweis: Bei Regeln für das Nicht-Vorhandensein (Regeln, die !$e oder #e = 0 im Abschnitt condition enthalten) fügt die Erkennungs-Engine der erwarteten Latenz (basierend auf der Ausführungshäufigkeit der Regel) eine Verzögerung von +1 Stunde hinzu, um spät ankommende Daten zuzulassen.

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

Im folgenden Beispiel steht das Sonderzeichen # für eine Variable (die Ereignisvariable oder die Platzhaltervariable) für die Anzahl der einzelnen Ereignisse oder Werte dieser Variablen.

$e and #port > 50 or #event1 > 2 or #event2 > 1 or #event3 > 0

Das folgende Beispiel, wenn keine Existenz vorhanden ist, ist ebenfalls gültig und wird mit „true“ ausgewertet, wenn es mehr als zwei verschiedene Ereignisse aus $event1 und null verschiedene Ereignisse aus $event2 gibt.

#event1 > 2 and !$event2

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

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

Hinweis: Bei Verwendung eines Schiebefensters muss die Pivot-Ereignisvariable in mindestens einer Begrenzungsrahmenbedingung beteiligt sein.

Die folgenden Beispiele sind Beispiele für ungültige Prädikate:

• $e, #port > 50 // incorrect keyword usage
• $e or #port < 50 // or keyword not supported with non-bounding conditions
• not $e // not keyword is not allowed for event and placeholder conditions

Ergebnisbedingungen

Hier werden Bedingungen für Ergebnisvariablen aufgelistet, die mit dem Keyword and oder or verbunden sind oder denen das Keyword not vorangestellt ist.

Geben Sie Ergebnisbedingungen je nach Typ der Ergebnisvariablen unterschiedlich an:

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

  $risk_score > 10

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

  $severity = "HIGH"

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

  arrays.contains($event_ids, "id_1234")

Hinweis: Wenn Sie das Keyword or im Unterabschnitt für <event/placeholderConditionals> verwenden, müssen Sie den gesamten Unterabschnitt mit Klammern umgeben. Folgendes ist beispielsweise gültig: ($e1 or $e2) and $outcome > 0.

Regelklassifizierung

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

Anzahl (#) Zeichen

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

Wert ($)

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

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

Syntax des Abschnitts „Optionen“

Im Abschnitt options können Sie die Optionen für die Regel angeben. Die Syntax für den Bereich options ähnelt der im Abschnitt meta. Ein Schlüssel muss jedoch einer der vordefinierten Optionnamen sein und der Wert ist nicht auf den Stringtyp beschränkt.

Derzeit ist allow_zero_values die einzige verfügbare Option.

• allow_zero_value: Wenn dieser Wert auf „true“ gesetzt ist, können durch die Regel generierte Übereinstimmungen null Werte als Übereinstimmungsvariablenwerte haben. Ereignisfelder werden null Werte zugewiesen, wenn sie nicht ausgefüllt werden. Diese Option ist standardmäßig auf „falsch“ gesetzt.

Hinweis: Standardmäßig gibt Chronicle keine Nullwerte als Variablenwerte zurück.

Die folgende Zeile für den Abschnitt options ist gültig:

• allow_zero_values = true

Typprüfung

Chronicle führt während der Erstellung von Regeln in der Benutzeroberfläche eine Typprüfung für Ihre YARA-L-Syntax durch. Mit den angezeigten Typfehlern können Sie die Regel so überarbeiten, dass sie wie erwartet funktioniert.

Die folgenden Beispiele sind Beispiele für ungültige Prädikate:

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

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