YARA-L 2.0-Sprachsyntax
In diesem Abschnitt werden die wichtigsten Elemente der YARA-L-Syntax beschrieben. Siehe auch Übersicht über die Sprache YARA-L 2.0.
Regelstruktur
Für YARA-L 2.0 müssen Sie Variablendeklarationen, -definitionen und -verwendungen in der folgenden Reihenfolge angeben:
- Meta
- Ereignisse
- Übereinstimmung (optional)
- Ergebnis (optional)
- Bedingung
- Optionen (optional)
Im Folgenden wird die allgemeine Struktur einer Regel dargestellt:
rule <rule Name>
{
meta:
// Stores arbitrary key-value pairs of rule details, such as who wrote
// it, what it detects on, version control, etc.
events:
// Conditions to filter events and the relationship between events.
match:
// Values to return when matches are found.
outcome:
// Additional information extracted from each detection.
condition:
// Condition to check events and the variables used to find matches.
options:
// Options to turn on or off while executing this rule.
}
Syntax des Metaabschnitts
Der Meta-Abschnitt besteht aus mehreren Zeilen, wobei jede Zeile ein Schlüssel/Wert-Paar definiert. Ein Schlüsselteil muss ein String ohne Anführungszeichen und ein Wertteil ein String in Anführungszeichen sein:
<key> = "<value>"
Das folgende Beispiel zeigt eine gültige meta
-Abschnittszeile:
meta:
author = "Google"
severity = "HIGH"
Syntax für den Bereich „Ereignisse“
Listen Sie im Abschnitt events
die Prädikate auf, um Folgendes anzugeben:
- Variablendeklarationen
- Filter für Ereignisvariablen
- Joins für Ereignisvariablen
Variablendeklarationen
Verwenden Sie für Variablendeklarationen die folgende Syntax:
<EVENT_FIELD> = <VAR>
<VAR> = <EVENT_FIELD>
Beide sind äquivalent, wie in den folgenden Beispielen gezeigt:
$e.source.hostname = $hostname
$userid = $e.principal.user.userid
Diese Deklaration gibt an, dass diese Variable das angegebene Feld für die Ereignisvariable darstellt. Wenn das Ereignisfeld ein wiederkehrendes Feld ist, kann die Übereinstimmungsvariable einen beliebigen Wert im Array darstellen. Es ist auch möglich, einer einzigen Abgleich- oder Platzhaltervariablen mehrere Ereignisfelder zuzuweisen. Dies ist eine transitive Join-Bedingung.
Beispiel:
$e1.source.ip = $ip
$e2.target.ip = $ip
entsprechen:
$e1.source.ip = $ip
$e1.source.ip = $e2.target.ip
Wenn eine Variable verwendet wird, muss sie durch eine Variablendeklaration deklariert werden. Wird eine Variable ohne Deklaration verwendet, gilt sie als Kompilierungsfehler.
Filter für Ereignisvariablen
Ein boolescher Ausdruck, der auf eine einzelne Ereignisvariable angewendet wird, wird als Filter betrachtet.
Joins für Ereignisvariablen
Alle in der Regel verwendeten Ereignisvariablen müssen mit jeder anderen Ereignisvariablen auf eine der folgenden Arten verknüpft werden:
Direkt durch einen Gleichheitsvergleich zwischen Ereignisfeldern der beiden verknüpften Ereignisvariablen, z. B.
$e1.field = $e2.field
. Der Ausdruck darf keine Arithmetik enthalten.Indirekt durch einen transitiven Join, der nur ein Ereignisfeld umfasst. Eine Definition des Begriffs „transitiver Join“ finden Sie unter Variablendeklaration. Der Ausdruck darf keine Arithmetik enthalten.
Wenn beispielsweise $e1, $e2 und $e3 in der Regel verwendet werden, sind die folgenden events
-Abschnitte gültig.
events:
$e1.principal.hostname = $e2.src.hostname // $e1 joins with $e2
$e2.principal.ip = $e3.src.ip // $e2 joins with $e3
events:
// $e1 joins with $e2 via function to event comparison
re.capture($e1.src.hostname, ".*") = $e2.target.hostname
events:
// $e1 joins with $e2 via an `or` expression
$e1.principal.hostname = $e2.src.hostname
or $e1.principal.hostname = $e2.target.hostname
or $e1.principal.hostname = $e2.principal.hostname
events:
// all of $e1, $e2 and $e3 are transitively joined via the placeholder variable $ip
$e1.src.ip = $ip
$e2.target.ip = $ip
$e3.about.ip = $ip
events:
// $e1 and $e2 are transitively joined via function to event comparison
re.capture($e2.principal.application, ".*") = $app
$e1.principal.hostname = $app
Hier einige Beispiele für ungültige events
-Bereiche.
events:
// Event to arithmetic comparison is an invalid join condition for $e1 and $e2.
$e1.principal.port = $e2.src.port + 1
events:
$e1.src.ip = $ip
$e2.target.ip = $ip
$e3.about.ip = "192.1.2.0" //$e3 is not joined with $e1 or $e2.
events:
$e1.src.port = $port
// Arithmetic to placeholder comparison is an invalid transitive join condition.
$e2.principal.port + 800 = $port
Syntax des Abgleichsabschnitts
Listen Sie im Bereich match
die Abgleichsvariablen für Gruppenereignisse auf, bevor Sie die Übereinstimmungsbedingungen prüfen. Diese Felder werden bei jeder Übereinstimmung zurückgegeben.
- Geben Sie im Abschnitt
events
an, was jede Abgleichsvariable darstellt. - Geben Sie die Zeitdauer 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
für Minuten, Stunden bzw. Tage.Die angegebene Mindestzeit beträgt 1 Minute.
Sie können maximal 48 Stunden angeben.
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, stehen nicht in Beziehung und werden daher von der Regel ignoriert.
Hier ist ein weiteres Beispiel für einen gültigen match
-Abschnitt:
$user over 1h
Diese Anweisung gibt $user
zurück, wenn die Regel eine Übereinstimmung findet. Der angegebene Zeitraum beträgt eine Stunde. Ereignisse, die mehr als eine Stunde auseinanderliegen, stehen nicht zur Verfügung. Die Regel betrachtet sie nicht als Erkennung.
Hier ein weiteres Beispiel für einen gültigen match
-Abschnitt:
$source_ip, $target_ip, $hostname over 2m
Diese Anweisung gibt $source_ip
, $target_ip
und $hostname
zurück, wenn die Regel eine Übereinstimmung findet. Das angegebene Zeitfenster beträgt 2 Minuten. Ereignisse, die mehr als zwei Minuten auseinanderliegen, stehen nicht zur Verfügung. Die Regel betrachtet sie nicht als Erkennung.
Die folgenden Beispiele veranschaulichen ungültige match
-Abschnitte:
var1, var2 over 5m // invalid variable name
$user 1h // missing keyword
Umgang mit Nullwerten im Übereinstimmungsbereich
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ählte Typen).
Das folgende Beispiel zeigt Regeln, die Nullwerte herausfiltern.
rule ZeroValuePlaceholderExample {
meta:
events:
// Because $host is used in the match section, the rule behaves
// as if the following predicate was added to the events section:
// $host != ""
$host = $e.principal.hostname
// Because $otherPlaceholder was not used in the match section,
// there is no implicit filtering of zero values for $otherPlaceholder.
$otherPlaceholder = $e.principal.ip
match:
$host over 5m
condition:
$e
}
Wenn jedoch einer Funktion ein Platzhalter zugewiesen ist, Filtern Sie implizit die Nullwerte von Platzhaltern heraus, die in „Übereinstimmung“. Das folgende Beispiel zeigt Regeln, die Nullwerte herausfiltern:
rule ZeroValueFunctionPlaceholder {
meta:
events:
// Even though $ph is used in the match section, there is no
// implicit filtering of zero values for $ph, because $ph is assigned to a function.
$ph = re.capture($e.principal.hostname, "some-regex")
match:
$ph over 5m
condition:
$e
}
Um das implizite Filtern von Nullwerten zu deaktivieren,
können Sie die Option allow_zero_values
im Abschnitt „Optionen“ verwenden.
Hop-Fenster
Standardmäßig werden YARA-L 2.0-Regeln mit einem Übereinstimmungsbereich mithilfe von Hop-Fenstern ausgewertet.
Der Zeitraum für die Ausführung der Regel ist in einen Satz
überlappender Hop-Fenster unterteilt.
mit der im Abschnitt match
angegebenen Dauer. Die Ereignisse werden dann
innerhalb der einzelnen Hop-Fenster.
Für eine Regel, die für den Zeitraum [1:00, 2:00] ausgeführt wird,
match
-Abschnitt über 30m
, ein möglicher Satz sich überschneidender Hop-Fenster
[1:00, 1:30], [1:03, 1:33] und [1:06, 1:36].
Diese Fenster werden verwendet, um mehrere Ereignisse in Beziehung zu setzen.
Schiebefenster
Die Verwendung von Hop-Fenstern ist keine effektive Möglichkeit, um nach Ereignissen zu suchen, die in einer bestimmten Reihenfolge auftreten (z. B. tritt e1
bei maximal zwei
Minuten nach e2
). Ereignis e1
und Ereignis e2
werden nur korreliert, wenn sie in dasselbe generierte Hop-Fenster fallen.
Eine effektivere Methode zur Suche nach solchen Ereignissequenzen sind gleitende Fenster.
Gleitende Zeitfenster mit der im Abschnitt match
angegebenen Dauer werden generiert, wenn sie mit einer bestimmten Pivot-Ereignisvariablen beginnen oder enden. Ereignisse werden dann
korreliert mit den einzelnen
gleitenden Fenstern. Dadurch wird es möglich, nach bestimmten
Ereignisse, die in einer bestimmten Reihenfolge auftreten, z. B. e1
Minuten e2
). Ereignis e1
und Ereignis e2
korrelieren, wenn das Ereignis e1
innerhalb der gleitenden Fensterdauer nach
Ereignis e2
.
So geben Sie gleitende Fenster im Abschnitt match
einer Regel an:
<match-var-1>, <match-var-2>, ... over <duration> before|after <pivot-event-var>
Die Pivot-Ereignisvariable ist die Ereignisvariable, auf der gleitende Fenster basieren.
aktiviert. Wenn Sie das Schlüsselwort before
verwenden, werden gleitende Fenster generiert, die mit
jedes Vorkommens des Pivot-Ereignisses. Wenn das Schlüsselwort after
verwendet wird,
Fenster werden beginnend mit jedem Auftreten des Pivot-Ereignisses generiert.
Im Folgenden finden Sie Beispiele für gültige gleitende Fenster:
$var1, $var2 over 5m after $e1
$user over 1h before $e2
Beispiel für eine gleitende Fensterregel
Google rät davon ab, gleitende Fenster für Einzelereignisregeln zu verwenden, gleitende Fenster sind so konzipiert, dass mehrere Ereignisse erkannt werden. Wenn eine Ihrer Regeln in diese Kategorie fällt, empfiehlt Google eine der folgenden Problemumgehungen:
- Konvertieren Sie die Regel so, dass mehrere Ereignisvariablen verwendet werden, und aktualisieren Sie den Abschnitt „Bedingung“, wenn für die Regel mehr als ein Ereignis erforderlich ist.
- Optional können Sie Zeitstempelfilter hinzufügen, anstatt ein gleitendes Fenster zu verwenden.
Beispiel:
$permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
- Optional können Sie Zeitstempelfilter hinzufügen, anstatt ein gleitendes Fenster zu verwenden.
Beispiel:
- Entfernen Sie das Schiebefenster.
Syntax des Ergebnisabschnitts
Im Abschnitt outcome
können Sie bis zu 20 Ergebnisvariablen mit beliebigen Namen definieren. Diese Ergebnisse werden in den Erkennungen gespeichert, die von
die Regel. Jede Erkennung kann unterschiedliche Werte für die Ergebnisse haben.
Der Ergebnisname $risk_score
ist etwas ganz Besonderes. Sie können optional ein
diesem Namen ein. Falls ja, muss es
eine Ganzzahl oder ein Gleitkommawert sein. Wenn das Feld ausgefüllt ist,
Das risk_score
wird im
Enterprise Insights-Ansicht für
die über die Regelerkennung gesendet werden.
Wenn Sie im Ergebnisbereich einer Regel keine Variable $risk_score
einfügen,
einer der folgenden Standardwerte festgelegt ist:
- Wenn die Regel so konfiguriert ist, dass eine Benachrichtigung generiert wird, ist
$risk_score
auf 40 gesetzt. - Wenn die Regel nicht zum Generieren einer Benachrichtigung konfiguriert ist, wird
$risk_score
auf 15 gesetzt.
Der Wert von $risk_score
wird im UDM-Feld security_result.risk_score
gespeichert.
Datentypen der Ergebnisvariablen
Jede Ergebnisvariable kann einen anderen Datentyp haben, der durch den Ausdruck bestimmt wird. die zur Berechnung verwendet werden. Wir unterstützen die folgenden Datentypen für Ergebnisse:
- integer
- floats
- String
- Listen mit Ganzzahlen
- Listen mit Gleitkommazahlen
- Listen mit Strings
Bedingte Logik
Sie können bedingte Logik verwenden, um den Wert eines Ergebnisses zu berechnen. Bedingungen werden mit dem folgenden Syntaxmuster angegeben:
if(BOOL_CLAUSE, THEN_CLAUSE)
if(BOOL_CLAUSE, THEN_CLAUSE, ELSE_CLAUSE)
Sie können einen bedingten Ausdruck so lesen wie: „Wenn BOOL_CLAUSE wahr ist, dann THEN_CLAUSE, sonst wird ELSE_CLAUSE" zurückgegeben.
BOOL_CLAUSE muss einen booleschen Wert ergeben. Ein BOOL_CLAUSE-Ausdruck nimmt eine
ähnliche Formen wie Ausdrücke im Abschnitt events
enthalten. Beispiele:
UDM-Feldnamen mit Vergleichsoperator, z. B.:
if($context.graph.entity.user.title = "Vendor", 100, 0)
Platzhaltervariable, die im Abschnitt
events
definiert wurde. Beispiel:if($severity = "HIGH", 100, 0)
eine andere Ergebnisvariable, die im Abschnitt
outcome
definiert ist, z. B.:if($risk_score > 20, "HIGH", "LOW")
Funktionen, die einen booleschen Wert zurückgeben. Beispiel:
if(re.regex($e.network.email.from, `.*altostrat.com`), 100, 0)
in einer Referenzliste nachschlagen. Beispiel:
if($u.principal.hostname in %my_reference_list_name, 100, 0)
Aggregationsvergleich. Beispiel:
if(count($login.metadata.event_timestamp.seconds) > 5, 100, 0)
THEN_CLAUSE und ELSE_CLAUSE müssen vom selben Datentyp sein. Wir unterstützen Ganzzahlen, Gleitkommazahlen und Strings.
Sie können ELSE_CLAUSE weglassen, wenn der Datentyp eine Ganzzahl oder eine Gleitkommazahl ist. Bei Auslassung wird der Parameter ELSE_CLAUSE ergibt 0. Beispiel:
`if($e.field = "a", 5)` is equivalent to `if($e.field = "a", 5, 0)`
Sie müssen ELSE_CLAUSE angeben, wenn der Datentyp ein String ist oder wenn die Funktion THEN_CLAUSE ist eine Platzhalter- oder Ergebnisvariable.
Mathematische Operationen
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 Operationen sind für die folgenden Operandentypen zulässig, solange jeder Operand und der gesamte arithmetische Ausdruck ordnungsgemäß aggregiert wurden (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 zuvor
Ereignisbereich Ihrer Regel definiert. In diesem Beispiel wird davon ausgegangen,
$email_sent_bytes
wurde im Bereich „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 mit mehreren Ereignissen:
match:
// This is a multi event rule with a match section.
$hostname over 5m
outcome:
// Use placeholder directly in an aggregation function.
$max_email_size = max($email_sent_bytes)
// Use placeholder in a mathematical computation.
$total_bytes_exfiltrated = sum(
1024
+ $email_sent_bytes
+ $file_event.principal.file.size
)
condition:
$email_event and $file_event
Ergebnisvariablen in Ergebniszuweisungsausdrücken
Ergebnisvariablen können verwendet werden, um andere Ergebnisvariablen abzuleiten, ähnlich wie
Platzhaltervariablen, die im Bereich events
definiert wurden. Sie können auf ein Ergebnis verweisen,
Variable in der Zuweisung einer anderen Ergebnisvariablen mit einem gefolgten $
-Token
Variablennamen ein. Ergebnisvariablen müssen definiert werden, bevor auf sie verwiesen werden kann
im Regeltext ein. Bei Verwendung in einem Zuweisungsausdruck müssen Ergebnisvariablen
nicht aggregiert werden (siehe Zusammenfassungen).
Im folgenden Beispiel leitet die Ergebnisvariable $risk_score
ihre Werte
Wert aus der Ergebnisvariablen $event_count
:
Beispiel mit mehreren Ereignissen:
match:
// This is a multi event rule with a match section.
$hostname over 5m
outcome:
// Aggregates all timestamp on login events in the 5 minute match window.
$event_count = count($login.metadata.event_timestamp.seconds)
// $event_count cannot be aggregated again.
$risk_score = if($event_count > 5, "SEVERE", "MODERATE")
// This is the equivalent of the 2 outcomes above combined.
$risk_score2 = if(count($login.metadata.event_timestamp.seconds) > 5, "SEVERE", "MODERATE")
condition:
$e
Ergebnisvariablen können in jeder Art von Ausdruck rechts neben einer Ergebniszuweisung verwendet werden. mit Ausnahme der folgenden Ausdrücke:
- Zusammenfassungen
Arrays.length()
-Funktionsaufrufe- Mit
any
- oderall
-Modifikatoren
Zusammenfassungen
Wiederkehrende Ereignisfelder sind nicht skalare Werte. Das heißt, eine Variable verweist auf
mehrere Werte. So ist beispielsweise die Ereignisfeldvariable $e.target.ip
ein wiederkehrendes Feld.
und kann null, eins oder viele IP-Werte haben. Es handelt sich um einen nicht skalaren Wert. Die Ereignisfeldvariable $e.principal.hostname
ist dagegen kein wiederkehrendes Feld und hat nur einen Wert (d. h. einen Skalarwert).
In ähnlicher Weise werden sowohl nicht wiederkehrende Ereignisfelder als auch wiederkehrende Ereignisfelder im Ergebnisbereich verwendet. einer Regel mit einem Übereinstimmungsfenster sind nicht skalare Werte. Die folgende Regel gruppiert beispielsweise Ereignisse mithilfe eines Übereinstimmungsbereichs und bezieht sich auf ein nicht wiederkehrendes Ereignisfeld im Ergebnisbereich:
rule OutcomeAndMatchWindow{
...
match:
$userid over 5m
outcome:
$hostnames = array($e.principal.hostname)
...
}
Jedes 5-Minuten-Fenster, für das die Regel ausgeführt wird, kann null, ein oder viele Ereignisse enthalten. Der Abschnitt „Ergebnis“
wird für alle Ereignisse in einem Übereinstimmungsfenster ausgeführt. Jede Ereignisfeldvariable, auf die im
Ergebnisbereich kann auf null, einen oder viele Werte des Felds für jedes Ereignis im Übereinstimmungsfenster verweisen.
Wenn in der obigen Regel ein 5-Minuten-Fenster 5 $e
-Ereignisse enthält, gilt $e.principal.hostname
im Ergebnisbereich verweist auf 5 verschiedene Hostnamen. Variable „Ereignisfeld“
$e.principal.hostname
ist somit ein nicht skalarer Wert im Ergebnisabschnitt dieser Regel.
Da Ergebnisvariablen immer einen einzigen skalaren Wert liefern müssen, kann jeder nicht skalare Wert, der von denen eine Ergebniszuweisung abhängt, muss aggregiert werden, um einen einzigen Skalarwert zu erhalten. In einem Ergebnisabschnitt sind die folgenden Werte nicht skalar und müssen aggregiert werden:
- Ereignisfelder (wiederkehrend oder nicht wiederholt), wenn in der Regel ein Übereinstimmungsbereich verwendet wird
- Ereignisplatzhalter (wiederholt oder nicht wiederholt), wenn die Regel einen Übereinstimmungsbereich verwendet
- Felder für wiederkehrende Ereignisse, wenn für die Regel kein Übereinstimmungsbereich verwendet wird
- Platzhalter für wiederkehrende Ereignisse, wenn für die Regel kein Übereinstimmungsbereich verwendet wird
Skalare Ereignisfelder, Platzhalter für skalare Ereignisse und Konstanten können in
eine Aggregation in einer Regel ohne Übereinstimmungsbereich. Die meisten Aggregationen
ergibt den umschlossenen Wert und sind daher nicht erforderlich. Ausnahme: array()
-Aggregation, die verwendet werden kann, um einen skalaren Wert in ein Array umzuwandeln.
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 den Maximalwert für alle möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.min()
: gibt den Mindestwert für alle möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.sum()
: Gibt die Summe für alle möglichen Werte aus. Funktioniert nur mit Ganzzahlen und Gleitkommazahlen.count_distinct()
: sammelt alle möglichen Werte und gibt dann die eindeutige Anzahl von möglichen Werten.count()
: Verhält sich wiecount_distinct()
, gibt jedoch eine nicht eindeutige Anzahl von zurück möglichen Werten.array_distinct()
: Sammelt alle möglichen unterschiedlichen Werte und gibt dann eine Liste dieser Werte aus. Es wird die Liste der eindeutigen Werte auf 25 zufällige Elemente gekürzt. Die Deduplizierung um eine eindeutige Liste zu erhalten, wird die Kürzung angewendet.array()
: Verhält sich wiearray_distinct()
, gibt jedoch eine nicht eindeutige Liste von Werte. Außerdem wird die Liste der Werte auf 25 zufällige Elemente gekürzt.period_start_for_max()
: Beginn des Zeitraums, für den der Maximalwert von der aufgeführte Wert aufgetreten ist.period_start_for_min()
: Beginn des Zeitraums, für den das Minimum der aufgeführte Wert aufgetreten ist.
Die Aggregatfunktion ist wichtig, wenn eine Regel den Abschnitt condition
enthält
das mehrere Ereignisse angibt, müssen vorhanden sein, da die Aggregatfunktion
auf alle Ereignisse angewendet werden,
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 der Bedingungsbereich erfordert, dass es mehr als eine event
pro
werden die Aggregatfunktionen auf mehrere Ereignisse angewendet. Angenommen,
folgende Ereignisse haben eine Erkennung generiert:
event:
// UDM event 1
asset_id="asset-a"
event:
// UDM event 2
asset_id="asset-b"
event:
// UDM event 3
asset_id="asset-b"
Dann sind die Werte Ihrer Ergebnisse:
- $asset_id_count =
3
- $asset_id_distinct_count =
2
- $asset_id_list =
["asset-a", "asset-b", "asset-b"]
- $asset_id_distinct_list =
["asset-a", "asset-b"]
Beachten Sie bei der Verwendung des Ergebnisabschnitts Folgendes:
Weitere Hinweise und Einschränkungen:
- Der Abschnitt
outcome
darf nicht auf eine neue Platzhaltervariable verweisen, die wurde nicht bereits im Abschnittevents
oderoutcome
definiert. - Im Bereich
outcome
können nur Ereignisvariablen verwendet werden,events
definiert wurde. - Im Bereich „
outcome
“ kann ein Ereignisfeld verwendet werden, das nicht im Abschnittevents
verwendet, da die Ereignisvariable, mit der das Ereignis Feld, zu dem gehört, wurde bereits im Abschnittevents
definiert. - Im Bereich
outcome
können nur Ereignisvariablen korreliert werden, die bereits im Abschnittevents
korreliert. Korrelationen treten auf, wenn zwei Ereignisfelder aus verschiedenen Ereignisvariablen gleichgestellt.
Ein Beispiel finden Sie im Ergebnisbereich unter Übersicht über YARA-L 2.0 Details zur Erkennung finden Sie unter Kontextsensitive Analysen erstellen. der Deduplizierung mit dem Ergebnisabschnitt.
Syntax des Bedingungsabschnitts
- Geben Sie eine Abgleichsbedingung für Ereignisse und Platzhalter an, die im Abschnitt
events
definiert sind. Weitere Informationen finden Sie unten im Abschnitt Bedingungen für Ereignisse und Platzhalter. - (Optional) Verwenden Sie das Keyword
and
, um eine Übereinstimmungsbedingung mithilfe von Ergebnisvariablen anzugeben, die im Abschnittoutcome
definiert sind. Weitere Informationen finden Sie im folgenden Abschnitt Ergebnisbedingungen.
Zeichen zählen
Das Zeichen #
ist ein Sonderzeichen im Abschnitt condition
. Falls ja
vor jedem Ereignis- oder Platzhaltervariablennamen verwendet, steht er für die Anzahl
separate Ereignisse oder Werte, die alle Bedingungen des Abschnitts events
erfüllen.
Zum Beispiel bedeutet #c > 1
, dass die Variable c
öfter als einmal auftreten muss.
Wertzeichen
Das Zeichen $
ist ein Sonderzeichen im Abschnitt condition
. Falls ja
vor jedem Ergebnisvariablennamen verwendet wird, stellt sie den Wert dieses Ergebnisses dar.
Wird es vor einem Ereignis- oder Platzhaltervariablennamen verwendet (z. B.
$event
) dargestellt ist, steht er für #event > 0
.
Ereignis- und Platzhalterbedingungen
Bedingungsprädikate für Ereignisse und Platzhaltervariablen hier auflisten, verbunden
mit dem Keyword and
oder or
. Das Keyword and
kann zwischen beliebigen
Das Keyword "or
" kann jedoch nur verwendet werden, wenn die Regel nur eine
Einzelereignis-Variable zu erstellen.
Ein gültiges Beispiel für die Verwendung von or
zwischen zwei Platzhaltern für dasselbe Ereignis:
rule ValidConditionOr {
meta:
events:
$e.metadata.event_type = "NETWORK_CONNECTION"
// Note that all placeholders use the same event variable.
$ph = $e.principal.user.userid // Define a placeholder variable to put in match section.
$ph2 = $e.principal.ip // Define a second placeholder variable to put in condition section.
$ph3 = $e.principal.hostname // Define a third placeholder variable to put in condition section.
match:
$ph over 5m
condition:
$ph2 or $ph3
}
Ein ungültiges Beispiel für die Verwendung von or
zwischen zwei Bedingungen bei verschiedenen Ereignissen:
rule InvalidConditionOr {
meta:
events:
$e.metadata.event_type = "NETWORK_CONNECTION"
$e2.graph.metadata.entity_type = "FILE"
$e2.graph.entity.hostname = $e.principal.hostname
$ph = $e.principal.user.userid // Define a placeholder variable to put in match section.
match:
$ph over 5m
condition:
$e or $e2 // This line will cause an error because there is an or between events.
}
Begrenzte und unbegrenzte Bedingungen
Die folgenden Bedingungen sind begrenzte Bedingungen. Sie erzwingen die damit verbundenen muss vorhanden sein, d. h., mindestens ein Ereignis muss in allen Erkennungen erscheinen.
$var // equivalent to #var > 0
#var > n // where n >= 0
#var >= m // where m > 0
Die folgenden Bedingungen sind unbegrenzt. Sie ermöglichen die damit verbundenen nicht existieren. Es ist also möglich, dass kein Das Ereignis erscheint in einer Erkennung und in allen Verweisen auf die Felder des Ereignisses. gibt den Wert Null zurück. 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 unbegrenzter werden Bedingungen als nicht vorhandene Regeln bezeichnet.
!$var // equivalent to #var = 0
#var >= 0
#var < n // where n > 0
#var <= m // where m >= 0
Voraussetzungen für Nicht-Existenz
Damit eine Regel mit Nichtvorhandensein kompiliert werden kann, müssen die folgenden Anforderungen erfüllt sein:
- Mindestens ein UDM-Ereignis muss eine begrenzte Bedingung haben. Es muss also mindestens ein UDM-Ereignis vorhanden sein.
- Wenn ein Platzhalter eine unbegrenzte Bedingung hat, muss er mindestens einem begrenzten UDM-Ereignis zugeordnet sein.
- Wenn eine Entität eine unbegrenzte Bedingung besitzt, muss sie unter mindestens ein begrenztes UDM-Ereignis.
Betrachten Sie die folgende Regel ohne den Abschnitt „Bedingung“:
rule NonexistenceExample {
meta:
events:
$u1.metadata.event_type = "NETWORK_CONNECTION" // $u1 is a UDM event.
$u2.metadata.event_type = "NETWORK_CONNECTION" // $u2 is a UDM event.
$e1.graph.metadata.entity_type = "FILE" // $e1 is an Entity.
$e2.graph.metadata.entity_type = "FILE" // $e2 is an Entity.
$user = $u1.principal.user.userid // Match variable is required for Multi-Event Rule.
// Placeholder Associations:
// u1 u2
// | \ /
// port ip
// | \
// e1 e2
$u1.target.port = $port
$e1.graph.entity.port = $port
$u1.principal.ip = $ip
$u2.target.ip = $ip
$e2.graph.entity.ip = $ip
// UDM-Entity Associations:
// u1 - u2
// | \ |
// e1 e2
$u1.metadata.event_type = $u2.metadata.event_type
$e1.graph.entity.hostname = $u1.principal.hostname
$e2.graph.entity.hostname = $u1.target.hostname
$e2.graph.entity.hostname = $u2.principal.hostname
match:
$user over 5m
condition:
<condition_section>
}
Im Folgenden finden Sie gültige Beispiele für <condition_section>
:
$u1 and !$u2 and $e1 and $e2
- Alle UDM-Ereignisse und -Entitäten sind im Bereich „Bedingung“ vorhanden.
- Mindestens ein UDM-Ereignis ist begrenzt.
$u1 and !$u2 and $e1 and !$e2
$e2
ist unbegrenzt. Dies ist zulässig, da es der begrenzten$u1
zugeordnet ist. Wenn$e2
nicht mit$u1
verknüpft wäre, wäre dies ungültig.
#port > 50 and #ip = 0
- 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 stärker als unbegrenzte Bedingungen. Da$port
$u1
zugewiesen ist und#port > 50
eine begrenzte Bedingung ist, ist$u1
weiterhin begrenzt.
Die folgenden Beispiele sind für <condition_section>
ungültig:
$u1 and $e1
- Jedes UDM-Ereignis und jede Entität, die im Bereich „Ereignisse“ erscheint, muss in den Abschnitt Bedingung (oder weisen ihm einen Platzhalter zu, der im Abschnitt Bedingung angezeigt wird).
$u1, $u2, $e1, $u2, #port > 50
- Kommas sind als Bedingungstrennzeichen nicht zulässig.
!$u1 and !$u2 and $e1 and $e2
- Verstößt gegen die erste Anforderung, dass mindestens ein UDM-Ereignis begrenzt ist.
($u1 or #port < 50) and $u2 and $e1 and $e2
- Das Keyword
or
wird nicht mit unbegrenzten Bedingungen unterstützt.
- Das Keyword
($u1 or $u2) and $e1 and $e2
- Das Keyword „
or
“ wird zwischen verschiedenen Ereignisvariablen nicht unterstützt.
- Das Keyword „
not $u1 and $u2 and $e1 and $e2
- Das Keyword „
not
“ ist für Ereignis- und Platzhalterbedingungen nicht zulässig.
- Das Keyword „
#port < 50 and #ip = 0
- Die vorhandenen Platzhalter decken alle UDM-Ereignisse und -Entitäten ab. aber alle Bedingungen sind unbegrenzt. Das bedeutet, dass keines der UDM-Ereignisse begrenzt ist, sodass die Regel nicht kompiliert werden kann.
Bedingungen für Ergebnisse
Listen Sie Bedingungsprädikate für Ergebnisvariablen hier auf, die mit dem Keyword and
oder or
verbunden sind oder dem Keyword not
vorangestellt sind.
Geben Sie Ergebnisbedingungen je nach Typ der Ergebnisvariablen unterschiedlich an:
integer: Vergleich mit einem Ganzzahlliteral mit Operatoren
=, >, >=, <, <=, !=
. Beispiel:$risk_score > 10
float: Vergleich mit einem Float-Literal mit den Operatoren
=, >, >=, <, <=, !=
. Beispiel:$risk_score <= 5.5
string: Vergleich mit einem Stringliteral mit
=
oder!=
. Beispiel:$severity = "HIGH"
Liste mit Ganzzahlen oder Arrays: Geben Sie die Bedingung mit der Funktion
arrays.contains
an. Beispiel:arrays.contains($event_ids, "id_1234")
Regelklassifizierung
Wenn Sie eine Ergebnisbedingung in einer Regel mit einem Übereinstimmungsbereich angeben, wird die Regel für das Regelkontingent als Multi-Ereignis-Regel klassifiziert. Weitere Informationen finden Sie unter Regel für einzelne Ereignisse und Regel für mehrere Ereignisse.
Syntax des Optionsabschnitts
Im Abschnitt options
können Sie die Optionen für die Regel angeben. Hier ist
Beispiel für die Angabe des Bereichs „Optionen“:
rule RuleOptionsExample {
// Other rule sections
options:
allow_zero_values = true
}
Sie können Optionen mit der Syntax key = value
angeben, wobei key
ein
vordefinierter Optionsname und value
müssen ein gültiger Wert für die Option sein, da
für die folgenden Optionen angegeben:
allow_zero_values
Die gültigen Werte für diese Option sind true
und false
, die bestimmen,
ob diese Option aktiviert ist oder nicht. Der Standardwert ist false
. Diese Option ist deaktiviert, wenn sie in der Regel nicht angegeben ist.
Fügen Sie Folgendes hinzu, um diese Einstellung zu aktivieren
zum Abschnitt „Optionen“ Ihrer Regel: allow_zero_values = true
. Andernfalls werden die Nullwerte von Platzhaltern, die im Abgleichsabschnitt verwendet werden, von der Regel implizit herausgefiltert, wie unter Nullwertbehandlung im Abgleichsabschnitt beschrieben.
Boolesche Ausdrücke
Boolesche Ausdrücke sind Ausdrücke eines booleschen Typs.
Vergleiche
Verwenden Sie für einen binären Ausdruck, der als Bedingung verwendet werden soll, die folgende Syntax:
<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")
"email@google.org" = re.replace($e.network.email.from, "com", "org")
Wenn beide Seiten Literale sind, wird dies als Kompilierungsfehler betrachtet.
Funktionen
Einige Funktionsausdrücke geben einen booleschen Wert zurück, der als einzelnes Prädikat im Abschnitt events
verwendet werden kann. Zu diesen Funktionen gehören:
re.regex()
net.ip_in_range_cidr()
Beispiel:
re.regex($e.principal.hostname, `.*\.google\.com`)
net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")
Ausdrücke der Referenzliste
Im Bereich „Ereignisse“ können Sie Referenzlisten verwenden. Weitere Informationen finden Sie im Abschnitt Weitere Informationen zu Referenzlisten
Logische Ausdrücke
Sie können die logischen and
- und logischen or
-Operatoren im Abschnitt events
verwenden, wie in den folgenden Beispielen gezeigt:
$e.metadata.event_type = "NETWORK_DNS" or $e.metadata.event_type = "NETWORK_DHCP"
($e.metadata.event_type = "NETWORK_DNS" and $e.principal.ip = "192.0.2.12") or ($e.metadata.event_type = "NETWORK_DHCP" and $e.principal.mac = "AB:CD:01:10:EF:22")
not $e.metadata.event_type = "NETWORK_DNS"
Standardmäßig ist die Reihenfolge von der höchsten zur niedrigsten Priorität not
, and
, or
.
Beispiel: „a oder b und c“ als „a oder (b und c)“ ausgewertet wird. Die Operatoren or
und and
sind explizit im Ausdruck definiert.
Im Abschnitt events
werden Prädikate mit dem and
-Operator verknüpft, wenn kein Operator explizit definiert ist.
Die Reihenfolge der Auswertung kann unterschiedlich sein, wenn der and
-Operator im Ausdruck impliziert wird.
Betrachten Sie beispielsweise die folgenden Vergleichsausdrücke, bei denen or
explizit definiert ist. Der Operator and
wird impliziert.
$e1.field = "bat"
or $e1.field = "baz"
$e2.field = "bar"
Dieses Beispiel wird so interpretiert:
($e1.field = "bat" or $e1.field = "baz")
and ($e2.field = "bar")
Da or
explizit definiert ist, werden die Prädikate, die or
umgeben, zuerst gruppiert und ausgewertet.
Das letzte Prädikat $e2.field = "bar"
wird implizit mit and
verknüpft. Das hat zur Folge, dass sich die Reihenfolge der Auswertung ändert.
Aufgezählte Typen
Sie können die Operatoren mit enumerated-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 ist „USER_UNCATEGORIZED“ und "USER_RESOURCE_DELETION" entsprechen 15.000 und 15.014, sodass die Regel nach allen aufgeführten Ereignissen sucht:
$e.metadata.event_type >= "USER_CATEGORIZED" and $e.metadata.event_type <= "USER_RESOURCE_DELETION"
Liste der Ereignisse:
- USER_RESOURCE_DELETION
- USER_RESOURCE_UPDATE_CONTENT
- USER_RESOURCE_UPDATE_PERMISSIONS
- USER_STATS
- USER_UNCATEGORIZED
Nocase-Modifikator
Wenn Sie einen Vergleichsausdruck zwischen Stringwerten oder einem regulären Ausdruck haben, können Sie am Ende des Ausdrucks nocase anhängen, um die Großschreibung zu ignorieren.
$e.principal.hostname != "http-server" nocase
$e1.principal.hostname = $e2.target.hostname nocase
$e.principal.hostname = /dns-server-[0-9]+/ nocase
re.regex($e.target.hostname, `client-[0-9]+`) nocase
Diese Option kann nicht verwendet werden, wenn ein Feldtyp ein enumerierter Wert ist. Die folgenden Beispiele sind ungültig und verursachen Kompilierungsfehler:
$e.metadata.event_type = "NETWORK_DNS" nocase
$e.network.ip_protocol = "TCP" nocase
Wiederkehrende Felder
Im Unified Data Model (UDM) sind einige Felder als wiederholt gekennzeichnet. 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 wiederkehrende Felder angewendet werden:
- Geändert
- Unverändert
Sehen Sie sich folgendes Ereignis an:
event_original {
principal {
// ip is a repeated field
ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]
hostname: "host"
}
}
Geänderte Ausdrücke
In den folgenden Abschnitten wird der Zweck und die Verwendung der Modifikatoren any
und all
in Ausdrücken beschrieben.
Beliebig
Wenn ein beliebiges Element des wiederholten Felds die Bedingung erfüllt, erfüllt das Ereignis als Ganzes die Bedingung.
event_original
erfülltany $e.principal.ip = "192.0.2.1"
.event_original
schlägtany $e.repeated_field.field_a = "9.9.9.9
fehl.
Alle
Wenn alle Elemente des wiederkehrenden Felds die Bedingung erfüllen, erfüllt das Ereignis als Ganzes die Bedingung.
event_original
erfülltnet.ip_in_range_cidr(all $e.principal.ip, "192.0.2.0/8")
.event_original
schlägt fehlall $e.principal.ip = "192.0.2.2"
.
Beachten Sie beim Schreiben einer Bedingung mit any
oder all
, dass das Negieren der Bedingung
mit not
möglicherweise nicht dieselbe Bedeutung wie die Verwendung des negierten Operators.
Beispiel:
- Mit
not all $e.principal.ip = "192.168.12.16"
wird geprüft, ob nicht alle IP-Adressen mit192.168.12.16
übereinstimmen. Mit anderen Worten: Die Regel prüft, ob mindestens eine IP-Adresse nicht mit192.168.12.16
übereinstimmt. all $e.principal.ip != "192.168.12.16"
prüft, ob alle IP-Adressen nicht übereinstimmen192.168.12.16
, was bedeutet, dass die Regel prüft, ob keine IP-Adressen mit192.168.12.16
übereinstimmen.
Einschränkungen:
- Die Operatoren
any
undall
sind nur mit sich wiederholenden Feldern (nicht mit Skalarfeldern) kompatibel. any
undall
können nicht verwendet werden, um zwei wiederkehrende Felder zu verbinden.any $e1.principal.ip = $e2.principal.ip
ist beispielsweise ungültig.- Die Operatoren
any
undall
werden für den Ausdruck mit der Referenzliste nicht unterstützt.
Unmodifizierte Ausdrücke
Bei unveränderten Ausdrücken wird jedes Element im wiederkehrenden Feld einzeln behandelt. Wenn das wiederkehrende Feld eines Ereignisses n Elemente enthält, wird die Regel auf n Kopien des Ereignisses angewendet, wobei jede Kopie eines der Elemente des wiederkehrenden Felds enthält. Diese Kopien sind 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 beliebige Ereigniskopie alle unveränderten Bedingungen für das wiederkehrende Feld erfüllt, erfüllt das Ereignis als Ganzes alle Bedingungen. Wenn also für ein wiederkehrendes Feld mehrere Bedingungen vorliegen, muss die Ereigniskopie alle Bedingungen erfüllen. In den folgenden Regelbeispielen wird dieses Verhalten anhand des vorherigen Beispieldatensatzes veranschaulicht.
Die folgende Regel gibt eine Übereinstimmung zurück, wenn sie auf das Beispiel-Dataset 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 keine Übereinstimmung zurück, wenn sie für event_original
ausgeführt wird
Beispiel-Dataset, weil es in $e.principal.ip
keine Ereigniskopie gibt, die
alle Ereignisprädikate erfüllt.
rule repeated_field_2 {
meta:
events:
$e.principal.ip = "192.0.2.1"
$e.principal.ip = "192.0.2.2"
condition:
$e
}
Geänderte Ausdrücke in wiederkehrenden Feldern sind mit unveränderten Ausdrücken für wiederkehrende Felder kompatibel, da die Elementliste für jede Ereigniskopie identisch ist. Betrachten Sie die folgende Regel:
rule repeated_field_3 {
meta:
events:
any $e.principal.ip = "192.0.2.1"
$e.principal.ip = "192.0.2.3"
condition:
$e
}
Die Regel wird auf die folgenden Kopien angewendet:
Ereignistext | principal.ip | beliebige $e.principal.ip |
---|---|---|
event_copy_1 | „192.0.2.1“ | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
event_copy_2 | „192.0.2.2“ | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
event_copy_3 | „192.0.2.3“ | ["192.0.2.1", "192.0.2.2", "192.0.2.3"] |
In diesem Fall erfüllen alle Kopien any $e.principal.ip = "192.0.2.1"
, aber nur event_copy_3
erfüllt $e.principal.ip = "192.0.2.3". Infolgedessen würde das Ereignis als Ganzes übereinstimmen.
Anders ausgedrückt:
- Ausdrücke für wiederholte Felder, die
any
oderall
verwenden, werden auf die Liste inevent_original
angewendet. - Ausdrücke in wiederholten Feldern, die nicht
any
oderall
verwenden, werden auf einzelneevent_copy_n
-Ereignisse angewendet.
Wiederkehrende Felder und Platzhalter
Wiederkehrende Felder können mit Platzhalterzuweisungen verwendet werden. Ähnlich wie bei unveränderten Ausdrücken für wiederkehrende Felder wird für jedes Element eine Kopie des Ereignisses erstellt. Im selben Beispiel für event_copy
verwendet der Platzhalter für jede Ereigniskopie den Wert des wiederkehrenden Feldwerts von event_copy_n
, wobei n die Ereigniskopie-Nummer ist. Wenn der Platzhalter im Übereinstimmungsbereich verwendet wird, kann dies zu mehreren Übereinstimmungen führen.
Im folgenden Beispiel wird eine Übereinstimmung generiert. Der Platzhalter $ip
ist gleich
auf 192.0.2.1
für event_copy_1
, was die Prädikate in der Regel erfüllt.
Die Ereignisbeispiele für die Übereinstimmung enthalten nur das Element event_original
.
// Generates 1 match.
rule repeated_field_placeholder1 {
meta:
events:
$ip = $e.principal.ip
$ip = "192.0.2.1"
$host = $e.principal.hostname
match:
$host over 5m
condition:
$e
}
Im folgenden Beispiel werden drei Übereinstimmungen generiert. Der Platzhalter $ip
hat für jede der verschiedenen event_copy_n
-Kopien einen anderen Wert.
Die Gruppierung erfolgt am $ip
, da es sich im Bereich „Übereinstimmung“ befindet. Sie erhalten also drei Übereinstimmungen,
Dabei hat jede Übereinstimmung einen anderen Wert für die Übereinstimmungsvariable $ip
. Jede Übereinstimmung hat
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
}
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
}
Die Ausführung dieser Regel erfolgt in vier Phasen. Die erste Phase ist das Kopieren von Ereignissen:
Terminkopie | $ip | $host | $e |
---|---|---|---|
event_copy_1 | „192.0.2.1“ | "host" | event_id |
event_copy_2 | „192.0.2.2“ | „host“ | event_id |
event_copy_3 | „192.0.2.3“ | "host" | event_id |
Im Bereich „Ereignisse“ werden dann Zeilen herausgefiltert, die nicht mit den Filtern übereinstimmen:
Terminkopie | $ip | $host | $e |
---|---|---|---|
event_copy_1 | „192.0.2.1“ | "host" | event_id |
event_copy_2 | „192.0.2.2“ | „host“ | event_id |
event_copy_3
wird herausgefiltert, weil "192.0.2.3"
nicht die Kriterien für $ip = "192.0.2.1" or $ip = "192.0.2.2"
erfüllt.
Im Übereinstimmungsbereich wird dann nach Übereinstimmungsvariablen gruppiert und im Ergebnisbereich wird für jede Gruppe eine Aggregation durchgeführt:
$host | $o | $e |
---|---|---|
„host“ | ["192.0.2.1", "192.0.2.2"] | event_id |
$o = array_distinct($ip)
wird mit $ip
aus der vorherigen Phase und nicht mit dem Kopiervorgang für das Ereignis berechnet.
Im Bereich „Condition“ (Bedingung) werden alle Gruppen gefiltert. Da diese Regel nur prüft, ob $e vorhanden ist, erzeugt die Zeile von zuvor eine einzelne Erkennung.
$o
enthält nicht alle Elemente aus $e.principal.ip
, weil nicht alle Elemente alle Bedingungen im Ereignisbereich erfüllen. Es werden jedoch alle Elemente von e.principal.ip
im Ereignisbeispiel angezeigt, weil im Ereignisbeispiel event_original
verwendet wird.
Array-Indexierung
Sie können für wiederkehrende Felder eine Array-Indexierung durchführen. Verwenden Sie die Standardlistensyntax, um auf das n-te wiederholte Feldelement zuzugreifen (die Elemente sind 0-indexiert). Ein Element außerhalb des gültigen Bereichs gibt den Standardwert zurück.
$e.principal.ip[0] = "192.168.12.16"
$e.principal.ip[999] = ""
Wenn weniger als 1.000 Elemente vorhanden sind, wirdtrue
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 aufint
gesetzt ist) werden nicht gezählt. - Die Array-Indexierung kann nicht mit
any
oderall
kombiniert werden.any $e.intermediary.ip[0]
ist beispielsweise ungültig. - Die Array-Indexierung kann nicht mit der Kartensyntax kombiniert werden.
$e.additional.fields[0]["key"]
ist beispielsweise ungültig. - Wenn der Feldpfad mehrere wiederkehrende Felder enthält, muss für alle wiederkehrenden Felder die Array-Indexierung verwendet werden.
$e.intermediary.ip[0]
ist beispielsweise ungültig, daintermediary
undip
wiederkehrende Felder sind, aber nur ein Index fürip
vorhanden ist.
Wiederholte Nachrichten
Wenn sich ein message
-Feld wiederholt, hat das eine unbeabsichtigte Auswirkung darin, die Wahrscheinlichkeit einer Übereinstimmung zu verringern. Dies wird in den folgenden Beispielen veranschaulicht.
Sehen Sie sich folgendes Ereignis an:
event_repeated_message {
// about is a repeated message field.
about {
// ip is a repeated string field.
ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]
hostname: "alice"
}
about {
hostname: "bob"
}
}
Wie bei unveränderten Ausdrücken 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:
Terminkopie | about.ip | about.hostname |
---|---|---|
event_copy_1 | „192.0.2.1“ | „Alice“ |
event_copy_2 | „192.0.2.2“ | „Alice“ |
event_copy_3 | „192.0.2.3“ | „Alice“ |
event_copy_4 | "" | „Bernd“ |
Das Ereignis stimmt nicht mit der Regel überein, da keine Ereigniskopie vorhanden ist, die allen Ausdrücken entspricht.
Wiederholte Nachrichten und Array-Indexierung
Ein weiteres unerwartetes Verhalten kann auftreten, wenn die Array-Indexierung mit unveränderten Ausdrücken für wiederkehrende Nachrichtenfelder verwendet wird. 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:
Terminkopie | about.ip | about[1].hostname |
---|---|---|
event_copy_1 | „192.0.2.1“ | „Bernd“ |
event_copy_2 | „192.0.2.2“ | „Bernd“ |
event_copy_3 | „192.0.2.3“ | „Bernd“ |
event_copy_4 | "" | „max“ |
Da event_copy_1
alle Ausdrücke in repeated_message_2
erfüllt, stimmt das Ereignis mit der Regel überein.
Dies kann zu unerwartetem Verhalten führen, da Regel repeated_message_1
keine Array-Indexierung hat und keine Übereinstimmungen erzeugt hat, während Regel repeated_message_2
die Array-Indexierung verwendet und eine Übereinstimmung erzeugt hat.
Kommentare
Kommentare können wie in C mit zwei Schrägstrichen (// comment
) oder mehrzeiligen Kommentaren mit Schrägstrich-Sternchen (/* comment */
) gekennzeichnet werden.
Literale
Nicht negative Ganzzahlen und Gleitkommazahlen, Strings, boolesche Ausdrücke und Literale für reguläre Ausdrücke werden unterstützt.
String- und reguläre Ausdruckliterale
Sie können eines der folgenden Anführungszeichen verwenden, um Strings in YARA-L 2.0 zu umschließen. Zitierter Text wird jedoch unterschiedlich interpretiert, je nachdem, welche Sie verwenden.
Doppelte Anführungszeichen ("): Wird für normale Strings verwendet. Muss Escape-Zeichen enthalten.
Beispiel: „hallo\twelt“ – \t wird als Tabulatorzeichen interpretiertAnführungszeichen (`): Wird verwendet, um alle Zeichen wortgetreu zu interpretieren.
Beispiel: „hello\tworld“ —\t wird nicht als Tabulator interpretiert
Für reguläre Ausdrücke haben Sie zwei Möglichkeiten.
Wenn Sie reguläre Ausdrücke direkt ohne die re.regex()
-Funktion verwenden möchten, verwenden Sie /regex/
für die Literale für reguläre Ausdrücke.
Wenn Sie die Funktion re.regex()
nutzen, können Sie auch Stringliterale als Literale für reguläre Ausdrücke verwenden. Beachten Sie, dass Sie bei Stringliteralen mit doppelten Anführungszeichen umgekehrte Schrägstriche mit umgekehrten Schrägstrichen maskieren müssen. Dies kann umständlich aussehen.
Die folgenden regulären Ausdrücke sind beispielsweise äquivalent:
re.regex($e.network.email.from, `.*altostrat\.com`)
re.regex($e.network.email.from, ".*altostrat\\.com")
$e.network.email.from = /.*altostrat\.com/
Google empfiehlt, für Strings in regulären Ausdrücken Anführungszeichen zu verwenden, um die Lesbarkeit zu verbessern.
Operatoren
In YARA-L können Sie die folgenden Operatoren verwenden:
Operator: | Beschreibung |
= | Gleichheit/Deklaration |
!= | Ungleich |
< | 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: Sie stellen Ereignisgruppen in normalisierter Form (UDM) oder Entitätsereignisse dar. Geben Sie im Bereich
events
Bedingungen für Ereignisvariablen an. Ereignisvariablen werden anhand der Felder „Name“, „Ereignisquelle“ und „Ereignis“ identifiziert. Zulässige Quellen sindudm
(für normalisierte Ereignisse) undgraph
(für Entitätsereignisse). Wenn keine Quelle angegeben wird, wirdudm
als Standardquelle festgelegt. Ereignisfelder werden als Kette von .<field name> dargestellt (z. B. $e.field1.field2). Ereignisfeldketten beginnen immer bei der Quelle auf oberster Ebene (UDM oder Entität).Abgleichvariablen: Deklarieren Sie diese im Abschnitt
match
. Übereinstimmungsvariablen werden zu Gruppierungsfeldern für die Abfrage, da für jeden eindeutigen Satz von Übereinstimmungsvariablen (und für jedes Zeitfenster) eine Zeile zurückgegeben wird. Findet die Regel eine Übereinstimmung, werden die entsprechenden Variablenwerte zurückgegeben. Geben Sie im Abschnittevents
an, was die einzelnen Abgleichsvariablen darstellen.Platzhaltervariablen: Deklarieren und definieren Sie diese im Abschnitt
events
. Platzhaltervariablen ähneln Abgleichvariablen. Sie können jedoch im Bereichcondition
Platzhaltervariablen verwenden, um Übereinstimmungsbedingungen anzugeben.
Verwenden Sie Übereinstimmungsvariablen und Platzhaltervariablen, um Beziehungen zwischen Ereignisfeldern über Transitive Join-Bedingungen zu deklarieren. Weitere Informationen finden Sie unter Syntax des Ereignisabschnitts.
Keywords
Bei Keywords in YARA-L 2.0 wird nicht zwischen Groß- und Kleinschreibung unterschieden. and
oder AND
sind beispielsweise
Äquivalent. Variablennamen dürfen nicht mit Keywords in Konflikt stehen. Beispiel: $AND
oder $outcome
ist ungültig.
Die folgenden Schlüsselwörter für Erkennungs-Engine-Regeln sind: rule
, meta
, match
, over
, events
, condition
, outcome
, options
, and
, or
, not
, nocase
, in
, regex
, cidr
, before
, after
, all
, any
, if
, max
, {2/6. {2/6.min
sum
array
array_distinct
count
count_distinct
is
null
Maps
YARA-L unterstützt den Kartenzugriff für Strukturen und Labels.
Strukturen und Labels
Einige UDM-Felder verwenden entweder den Datentyp Struct oder Label.
Um sowohl in Struct als auch in Label nach einem bestimmten Schlüssel/Wert-Paar zu suchen, verwenden Sie die Standardzuordnungssyntax:
// A Struct field.
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// A Label field.
$e.metadata.ingestion_labels["MetadataKeyDeletion"] = "startup-script"
Beim Kartenzugriff wird immer ein String zurückgegeben.
Unterstützte Fälle
Abschnitt „Ereignisse und Ergebnisse“
// Using a Struct field in the events section
events:
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// Using a Label field in the outcome section
outcome:
$value = array_distinct($e.metadata.ingestion_labels["MetadataKeyDeletion"])
Platzhalter einen Kartenwert zuweisen
$placeholder = $u1.metadata.ingestion_labels["MetadataKeyDeletion"]
Zuordnungsfeld in einer Join-Bedingung verwenden
// using a Struct field in a join condition between two udm events $u1 and $u2
$u1.metadata.event_type = $u2.udm.additional.fields["pod_name"]
Nicht unterstützte Fälle
Karten werden in den folgenden Fällen nicht unterstützt.
Keywords für any
oder all
mit einer Karte kombinieren
Folgendes wird beispielsweise nicht unterstützt:
all $e.udm.additional.fields["pod_name"] = "kube-scheduler"
Andere Arten von Werten
Die Kartensyntax kann nur einen Stringwert zurückgeben. Im Fall von Struct -Datentypen kann die Kartensyntax nur auf Schlüssel zugreifen, deren Werte Zeichenfolgen sind. Der Zugriff auf Schlüssel, deren Werte andere primitive Typen wie Ganzzahlen sind, ist nicht möglich.
Umgang mit doppelten Werten
Beim Kartenzugriff wird immer ein einzelner Wert zurückgegeben. Seltene dass der Kartenzugriff auf mehrere Werte verweisen könnte, access gibt deterministisch den ersten Wert zurück.
Das kann in folgenden Fällen passieren:
Ein Label hat einen doppelten Schlüssel.
Die Labelstruktur stellt eine Zuordnung dar, erzwingt jedoch nicht die Eindeutigkeit des Schlüssels. Konventionsgemäß sollte eine Zuordnung eindeutige Schlüssel haben, damit Google Security Operations raten wir davon ab, ein Label mit doppelten Schlüsseln zu füllen.
Der Regeltext „
$e.metadata.ingestion_labels["dupe-key"]
“ würde Folgendes zurückgeben: den ersten möglichen Wert,val1
, wenn das folgende Datenbeispiel verwendet 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 wiederkehrendes Ancestor-Feld.
Ein wiederkehrendes Feld kann ein Label als untergeordnetes Feld enthalten. Zwei verschiedene können Einträge im wiederkehrenden Feld auf oberster Ebene Labels enthalten, die den gleichen Schlüssel haben. Regeltext
$e.security_result.rule_labels["key"]
den ersten möglichen Wert,val3
, bei Ausführung über Datenbeispiel: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 Erkennungsengine und in Suchanfragen verwenden können.
Diese Funktionen können in den folgenden Teilen einer YARA-L-Regel verwendet werden:
events
Abschnitt.BOOL_CLAUSE
einer Bedingung im Ergebnisbereich.
arrays.concat
arrays.concat(string_array, string_array)
Beschreibung
Gibt ein neues String-Array zurück, indem Elemente aus den ursprünglichen String-Arrays kopiert werden
Parameterdatentypen
ARRAY_STRINGS
, ARRAY_STRINGS
Rückgabetyp
ARRAY_STRINGS
Codebeispiele
Beispiel 1
Im folgenden Beispiel werden zwei verschiedene 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 verkettet.
arrays.concat([], []) = []
arrays.join_string
arrays.join_string(array_of_strings, optional_delimiter)
Beschreibung
Wandelt ein Array von Strings in einen einzelnen String um, der durch den optionalen Parameter getrennt ist. Wenn kein Trennzeichen angegeben ist, wird der leere String verwendet.
Parameterdatentypen
ARRAY_STRINGS
, STRING
Rückgabetyp
STRING
Codebeispiele
Hier sind 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 verknüpft.
arrays.join_string(["foo", NULL, "bar"], ",") = "foo,bar"
Beispiel 3
In diesem Beispiel wird ein Array mit Nicht-Null-Elementen und ohne Trennzeichen zusammengeführt.
arrays.join_string(["foo", "bar"]) = "foobar"
arrays.length
arrays.length(repeatedField)
Beschreibung
Gibt die Anzahl der wiederkehrenden Feldelemente zurück.
Parameterdatentypen
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
arrays.max(array_of_ints_or_floats)
Beschreibung
Gibt das größte Element in einem Array oder null zurück, wenn das Array leer ist.
Parameterdatentypen
ARRAY_INTS|ARRAY_FLOATS
Rückgabetyp
FLOAT
Codebeispiele
Hier sind einige Beispiele für die Verwendung der Funktion:
Beispiel 1
In diesem Beispiel wird das größere Element in einem Array von Ganzzahlen zurückgegeben.
arrays.max([10, 20]) = 20.000000
Beispiel 2
In diesem Beispiel wird das größere Element in einem Array von Gleitkommazahlen zurückgegeben.
arrays.max([10.000000, 20.000000]) = 20.000000
arrays.min
arrays.min(array_of_ints_or_floats[, ignore_zeros=false])
Beschreibung
Gibt das kleinste Element in einem Array oder null zurück, wenn das Array leer ist. Wenn das zweite optionale Argument auf „wahr“ gesetzt ist, werden Elemente, die null sind, ignoriert.
Parameterdatentypen
ARRAY_INTS|ARRAY_FLOATS
, BOOL
Rückgabetyp
FLOAT
Codebeispiele
Hier sind 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
Dieses Beispiel gibt das kleinste Element in einem Array von Gleitkommazahlen zurück.
arrays.min([10.000000, 20.000000]) = 10.000000
Beispiel 3
In diesem Beispiel wird das kleinste Element in einem Array von Gleitkommazahlen zurückgegeben und die Nullen werden ignoriert.
arrays.min([10.000000, 20.000000, 0.0], true) = 10.000000
arrays.size
arrays.size( array )
Beschreibung
Gibt die Größe des Arrays zurück. Gibt 0 für ein leeres Array zurück.
Parameterdatentypen
ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS
Rückgabetyp
INT
Codebeispiele
Beispiel 1
In diesem Beispiel wird ein String-Array verwendet, das zwei Elemente enthält.
arrays.size(["test1", "test2"]) = 2
Beispiel 2
In diesem Beispiel wird ein int-Array verwendet, das drei Elemente enthält.
arrays.size([1, 2, 3]) = 3
Beispiel 3
In diesem Beispiel wird ein Float-Array verwendet, das 1 Element enthält.
arrays.size([1.200000]) = 1
Beispiel 4
In diesem Beispiel wird ein leeres Array verwendet.
arrays.size([]) = 0
arrays.index_to_int
arrays.index_to_int(array_of_inputs, index)
Beschreibung
Gibt den Wert an einem bestimmten Index in einem Array als Ganzzahl zurück. Wenn der Index eine negative Zahl ist, wird der Wert von der Rückseite des Arrays abgerufen.
Parameterdatentypen
ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS
, INT
Rückgabetyp
INT
Codebeispiele
Beispiel 1
Dieser Funktionsaufruf gibt 0 zurück, wenn der Wert am Index eine nicht numerische Zeichenfolge ist.
arrays.index_to_int(["str0", "str1", "str2"], 1) = 0
Beispiel 2
Diese Funktion gibt das Element bei Index -1 zurück.
arrays.index_to_int(["44", "11", "22", "33"], -1) = 33
Beispiel 3
Gibt 0 für das Element außerhalb des Grenzwerts zurück.
arrays.index_to_int(["44", "11", "22", "33"], 5) = 0
Beispiel 4
Diese Funktion ruft das Element aus dem Float-Array bei Index 2 ab.
arrays.index_to_int([1.100000, 1.200000, 1.300000], 1) = 1
Beispiel 5
Diese Funktion ruft das Element aus dem int-Array bei Index 0 ab.
arrays.index_to_int([1, 2, 3], 2) = 1
cast.as_bool
cast.as_bool(string_or_int)
Beschreibung
Die Funktion wandelt einen Ganzzahl- oder Stringwert in einen Booleschen Wert um. Funktionsaufrufe mit Werten, die nicht umgewandelt werden können, geben FALSE zurück. Gibt TRUE nur für Ganzzahl 1 und String 'true' ohne Berücksichtigung der Groß-/Kleinschreibung zurück.
Datentypen für Parameter
INT|STRING
Rückgabetyp
BOOL
Codebeispiele
Beispiel 1
In diesem Beispiel wird gezeigt, wie Sie einen nicht booleschen String umwandeln
cast.as_bool("123") = false
Beispiel 2
Wahrheitsgemäße Ganzzahl (1)
cast.as_bool(1) = true
Beispiel 3
Falscher String
cast.as_bool("true") = true
Beispiel 4
Wahrheitsstring in Großbuchstaben
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
cast.as_float(string_to_cast)
Beschreibung
Wandelt eine numerische Zeichenfolge in eine Gleitkommazahl um. Alle Funktionsaufrufe mit Werten, die nicht umgewandelt werden können, geben 0 zurück. Bei Gleitkommazahlen wird eine Genauigkeit von bis zu sieben Dezimalstellen beibehalten.
Parameterdatentypen
STRING
Rückgabetyp
FLOAT
Codebeispiele
Beispiel 1
Beim Umwandeln eines nicht numerischen Strings wird 0 zurückgegeben.
cast.as_float("str") = 0.0000000
Beispiel 2
Beim Umwandeln eines leeren Strings wird 0 zurückgegeben.
cast.as_float("") = 0.0000000
Beispiel 3
Beim Umwandeln eines gültigen numerischen Strings wird ein Gleitkommawert zurückgegeben.
cast.as_float("1.012345678") = 1.0123456
Fingerprint
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.
Parameterdatentypen
BTYE
, STRING
Rückgabetyp
INT
Codebeispiel
id_fingerprint = hash.fingerprint2011("user123")
Gruppe
group(field1, field2, field3, ...)
Beschreibung
Gruppieren Sie Felder eines ähnlichen Typs in einer Platzhaltervariablen.
In der UDM-Suche: gruppiert Felder werden verwendet, um in mehreren Feldern eines ähnlichen Typs zu suchen. Die Gruppe ähnelt gruppierten Feldern, mit der Ausnahme, dass Sie hier auswählen können, welche Felder um eine Erkennung auszulösen. Mit der Funktion group können Sie Informationen über eine bestimmte Entität (z. B. Hostnamen, IP-Adressen oder Nutzer-IDs) für verschiedene Substantive-Typen erfassen.
Codebeispiele
Beispiel 1
Gruppieren Sie alle IP-Adressen und geben Sie die im gescannten Zeitraum am häufigsten verwendeten IP-Adressen in absteigender Reihenfolge an.
$ip = group(principal.ip, about.ip, target.ip)
$ip != ""
match:
$ip
outcome:
$count = count_distinct(metadata.id)
order:
$count desc
hash.sha256
hash.sha256(string)
Beschreibung
Gibt einen SHA-256-Hash des Eingabestrings zurück.
Parameterdatentypen
STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
In diesem Beispiel wird der SHA-256-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
math.abs(numericExpression)
Beschreibung
Gibt den absoluten Wert eines Ganzzahl- oder Gleitkommaausdrucks zurück.
Datentypen für Parameter
NUMBER
Rückgabetyp
NUMBER
Codebeispiele
Beispiel 1
In diesem Beispiel wird „True“ zurückgegeben, wenn das Ereignis mehr als 5 Minuten vom Zeitpunkt entfernt liegt
angegeben (in Sekunden seit der Unix-Epoche), unabhängig davon, ob das Ereignis
vor oder nach der angegebenen Zeit liegt. Ein Aufruf von math.abs
darf nicht von
Variablen oder Platzhalter verwenden. Beispielsweise können Sie den Parameter
hartcodierten Zeitwert von 1643687343 im folgenden Beispiel durch
$e2.metadata.event_timestamp.seconds
300 < math.abs($e1.metadata.event_timestamp.seconds - 1643687343)
math.ceil
math.ceil(number)
Beschreibung
Gibt die kleinste Ganzzahl zurück, die nicht kleiner als die angegebene Zahl ist (aufrunden). Gibt 0 zurück, wenn die Eingabe NULL oder zu groß für einen Int64-Wert ist.
Datentypen für Parameter
FLOAT
Rückgabetyp
INT
Codebeispiele
Dieser Abschnitt enthält Beispiele für die Verwendung von math.ceil
.
Beispiel 1
In diesem Beispiel wird der Höchstwert einer ganzen Zahl zurückgegeben.
math.ceil(2.000000) = 2
Beispiel 2
In diesem Beispiel wird der Höchstwert einer negativen Zahl zurückgegeben.
math.ceil(-1.200000) = -1
Beispiel 3
Dieses Beispiel gibt 0 als Höchstwert einer Zahl zurück, die für eine 64-Bit-Ganzzahl zu groß ist.
math.ceil(184467440737095516160.0) = 0
math.floor
math.floor(float_val)
Beschreibung
Gibt den größten ganzzahligen Wert zurück, der 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.
Parameterdatentypen
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
math.geo_distance(longitude1, latitude1, longitude2, latitude2))
Beschreibung
Gibt die Entfernung zwischen zwei geografischen Standorten (Koordinaten) zurück. Gibt -1 zurück, wenn die Geokoordinate ungültig ist.
Parameterdatentypen
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 abgeschnittene 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 identisch sind.
math.geo_distance(-122.897680, 37.407574, -122.897680, 37.407574) = 0.000000
math.is_increasing
math.is_increasing(num1, num2, num3)
Beschreibung
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
.
Datentypen für Parameter
INT|FLOAT
, INT|FLOAT
und 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 umfasst einen negativen Double-Wert, einen INT64-Wert von null und einen negativen INT64-Wert.
math.is_increasing(-1.200000, 0, -3) = false
Beispiel 4
Dieses Beispiel enthält zwei negative Double-Werte und einen INT64-Wert mit Null.
math.is_increasing(-1.200000, -1.50000, 0) = false
Beispiel 5
Dieses Beispiel enthält einen negativen Double-Wert und zwei gleiche Werte.
math.is_increasing(-1.200000, 0, 0) = false
math.log
math.log(numericExpression)
Beschreibung
Gibt den natürlichen Logwert eines Ganzzahl- oder Gleitkommawerts zurück.
Datentypen für Parameter
NUMBER
Rückgabetyp
NUMBER
Codebeispiele
Beispiel 1
math.log($e1.network.sent_bytes) > 20
math.pow
math.pow(base, exponent)
Beschreibung
Gibt den Wert des ersten Arguments zurück, das auf die Potenz des zweiten Arguments hochgesetzt wird. Gibt bei Überlauf 0 zurück.
Datentypen für Parameter
Basis: INT|FLOAT
Exponent: INT|FLOAT
Rückgabetyp
FLOAT
Codebeispiele
Beispiel 1
Dieses Beispiel zeigt die Groß-/Kleinschreibung einer Ganzzahl.
math.pow(2, 2) // 4.00
Beispiel 2
In diesem Beispiel wird der Basisfall anhand eines Bruchs dargestellt.
math.pow(2.200000, 3) // 10.648
Beispiel 3
Dieses Beispiel zeigt eine Basis mit Brüchen und einem Potenz.
math.pow(2.200000, 1.200000) // 2.575771
Beispiel 4
Dieses Beispiel zeigt einen Fall mit negativer Potenz.
math.pow(3, -3) // 0.037037
Beispiel 5
In diesem Beispiel wird die Potenz als Bruchzahl verwendet.
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
math.random()
Beschreibung
Erzeugt einen Pseudozufallswert vom Typ DOUBLE im Bereich von [0, 1)
, einschließlich 0 und ausschließlich 1.
Rückgabetyp
FLOAT
Codebeispiele
Im folgenden Beispiel wird geprüft, ob der Zufallswert im Bereich [0, 1)
liegt.
none
if(math.random() >= 0 and math.random() < 1) = true
math.round
math.round(numericExpression, decimalPlaces)
Beschreibung
Gibt einen Wert zurück, gerundet auf die nächste Ganzzahl oder auf die angegebene Anzahl von Dezimalstellen.
Parameterdatentypen
NUMBER
Rückgabetyp
NUMBER
Codebeispiele
math.round(10.7) // returns 11
math.round(1.2567, 2) // returns 1.25
math.round(-10.7) // returns -11
math.round(-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer
Messwerte
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
net.ip_in_range_cidr(ipAddress, subnetworkRange)
Beschreibung
Gibt true
zurück, wenn sich die angegebene IP-Adresse im angegebenen Subnetz befindet.
Sie können YARA-L verwenden, um in allen IP-Adressen nach UDM-Ereignissen zu suchen
in einem Subnetzwerk mit der net.ip_in_range_cidr()
-Anweisung.
Sowohl IPv4 als auch IPv6 werden unterstützt.
Geben Sie ein IP-UDM-Feld und ein CIDR an, um in einem IP-Adressbereich zu suchen Bereich. YARA-L kann sowohl einzelne als auch wiederkehrende 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 wiederkehrende IP-Adressfelder verarbeiten.
Datentypen für Parameter
STRING
, STRING
Rückgabetyp
BOOL
Codebeispiele
Beispiel 1
IPv4-Beispiel:
net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")
Beispiel 2
IPv6-Beispiel:
net.ip_in_range_cidr($e.network.dhcp.yiaddr, "2001:db8::/32")
Eine Beispielregel mit der Anweisung net.ip_in_range_cidr()
finden Sie in der Beispielregel unter Einzelnes Ereignis im Bereich von IP-Adressen.
re.regex
Sie können den Abgleich regulärer Ausdrücke in YARA-L 2.0 mit einer der folgenden Syntaxen definieren:
Verwendung der YARA-L-Syntax – Bezieht sich auf Ereignisse. Im Folgenden finden Sie eine allgemeine Darstellung dieser Syntax:
$e.field = /regex/
Verwendung der YARA-L-Syntax: Eine Funktion, die die folgenden Parameter verwendet:
- Feld, auf das der reguläre Ausdruck angewendet wird.
- Regulärer Ausdruck, der als String angegeben wird.
Im Folgenden finden Sie eine allgemeine Darstellung dieser Syntax:
re.regex($e.field, `regex`)
Beschreibung
Diese Funktion gibt true
zurück, wenn der String einen Teilstring enthält, der mit dem angegebenen regulären Ausdruck übereinstimmt. Es ist nicht erforderlich, .*
am Anfang oder Ende des regulären Ausdrucks hinzuzufügen.
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. Beispiel:/^full$/
stimmt genau mit"full"
überein, während/full/
eine Übereinstimmung mit"fullest"
,"lawfull"
und"joyfully"
. - Wenn das UDM-Feld Zeilenumbruchzeichen enthält, stimmt
regexp
nur mit den des UDM-Felds ein. Um einen vollständigen UDM-Feldabgleich zu erzwingen, fügen Sie ein(?s)
zu dem regulären Ausdruck. Ersetzen Sie beispielsweise/.*allUDM.*/
durch/(?s).*allUDM.*/
. - Sie können den
nocase
-Modifikator nach Strings verwenden, um anzugeben, dass die Suche die Groß- und Kleinschreibung zu ignorieren.
Parameterdatentypen
STRING
, STRING
Parameterausdruckstypen
ANY
, ANY
Rückgabetyp
BOOL
Codebeispiele
Beispiel 1
// Equivalent to $e.principal.hostname = /google/
re.regex($e.principal.hostname, "google")
re.capture
re.capture(stringText, regex)
Beschreibung
Erfasst (extrahiert) Daten aus einem String mithilfe des Musters für reguläre Ausdrücke im Argument übergeben werden.
Diese Funktion verwendet zwei Argumente:
stringText
: Der ursprüngliche String, in dem gesucht werden soll.regex
: Der reguläre Ausdruck, der das Muster angibt, nach dem gesucht werden soll.
Der reguläre Ausdruck kann 0 oder 1 Erfassungsgruppen in Klammern enthalten. Wenn die der reguläre Ausdruck 0 Erfassungsgruppen enthält, gibt die Funktion das erste gesamte übereinstimmende Teilzeichenfolge. Wenn der reguläre Ausdruck eine Erfassungsgruppe enthält, wird die erste übereinstimmende Teilzeichenfolge für die Erfassungsgruppe zurückgegeben. Wenn Sie zwei oder weitere Erfassungsgruppen geben einen Compiler-Fehler zurück.
Parameterdatentypen
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. Dieses Beispiel hat keine Erfassungsgruppen.
"aaa1" = re.capture($e.principal.hostname, "a+[1-9]")
Beispiel 2
In diesem Beispiel wird alles nach dem @-Symbol in einer E-Mail erfasst. Wenn die
$e.network.email.from
ist test@google.com
, im Beispiel wird Folgendes zurückgegeben:
google.com
Das folgende Beispiel enthält eine Erfassungsgruppe.
"google.com" = re.capture($e.network.email.from , "@(.*)")
Beispiel 3
Wenn der reguläre Ausdruck mit keiner Teilzeichenfolge im Text übereinstimmt, wird der Parameter
-Funktion gibt einen leeren String zurück. Ereignisse, bei denen keine Übereinstimmung vorliegt, können Sie weglassen
indem Sie die leere Zeichenfolge ausschließen. Dies ist besonders wichtig,
Verwenden von re.capture()
mit einer Ungleichung:
// Exclude the empty string to omit events where no match occurs.
"" != re.capture($e.network.email.from , "@(.*)")
// Exclude a specific string with an inequality.
"google.com" != re.capture($e.network.email.from , "@(.*)")
re.replace
re.replace(stringText, replaceRegex, replacementText)
Beschreibung
Führt eine Ersetzung eines regulären Ausdrucks durch.
Diese Funktion verwendet drei Argumente:
stringText
: der ursprüngliche String.replaceRegex
: Der reguläre Ausdruck, der das Muster angibt, nach dem gesucht werden soll.replacementText
: Der Text, der in jede Übereinstimmung eingefügt werden soll.
Gibt einen neuen String zurück, der aus dem ursprünglichen stringText
abgeleitet ist, wobei alle
Teilstrings, die mit dem Muster in replaceRegex
übereinstimmen, werden durch den Wert in
replacementText
Sie können Escape-Ziffern mit umgekehrtem Schrägstrich (\1
bis \9
) in
replacementText
, um Text einzufügen, der mit der entsprechenden Klammergruppe übereinstimmt
im Muster replaceRegex
. Mit \0
können Sie auf den gesamten übereinstimmenden Text verweisen.
Die Funktion ersetzt nicht überlappende Übereinstimmungen und priorisiert das Ersetzen der
erstes Vorkommen gefunden. Beispiel: re.replace("banana", "ana", "111")
gibt den String "b111na" zurück.
Parameterdatentypen
STRING
, STRING
und 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.
"email@google.org" = re.replace($e.network.email.from, "com", "org")
Beispiel 2
In diesem Beispiel werden im Argument replacementText
Ziffern mit umgekehrten Schrägstrichen verwendet, um
Referenzübereinstimmungen mit dem Muster replaceRegex
.
"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:
Leeren String als replaceRegex
verwenden:
// In the function call below, if $e.principal.hostname contains "name",
// the result is: 1n1a1m1e1, because an empty string is found next to
// every character in `stringText`.
re.replace($e.principal.hostname, "", "1")
Um einen leeren String zu ersetzen, können Sie "^$"
als replaceRegex
verwenden:
// In the function call below, if $e.principal.hostname contains the empty
// string, "", the result is: "none".
re.replace($e.principal.hostname, "^$", "none")
sample_rate
optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)
Beschreibung
Diese Funktion bestimmt anhand einer deterministischen der Stichprobenerhebung. 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
gibt an, dass das Ereignis nicht in die Stichprobe aufgenommen werden soll.
Diese Funktion ist nützlich für Optimierungsszenarien, in denen Sie nur eine Teilmenge der Ereignisse. Entspricht:
hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator
Parameterdatentypen
- byteOrString: Ausdruck, der als
BYTE
oderSTRING
ausgewertet wird. - rateNumerator: 'INT'
- rateDenominator: 'INT'
Rückgabetyp
BOOL
Codebeispiel
events:
$e.metadata.event_type = "NETWORK_CONNECTION"
$asset_id = $e.principal.asset.asset_id
optimization.sample_rate($e.metadata.id, 1, 5) // Only 1 out of every 5 events
match:
$asset_id over 1h
outcome:
$event_count = count_distinct($e.metadata.id)
// estimate the usage by multiplying by the inverse of the sample rate
$usage_past_hour = sum(5.0 * $e.network.sent_bytes)
condition:
// Requiring a certain number of events after sampling avoids bias (e.g. a
// device with just 1 connection will still show up 20% of the time and
// if we multiply that traffic by 5, we'll get an incorrect estimate)
$e and ($usage_past_hour > 1000000000) and $event_count >= 100
strings.base64_decode
strings.base64_decode(encodedString)
Beschreibung
Gibt einen String zurück, der die Base64-decodierte Version des codierten Strings enthält.
Diese Funktion verwendet einen base64-codierten String als Argument. Wenn encodedString
kein gültiger base64-codierter String ist, gibt die Funktion encodedString
unverändert zurück.
Parameterdatentypen
STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
"test" = strings.base64_decode($e.principal.domain.name)
strings.coalesce
strings.coalesce(a, b, c, ...)
Beschreibung
Diese Funktion verwendet eine unbegrenzte Anzahl von Argumenten und gibt den Wert des ersten Ausdrucks zurück, der nicht als leerer String ausgewertet wird (z. B. „Wert ungleich null“). Wenn alle Argumente einen leeren String ergeben, gibt der Funktionsaufruf einen leeren String zurück.
Die Argumente können Literale, Ereignisfelder oder Funktionsaufrufe sein. Alle Argumente müssen vom Typ STRING
sein. Wenn Argumente Ereignisfelder sind, müssen die Attribute aus demselben Ereignis stammen.
Datentypen für Parameter
STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
Das folgende Beispiel enthält Stringvariablen als Argumente. Die Bedingung
wird mit "true" ausgewertet, wenn (1) $e.network.email.from
gleich suspicious@gmail.com
ist oder
(2) $e.network.email.from
ist leer und $e.network.email.to
ist
suspicious@gmail.com
.
"suspicious@gmail.com" = strings.coalesce($e.network.email.from, $e.network.email.to)
Beispiel 2
Im folgenden Beispiel wird die Funktion coalesce
mit mehr als zwei
Argumente. Diese Bedingung vergleicht die erste IP-Adresse, die nicht null ist aus dem Ereignis $e
den Werten in der Referenzliste ip_watchlist
entsprechen. Die Reihenfolge, in der die
Argumente werden in diesem Aufruf in derselben Reihenfolge zusammengeführt.
in der Regelbedingung aufgezählt:
$e.principal.ip
wird zuerst ausgewertet.- Als Nächstes wird
$e.src.ip
ausgewertet. $e.target.ip
wird als Nächstes ausgewertet.- 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 einem Ereignis zusammenzuführen
$e1
und Ereignis $e2
. Es wird ein Compilerfehler zurückgegeben, da die Argumente unterschiedliche Ereignisvariablen sind.
// returns a compiler error
"test" = strings.coalesce($e1.principal.hostname, $e2.principal.hostname)
strings.concat
strings.concat(a, b, c, ...)
Beschreibung
Gibt die Verkettung einer unbegrenzten Anzahl von Elementen zurück, von denen jedes Element sein kann. als String, Ganzzahl oder Gleitkommazahl.
Wenn Argumente Ereignisfelder sind, müssen die Attribute aus demselben Ereignis stammen.
Parameterdatentypen
STRING
, FLOAT
, INT
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
Das folgende Beispiel enthält eine Zeichenfolgen- und eine Ganzzahlvariable als
Argumente. principal.hostname
und principal.port
sind vom selben
$e
und werden so verkettet, dass ein String zurückgegeben wird.
"google:80" = strings.concat($e.principal.hostname, ":", $e.principal.port)
Beispiel 2
Das folgende Beispiel enthält eine Stringvariable und ein Stringliteral als Argumente.
"google-test" = strings.concat($e.principal.hostname, "-test") // Matches the event when $e.principal.hostname = "google"
Beispiel 3
Das folgende Beispiel enthält eine Stringvariable und ein Float-Literal als Argumente. Wenn Gleitkommazahlen als ganze Zahlen dargestellt werden, werden sie ohne Durch das Dezimaltrennzeichen (1, 0 wird beispielsweise als „1“ dargestellt). Außerdem Gleitkommazahlen mit mehr als sechzehn Dezimalstellen werden auf die sechzehnte Dezimalzahl gekürzt
"google2.5" = strings.concat($e.principal.hostname, 2.5)
Beispiel 4
Das folgende Beispiel enthält eine Stringvariable, ein Stringliteral,
Ganzzahlvariable und Float-Literal als Argumente. Alle Variablen stammen aus der
dasselbe Ereignis, $e
, und werden mit den Literalen verkettet, um einen String zurückzugeben.
"google-test802.5" = strings.concat($e.principal.hostname, "-test", $e.principal.port, 2.5)
Beispiel 5
Im folgenden Beispiel wird versucht, principal.port aus dem Ereignis $e1
zu verketten.
mit principal.hostname
aus Ereignis $e2
. Es wird ein Compilerfehler zurückgegeben, da die Argumente unterschiedliche Ereignisvariablen sind.
// Will not compile
"test" = strings.concat($e1.principal.port, $e2.principal.hostname)
strings.contains
strings.contains( str, substr )
Beschreibung
Gibt „wahr“ zurück, wenn ein bestimmter String den angegebenen Teilstring enthält. Andernfalls wird „false“ zurückgegeben.
Parameterdatentypen
STRING
, STRING
Rückgabetyp
BOOL
Codebeispiele
Beispiel 1
In diesem Beispiel wird „true“ zurückgegeben, da der String die Teilzeichenfolge „is“ hat.
strings.contains("thisisastring", "is") = true
Beispiel 2
In diesem Beispiel wird „false“ zurückgegeben, weil der String nicht den Teilstring „that“ hat.
strings.contains("thisisastring", "that") = false
strings.count_substrings
strings.count_substrings(string_to_search_in, substring_to_count)
Beschreibung
Bei Angabe eines Strings und einer Teilzeichenfolge wird eine Ganzzahl 64 der Anzahl der sich nicht überlappenden Vorkommen der Teilzeichenfolge innerhalb des Strings zurückgegeben.
Parameterdatentypen
STRING
, STRING
Rückgabetyp
INT
Codebeispiele
Dieser Abschnitt enthält Beispiele, die berechnen, wie oft ein Teilstring in einem bestimmten String vorkommt.
Beispiel 1
In diesem Beispiel wird ein Nicht-Null-String und ein einzelnes Teilstring-Zeichen, das nicht null ist, verwendet.
strings.count_substrings("this`string`has`four`backticks", "`") = 4
Beispiel 2
In diesem Beispiel wird ein Nicht-Null-String und ein Nicht-Null-Teilstring mit mehr als einem Zeichen verwendet.
strings.count_substrings("str", "str") = 1
Beispiel 3
In diesem Beispiel wird ein String ungleich null und ein leerer Teilstring verwendet.
strings.count_substrings("str", "") = 0
Beispiel 4
In diesem Beispiel wird ein leerer String und ein Teilstring ungleich null verwendet, der größer als ein Zeichen ist.
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 wird ein Nicht-Null-String und ein Nicht-Null-Teilstring verwendet, der größer als ein Zeichen und größer als ein Vorkommen ist.
strings.count_substrings("fooABAbarABAbazABA", "AB") = 3
Beispiel 7
In diesem Beispiel wird ein Nicht-Null-String und ein Nicht-Null-Teilstring verwendet, der größer als ein Zeichen und größer als ein Vorkommen ist. Die Einschränkung mit sich überschneidenden Teilstring-Vorkommen wird hervorgehoben.
strings.count_substrings("ABABABA", "ABA") = 2
strings.extract_domain
strings.extract_domain(url_string)
Beschreibung
Extrahiert die Domain aus einem String.
Datentypen für Parameter
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
Umgang mit URIs
strings.extract_domain("mailto:?to=&subject=&body=") = ""
Beispiel 6
mehrere Zeichen vor der tatsächlichen URL
strings.extract_domain(" \t !$5*^)&dahgsdfs;http://www.google.com") = "google.com"
Beispiel 7
Sonderzeichen in 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
strings.extract_hostname(string)
Beschreibung
Extrahiert den Hostnamen aus einem String. Bei dieser Funktion wird zwischen Groß- und Kleinschreibung unterschieden.
Parameterdatentypen
STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
In diesem Beispiel wird ein leerer String zurückgegeben.
strings.extract_hostname("") = ""
Beispiel 2
Zufallsstring, keine URL
strings.extract_hostname("1234") = "1234"
Beispiel 3
mehrere umgekehrte Schrägstriche
strings.extract_hostname("\\\\") = ""
Beispiel 4
Nicht-englische Zeichen werden korrekt behandelt
strings.extract_hostname("http://例子.卷筒纸.中国") = "例子.卷筒纸.中国"
Beispiel 5
Umgang mit URIs
strings.extract_hostname("mailto:?to=&subject=&body=") = "mailto"
Beispiel 6
mehrere Zeichen vor der tatsächlichen URL
strings.extract_hostname(" \t !$5*^)&dahgsdfs;http://www.google.com") = "www.google.com"
Beispiel 7
Sonderzeichen in URI #
strings.extract_hostname("test#@google.com") = "test"
Beispiel 8
Sonderzeichen in URL #
strings.extract_hostname("https://test#@google.com") = "test"
strings.from_hex
strings.from_hex(hex_string)
Beschreibung
Gibt die Bytes zurück, die dem angegebenen hexadezimalen String zugeordnet sind.
Datentypen für Parameter
STRING
Rückgabetyp
BYTES
Codebeispiele
Bytes abrufen, die mit einem bestimmten Hexadezimalstring verknüpft sind.
Beispiel 1
In diesem Beispiel werden Konvertierungen in nicht hexadezimalen Zeichen dargestellt.
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 Umwandlung eines Hex-Strings.
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
strings.ltrim(string_to_trim, cutset)
Beschreibung
Passt führende Leerzeichen aus einer bestimmten Zeichenfolge an. Mit dieser Funktion werden führende Zeichen in diesem Cutset entfernt.
Parameterdatentypen
STRING
, STRING
Rückgabetyp
STRING
Codebeispiele
Im Folgenden finden Sie Beispiele für Anwendungsfälle.
Beispiel 1
In diesem Beispiel wird 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
strings.reverse(STRING)
Beschreibung
Gibt einen String zurück, der die Umkehrung des Eingabestrings ist.
Parameterdatentypen
STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
Im folgenden Beispiel wird ein kurzer String übergeben.
strings.reverse("str") = "rts" // The function returns 'rts'.
Beispiel 2
Im folgenden Beispiel wird ein leerer String übergeben.
strings.reverse("") = ""
Beispiel 3
Im folgenden Beispiel wird ein Palindrom übergeben.
strings.reverse("tacocat") = "tacocat"
strings.rtrim
strings.rtrim(string_to_trim, cutset)
Beschreibung
Passt nachgestellte Leerzeichen aus einer bestimmten Zeichenfolge an. Entfernt nachgestellte Zeichen, die in diesem Cutset vorhanden sind.
Parameterdatentypen
STRING
, STRING
Rückgabetyp
STRING
Codebeispiele
Im Folgenden finden Sie Beispiele für Anwendungsfälle.
Beispiel 1
Im folgenden Beispiel wird derselbe String wie beim ersten und zweiten Argument übergeben.
strings.rtrim("str", "str") = ""
Beispiel 2
Im folgenden Beispiel wird ein leerer String als zweites Argument übergeben.
strings.rtrim("str", "") = "str"
Beispiel 3
Im folgenden Beispiel wird ein leerer String als erstes Argument und ein nicht leerer String als zweites Argument übergeben.
strings.rtrim("", "str") = ""
Beispiel 4
Im folgenden Beispiel wird ein String mit Leerzeichen als erstes Argument und ein nicht leerer String als zweites Argument übergeben.
strings.rtrim("a aastraa aa ", " a") = "a aasstr"
strings.to_lower
strings.to_lower(stringText)
Beschreibung
Diese Funktion nimmt einen Eingabestring entgegen und gibt einen String zurück, nachdem alle Zeichen in Kleinbuchstaben umgewandelt wurden.
Parameterdatentypen
STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
Im folgenden Beispiel wird true
zurückgegeben.
"test@google.com" = strings.to_lower($e.network.email.to)
strings.to_upper
strings.to_upper(string_val)
Beschreibung
Gibt den ursprünglichen String mit allen alphabetischen Zeichen in Großbuchstaben zurück.
Parameterdatentypen
STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
Im folgenden Beispiel wird das angegebene Argument in Großbuchstaben zurückgegeben.
strings.to_upper("example") = "EXAMPLE"
strings.trim
strings.trim(string_to_trim, cutset)
Beschreibung
Passt voran- und nachgestellte Leerzeichen aus einer Zeichenfolge an. Außerdem werden unerwünschte Zeichen (über das Argument „cutset“ angegeben) aus dem Eingabestring entfernt.
Parameterdatentypen
STRING
, STRING
Rückgabetyp
STRING
Codebeispiele
Im Folgenden finden Sie Beispiele für 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. Dies führt zum ursprünglichen String "str", 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 liefert die Funktion "str", da die Funktion "cut" Folgendes entfernt:
- Nachgestelltes Leerzeichen in „a aastraa aa“
- die im Cutset angegebenen Zeichen (Leerzeichen, a)
strings.trim("a aastraa aa ", " a") = "str"
strings.url_decode
strings.url_decode(url_string)
Beschreibung
Decodieren Sie bei einem URL-String die Escape-Zeichen und verarbeiten Sie die codierten UTF-8-Zeichen. Gibt einen leeren String zurück, wenn die Decodierung fehlschlägt.
Parameterdatentypen
STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
Dieses Beispiel zeigt einen positiven Testfall.
strings.url_decode("three%20nine%20four") = "three nine four"
Beispiel 2
In diesem Beispiel wird die Groß-/Kleinschreibung eines leeren Strings dargestellt.
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+"¶m2=2;'
timestamp.as_unix_seconds
timestamp.as_unix_seconds(timestamp [, time_zone])
Beschreibung
Diese Funktion gibt eine Ganzzahl zurück, die die Anzahl der Sekunden seit einer Unix-Epoche für den angegebenen Zeitstempelstring angibt.
timestamp
ist ein String, der einen gültigen Epochenzeitstempel darstellt. Das Format muss wird als%F %T
festgelegt.time_zone
ist optional und ein String, der eine Zeitzone darstellt. Wenn ausgelassen, wird der StandardwertGMT
verwendet. Sie können Zeitzonen mithilfe eines Strings angeben Literalen. Folgende Optionen sind verfügbar:- Der Name der Zeitzonendatenbank, z. B.
America/Los_Angeles
. Weitere Informationen finden Sie in der Liste der Zeitzonen in der tz-Datenbank bei Wikipedia - Der Zeitzonenversatz zur UTC im Format
(+|-)H[H][:M[M]]
, Beispiel: „-08:00“.
- Der Name der Zeitzonendatenbank, z. B.
Hier sind Beispiele für gültige time_zone
-Spezifizierer, die Sie als zweites Argument an Zeitextraktionsfunktionen übergeben können:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Parameterdatentypen
STRING
, STRING
Rückgabetyp
INT
Codebeispiele
Beispiel 1
Gültiger Epochenzeitstempel
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
timestamp.current_seconds()
Beschreibung
Gibt eine Ganzzahl zurück, die die aktuelle Zeit in Unix-Sekunden darstellt. Dies ist
Sie entspricht ungefähr dem Zeitstempel der Erkennung und basiert darauf, wann die Regel
ausführen. Diese Funktion ist ein Synonym für die Funktion timestamp.now()
.
Parameterdatentypen
NONE
Rückgabetyp
INT
Codebeispiele
Beispiel 1
Im folgenden Beispiel wird true
zurückgegeben, wenn das Zertifikat bereits für weitere
als 24 Stunden. Er berechnet den Zeitunterschied durch Subtrahieren des aktuellen Unix
Sekunden und dann mit dem Operator „Größer als“ verglichen.
86400 < timestamp.current_seconds() - $e.network.tls.certificate.not_after
timestamp.get_date
timestamp.get_date(unix_seconds [, time_zone])
Beschreibung
Diese Funktion gibt einen String im Format YYYY-MM-DD
zurück, der den Tag darstellt, an dem sich ein Zeitstempel befindet.
unix_seconds
ist eine Ganzzahl, die die Anzahl der Sekunden nach Unix darstellt Epoche, z. B.$e.metadata.event_timestamp.seconds
, oder ein Platzhalter das diesen Wert enthält.time_zone
ist optional und ein String, der eine Zeitzone darstellt. Wenn wird weggelassen, wird standardmäßig "GMT" verwendet. Sie können Zeitzonen mithilfe eines Strings angeben Literalen. Folgende Optionen sind verfügbar:- Der TZ-Datenbankname, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie in der Spalte Name der Zeitzonendatenbank auf dieser Seite.
- Der Zeitzonenversatz zur UTC im Format
(+|-)H[H][:M[M]]
, Beispiel: „-08:00“.
Im Folgenden finden Sie Beispiele für gültige Zeitzonenbezeichner, die Sie als zweites Argument an Zeitextraktionsfunktionen übergeben können:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Parameterdatentypen
INT
, STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
In diesem Beispiel wird das Argument time_zone
weggelassen. Standardmäßig wird „GMT“ verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_date($ts) = "2024-02-19"
Beispiel 2
In diesem Beispiel wird ein Stringliteral zur Definition von time_zone
verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_date($ts, "America/Los_Angeles") = "2024-02-20"
timestamp.get_minute
timestamp.get_minute(unix_seconds [, time_zone])
Beschreibung
Diese Funktion gibt eine Ganzzahl im Bereich [0, 59]
zurück, die für die Minute steht.
unix_seconds
ist eine Ganzzahl, die die Anzahl der Sekunden nach Unix darstellt Epoche, z. B.$e.metadata.event_timestamp.seconds
, oder ein Platzhalter das 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 TZ-Datenbankname, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie unter "TZ Database Name" Spalte von 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 Zeitextraktionsfunktionen übergeben können:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Parameterdatentypen
INT
, STRING
Rückgabetyp
INT
Codebeispiele
Beispiel 1
In diesem Beispiel wird das Argument time_zone
weggelassen. Standardmäßig wird „GMT“ verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts) = 15
Beispiel 2
In diesem Beispiel wird ein Stringliteral zur Definition von time_zone
verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts, "America/Los_Angeles") = 15
timestamp.get_hour
timestamp.get_hour(unix_seconds [, time_zone])
Beschreibung
Diese Funktion gibt eine Ganzzahl im Bereich [0, 23]
für die Stunde zurück.
unix_seconds
ist eine Ganzzahl, die die Anzahl der Sekunden nach Unix darstellt Epoche, z. B.$e.metadata.event_timestamp.seconds
, oder ein Platzhalter das diesen Wert enthält.time_zone
ist optional und ein String, der eine Zeitzone darstellt. Wenn wird weggelassen, wird standardmäßig "GMT" verwendet. Sie können Zeitzonen mithilfe eines Strings angeben Literalen. Folgende Optionen sind verfügbar:- Der TZ-Datenbankname, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie unter "TZ Database Name" Spalte von dieser Seite
- Der Zeitzonenversatz zur UTC im Format
(+|-)H[H][:M[M]]
, Beispiel: „-08:00“.
Hier sind Beispiele für gültige time_zone
-Spezifizierer, die Sie als zweites Argument an Zeitextraktionsfunktionen übergeben können:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Parameterdatentypen
INT
, STRING
Rückgabetyp
INT
Codebeispiele
Beispiel 1
In diesem Beispiel wird das Argument time_zone
weggelassen. Standardmäßig wird „GMT“ verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts) = 15
Beispiel 2
In diesem Beispiel wird ein Stringliteral zur Definition von time_zone
verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_hour($ts, "America/Los_Angeles") = 15
timestamp.get_day_of_week
timestamp.get_day_of_week(unix_seconds [, time_zone])
Beschreibung
Diese Funktion gibt eine Ganzzahl im Bereich [1, 7]
zurück, die den Tag des
Woche beginnend mit Sonntag beginnen. Beispiel: 1 = Sonntag und 2 = Montag.
unix_seconds
ist eine Ganzzahl, die die Anzahl der Sekunden nach Unix darstellt Epoche, z. B.$e.metadata.event_timestamp.seconds
, oder ein Platzhalter das diesen Wert enthält.time_zone
ist optional und ein String, der eine Zeitzone darstellt. Wenn wird weggelassen, wird standardmäßig "GMT" verwendet. Sie können Zeitzonen mithilfe eines Strings angeben Literalen. Folgende Optionen sind verfügbar:- Der TZ-Datenbankname, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie unter "TZ Database Name" Spalte von dieser Seite
- Der Zeitzonenversatz zur UTC im Format
(+|-)H[H][:M[M]]
, Beispiel: „-08:00“.
Im Folgenden finden Sie Beispiele für gültige Zeitzonenbezeichner, die Sie als zweites Argument an Zeitextraktionsfunktionen übergeben können:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Parameterdatentypen
INT
, STRING
Rückgabetyp
INT
Codebeispiele
Beispiel 1
In diesem Beispiel wird das Argument time_zone
weggelassen. Standardmäßig wird „GMT“ verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_day_of_week($ts) = 6
Beispiel 2
In diesem Beispiel wird ein Stringliteral verwendet, um die time_zone
zu definieren.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_day_of_week($ts, "America/Los_Angeles") = 6
timestamp.get_timestamp
timestamp.get_timestamp(unix_seconds, optional timestamp_format, optional timezone)
Beschreibung
Diese Funktion gibt einen String im Format YYYY-MM-DD
zurück, der den Tag darstellt, an dem sich ein Zeitstempel befindet.
unix_seconds
ist eine Ganzzahl, die die Anzahl der Sekunden 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 ist ein String, der das Format für den Zeitstempel. Wenn keine Angabe gemacht wird, lautet der Standardwert%F %T
. Sie können das Format mithilfe von String-Literalen. Informationen zu Optionen finden Sie unter Formatelemente für Datums- und Uhrzeitangaben.time_zone
ist optional und ein String, der eine Zeitzone darstellt. Wenn keine Angabe gemacht wird, lautet der StandardwertGMT
. Sie können Zeitzonen mithilfe eines Strings angeben Literalen. Folgende Optionen sind verfügbar:- Der Name der IANA-Zeitzone (TZ), z. B.
America/Los_Angeles
. Weitere Informationen Weitere Informationen finden Sie in der Liste der Zeitzonen in der tz-Datenbank auf Wikipedia. - Die Zeitzone, die von UTC abweicht, im Format
(+|-)H[H][:M[M]]
, Beispiel: „-08:00“.
- Der Name der IANA-Zeitzone (TZ), z. B.
Hier sind Beispiele für gültige time_zone
-Spezifizierer, die Sie als zweites Argument an Zeitextraktionsfunktionen übergeben können:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Parameterdatentypen
INT
, STRING
, STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
In diesem Beispiel wird das Argument time_zone
weggelassen. Der Standardwert ist GMT
.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_timestamp($ts) = "2024-02-22 10:43:51"
Beispiel 2
In diesem Beispiel wird ein Stringliteral zur Definition von time_zone
verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_timestamp($ts, "%F %T", "America/Los_Angeles") = "2024-02-22 10:43:51"
Beispiel 3
In diesem Beispiel wird ein Stringliteral zur Definition von timestamp_format
verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_timestamp($ts, "%Y-%m", "GMT") = "2024-02"
timestamp.get_week
timestamp.get_week(unix_seconds [, time_zone])
Beschreibung
Diese Funktion gibt eine Ganzzahl im Bereich [0, 53]
zurück, die für die Woche vom
des Jahres. Wochen beginnen mit Sonntag. Datumsangaben vor dem ersten Sonntag des Jahres sind
in Woche 0.
unix_seconds
ist eine Ganzzahl, die die Anzahl der Sekunden nach Unix darstellt Epoche, z. B.$e.metadata.event_timestamp.seconds
, oder ein Platzhalter das diesen Wert enthält.time_zone
ist optional und ein String, der eine Zeitzone darstellt. Wenn wird weggelassen, wird standardmäßig "GMT" verwendet. Sie können Zeitzonen mithilfe eines Strings angeben Literalen. Folgende Optionen sind verfügbar:- Der TZ-Datenbankname, z. B. „America/Los_Angeles“. Weitere Informationen finden Sie unter "TZ Database Name" Spalte von dieser Seite
- Der Zeitzonenversatz zur UTC im Format
(+|-)H[H][:M[M]]
, Beispiel: „-08:00“.
Hier sind Beispiele für gültige time_zone
-Spezifizierer, die Sie als zweites Argument an Zeitextraktionsfunktionen übergeben können:
"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"
Parameterdatentypen
INT
, STRING
Rückgabetyp
INT
Codebeispiele
Beispiel 1
In diesem Beispiel wird das Argument time_zone
weggelassen. Standardmäßig wird „GMT“ verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_week($ts) = 0
Beispiel 2
In diesem Beispiel wird ein Stringliteral zur Definition von time_zone
verwendet.
$ts = $e.metadata.collected_timestamp.seconds
timestamp.get_week($ts, "America/Los_Angeles") = 0
timestamp.now
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
window.avg(numeric_values [, should_ignore_zero_values])
Beschreibung
Gibt den Durchschnitt der Eingabewerte zurück (Ganzzahlen oder Gleitkommazahlen). Wird das optionale zweite Argument auf „true“ festgelegt, werden Nullwerte ignoriert.
Datentypen für Parameter
INT|FLOAT
Rückgabetyp
FLOAT
Codebeispiele
Beispiel 1
Dieses Beispiel zeigt den ganzzahligen Durchschnitt.
// 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
Dieses Beispiel zeigt den Gleitkommadurchschnitt.
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 gibt 0 zurück
events:
$e.user.userid = $userid
match:
$userid over 5m
outcome:
$size_mode = window.avg($e.file.size) // yields 0 if the event file size values in the match window is 0
Beispiel 5
Nullwerte werden ignoriert
events:
$e.user.userid = $userid
match:
$userid over 5m
outcome:
$size_mode = window.avg($e.file.size, true) // yields 394 if the event file size values in the match window are 0, 0, 0 and 394
window.first
window.first(values_to_sort_by, values_to_return)
Beschreibung
Diese Aggregationsfunktion gibt einen Stringwert zurück, der von einem Ereignis mit dem niedrigsten 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).
Parameterdatentypen
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
window.last(values_to_sort_by, values_to_return)
Beschreibung
Diese Aggregationsfunktion gibt einen Stringwert zurück, der aus einem Ereignis mit dem höchsten korrelierten Ganzzahlwert im Übereinstimmungsfenster abgeleitet ist. Ein Beispiel für einen Anwendungsfall ist das Abrufen der Nutzer-ID aus dem Ereignis mit dem niedrigsten Zeitstempel im Übereinstimmungsfenster (höchster Zeitstempel).
Parameterdatentypen
INT
, STRING
Rückgabetyp
STRING
Codebeispiele
Ruft einen Stringwert ab, der aus einem Ereignis mit dem höchsten korrelierten Ganzzahlwert im Übereinstimmungszeitraum abgeleitet wird.
// This rule sets the outcome $last_event to the highest correlated int value
// in the 5 minute match window.
events:
$e.user.userid = $userid
match:
$userid over 5m
outcome:
$last_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v3 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.
window.median
window.median(numeric_values, should_ignore_zero_values)
Beschreibung
Gibt den Medianwert der Eingabewerte zurück. Wenn es zwei Medianwerte gibt, wird nur einer nicht deterministisch als Rückgabewert ausgewählt.
Parameterdatentypen
INT|FLOAT
, BOOL
Rückgabetyp
FLOAT
Codebeispiele
Beispiel 1
In diesem Beispiel wird der Median zurückgegeben, wenn die Eingabewerte nicht null sind.
rule median_file_size {
meta:
events:
$e.metadata.event_type = "FILE_COPY"
$userid = $e.principal.user.userid
match:
$userid over 1h
outcome:
$median_file_size = window.median($e.principal.file.size) // returns 2 if the file sizes in the match window are [1, 2, 3]
condition:
$e
}
Beispiel 2
In diesem Beispiel wird der Median zurückgegeben, wenn die Eingabe 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 Medianwert zurückgegeben, wenn die Eingabe einige Nullwerte enthält, die ignoriert werden sollten.
rule median_file_size {
meta:
events:
$e.metadata.event_type = "FILE_COPY"
$userid = $e.principal.user.userid
match:
$userid over 1h
outcome:
$median_file_size = window.median($e.principal.file.size, 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 Medianwert 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 Medianwerten nur ein Medianwert zurückgegeben wird.
rule median_file_size {
meta:
events:
$e.metadata.event_type = "FILE_COPY"
$userid = $e.principal.user.userid
match:
$userid over 1h
outcome:
$median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [1, 2, 3, 4]
condition:
$e
}
window.mode
window.mode(values)
Beschreibung
Gibt den Modus der Eingabewerte zurück. Bei mehreren möglichen Moduswerten wird nur einer dieser Werte nicht deterministisch als Rückgabewert ausgewählt.
Parameterdatentypen
INT|FLOAT|STRING
Rückgabetyp
STRING
Codebeispiele
Beispiel 1
Ruft den Modus der Werte im Übereinstimmungsfenster ab.
// This rule sets the outcome $size_mode to the most frequently occurring
// file size in the 5 minute match window.
events:
$e.user.userid = $userid
match:
$userid over 5m
outcome:
$size_mode = window.mode($e.file.size) // yields 1.6 if the event file size values in the match window are 1.6, 2, and 1.6
window.stddev
window.stddev(numeric_values)
Beschreibung
Gibt die Standardabweichung von Eingabewerten in einem Übereinstimmungsfenster zurück.
Parameterdatentypen
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
Dieses Beispiel gibt die Standardabweichung von Gleitkommazahlen in einem Übereinstimmungsfenster zurück.
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 Übereinstimmungsfenster 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
Dieses Beispiel gibt die Standardabweichung eines Übereinstimmungsfensters mit positiven und negativen Zahlen zurück.
events:
$e.user.userid = $userid
match:
$userid over 5m
outcome:
$p1 = window.stddev($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
$e and #p1 > 10
window.variance
window.variance(values)
Beschreibung
Diese Funktion gibt die angegebene Varianz der Eingabewerte zurück.
Parameterdatentypen
INT|FLOAT
Rückgabetyp
FLOAT
Codebeispiele
Beispiel 1
In diesem Beispiel wird die Varianz aller Ganzzahlen zurückgegeben.
// This rule creates a detection when the file size variance in 5 minutes for a user is over a threshold.
events:
$e.user.userid = $userid
match:
$userid over 5m
outcome:
$p1 = window.variance($e.file.size) // yields 16 if the event file size values in the match window are [10, 14, 18].
condition:
$e and #p1 > 10
Beispiel 2
Dieses Beispiel gibt die Varianz aller Gleitkommazahlen zurück.
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 von positiven und negativen Zahlen zurückgegeben.
events:
$e.user.userid = $userid
match:
$userid over 5m
outcome:
$p1 = window.variance($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
$e and #p1 > 10
Zuweisung von Funktion zu Platzhalter
Sie können das Ergebnis eines Funktionsaufrufs einem Platzhalter im Abschnitt events
zuweisen. Beispiel:
$placeholder = strings.concat($e.principal.hostname, "my-string").
Sie können dann die Platzhaltervariablen in den Bereichen match
, condition
und outcome
verwenden.
Es gibt jedoch zwei Einschränkungen in Bezug auf die Zuweisung von Funktionen zu Platzhaltern:
Jeder Platzhalter in einer Zuweisung von Funktionen zu Platzhaltern muss einem Ausdruck zugewiesen werden, der ein Ereignisfeld enthält. Hier einige Beispiele:
$ph1 = $e.principal.hostname $ph2 = $e.src.hostname // Both $ph1 and $ph2 have been assigned to an expression containing an event field. $ph1 = strings.concat($ph2, ".com")
$ph1 = $e.network.email.from $ph2 = strings.concat($e.principal.hostname, "@gmail.com") // Both $ph1 and $ph2 have been assigned to an expression containing an event field. $ph1 = strings.to_lower($ph2)
Das folgende Beispiel ist jedoch ungültig:
$ph1 = strings.concat($e.principal.hostname, "foo") $ph2 = strings.concat($ph1, "bar") // $ph2 has NOT been assigned to an expression containing an event field.
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 finden Sie auf unserer Seite zu Referenzlisten. Referenzlistenverhalten und Referenzlistensyntax.
Sie können Referenzlisten in den Abschnitten events
oder outcome
verwenden. Hier sind die
Syntax zur Verwendung verschiedener Arten von Referenzlisten in einer Regel:
// STRING reference list
$e.principal.hostname in %string_reference_list
// REGEX reference list
$e.principal.hostname in regex %regex_reference_list
// CIDR reference list
$e.principal.ip in cidr %cidr_reference_list
Sie können auch die Operatoren not
und nocase
mit Referenzlisten verwenden, wie im folgenden Beispiel gezeigt:
// Exclude events whose hostnames match substrings in my_regex_list.
not $e.principal.hostname in regex %my_regex_list
// Event hostnames must match at least 1 string in my_string_list (case insensitive).
$e.principal.hostname in %my_string_list nocase
Der Operator nocase
ist mit STRING
- und REGEX
-Listen kompatibel.
Aus Leistungsgründen schränkt die Erkennungs-Engine die Verwendung von Referenzlisten ein.
- Maximale
in
-Anweisungen in einer Regel, mit oder ohne spezielle Operatoren: 7 - Maximale
in
-Anweisungen mit demregex
-Operator: 4 - Maximale Anzahl von
in
-Anweisungen mit dem Operatorcidr
: 2
Typprüfung
Google Security Operations führt eine Typprüfung anhand Ihrer YARA-L-Syntax durch, während Sie Regeln in der Benutzeroberfläche erstellen. Die angezeigten Fehler bei der Typprüfung helfen Ihnen, die Regel so zu überarbeiten, dass sie wie erwartet funktioniert.
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 für Erkennungsereignisse
Erkennungen aus Regeln für mehrere Ereignisse enthalten Ereignisbeispiele, die Kontext zu den Ereignissen liefern, die die Erkennung verursacht haben. Es sind maximal 10 Termine zulässig Stichproben für jede in der Regel definierte Ereignisvariable. Wenn beispielsweise eine Regel definiert zwei Ereignisvariablen, wobei für jede Erkennung bis zu 20 Ereignisstichproben vorhanden sein können. Die für jede Ereignisvariable einzeln an. Wenn eine Ereignisvariable Bei dieser Erkennung sind 2 anwendbare Ereignisse vorhanden, die andere Ereignisvariable hat 15 anwendbaren Ereignissen entsprechen, enthält die resultierende Erkennung 12 Ereignisbeispiele (2 + 10).
Ereignisstichproben, die das Limit überschreiten, werden 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 Erkennungen auf der Benutzeroberfläche ansehen, können Sie alle Beispiele für Ereignisse herunterladen für eine Erkennung. Weitere Informationen finden Sie unter Ereignisse herunterladen.