Parsery

Logmanager používá Parsers k definování zdrojových zařízení a zpracování příchozích logů. Každá zpráva vstupující do systému musí projít pravidlem parseru, aby byla dekódována, normalizována a rozšířena o nové atributy.

Sekce Parsers vám umožňuje spravovat způsob, jakým jsou data získávána a interpretována. Klasifikace příchozích zpráv je určena identifikátory uvnitř každé zprávy, které následně zprávu nasměrují k příslušnému parseru pro zpracování obsahu.

Hlavní tabulka poskytuje následující informace:

NAME: Unikátní název pravidla parseru.
DESCRIPTION: Stručné vysvětlení účelu pravidla.
TAG: Přidružená metadata pro kategorizaci. Více informací v sekci Tags.
BUILT-IN: Indikuje, zda je pravidlo integrovanou součástí systému.
ACTION: Tlačítka pro úpravu nebo odstranění existujících pravidel.

Integrovaná pravidla parsování popsaná jako „vestavěný parser“ nelze upravovat ani mazat, ale lze je zobrazit a zkopírovat.

Přidat nový Parser

Klikněte na zelené tlačítko Create new v pravém horním rohu hlavní tabulky.
Zadejte následující údaje:
- Name: Zadejte unikátní název pro parser.
- Description: Uveďte popis zdrojového zařízení nebo softwaru.
- Blocks: Definujte logiku pomocí vizuálního editoru Blockly editor.

Upravit existující Parser

Chcete-li pravidlo upravit, klikněte na tyrkysové tlačítko Edit v příslušném řádku.

Smazat Parser

Chcete-li odstranit vlastní pravidlo, klikněte na červené tlačítko Delete. Akci potvrďte v následujícím dialogu.

Formát uložených zpráv

Každá zpráva zpracovaná Logmanagerem je uložena ve standardizovaném formátu JSON. Pochopení této syntaxe je zásadní pro vytváření efektivních pravidel parsování a práci s proměnnými.

Pravidla pojmenování polí

Pro zajištění kompatibility databáze a stability systému platí následující pravidla:

Název pole se skládá vždy pouze z malých písmen, doplněných o čísla, pomlčku a podtržítko.
Pokud je pole pojmenováno nesprávně, bude automaticky očištěno od chybných znaků a doplněno textem invalid_.
Názvy polí nesmí začínat číslem.

Wrong name of fields	Automatic correction name
`Protocol`	`invalid_protocol`
`url%path`	`invalid_url_path`
`1-service-internal`	`invalid_1-service-internal`

Práce se strukturovanými daty

Pokud zařízení odesílá logy ve strukturovaných formátech, můžete k jejich automatickému dekódování použít specializované bloky:

JSON: Decode JSON
CEF: Decode CEF

Při práci se zprávami používejte pouze hodnoty uvedené v polích msg, meta a raw. Ostatní pole jsou systémová a mohou se v budoucích verzích změnit.

Příklady pravidel parsování

Pro lepší představu o tom, jak vytvářet pravidla parsování, jsme připravili několik funkčních příkladů pro různé systémy:

Chybějící Parsery

Pokud vaše zařízení v Logmanageru nezobrazuje data správně, budete muset vytvořit parser pro normalizaci hodnot.

Možnosti svépomocí

Manual Creation: Sestavte parser pomocí Blockly editoru, abyste rozdělili data do proměnných a přidali volitelné informace.
Strukturované logy: Pokud vaše zařízení podporuje JSON, CEF nebo LEEF, jsou data již strukturovaná a stačí na ně aplikovat vhodný klasifikátor.

Profesionální podpora

Případně můžete kontaktovat svého Logmanager partnera nebo výrobce a požádat o vytvoření konkrétního parseru. Připravte si prosím následující:

Device Details: Výrobce, název softwaru a konkrétní verze.
Configuration Guide: Pokyny, jak nastavit zařízení pro odesílání logů do Logmanageru.
Documentation: Odkazy na dokumentaci logů/auditů od výrobce.
Sample logy: Export polí raw ze serveru Logmanager.

Jak Parsery fungují?

Tato sekce definuje zdrojová zařízení, ze kterých jsou logy získávány. Zařízením může být hardware, ale i software, včetně systému Windows. Každé zařízení, které nastavíte pro odesílání logů do Logmanageru, musí být definováno v této sekci. Parsery fungují jako základní překladová vrstva, která převádí různé formáty logů do jednotné struktury.

Definice je rozdělena do několika skupin. Nejprve se řeší klasifikace příchozích zpráv podle identifikátorů, které každá zpráva obsahuje. Zpráva je následně předána z klasifikace do parseru, kde je zpracován její obsah.

Formát uložených zpráv

Každá zpráva, která projde systémem, je uložena do databáze ve standardizovaném formátu. Na základě tohoto formátu je možné se zprávami v systému pracovat, proto je vhodné znát uložení a význam konkrétních prvků zprávy.

Syntax

Zprávy používají následující syntaxi:

{
  "field": "value"
}

{
  "field1": "string_value",
  "field2": integer_value,
  "field3": float_value,
  "field4": [
    list
  ],
  "field5": {
    dictionary
  },
  "field6": {
    "subfield1": "value1",
    "subfield2": "value2"
  }
}

Příklady:

String value: "sample text"
Integer value: 259
Float value: 259.57
List: ["sample text", 259, ""]
Dictionary: {"field1": "sample text", "field2": 259}
Subfield access: field6.subfield2

Pravidla pro práci se zprávami

Pro zajištění kompatibility s databází a stability systému platí následující pravidla:

Field names: Musí obsahovat pouze malá písmena, doplněná čísly, pomlčkou a podtržítkem.
Auto-correction: Pokud je pole pojmenováno nesprávně, bude automaticky očištěno od chybných znaků a doplněno textem invalid_.
Naming constraints: Field names nesmí začínat číslem. Symboly @ nebo _ nelze použít jako názvy proměnných v parserech nebo klasifikátorech.
Value types: Hodnota může být prázdná, celé číslo, desetinné číslo, řetězec, seznam nebo slovník. Floats nesmí být NaN nebo nekonečné.
Speciální pole: Seznamy obsahující v názvu @ jsou generovány interně a mohou obsahovat doplňkové informace ve formátu seznamu nebo slovníku.

Wrong name of fields	Automatic correction name
`Protocol`	`invalid_protocol`
`url%path`	`invalid_url_path`
`1-service-internal`	`invalid_1-service-internal`
`<service@internal>`	`invalid_service_internal`

Struktura zprávy

Obecný formát uložené zprávy:

{
  "@timestamp": "",
  "raw": "",
  "meta": {
    "event@id": "",
    "forwarder@id": "",
    "instance@id": "",
    "parser": "",
    "plugin": "",
    "tags": [],
    "tags@id": [],
    "timestamp": "",
    "src": {},
    "type": ""
  },
  "msg": {},
  "raw_offset": 0,
  "@version": ""
}

Popis polí:

@timestamp / timestamp: Kdy byla zpráva doručena do systému Logmanager.
raw: Původní obsah zdrojové zprávy.
meta: Obsahuje interní informace o zprávě (unikátní event ID, identifikace instance a přiřazené tagy).
src: Obsahuje zdrojové informace (IP adresa, protokol, host a severity).
msg: Slovník polí vygenerovaných na základě konkrétních parserů, kterými zpráva prošla.
raw_offset: Určuje pozici v textu, od které je zpráva zpracovávána parsery.

Při práci se zprávami používejte pouze hodnoty uvedené v polích msg, meta, raw a raw_offset. Ostatní pole jsou systémová a mohou se v budoucích verzích změnit, proto se nedoporučuje s nimi pracovat.

Příklad kompletní zprávy uložené v systému Logmanager

{
  "_index": "lm-demo-2017.01.26",
  "_type": "microsoft-windows",
  "_id": "AVnZ_79FTDlIxPtA3bf8",
  "_score": null,
  "_source": {
    "msg": {
      "eventid": "7036",
      "processid": "500",
      "systemtime": "2017-01-26T08:58:00.078932400Z",
      "guid": "{555908d1-a6d7-4695-8e1e-26931d2012f4}",
      "uuid": "34B64D56-E785-1328-0EC0-E6CD20C4A9F9",
      "osservicepack": "",
      "eventsourcename": "Service Control Manager",
      "eventrecordid": "140740",
      "osname": "Windows 8 or Windows Server 2012",
      "eventtype": "System",
      "osedition": "Standard Server",
      "computer": "pc-example",
      "param2": "stopped",
      "param1": "Adobe Flash Player Update Service",
      "threadid": "2384",
      "message": "The Adobe Flash Player Update Service service entered the stopped state.",
      "eventid@int": {
        "value": 7036
      },
      "senderversion": "2.4.6004.23920",
      "channel": "System",
      "name": "Service Control Manager"
    },
    "raw": "<36>1 2017-01-26T09:58:01.094556+01:00 pc-example ServiceControlManager 500 msgld {\"senderversion\": \"2.4.6004.23920\", \"eventtype\": \"System\", \"eventid\": \"7036\", \"eventrecordid\": \"140740\", \"osname\": \"Windows 8 or Windows Server 2012\", \"osedition\": \"Standard Server\", \"osservicepack\": \"\", \"uuid\": \"34B64D56-E785-1328-0EC0-E6CD20C4A9F9\", \"name\": \"Service Control Manager\", \"guid\": \"{555908d1-a6d7-4695-8e1e-26931d2012f4}\", \"eventsourcename\": \"Service Control Manager\", \"systemtime\": \"2017-01-26T08:58:00.078932400Z\", \"processid\": \"500\", \"threadid\": \"2384\", \"channel\": \"System\", \"computer\": \"pc-example\", \"param1\": \"Adobe Flash Player Update Service\", \"param2\": \"stopped\", \"message\": \"The Adobe Flash Player Update Service service entered the stopped state.\"}",
    "@timestamp": "2017-01-26T08:58:03.595+00:00",
    "meta": {
      "forwarder@id": "00000000-0000-0000-0000-000000000000",
      "tags": ["windows"],
      "timestamp": "2017-01-26T08:58:03.595836+00:00",
      "parser": "microsoft-windows",
      "tags@id": ["3d3f2c7f-d1db-4442-9ff2-ea60c56716a8"],
      "instance@id": "00000000-0000-0000-0000-000000000000",
      "src": {
        "dialect": "relp",
        "severity": "warning",
        "facility": "auth",
        "ip": "192.0.2.56",
        "ip@ip": {
          "city": "New York",
          "is_reserved": false,
          "value": "192.0.2.56",
          "version": 4,
          "country_code": "US",
          "is_multicast": false,
          "country_name": "United States",
          "ptr": "pc-example.example.com",
          "is_link_local": false
        },
        "pid": "500",
        "host": "pc-example",
        "program": "ServiceControlManager"
      },
      "type": "user",
      "plugin": "windows"
    },
    "raw_offset": 82,
    "@version": "1"
  }
}

Popis ukázkové zprávy:

msg: Zpracované informace ze zdrojové zprávy.
raw: Původní zdrojová zpráva.
src: Podrobné informace o původu zprávy.