Parser preprocesoru

parser preprocessor umožňuje předzpracovat vstupní událost pomocí imperativního kódu, např. Python, Cython, C atd.

Příklad

---
define:
  název: Demo vestavěného preprocesoru Syslog
  typ: parser/preprocesor
  tenant: (nepovinné)
  count: CEF.cnt # (nepovinné)

function: lmiopar.preprocessor.Syslog_RFC5424

tenant určuje atribut tenanta, který má být načten a předán do context['tenant'] pro další distribuci analyzovaných a nerozparsovaných událostí do specifických tenantů. indexům/úložištím v LogMan.io Dispatcher

count určuje atribut count s počtem událostí, které mají být načteny a předány do context['count'].

Vestavěné preprocesory

Modul lmiopar.preprocessor obsahuje následující běžně používané preprocesory. Tyto preprocesory jsou optimalizovány pro nasazení s vysokým výkonem.

Vestavěný preprocesor Syslog RFC5425

funkce: lmiopar.preprocessor.Syslog_RFC5424

Toto je preprocesor pro protokol Syslog (nový) podle RFC5425.

Vstupem pro tento preprocesor je platná položka protokolu Syslog, např:

<165>1 2003-10-11T22:14:15.003Z mymachine.example.com evntslog 10 ID47 [exampleSDID@32473 iut="3" eventSource="Application" eventID="1011"] Záznam protokolu událostí aplikace.

Výstupem je, část zprávy protokolu v události a analyzované prvky v context.syslog_rfc5424.

událost: Záznam v protokolu událostí aplikace.

context:
  Syslog_RFC5424:
    PRI: 165
    FACILITY: 20
    PRIORITA: 5
    VERZE: 1
    TIMESTAMP: 2003-10-11T22:14:15.003Z
    HOSTNAME: mymachine.example.com
    APP_NAME: evntslog
    PROCID: 10
    MSGID: ID47
    STRUCTURED_DATA:
      exampleSDID@32473:
        iut: 3
        eventSource: Aplikace:
        eventID: 1011
      ...

Vestavěný preprocesor Syslog RFC3164

funkce: lmiopar.preprocessor.Syslog_RFC3164

Toto je preprocesor pro BSD syslog protokol (starý) podle RFC3164.

Preprocesor Syslog RFC3164 lze konfigurovat v sekci define:

define:
  type: parser/preprocessor
  year: 1999
  časové pásmo: Evropa/Praha

year určuje číselnou reprezentaci roku, která bude použita na časovou značku protokolů. Můžete také zadat smart (výchozí) pro pokročilý výběr roku na základě měsíce.

timezone určuje časové pásmo protokolů, výchozí je UTC.

Vstupem pro tento preprocesor je platný záznam Syslogu, např:

<34>Oct 11 22:14:15 mymachine su[10]: 'su root' selhalo pro lonvick na /dev/pts/8

Výstupem je, zpráva část logu v události a rozebrané prvky v context.syslog_rfc3164.

událost: "``su root' selhalo pro lonvick na /dev/pts/8"

context:
  Syslog_RFC3164:
    PRI: 34
    PRIORITA: 2
    FACILITY: 4
    TIMESTAMP: '2003-10-11T22:14:15.003Z'
    HOSTNAME: mymachine
    TAG: su
    PID: 10

TAG a PID jsou nepovinné parametry.

Vestavěný preprocesor CEF

funkce: lmiopar.preprocessor.CEF

Toto je preprocesor pro CEF neboli Common Event Format.

define:
  typ: parser/preprocesor
  year: 1999
  časové pásmo: Evropa/Praha

year určuje číselnou reprezentaci roku, která bude použita na časovou značku protokolů. Můžete také zadat smart (výchozí) pro pokročilý výběr roku na základě měsíce.

timezone určuje časové pásmo protokolů, výchozí je UTC.

Vstupem pro tento preprocesor je platná položka CEF, např:

CEF:0|Výrobce|Produkt|Verze|foobar:1:2|Neúspěšné heslo|Medium| eventId=1234 app=ssh categorySignificance=/Informational/Warning categoryBehavior=/Authentication/Verify

