Mapování

Po získání všech deklarovaných polí z analyzátorů musí být pole obvykle přejmenována podle nějakého schématu (ECS, CEF) v procesu nazývaném mapování.

Proč je mapování nezbytné?

Pro uložení dat událostí v Elasticsearch je důležité, aby názvy polí v logech odpovídaly Elastic Common Schema (ECS), standardizované, otevřené kolekci názvů polí kompatibilních s Elasticsearch. Proces mapování přejmenuje pole z analyzovaných logů podle tohoto schématu. Mapování zajišťuje, že logy z různých zdrojů mají jednotné a konzistentní názvy polí, což umožňuje Elasticsearch je správně interpretovat.

Důležité

Ve výchozím nastavení pracuje mapování jako filtr. Ujistěte se, že do deklarace mapování zahrnete všechna pole, která chcete v analyzovaném výstupu. Jakékoliv pole, které není specifikováno v mapování, bude z události odstraněno.

Psaní deklarace mapování

Deklarace mapování napište v YAML. (Deklarace mapování nepoužívají výrazy SP-Lang.)

define:
    type: parser/mapping
    schema: /Schemas/ECS.yaml

mapping:
    <original_key>: <new_key>
    <original_key>: <new_key>
    ...

Specifikujte parser/mapping jako type v sekci define. V poli schema specifikujte cestu k souboru schématu, který používáte. Pokud používáte Elasticsearch, použijte Elastic Common Schema (ECS).

Standardní mapování

Pro přejmenování klíče a změnu datového typu hodnoty:

Warning

Nový datový typ musí odpovídat datovému typu specifikovanému ve schématu pro toto pole.

Specifikací type: auto bude datový typ automaticky určen ze schématu na základě názvu pole.

mapping:
    <original_key>:
        field: <new_key>
        type: <new_type>

Dostupné datové typy najdete zde.

Pro přejmenování klíče a úpravu hodnoty:

mapping:
    <original_key>:
        field: <new_key>
        apply: <new_type>

Chcete-li použít hodnotu mapování jako argument v rámci funkce apply, musíte specifikovat typ analyzované hodnoty a název argumentu VALUE.

mapping:
    <original_key>:
        field: <new_key>
        value_type: <type>
        apply: <new_type>

Example

Upravení hodnoty řetězce na hodnotu IP pomocí výrazu PARSE.IP a přejmenování na nový klíč:

  'json /client-ip':
          field: client.ip
          apply: !PARSE.IP

Upravení hodnoty řetězce na malá písmena a přejmenování na nový klíč:

Uveďte počáteční typ hodnoty a použijte jej jako argument VALUE ve funkci apply.

  'json /client-hostname':
          field: client.address
          value_type: str
          apply: !LOWER
                 what: !ARG VALUE

Pro přejmenování klíče bez změny datového typu hodnoty:

mapping:
    <original_key>: <new_key>

Mapování z JSON

Pro přejmenování klíče uloženého v objektu JSON:

mapping:
    <jsonObject> <jsonPointer>: <new_key>

Název objektu JSON a JSON ukazatel musí být odděleny mezerou. JSON ukazatel vždy začíná znakem / a každá další úroveň je oddělena znakem /.

Pro přejmenování klíče uloženého v objektu JSON se specifickým párem klíč-hodnota:

mapping:
    <jsonObject> <jsonPointer/[key:value]/jsonPointer>: <new_key>

Název objektu JSON a JSON ukazatel musí být odděleny mezerou. JSON ukazatel vždy začíná znakem / a každá další úroveň je oddělena znakem /. Specifikovaný pár klíč-hodnota umožňuje vybrat požadovaný objekt JSON (viz příklad níže).

Pro přejmenování klíče uloženého v objektu JSON a změnu datového typu hodnoty:

mapping:
    <jsonObject> <jsonPointer>:
        field: <new_key>
        type: <new_type>

Jak bylo uvedeno dříve, je možné změnit datový typ specifikací pole type.

Příklad

Příklad 1: Mapování z JSON

Pro účely příkladu si představme, že chceme analyzovat jednoduchou událost ve formátu JSON:

{
    "act": "user login",
    "ip": "178.2.1.20",
    "usr": "harry_potter",
    "id": "6514-abb6-a5f2"
}

a chtěli bychom, aby finální výstup vypadal takto:

{
    "event.action": "user login",
    "source.ip": "178.2.1.20",
    "user.name": "harry_potter"
}

Všimněte si, že názvy klíčů v původní události se liší od názvů klíčů v požadovaném výstupu.

Pro počáteční deklaraci parseru v tomto případě můžeme použít jednoduchý JSON parser:

10_parser.yaml

define:
type: parser/json

Tento parser vytvoří objekt JSON a uloží jej do pole json.

Pro změnu názvů jednotlivých polí vytvoříme tento soubor deklarace mapování, 20_mapping_ECS.yaml, ve kterém popíšeme, která pole mapovat a jak:

20_mapping_ECS.yaml

---
define:
type: parser/mapping  # určete typ deklarace
schema: /Schemas/ECS.yaml  # které schéma je použito

mapping:
    json /act: 'event.action'
    json /ip:
        field: 'source.ip'
        type: auto
    json /usr: 'user.name'

Tato deklarace vytvoří požadovaný výstup. Datový typ pole source.ip bude automaticky určen na základě schématu a odpovídajícím způsobem změněn.

Příklad 2: Mapování z JSON se specifickým párem klíč-hodnota

Dalším příkladem je mapování pro složitou událost ve formátu JSON, která se skládá z objektu JSON se specifickým párem klíč-hodnota:

{
    "CreationTime": "2022-01-19T11:07:41",
    "ExtendedProperties": [
        {
            "Name": "ResultStatusDetail",
            "Value": "Redirect"
        },
        {
            "Name": "UserAgent",
            "Value": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) MicrosoftTeams-Preview/1.4.00.26453 Chrome/85.0.4183.121 Electron/10.4.7 Safari/537.36"
        },
        {
            "Name": "RequestType",
            "Value": "OAuth2:Authorize"
        }
    ],
}

Abychom získali pole z objektu JSON, který obsahuje specifický pár klíč-hodnota, použijte následující syntaxi:

20_mapping_ECS.yaml

---
define:
type: parser/mapping  # určete typ deklarace
schema: /Schemas/ECS.yaml  # které schéma je použito

mapping:
  json /ExtendedProperties/[Name:ResultStatusDetail]/Value: 'o365.audit.ExtendedProperties.ResultStatusDetail'
  json /ExtendedProperties/[Name:UserAgent]/Value: 'o365.audit.ExtendedProperties.UserAgent'
  json /ExtendedProperties/[Name:RequestType]/Value: 'o365.audit.ExtendedProperties.RequestType'