Übersicht über die Sprache YARA-L 2.0

Unterstützt in:

Google SecOps SIEM

YARA-L 2.0 ist eine Computersprache, mit der Regeln für die Suche in den Logdaten Ihres Unternehmens bei der Aufnahme in Ihre Google Security Operations-Instanz erstellt werden. Die YARA-L-Syntax leitet sich von der von VirusTotal entwickelten YARA-Sprache ab. Die Sprache arbeitet mit der Google Security Operations Detection Engine zusammen und ermöglicht die Suche nach Bedrohungen und anderen Ereignissen in großen Datenmengen.

Hier finden Sie weitere Informationen:

• Syntax der Sprache YARA-L 2.0

• Best Practices

Hinweis: YARA-L 2.0 ist nicht mit früheren Versionen der YARA-L-Sprache kompatibel. Regeln, die in älteren Versionen von YARA-L geschrieben sind, funktionieren nicht mit der aktuellen Version der Erkennungs-Engine und müssen überarbeitet werden, um die neue Syntax zu verwenden.

Beispielregeln für YARA-L 2.0

Die folgenden Beispiele zeigen Regeln, die in YARA-L 2.0 geschrieben wurden. Jede davon zeigt, wie Ereignisse innerhalb der Regelsprache in Beziehung gesetzt werden.

Regeln und Optimierung

Die folgende Regel prüft Ereignisdaten auf bestimmte Muster und erstellt eine Erkennung, wenn sie diese findet. Diese Regel enthält die Variable $e1 für das Tracking-Ereignis „type“ und das UDM-Feld metadata.event_type. Die Regel prüft auf bestimmte Vorkommen von Übereinstimmungen mit regulären Ausdrücken mit e1. Wenn das Ereignis $e1 eintritt, wird eine Erkennung erstellt. Die Regel enthält die Bedingung not, um bestimmte nicht schädliche Pfade auszuschließen. Sie können not-Bedingungen hinzufügen, um falsch positive Ergebnisse zu vermeiden.

rule suspicious_unusual_location_svchost_execution
{

 meta:
   author = "Google Cloud Security"
   description = "Windows 'svchost' executed from an unusual location"
   yara_version = "YL2.0"
   rule_version = "1.0"

 events:

   $e1.metadata.event_type = "PROCESS_LAUNCH"
   re.regex($e1.principal.process.command_line, `\bsvchost(\.exe)?\b`) nocase
   not re.regex($e1.principal.process.command_line, `\\Windows\\System32\\`) nocase

condition:

   $e1
}

Anmeldungen von verschiedenen Orten

Mit der folgenden Regel wird nach Nutzern gesucht, die sich in weniger als 5 Minuten in zwei oder mehr Städten bei Ihrem Unternehmen angemeldet haben:

rule DifferentCityLogin {
  meta:

  events:
    $udm.metadata.event_type = "USER_LOGIN"
    $udm.principal.user.userid = $user
    $udm.principal.location.city = $city

  match:
    $user over 5m

  condition:
    $udm and #city > 1
}

Übereinstimmungsvariable: $user

Ereignisvariable:$udm

Platzhaltervariable: $city und $user

Im Folgenden wird beschrieben, wie diese Regel funktioniert:

• Gruppiert Ereignisse nach Nutzername ($user) und gibt ihn ($user) zurück, wenn eine Übereinstimmung gefunden wird.
• Die Zeitspanne beträgt 5 Minuten. Das bedeutet, dass nur Ereignisse, die weniger als 5 Minuten auseinanderliegen, miteinander in Beziehung gesetzt werden.
• Es wird nach einer Ereignisgruppe ($udm) gesucht, deren Ereignistyp USER_LOGIN ist.
• Für diese Ereignisgruppe ruft die Regel die Nutzer-ID als $user und den Anmeldeort als $city. auf
• Gibt eine Übereinstimmung zurück, wenn die eindeutige Anzahl der city-Werte (gekennzeichnet mit #city) in der Ereignisgruppe ($udm) innerhalb des Zeitraums von 5 Minuten größer als 1 ist.

Schnelle Erstellung und Löschung von Nutzern

Mit der folgenden Regel wird nach Nutzern gesucht, die erstellt und dann innerhalb von 4 Stunden gelöscht wurden:

rule UserCreationThenDeletion {
  meta:

  events:
    $create.target.user.userid = $user
    $create.metadata.event_type = "USER_CREATION"

    $delete.target.user.userid = $user
    $delete.metadata.event_type = "USER_DELETION"

    $create.metadata.event_timestamp.seconds <=
       $delete.metadata.event_timestamp.seconds

  match:
    $user over 4h

  condition:
    $create and $delete
}

Ereignisvariablen:$create und $delete

Übereinstimmungsvariable: $user

Platzhaltervariable: –

Im Folgenden wird beschrieben, wie diese Regel funktioniert:

• Gruppiert Ereignisse nach Nutzername ($user) und gibt ihn ($user) zurück, wenn eine Übereinstimmung gefunden wird.
• Das Zeitfenster beträgt 4 Stunden. Das bedeutet, dass nur Ereignisse, die weniger als 4 Stunden auseinanderliegen, miteinander in Beziehung gesetzt werden.
• Sucht nach zwei Ereignisgruppen ($create und $delete, wobei $create #create >= 1 entspricht).
• $create entspricht USER_CREATION-Ereignissen und ruft die User-ID als $user auf.
• Mit $user werden die beiden Ereignisgruppen zusammengeführt.
• $delete entspricht USER_DELETION-Ereignissen und ruft die User-ID als $user auf. Bei dieser Regel wird nach einer Übereinstimmung gesucht, bei der die Nutzer-ID in den beiden Ereignisgruppen identisch ist.
• Mit dieser Regel wird nach Fällen gesucht, in denen das Ereignis von $delete später als das Ereignis von $create eintritt. Wenn ein Übereinstimmung gefunden wird, wird ein Treffer zurückgegeben.

Regel für einzelne Ereignisse

Regeln für einzelne Ereignisse beziehen sich auf ein einzelnes Ereignis. Eine einzelne Ereignisregel kann Folgendes sein:

• Alle Regeln ohne Abgleichbereich
• Regel mit einem match- und einem condition-Abschnitt, in dem nur nach einem Ereignis gesucht wird (z. B. „$e“, „#e > 0“, „#e >= 1“, „1 <= #e“, „0 < #e“).

Mit der folgenden Regel wird beispielsweise nach einem Nutzeranmeldeereignis gesucht und das erste Ereignis in den in Ihrem Google Security Operations-Konto gespeicherten Unternehmensdaten zurückgegeben:

rule SingleEventRule {
  meta:
    author = "[e-mail]"

  events:
    $e.metadata.event_type = "USER_LOGIN"

  condition:
    $e
}

Hier ist ein weiteres Beispiel für eine Regel für ein einzelnes Ereignis mit einem Abgleichbereich. Mit dieser Regel wird nach einem Nutzer gesucht, der sich mindestens einmal in weniger als 5 Minuten angemeldet hat. Es wird geprüft, ob ein Nutzeranmeldeereignis vorhanden ist.

rule SingleEventRule {
  meta:
    author = "[e-mail]"
    description = "windowed single event example rule"

  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $user

  match:
    $user over 5m

  condition:
    #e > 0
}

Hinweis: Regeln mit dem Abschnitt match und condition, die zusätzlich zur einfachen Existenz eines Ereignisses Ergebnisvariablen enthalten, werden als Multi-Ereignis-Regeln klassifiziert. In diesen Regeln hängt die Logik zur Erkennungsgenerierung von allen Ereignissen in einem Übereinstimmungsfenster (z. B. viele Ereignisse) ab, nicht von jedem Ereignis in einem Übereinstimmungsfenster (z. B. einem einzelnen Ereignis). Im folgenden Beispiel für solche Regeln werden dieselben Erkennungen generiert wie im ersten Beispiel für Regeln für mehrere Ereignisse im nächsten Abschnitt.

rule MultiEventRule{
  meta:
    author = "[e-mail]"
    description = "Rule with outcome condition and simple existence condition on one event variable"

  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $user

  match:
    $user over 10m

  outcome:
    $num_events_in_match_window = count($e.metadata.id)

  condition:
    #e > 0 and $num_events_in_match_window >= 10 // Could be rewritten as #e >= 10
}

Regel für mehrere Ereignisse

Mit mehreren Ereignisregeln können Sie viele Ereignisse in einem bestimmten Zeitraum gruppieren und versuchen, Korrelationen zwischen Ereignissen zu finden. Eine typische Regel für mehrere Ereignisse enthält Folgendes:

• Ein match-Abschnitt, der den Zeitraum angibt, über den Ereignisse gruppiert werden müssen.
• Ein condition-Abschnitt, der angibt, welche Bedingung die Erkennung und Prüfung auf das Vorhandensein mehrerer Ereignisse auslösen soll.

Die folgende Regel sucht beispielsweise nach einem Nutzer, der sich in weniger als 10 Minuten mindestens 10-mal angemeldet hat:

rule MultiEventRule {
  meta:
    author = "[e-mail]"

  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $user

  match:
    $user over 10m

  condition:
    #e >= 10
}

Einzelnes Ereignis innerhalb des IP-Adressbereichs

Das folgende Beispiel zeigt eine Einzelereignisregel, die nach einer Übereinstimmung zwischen zwei bestimmten Nutzern und einem bestimmten IP-Adressbereich sucht:

rule OrsAndNetworkRange {
  meta:
    author = "[e-mail]"

  events:
    // Checks CIDR ranges.
    net.ip_in_range_cidr($e.principal.ip, "203.0.113.0/24")

    // Detection when the hostname field matches either value using or.
    $e.principal.hostname = /pbateman/ or $e.principal.hostname = /sspade/

  condition:
    $e
}

Beispiel für eine beliebige und alle Regeln

Mit der folgenden Regel wird nach Anmeldeereignissen gesucht, bei denen innerhalb von 5 Minuten keine der Quell-IP-Adressen mit einer als sicher bekannten IP-Adresse übereinstimmt.

rule SuspiciousIPLogins {
  meta:
    author = "[e-mail]"

  events:
    $e.metadata.event_type = "USER_LOGIN"

    // Detects if all source IP addresses in an event do not match "100.97.16.0"
    // For example, if an event has source IP addresses
    // ["100.97.16.1", "100.97.16.2", "100.97.16.3"],
    // it will be detected since "100.97.16.1", "100.97.16.2",
    // and "100.97.16.3" all do not match "100.97.16.0".

    all $e.principal.ip != "100.97.16.0"

    // Assigns placeholder variable $ip to the $e.principal.ip repeated field.
    // There will be one detection per source IP address.
    // For example, if an event has source IP addresses
    // ["100.97.16.1", "100.97.16.2", "100.97.16.3"],
    // there will be one detection per address.

    $e.principal.ip = $ip

  match:
    $ip over 5m

  condition:
    $e
}

Reguläre Ausdrücke in einer Regel

Im folgenden Beispiel für einen regulären Ausdruck für YARA-L 2.0 wird nach Ereignissen mit E-Mails gesucht, die von der Domain altostrat.com empfangen wurden. Da nocase dem Vergleich der $host-Variablen regex und der regex-Funktion hinzugefügt wurde, wird bei beiden Vergleichen die Groß-/Kleinschreibung nicht berücksichtigt.

rule RegexRuleExample {
  meta:
    author = "[e-mail]"

  events:
    $e.principal.hostname = $host
    $host = /.*HoSt.*/ nocase
    re.regex($e.network.email.from, `.*altostrat\.com`) nocase

  match:
    $host over 10m

  condition:
    #e > 10
}

Beispiel für eine Regel mit gleitendem Fenster

Im folgenden Beispiel für ein YARA-L 2.0-Fenster mit Text wird nach dem Fehlen von firewall_2-Ereignissen nach firewall_1-Ereignissen gesucht. Das Schlüsselwort after wird verwendet mit die Pivot-Ereignisvariable $e1, um anzugeben, dass jeweils nur 10-Minuten-Zeitfenster firewall_1-Ereignis sollte beim Korrelieren von Ereignissen geprüft werden.

rule SlidingWindowRuleExample {
  meta:
    author = "[e-mail]"

  events:
    $e1.metadata.product_name = "firewall_1"
    $e1.principal.hostname = $host

    $e2.metadata.product_name = "firewall_2"
    $e2.principal.hostname = $host

  match:
    $host over 10m after $e1

  condition:
    $e1 and !$e2
}

Beispiel für den Ausschluss von Nullwerten

Die Rules Engine filtert implizit die Nullwerte für alle Platzhalter heraus, die im Bereich match verwendet werden. Weitere Informationen finden Sie unter Umgang mit Nullwerten im Abschnitt match. Dies kann deaktiviert werden, indem Sie die Option allow_zero_values als unter allow_zero_values beschrieben.

Bei anderen referenzierten Ereignisfeldern werden Nullwerte jedoch nicht ausgeschlossen, es sei denn, Sie geben solche Bedingungen ausdrücklich an.

rule ExcludeZeroValues {
  meta:
    author = "[e-mail]"

  events:
    $e1.metadata.event_type = "NETWORK_DNS"
    $e1.principal.hostname = $hostname

    // $e1.principal.user.userid may be empty string.
    $e1.principal.user.userid != "Guest"

    $e2.metadata.event_type = "NETWORK_HTTP"
    $e2.principal.hostname = $hostname

    // $e2.target.asset_id cannot be empty string as explicitly specified.
    $e2.target.asset_id != ""

  match:
    // $hostname cannot be empty string. The rule behaves as if the
    // predicate, `$hostname != ""` was added to the events section, because
    // `$hostname` is used in the match section.
    $hostname over 1h

  condition:
    $e1 and $e2
}

Beispiel für eine Regel mit einem outcome-Abschnitt

Sie können den optionalen Abschnitt outcome in der YARA-L 2.0-Regel hinzufügen, um zusätzliche Informationen zu jeder Erkennung zu extrahieren. Im Abschnitt „Bedingung“ können Sie auch Bedingungen für Ergebnisvariablen angeben. Im Abschnitt outcome einer Erkennungsregel können Sie Variablen für den Downstream-Verbrauch festlegen. Sie können beispielsweise einen Schweregrad anhand von Daten aus den analysierten Ereignissen festlegen.

Hier finden Sie weitere Informationen:

• Syntax des Ergebnisabschnitts
• Syntax von Ergebnisbedingungen
• Übersicht über den Bereich outcome

Multi-Event-Regel mit Abschnitt „Ergebnis“:

In der folgenden Regel werden zwei Ereignisse berücksichtigt, um den Wert von $hostname zu ermitteln. Wenn der Wert von $hostname über einen Zeitraum von 5 Minuten übereinstimmt, wird ein Schweregrad angewendet. Wenn Sie im Abschnitt match einen Zeitraum angeben, wird innerhalb des angegebenen Zeitraums überprüft.

rule OutcomeRuleMultiEvent {
    meta:
      author = "Google Cloud Security"
    events:
      $u.udm.principal.hostname = $hostname
      $asset_context.graph.entity.hostname = $hostname

      $severity = $asset_context.graph.entity.asset.vulnerabilities.severity

    match:
      $hostname over 5m

    outcome:
      $risk_score =
        max(
            100
          + if($hostname = "my-hostname", 100, 50)
          + if($severity = "HIGH", 10)
          + if($severity = "MEDIUM", 5)
          + if($severity = "LOW", 1)
        )

      $asset_id_list =
        array(
          if($u.principal.asset_id = "",
             "Empty asset id",
             $u.principal.asset_id
          )
        )

      $asset_id_distinct_list = array_distinct($u.principal.asset_id)

      $asset_id_count = count($u.principal.asset_id)

      $asset_id_distinct_count = count_distinct($u.principal.asset_id)

    condition:
      $u and $asset_context and $risk_score > 50 and not arrays.contains($asset_id_list, "id_1234")
}

rule OutcomeRuleMultiEvent {
    meta:
      author = "[e-mail]"
    events:
      $u.udm.principal.hostname = $hostname
      $asset_context.graph.entity.hostname = $hostname

      $severity = $asset_context.graph.entity.asset.vulnerabilities.severity

    match:
      $hostname over 5m

    outcome:
      $total_network_bytes = sum($u.network.sent_bytes) + sum($u.network.received_bytes)

      $risk_score = if(total_network_bytes > 1024, 100, 50) + 
        max(
          if($severity = "HIGH", 10)
          + if($severity = "MEDIUM", 5)
          + if($severity = "LOW", 1)
        )

      $asset_id_list =
        array(
          if($u.principal.asset_id = "",
             "Empty asset id",
             $u.principal.asset_id
          )
        )

      $asset_id_distinct_list = array_distinct($u.principal.asset_id)

      $asset_id_count = count($u.principal.asset_id)

      $asset_id_distinct_count = count_distinct($u.principal.asset_id)

    condition:
      $u and $asset_context and $risk_score > 50 and not arrays.contains($asset_id_list, "id_1234")
}

Regel für ein einzelnes Ereignis mit Ergebnisbereich:

rule OutcomeRuleSingleEvent {
    meta:
        author = "[e-mail]"
    events:
        $u.metadata.event_type = "FILE_COPY"
        $u.principal.file.size = $file_size
        $u.principal.hostname = $hostname

    outcome:
        $suspicious_host = $hostname
        $admin_severity = if($u.principal.userid in %admin_users, "SEVERE", "MODERATE")
        $severity_tag = if($file_size > 1024, $admin_severity, "LOW")

    condition:
        $u
}

Refaktorieren einer Ergebnisregel für mehrere Ereignisse in eine Ergebnisregel für ein einzelnes Ereignis

Sie können den Abschnitt outcome für beide Einzelereignisregeln (Regeln ohne match-Abschnitt) und Multi-Ereignis-Regeln (Regeln mit einem match-Abschnitt). Wenn Sie eine Regel mit mehreren Ereignissen erstellt haben, verwenden, können Sie diese Regeln optional refaktorieren, indem Sie match, um die Leistung zu verbessern. Da Ihre Regel keinen Abschnitt match mehr enthält, in dem eine Gruppierung angewendet wird, erhalten Sie möglicherweise mehr Erkennungen. Diese Refaktorierung ist nur bei denen eine Ereignisvariable verwendet wird (siehe Abbildung folgenden Beispiel.

Ergebnisregel für Mehrfachereignisse, die nur eine Ereignisvariable (eine ein guter Kandidat für eine Refaktorierung):

rule OutcomeMultiEventPreRefactor {
    meta:
      author = "[e-mail]"
      description = "Outcome refactor rule, before the refactor"

    events:
      $u.udm.principal.hostname = $hostname

    match:
      $hostname over 5m

    outcome:
      $risk_score = max(if($hostname = "my-hostname", 100, 50))

    condition:
      $u
}

Sie können die Regel umstrukturieren, indem Sie den Abschnitt match löschen. Beachten Sie, dass Sie muss auch das Aggregat im Abschnitt outcome entfernen, da die Regel nun für ein einzelnes Ereignis. Weitere Informationen zu Zusammenfassungen finden Sie unter Ergebniszusammenfassungen.

rule OutcomeSingleEventPostRefactor {
    meta:
      author = "[e-mail]"
      description = "Outcome refactor rule, after the refactor"

    events:
      $u.udm.principal.hostname = $hostname

    // We deleted the match section.

    outcome:
      // We removed the max() aggregate.
      $risk_score = if($hostname = "my-hostname", 100, 50)

    condition:
      $u
}

Beispiel für Regel von Funktion zu Platzhalter

Sie können dem Ergebnis eines Funktionsaufrufs eine Platzhaltervariable zuweisen und die Platzhaltervariable in anderen Abschnitten der Regel verwenden, wie z. B. Bereich „match“, Bereich „outcome“ oder Bereich „condition“. Sehen Sie sich folgendes Beispiel an:

rule FunctionToPlaceholderRule {
    meta:
      author = "[e-mail]"
      description = "Rule that uses function to placeholder assignments"

    events:
        $u.metadata.event_type = "EMAIL_TRANSACTION"

        // Use function-placeholder assignment to extract the
        // address from an email.
        // [e-mail] -> address
        $email_to_address_only = re.capture($u.network.email.from , "(.*)@")

        // Use function-placeholder assignment to normalize an email:
        // uid@??? -> [e-mail]
        $email_from_normalized = strings.concat(
            re.capture($u.network.email.from , "(.*)@"),
            "@company.com"
        )

        // Use function-placeholder assignment to get the day of the week of the event.
        // 1 = Sunday, 7 = Saturday.
        $dayofweek = timestamp.get_day_of_week($u.metadata.event_timestamp.seconds)

    match:
        // Use placeholder (from function-placeholder assignment) in match section.
        // Group by the normalized from email, and expose it in the detection.
        $email_from_normalized over 5m

    outcome:
        // Use placeholder (from function-placeholder assignment) in outcome section.
        // Assign more risk if the event happened on weekend.
        $risk_score = max(
            if($dayofweek = 1, 10, 0) +
            if($dayofweek = 7, 10, 0)
        )

    condition:
        // Use placeholder (from function-placeholder assignment) in condition section.
        // Match if an email was sent to multiple addresses.
        #email_to_address_only > 1
}

Beispielregel für bedingte Ergebnisse

Im Abschnitt condition können Sie Ergebnisvariablen verwenden, die im Abschnitt outcome definiert wurden. Das folgende Beispiel zeigt, wie nach Risikobewertungen, um Rauschen in Erkennungen mithilfe von Ergebnisbedingungen zu reduzieren.

rule OutcomeConditionalRule {
    meta:
        author = "[e-mail]"
        description = "Rule that uses outcome conditionals"

    events:
        $u.metadata.event_type = "FILE_COPY"
        $u.principal.file.size = $file_size
        $u.principal.hostname = $hostname

        // 1 = Sunday, 7 = Saturday.
        $dayofweek = timestamp.get_day_of_week($u.metadata.collected_timestamp.seconds)

    outcome:
        $risk_score =
            if($file_size > 500*1024*1024, 2) + // Files 500MB are moderately risky
            if($file_size > 1024*1024*1024, 3) + // Files over 1G get assigned extra risk
            if($dayofweek=1 or $dayofweek=7, 4) + // Events from the weekend are suspicious
            if($hostname = /highly-privileged/, 5) // Check for files from highly privileged devices

    condition:
        $u and $risk_score >= 10
}