Parser-Referenz

Important

Lakewatch befindet sich in der Beta-Phase. Arbeitsbereichsadministratoren können den Zugriff auf dieses Feature über die Vorschauseite steuern. Siehe Verwalten von Vorschauen auf Arbeitsbereichsebene.

Ein Parser ist ein YAML-Dokument, das die Ausgabespalten einer Sicherheitsprotokollquelle beschreibt. Ein Parser wird versioniert und in einem Ordner in Ihrer Lakewatch-Umgebung gespeichert. Das Bearbeiten eines Parsers fügt eine neue, unveränderliche Version hinzu, sodass eine Datenquelle, die eine Version anpinnt, von späteren Bearbeitungen nicht beeinflusst wird. Diese Seite beschreibt die Parser-Syntax, die Lakewatch akzeptiert.

Dokumentstruktur

description: Product audit events # what this log source is
fields:
  - name: event_name
    type: STRING
    required: true
    validate:
      in: ['sale', 'buy']
  - name: source_ip
    type: STRING
    observables: [ip]
  - name: actor
    type: VARIANT
    fields:
      - name: id
        type: STRING
        observables: [actor_id]
time:
  coalesce:
    - path: published
      time_formats: ['#rfc3339']

Du kannst es im YAML wie hier gezeigt angeben description oder es in der Benutzeroberfläche einstellen, wenn du den Parser erstellst (empfohlen).

Ereigniszeit

Jeder Parser erzeugt eine Spalte time : den Ereignis-Zeitstempel, auf dem Lakewatch clustert. Sie müssen es mit einem oberen Block time definieren und nicht mit einem Feld in fields. Ein benutzerdefinierter Parser ohne solchen wird abgelehnt. Da Lakewatch die Spalte time für jeden Parser als einen TIMESTAMPerstellt, setzt man nicht sein name, type, oder required. Füge kein Feld hinzu time : fieldsDer Name ist für die Spalte reserviert, die der oberste Block time erzeugt, und ein Parser, der ihn als Feld deklariert, wird abgelehnt.

Der oberste Block time nimmt eine coalesce Liste: eine priorisierte Liste von Quellen, die Lakewatch der Reihe nach auswertet, wobei der erste wertige Wert als Zeitstempel verwendet wird. Wenn keine Quelle einen Zeitstempel liefert, fällt Lakewatch auf die Aufnahmezeit zurück. Jede Quelle ist eine der folgenden:

  • Pfad: Lesen Sie den Wert von einem Quellstandort aus:

    time:
      coalesce:
        - path: published
          time_formats: ['#rfc3339']
    
  • Pfad mit regulärem Ausdruck: Extrahieren Sie den Wert aus einem Quellstandort mit einem Regex:

    time:
      coalesce:
        - path: raw_message
          regexp: '<pattern>'
          match_group_index: 1 # which capture group holds the value; defaults to 1
          time_formats: ['#unix']
    

time_formats verwendet dasselbe Format wie Sets und Muster wie ein TIMESTAMP Feld. Siehe Zeitstempel. Im Gegensatz zu einem Feld verwendet eine time Quelle mit time_formats nur die aufgeführten Formate, ohne #extended Fallback. Ein Wert, der keinem von ihnen entspricht, lässt sich nicht aufschlüsseln, und Lakewatch geht zur nächsten Quelle über.

Weil time es kein Fachgebiet ist, wird es nicht in der Klassifikation verwendet. Um zu verlangen, dass das Quell-Ereignis-Zeitfeld vorhanden ist, damit ein Ereignis übereinstimmt, fügen Sie es als Feld required in fieldshinzu.

Feldattribute