Výstupem je část protokolu s hlášením v události a analyzované prvky v context.CEF:

context:
  CEF:
    Verze: 0
    DeviceVendor: Vendor
    DeviceProduct: Product
    DeviceVersion: Verze:
    DeviceEventClassID: "foobar:1:2
    Name: Název: Failed password
    Závažnost: Heslo: Střední

    EventId: '1234'
    aplikace: ssh
    categorySignificance: /Informational/Warning
    categoryBehavior: /Authentication/Verify

CEF může obsahovat také hlavičku Syslog. To je podporováno řetězením příslušného preprocesoru Syslog s preprocesorem CEF. Podrobnosti naleznete v kapitole o řetězení preprocesorů.

Vestavěný preprocesor pro formáty protokolu serveru Apache HTTP

Existují vysoce výkonné preprocesory pro běžné přístupové protokoly serveru Apache HTTP.

function: lmiopar.preprocessor.Apache_Common_Log_Format

Toto je preprocesor pro Apache Common Log Format.

funkce: lmiopar.preprocessor.Apache_Combined_Log_Format

Toto je preprocesor pro kombinovaný formát protokolu Apache.

Příklad společného protokolu Apache

Vstup:

127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326

Výstup:

kontext:
  Apache_Access_Log:
    HOST: '127.0.0.1'
    IDENT: '-'
    USERID: "frank
    TIMESTAMP: '2000-10-10T20:55:36.000Z'
    METODA: "GET
    RESOURCE: "/apache_pb.gif
    PROTOKOL: "HTTP/1.0
    STATUS_CODE: 200
    DOWNLOAD_SIZE: 2326

Příklad kombinovaného protokolu Apache

Vstupní data:

127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 "http://www.example.com/start.html" "Mozilla/4.08 [cs] (Win98; I ;Nav)"

Výstup:

kontext:
  Apache_Access_Log:
    HOST: '127.0.0.1'
    IDENT: '-'
    USERID: "frank
    TIMESTAMP: '2000-10-10T20:55:36.000Z'
    METODA: "GET
    RESOURCE: "/apache_pb.gif
    PROTOKOL: "HTTP/1.0
    STATUS_CODE: 200
    DOWNLOAD_SIZE: 2326
    REFERE": http://www.example.com/start.html
    USER_AGENT: Mozilla/4.08 [cs] (Win98; I ;Nav)

Vestavěný preprocesor Microsoft ULS

funkce: lmiopar.preprocessor.Microsoft_ULS

Toto je preprocesor pro Microsoft_ULS podle Microsoft Docs.

Pro protokoly Microsoft SharePoint ULS, které neobsahují název serveru ani korelační pole, je k dispozici speciální preprocesor:

