Přeskočit obsah

IP Enricher

IP Enricher rozšiřuje události o geografické a další údaje spojené s danou IPv6 nebo IPv4 adresou. Tento modul nahrazuje IP2Location Enricher a GeoIP Enricher, které jsou nyní zastaralé.

Deklarace

Sekce define

Tato sekce definuje název a typ obohacovače.

Položka name

Krátký, dobře čitelný název této deklarace.

Položka type

Existují čtyři typy IP Enricher, které se liší verzí IP (IPv4 nebo IPv6) a reprezentací IP adresy (číslo nebo řetězec). Použití číslovaného vstupu je rychlejší a preferovaná možnost.

  • enricher/ipv6 zpracovává IPv6 adresy v 128bitové dekadické číselné formě (například 281473902969579).
  • enricher/ipv4 zpracovává IPv4 adresy v 32bitové dekadické číselné formě (například 3221226219).
  • enricher/ipv6str zpracovává IPv6 adresy v hexadecimální řetězcové formě oddělené dvojtečkami (například 2001:db8:0:0:1:0:0:1) jak je definováno v RFC 5952. Může také převádět a zpracovávat řetězcové adresy IPv4 (jako enricher/ipv4str).
  • enricher/ipv4str zpracovává IPv4 adresy v čtyřdílném dekadickém řetězci (například 192.168.16.0) jak je definováno v RFC 4001.

Položka base_path

Specifikuje základní URL cestu, která obsahuje soubory zón pro vyhledávání. Může ukazovat na: * lokální souborový systém, např. /path/to/files/ * umístění v zookeeper, např. zk://zookeeper-server:2181/path/to/files/ * umístění HTTP, např. http://localhost:3000/path/to/files/

Sekce tenants

IP Enricher může být nastaven pro multitenantní konfigurace. Tato sekce seznamuje tenanty, které by měly být zohledněny obohacovačem při vytváření specificních vyhledávání podle tenantů. Události označené tenantem, který není uveden v této sekci, budou obohaceny pouze globálními obohaceními (viz níže).

Sekce zones

Specifikuje seznam vyhledávacích zón, které mají být použity obohacovačem, plus informaci, zda jsou globální nebo specifické pro tenant.

Globální vyhledávání může obohatit jakoukoliv událost, bez ohledu na jejího tenanta. Specifické pro tenant mohou obohatit pouze události s odpovídajícím kontextem tenanta.

Vyhledávací zóny by měly být seřazeny podle priority, od nejvyšší k nejnižší, protože vyhledávání probíhá přes zóny sekvenčně a končí, jakmile je nalezena první shoda.

zones:
- tenant: lookup-zone-1.pkl.gz
- tenant: lookup-zone-2.pkl.gz
- global: lookup-zone-glob.pkl.gz

Názvy zón musí odpovídat odpovídajícím názvům souborů včetně přípony. Soubory pro globální vyhledávání musí být přímo v adresáři base_path. Soubory specifické pro tenant musí být uspořádány pod base_path do složek podle jejich tenanta. Například, předpokládejme, že jsme deklarovali first_tenant a second_tenant, deklarace zón výše očekává následující strukturu souborů:

/base_path/
- first_tenant/
  - lookup-zone-1.pkl.gz
  - lookup-zone-2.pkl.gz
- second_tenant/
  - lookup-zone-1.pkl.gz
  - lookup-zone-2.pkl.gz
- lookup-zone-glob.pkl.gz

Příchozí událost, jejíž kontext je second_tenant, se první pokusí o shodu ve vyhledávání second_tenant/lookup-zone-1.pkl.gz, pak ve second_tenant/lookup-zone-2.pkl.gz a nakonec ve lookup-zone-glob.pkl.gz.

Sekce attributes

Tato sekce specifikuje, které atributy události obsahují IP adresu a které atributy budou přidány do události, pokud bude nalezena shoda. Má následující strukturu slovníku:

ip_address: 
  lookup_attribute_name: event_attribute_name