Attribute Gilt für: Description
name Alle Felder Name der Ausgabespalte. Auch der Standard-Quellschlüssel, sofern path er nicht gesetzt ist.
type Alle Felder Ausgabe-Spaltentyp. Siehe Unterstützte Typen.
required Alle Felder Wenn true, muss das Feld vorhanden sein, damit ein Ereignis diesem Parser entspricht. Wird standardmäßig auf false festgelegt.
path Felder auf oberster Ebene Quelle, um den Wert zu lesen, wenn er von nameabweicht, wie zum Beispiel published oder actor.id.
comment Alle Felder Beschreibung des Feldes, aufgetaucht, um dir beim Schreiben von Erkennungsregeln zu helfen.
time_formats TIMESTAMP-Typen Liste von Formaten, mit denen der Zeitstempel analysiert werden kann. Siehe Zeitstempel.
validate STRING Ein einzelner Validator. Siehe Validatoren.
observables STRING Eine oder mehrere beobachtbare Typen zu extrahieren. Siehe Observables.
scan_for_observables VARIANT Schlüsselabgleichsregeln zur Extraktion von Observablen aus verschachtelten Inhalten. Siehe Scannen für Observablen.
fields VARIANT, STRUCT Verschachtelte Felddefinitionen. A STRUCT erfordert mindestens ein Mitglied.
copy_event Oberste Ebene VARIANT Setzen Sie ein, whole um das gesamte Ereignis an das Feld zu binden. Kann nicht mit path kombiniert werden.
element ARRAY Die Elementdefinition des Arrays.

Unterstützte Typen

STRING, , (), (), (INTEGER), INT (LONG), BIGINT (REAL), DOUBLEFLOAT , DECIMAL(p,s), , TIMESTAMPTIMESTAMP_LTZ, , TIMESTAMP_NTZ, DATESTRUCTVARIANTBINARYund .ARRAYSHORTSMALLINTBYTETINYINTBOOLEAN

Nur die oben genannten Typen werden unterstützt. Um verschachtelte Objekte zu modellieren, verwenden VARIANT Sie mit innerem fields. A VARIANT toleriert zusätzliche, nicht deklarierte Felder, ohne den Parser zu unterbrechen.

Wählen Sie zwischen STRUCT und VARIANT

STRUCT und VARIANT beide modellieren verschachtelte Daten, gehen aber entgegengesetzte Kompromisse ein. A gibt die Form vorne an: Du listest STRUCT ihre Mitglieder und ihre Typen auf, und die geanalyste Spalte enthält genau das, was du deklarierst. A VARIANT hält den rohen, halbstrukturierten Wert ganz, und man liest ihn beim Abfragezeitpunkt per Pfad ein, zum Beispiel mit try_variant_get. Du kannst weiterhin unter einem VARIANTdeklarierenfields, aber das hängt nur Validierung und Observables an diese Pfade an. Der Rest des Wertes wird nicht verliert.

Verwenden STRUCT Sie, wenn Sie die Form kennen und einen stabilen, getippten Vertrag möchten:

  • Die Form existiert im Parser-Spec, daher wird sie versioniert und überprüft. Abfragen, Erkennungen und Dashboards lesen jedes Mitglied als bekannten Typ und brechen nicht aus, wenn sich die Quelldaten verschieben.
  • Lesungen sind günstiger. A STRUCT ist eine reelle typisierte Spalte, auf die man mit Punktnotation zugreift und die Spark beschneiden kann, während a VARIANT bei jedem Lesen entschlüsselt wird.
  • Der Preis ist die Starrheit: Alles, was du nicht deklarierst, wird weggelassen, und du musst den Parser aktualisieren, wenn sich die Form ändert.