lmiopar.preprocessor.Microsoft_ULS_Sharepoint`.

Preprocesor Microsoft SharePoint ULS lze nakonfigurovat v sekci define:

define:
  type: parser/preprocessor
  year: 1999
  časové pásmo: Evropa/Praha

year určuje číselnou reprezentaci roku, která bude použita na časovou značku protokolů. Můžete také zadat smart (výchozí) pro pokročilý výběr roku na základě měsíce.

timezone určuje časové pásmo protokolů, výchozí je UTC.

Vstupem pro tento preprocesor je platný záznam Microsoft ULS Sharepoint, např:

04/28/2021 12:31:57.69 mssdmn.exe (0x38E0) 0x4D10 SharePoint Server Search Connectors:SharePoint dvt6 High SetSTSErrorInfo ErrorMessage = Chyba z webu SharePoint: WebExceptionStatus: Podkladové spojení bylo uzavřeno: hr = 90141214 [sts3util.cxx:6994] search\native\gather\protocols\sts3\sts3util.cxx 3aeca97a-a9db-4010-970e-fe01483bfd4f

Výstupem je část zprávy protokolu v události a analyzované prvky v context.Microsoft_ULS.

událost: Zpráva obsažená v protokolu.

context:
  Microsoft_ULS:
    ČASOVÉ RAZÍTKO 1619613117.69
    PROCES: mssdmn.exe (0x38E0)
    THREAD: 0x4D10
    PRODUCT: SharePoint Server Search
    KATEGORIE: Konektory:SharePoint
    EVENTID: dvt6
    ÚROVEŇ: Vysoká

Query String preprocesor

funkce: lmiopar.preprocessor.Query_String

Toto je preprocesor pro řetězec dotazu (key=value&key=value...), jako jsou metainformace z LogMan.io Collector.

Příklad vstupu:

file_name=log.log&search=true

Výstupem je část logu v události a analyzované prvky v context.QUERY_STRING.

událost: Zpráva obsažená v protokolu.

context:
  QUERY_STRING:
    Název_souboru: log.log
    search: true

JSON vestavěný preprocesor

funkce: lmiopar.preprocessor.JSON

Jedná se o preprocesor pro formát JSON. Očekává vstup v binárním nebo textovém formátu, výstupní slovník je umístěn v události.

Vstupem pro tento preprocesor je tedy platný zápis JSON.

Vestavěný preprocesor XML

function: lmiopar.preprocessor.XML

Jedná se o preprocesor pro formát XML. Očekává vstup v binárním nebo textovém formátu, výstupní slovník je umístěn v události.

Vstupem pro tento preprocesor je tedy platný záznam XML, např:

<?xml version="1.0" encoding="UTF-8"?>
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event">
   <System>
      <Provider Name="Schannel" Guid="{1f678132-5938-4686-9fdc-c8ff68f15c85}" />
      <EventID>36884</EventID>
      <Version>0</Version>
      <Level>2</Level>
      <Task>0</Task>
      <Opcode>0</Opcode>
      <Keywords>0x8000000000000000</Keywords>
      <TimeCreated SystemTime="2020-06-26T07:12:01.331577900Z" />
      <EventRecordID>30286</EventRecordID>
      <Correlation ActivityID="{8e20742a-4b06-0002-c274-208e064bd601}" />
      <Execution ProcessID="788" ThreadID="948" />
      <Channel>Systém</Channel>
      <Computer>XX</Computer>
      <Security UserID="S-1-5-21-1627182167-2524376360-74743131-1001" />
   </System>
   <UserData>
      <EventXML xmlns="LSA_NS">
         <Name>localhost</Name>
      </EventXML>
   </UserData>
   <RenderingInfo Culture="en-US">
      <Message>Certifikát přijatý ze vzdáleného serveru neobsahuje očekávaný název. Proto není možné určit, zda se připojujeme ke správnému serveru. Název serveru, který jsme očekávali, je localhost. Požadavek na připojení TLS se nezdařil. Přiložené údaje obsahují certifikát serveru.</Message>
      <Level>Chyba</Level>
      <Task />
      <Opcode>Informace</Opcode>
      <Channel>Systém</Channel>
      <Provider />
      <Keywords />
   </RenderingInfo>
</Event>

Výstup preprocesoru v event:

{
  "System.EventID": "36884",
  "System.Version": "0",
  "System.Level": "2",
  "System.Task": "0",
  "System.Opcode": "0",
  "System.Keywords": "0x8000000000000000",
  "System.EventRecordID": "30286",
  "System.Channel": "System",
  "System.Computer": "XX",
  "UserData.EventXML.Name": "localhost",
  "RenderingInfo.Message": "Certifikát přijatý ze vzdáleného serveru neobsahuje očekávaný název. Není proto možné určit, zda se připojujeme ke správnému serveru. Název serveru, který jsme očekávali, je localhost. Požadavek na připojení TLS se nezdařil. Přiložené údaje obsahují certifikát serveru.",
  "RenderingInfo.Level": "Error",
  "RenderingInfo.Opcode": "Info",
  "RenderingInfo.Channel": "System"
}

Vestavěný preprocesor CSV

funkce: lmiopar.preprocessor.CSV

Toto je preprocesor pro formát CSV. Očekává vstup v binárním nebo textovém formátu, výstupní slovník je umístěn v události.

Vstupem pro tento preprocesor je tedy platný záznam CSV, např:

user,last_name\njack,black\njohn,doe

Výstup preprocesoru v context["CSV"]:

{
  "lines": [
    {"user": "jack", "last_name": "black"},
    {"user": "john", "last_name": "doe"}
  ]
}

Parametry

V sekci define preprocesoru CSV, lze nastavit následující parametry pro čtení CSV:

oddělovač: (výchozí: ",")
escapechar: únikový znak
doublequote: povolí dvojité uvozovky (výchozí: true)
lineterminator: znak pro ukončení řádku, buď \n, nebo \r (výchozí je oddělovač řádků operačního systému)
quotechar: výchozí znak uvozovek (výchozí: "\"")
quoting: typ uvozovek
skipinitialspace: vynechá počáteční mezeru (výchozí: false)
strict: přísný režim (výchozí: false)

Vlastní preprocesory

Vlastní preprocesory lze volat z parseru, příslušný kód musí být přístupný mikroslužbě parseru běžným způsobem importu Pythonu.

---
define:
  název: Ukázka vlastního preprocesoru Pythonu.
  typ: parser/preprocesor

funkce: mypreprocessors.preprocessor

mypreprocessors je modul odpovídající složce __init__.py, který obsahuje funkci preprocessor().

Parser určuje funkci, která se má zavolat. Používá se notace Pythonu a automaticky se provede import modulu.

Signatura funkce:

def preprocessor(context, event):
  ...
  return event

Preprocesor může (1) modifikovat událost (!EVENT) a/nebo (2) modifikovat kontext (!CONTEXT).

Výstup funkce preprocessor bude předán následnému parseru. Preprocesorový parser nevytváří přímo parsované události. Pokud funkce vrátí None, parsování eveny se tiše ukončí. Pokud funkce vyvolá výjimku, bude výjimka zaznamenána a událost bude předána do výstupu unparsed.

Řetězení preprocesorů

Preprocesory lze řetězit, aby bylo možné analyzovat složitější vstupní formáty. Výstup (neboli událost) prvního preprocesoru je přiveden jako vstup druhého preprocesoru (a tak dále).

Například vstupem je formát CEF se záhlavím Syslog RFC3164:

<14>Jan 28 05:51:33 connector-test CEF_PARSED_LOG: CEF:0|Výrobce|Produkt|Verze|foobar:1:2|Neúspěšné heslo|Medium| eventId=1234 app=ssh categorySignificance=/Informational/Warning categoryBehavior=/Authentication/Verify

Potrubí obsahuje dva preprocesory:

p01_parser.yaml:

---
define:
  název: Preprocesor pro část zprávy Syslog RFC5424
  type: parser/preprocessor
  nájemce: Syslog_RFC5424.STRUCTURED_DATA.soc@0.tenant

funkce: lmiopar.preprocessor.Syslog_RFC5424

p02_parser.yaml:

---
define:
  name: Preprocesor pro část zprávy CEF
  typ: parser/preprocesor

funkce: lmiopar.preprocessor.CEF

a finální parser p03_parser.yaml:

---
define:
  name: Finalizovat rozborem události do slovníku
  typ: parser/cascade

parse:
  !DICT
  set:
    Syslog_RFC5424: !ITEM CONTEXT Syslog_RFC5424
    CEF: !ITEM CONTEXT CEF
    Message: !EVENT

Příklad výstupu:

context:
  CEF:
    Verze: 0
    DeviceVendor: Vendor
    DeviceProduct: Product
    DeviceVersion: Verze:
    DeviceEventClassID: "foobar:1:2
    Name: Název: Failed password
    Závažnost: Heslo: Střední

    EventId: '1234'
    aplikace: ssh
    categorySignificance: /Informational/Warning
    categoryBehavior: /Authentication/Verify

  Syslog_RFC3164:
    PRI: 14
    FACILITY: 1
    PRIORITA: 6
    HOSTNAME: connector-test'
    TAG: CEF_PARSED_LOG
    TIMESTAMP': '2020-01-28T05:51:33.000Z'

  Zpráva: "Provedení: 1. Provedení: 2. Provedení: 3: ''

Vestavěný preprocesor Cisco ASA

funkce: lmiopar.preprocessor.CiscoASA

Warning

Tento preprocesor bude nahrazen parserem založeným na SP-Lang.