IP adresa je extrahována z atributu události ip_address. Pokud odpovídá nějaké vyhledávací zóně, hodnota lookup_attribute_name je uložena do atributu události event_attribute_name. Například:

source_ip:
  country_code: source_country

Tím se událost zkouší porovnat na základě jejího atributu source_ip a uložit odpovídající hodnotu country_code do pole události nazvaného source_country.

Obohacení názvu zóny

Může být užitečné zaznamenat název vyhledávací zóny, ve které došlo ke shodě. Pro přidání názvu zóny do události použijte zone jako název atribu pro vyhledávání, např.:

source_ip:
  zone: source_zone_name

Tím se přidá název odpovídajícího vyhledávání do pole události source_zone_name.

Mějte na paměti, že pokud ve vyhledávání existuje pole nazvané "zone", jeho hodnota bude použita místo jména vyhledávání.

Název vyhledávání je nastaven při vytváření souboru vyhledávací zóny. Výchozí hodnota je název zdrojového souboru, ale může být nakonfigurována na jinou hodnotu. Viz příkaz lmiocmd ipzone from-csv v LogMan.io Commander pro podrobnosti.

Příklad použití

Deklarační soubor

---
define:
  name: IPEnricher
  type: enricher/ipv6

tenants:
  - some-tenant
  - another-tenant

zones:
  - tenant: lookup-zone-1.pkl
  - global: ip2location.pkl.gz

attributes:
  ip_addr1:
    country_code: sourceCountry
    city_name: sourceCity
    L: sourceLocation
  ip_addr2:
    country_code: destinationCountry
    city_name: destinationCity
    L: destinationL
  ...

Zde obohacovač čte IP adresu z atributu události ip_addr1. Pak se pokusí najít adresu ve svých vyhledávacích objektech: nejdříve ve lookup-zone-1.pkl, poté v ip2location.pkl.gz. Pokud najde shodu, získá vyhledávací hodnoty country_code, city_name a L a uloží je do příslušných polí události sourceCountry, sourceCity a sourceLocation. Analogicky postupuje pro druhou adresu ip_addr2. Výsledek lze vidět níže.

Vstup

Feb 5 10:50:01 0:0:0:0:0:ffff:1f1f:e001 %ASA-1-105043 test

Řádek výše může být parsován do následujícího slovníku.

{
    'rt': 1580899801.0,
    'msg': 'test',
    'ip_addr1': '0:0:0:0:0:ffff:1f1f:e001'
}

To je předáno IP Enricheru, které jsme deklarovali výše.

Výstup

{
    'rt': 1580899801.0,
    'msg': 'test',
    'ip_addr1': '0:0:0:0:0:ffff:1f1f:e001',
    'sourceCountry': 'CZ',
    'sourceCity': 'Brno',
    'sourceLocation': (49.195220947265625, 16.607959747314453)
}

Soubor pro vyhledávání IP zón

Soubor pro vyhledávání IP je pickleovaný Python slovník. Může být jednoduše vytvořen ze souboru CSV pomocí příkazu lmiocmd ipzone from-csv naleznutelného v LogMan.io Commander. CSV musí obsahovat řádek s hlavičkami s názvy sloupců. Musí obsahovat sloupce ip_from a ip_to, a alespoň jeden další sloupec s požadovanými hodnotami pro vyhledávání.

Například: 

ip_from,ip_to,zone_info,latitude,longitude
127.61.100.0,127.61.111.255,my secret base,48.224673,-75.711505
127.61.112.0,127.61.112.255,my submarine,22.917923,267.490378

POZNÁMKA Zóny definované v jednom souboru pro vyhledávání nesmí překrývat.

POZNÁMKA IP zóny v souboru CSV jsou považovány za uzavřené intervaly, tj. obě pole ip_from a ip_to jsou zahrnuta v zóně, kterou vymezují.

IP2Location

Tímto příkazem lze také vytvořit soubor pro vyhledávání z IP2Location™ CSV databází. Všimněte si, že tyto soubory neobsahují názvy sloupců, takže řádek s hlavičkami musí být do souboru CSV přidán ručně před vytvořením vyhledávacího souboru.