Verwenden Sie, VARIANT wenn die Form unbekannt, sich entwickeln oder zu groß ist, um Feld für Feld zu modellieren:

  • Es hält Schema-Änderungen von selbst im Schritt. Quellen wie AWS CloudTrail und Okta fügen Felder ohne Parseränderung hinzu.
  • Es verarbeitet gemischte oder widersprüchliche Formen, wie einen Pfad, der in einem Ereignis ein Objekt und in einem anderen ein String ist, den ein einzelner STRUCT Typ nicht darstellen kann.
  • Es bewahrt die ursprüngliche Nutzlast für spätere Wiederverarbeitung auf, sodass du zuerst Daten landen und sie später modellieren kannst.
  • Es skaliert auf Nutzlasten mit Hunderten von Feldern, ohne jedes einzelne zu deklarieren.
  • Der Nachteil ist, dass man beim Ingest keine Typisierung oder Validierung erhält und dafür bezahlt, Felder bei jeder Abfrage zu extrahieren. Ein häufiges Muster besteht darin, die wenigen Felder, die Sie am häufigsten abfragen, in getippte Felder zu befördern.

Zeitstempel

Ein Feld wird mit den in time_formatsaufgeführten TIMESTAMP Formaten analysiert, in der Reihenfolge ausprobiert, mit parse_timestamp. Jeder Eintrag ist entweder ein vordefiniertes Format-Schlüsselwort oder ein wörtliches Spark-Datetime-Muster:

Eingabe Dies bedeutet
#rfc3339 Die RFC 3339-Familie.
#iso8601, #common, #extended Andere vordefinierte Schlüsselwörter im Format.
#unix Ein numerischer Unix-Epochen-Zeitstempel in Sekunden, Mikrosekunden oder Nanosekunden. Millisekundenwerte werden nicht erkannt.
MM/dd/yyyy hh:mm:ss a Ein buchstäbliches Muster.

Wenn kein angegebenes Format übereinstimmt, fällt ein TIMESTAMP Feld auf #extended, sodass eine kürzere time_formats Liste das Feld nicht strikter macht. Die aufgeführten Formate werden vor dem Fallback ausprobiert, also listen Sie die Formate auf, die das Protokoll tatsächlich verwendet.

Validatoren

Ein Validator stellt eine Bedingung auf ein STRING Feld fest. Verwenden Sie genau eines der folgenden Maßnahmen:

Validierungssteuerelement Wahr, wenn
in: [...] Der Wert ist einer der aufgeführten Zeichenketten.
not_in: [...] Der Wert ist nicht einer der aufgeführten Zeichenketten.
contains_any: [...] Der Wert enthält mindestens eine aufgeführte Teilzeichenkette.
contains_none: [...] Der Wert enthält keine der aufgeführten Teilzeichenketten.

Observables

Das Markieren eines Feldes mit observables entzieht seinen Wert in die gemeinsame lw_observables Spalte zur Bedrohungsjagd. Jeder Observable-Typ erfasst eine bestimmte Art von Wert und füllt ein oder mehrere Felder in lw_observables:

Observable Erfassung Besiedelt in lw_observables
ip IPv4- oder IPv6-Adressen ip_addresses
domain Domänennamen hostnames
hostname Hostnamen oder IP-Adressen, wenn der Wert eine IP ist hostnames, ip_addresses
url Der Host einer URL (ein Hostname oder IP) hostnames, ip_addresses
hash MD5-, SHA-1- und SHA-256-Hashes hashes
aws_arn Ein AWS ARN sowie die Konto-ID, Instanz-ID, E-Mail und Benutzername, die es enthält account_ids, resource_ids, emails, usernames, , device_ids
aws_account_id Eine 12-stellige AWS-Konto-ID account_ids
aws_instance_id Eine EC2-Instanz-ID device_ids
trace_id Eine Anfrage- oder Trace-ID request_trace_ids
username Ein Benutzername usernames
email Eine E-Mail-Adresse und der Benutzername-Teil davon emails, usernames
net_addr Der Host eines Wertes host:port (ein Hostname oder IP) hostnames, ip_addresses
mac Eine MAC-Adresse mac_addresses
actor_id Eine Schauspieler-ID actor_ids
serial_number Eine Seriennummer serial_numbers
cve Eine CVE-Kennung, wie zum Beispiel CVE-2024-1234 cves
resource_tag Ein Ressourcen-Tag resource_tags
mitre_attack_technique Eine MITRE ATT&CK-Technik-ID, wie zum Beispiel T1078 mitre_attack_technique_ids

lw_observables ist eine von Lakewatch verwaltete STRUCT Spalte, die zu jeder parsierten Tabelle hinzugefügt wird, mit einem Feld ARRAY<STRING> für jede in der vorhergehenden Tabelle aufgeführte Ausgabe, wie z. B. ip_addresses und hostnames. Mehrere beobachtbare Typen füllen dasselbe Feld. Lakewatch normalisiert, dedupliziert und sortiert die Werte jedes Feldes und überspringt ungültige Werte. Ein Feld ohne Werte ist []. Die Spalte ist bei jedem Ereignis vorhanden, selbst wenn der Parser keine Observablen deklariert.

Scanne nach Observablen

Verwenden Sie das optionale scan_for_observables Attribut auf einem VARIANT Feld, um Observablen aus Schlüsseln überall im verschachtelten Wert zu extrahieren, einschließlich Inhalten, die nicht in deklariert sind fields. Das Attribut ist bei anderen Feldtypen nicht gültig.

Map jeden Observable-Typ, den du extrahieren möchtest, auf ein explizites Matcher-Objekt. Ein Matcher kann , ends_with, und containsverwendenequals. Jeder Schlüssel akzeptiert ein Array von Schlüsselnamen-Zeichenketten. Das Schlüsselabgleich ist nicht großschreibungssensitiv.

- name: request
  type: VARIANT
  scan_for_observables:
    ip:
      equals: [sourceIp, destinationIp]
      ends_with: [IpAddress]
      contains: [clientIp]
    email:
      equals: [principalEmail]
      ends_with: [Email]

Lakewatch untersucht rekursiv Schlüssel im Wert VARIANT . Wenn ein Schlüssel mit einer konfigurierten Regel übereinstimmt, validiert Lakewatch den Kandidatenwert für diesen observablen Typ und fügt gültige Werte dem entsprechenden Feld in lw_observableshinzu. Das Matching verwendet nur die Regeln im Parser. Lakewatch fügt keine eingebauten Matching-Regeln hinzu.

Verschachtelte und Array-Felder

Verwenden VARIANT Sie mit fields für verschachtelte Objekte und ARRAY mit für element Listen. Ein Element ist wie ein Körper definiert, jedoch ohne name, required, oder path:

- name: resources
  type: ARRAY
  path: resources
  element:
    type: VARIANT
    fields:
      - name: accountId
        type: STRING
        observables: [aws_account_id]
- name: source_ips
  type: ARRAY
  path: sourceIps
  element:
    type: STRING
    observables: [ip]

Klassifizierung

Eine Datenquelle kann mehrere Parser haben, und jeder Parser schreibt in seine eigene geparste Tabelle. Lakewatch vergleicht jedes eingehende Event mit den Parsern in der Reihenfolge, in der es erklärt wird. Das Ereignis landet im ersten parser, das es abgibt, sodass jedes Ereignis auf höchstens eine geparste Tabelle geschrieben wird. Ein Ereignis stimmt überein, wenn die erforderlichen Felder vorhanden sind, seine typisierten Felder in die deklarierten Typen konvertieren und alle Validatoren bestehen. Unmatched Events werden nicht in eine geparste Tabelle geschrieben, und die Pipeline scheitert nicht. Die Datenquelle zählt sie unter Unmatched-Zeilen.

Die Parserdefinitionen bestimmen, welche Ereignisse jeder Parser erhält, daher konfigurieren Sie keine Filter auf der Datenquelle. Um einen Ereignistyp an einen Parser weiterzuleiten, markieren Sie die Felder, die diesen Ereignistyp identifizieren, als required im Parser. Wenn andere Ereignistypen diese Felder teilen, fügen Sie einen Validator hinzu, der sie voneinander unterscheidet. Da der erste übereinstimmende Parser gewinnt, bestellen Sie spezifischere Parser vor allgemeineren in der Datenquelle.

Eingebaute und benutzerdefinierte Parser

Lakewatch bietet integrierte Parser für gängige Sicherheitsprotokollquellen, und Sie können benutzerdefinierte Parser für Quellen erstellen, die nicht abgedeckt sind oder die Sie anpassen möchten. Beide verwenden das oben beschriebene YAML-Format.

Entdecken und inspizieren Sie eingebaute Parser

Wenn Sie Parser an eine Datenquelle anhängen, können Sie die verfügbaren integrierten Parser durchsuchen und diejenigen auswählen, die Ihrer Quelle entsprechen. Prüfe einen eingebauten Parser, um die erzeugten Spalten (Felder, Typen, Validatoren und Observables) zu sehen, bevor du ihn anhängst, damit du bestätigen kannst, dass er mit den Ereignissen übereinstimmt, die du einführst.

Eingebaute Parser sind schreibgeschützt. Um einen zu individualisieren, verwenden Sie die Aktion Klon im Parser, um einen editierbaren, benutzerdefinierten Parser aus der Definition des eingebauten Parsers zu erstellen, dann passen und speichern Sie ihn. Klonen ist ein UI-Komfort, der die Definition in einen neuen benutzerdefinierten Parser (Version 1) kopiert. Es handelt sich nicht um eine serverseitige Klonoperation, und der eingebaute Parser selbst ist unverändert.

Erstellen Sie einen benutzerdefinierten Parser

Um einen benutzerdefinierten Parser zu erstellen, stellen Sie ein YAML-Dokument im oben beschriebenen Format bereit. Lakewatch erstellt den Parser in deiner aktuellen Umgebung. Das Erstellen eines Parsers speichert die Definition als Version 1 und verzeichnet dich als Besitzer des Parsers.

Definieren Sie Ihre Felder sorgfältig, denn ein Ereignis, das ohne Parser übereinstimmt, wird nicht in eine geparste Tabelle geschrieben. Ein Ereignis, dessen Werte nicht in die deklarierten Typen konvertiert werden oder das einen Validator versagt, passt nicht zum Parser.

Versionssteuerung und Löschung

Das Bearbeiten eines Parsers fügt eine neue unveränderliche Version hinzu. Bestehende Versionen ändern sich nicht, und Versionsnummern werden nicht wiederverwendet. Der Server weist jeder neuen Version die nächste Zahl in der Reihenfolge zu. Nur der Eigentümer des Parsers oder ein Benutzer, der MANAGE im Ordner des Parsers liegt, kann eine Version hinzufügen.

Eine Datenquelle pinnt eine bestimmte Version, sodass sie diese Version weiterhin verwendet, bis du sie explizit änderst. Siehe Version eines Parsers ändern.

Du kannst einen ganzen benutzerdefinierten Parser löschen, der alle Versionen entfernt. Du kannst eine einzelne Version nicht löschen. Nur der Eigentümer des Parsers oder ein Benutzer, der MANAGE im Ordner des Parsers ist, kann einen Parser löschen, und das Löschen wird blockiert, solange jede Datenquelle auf eine beliebige Version des Parsers verweist. Trennen Sie vor dem Löschen den Parser von jeder Datenquelle, die ihn verwendet (ändern Sie jede Datenquelle auf einen anderen Parser und speichern Sie die Änderung), und löschen Sie dann den Parser.

Limits

Ein Parserdokument hat höchstens 256 KiB, und ein Parser kann höchstens 512 Felder deklarieren. Die Zählung umfasst verschachtelte VARIANT sowie STRUCT Mitglieder und ARRAY Elemente.

Feldnamen auf oberster Ebene müssen unabhängig vom Großformat eindeutig sein und dürfen die reservierten Namen time, lw_id, lw_meta, oder lw_observablesnicht verwenden. Mitgliedsnamen in a STRUCT müssen unabhängig vom Großfall ebenfalls eindeutig sein.