Lookupy v detekcích¶

Lookupy jsou seznamy (a tabulky klíč/hodnota), které detekční pravidla používají k rozhodnutí, zda má událost vyvolat alert. Jako analytik hlavně udržujete obsah lookupů a odkazujete na ně v predikátech, aby pravidla zůstala přesná bez hard-codování uživatelských jmen, IP nebo portů v YAML.

Typické použití:

Whitelisty: potlačení známé dobré aktivity (skenery, jump hosty, povolené segmenty, cloudové rozsahy dodavatelů jako Microsoft 365).
Blacklisty / watchlisty: zaměření na známě špatné nebo zajímavé entity (Tor exit nodes, ransom rozšíření, break-glass účty).
Inventářní seznamy: označení, kdo nebo co je v rozsahu (admini, servisní účty, privilegované skupiny, interní zóny).

Pro deklarace lookupů, typy a nasazení viz reference Lookups. Pro správu položek v UI viz Uživatelský manuál: Lookups. Vlastní geolokační zóny pokrývá Geolokační vyhledávání. Připojení MaxMind .mmdb viz Vlastní MaxMind enricher. Plnění IOC lookupů z externích zdrojů viz Threat intelligence feedy. Plnění usernames2userid z Active Directory viz LDAP / AD feed identity uživatelů.

Jak se lookupy objevují v pravidlech¶

V korelačních predikátech se lookup téměř vždy používá jako test členství: je hodnota pole klíčem v lookupu?

Shoda, když je hodnota v lookupu (`!IN` + `!LOOKUP`)¶

Pro watchlisty a seznamy „v rozsahu“ (admini, IoC, neobvyklé porty):

predicate:
  !AND
  - !IN
    what: user.name
    where: !EVENT
  - !IN
    what: !ITEM EVENT user.name
    where:
      !LOOKUP
      what: admins

Tento vzor je běžný v common library (např. Administrator Logon Outside Business Hours, Break Glass Account Used, Traffic from Tor Exit Nodes).

Vyloučení, když je hodnota v lookupu (whitelist)¶

Obalte test členství do !NOT, aby uvedené entity nespouštěly alert:

predicate:
  !AND
  - !IN
    what: source.ip
    where: !EVENT
  - !NOT
    what:
      !IN
      what: !ITEM EVENT source.ip
      where:
        !LOOKUP
        what: excludedipaddresses

Pravidla network sweep / port sweep používají excludedipaddresses tak, aby skenery a monitorovací hosty nevyvolaly false positives.

Use case: vyloučení rozsahů IP Microsoft 365 (nebo jiných)¶

Cíl: detekce nemá alertovat, když destination.ip (nebo source.ip) spadá do publikovaných rozsahů služeb Microsoft 365 / Office 365, ale stále alertuje na jiné cíle.

1. Lookup typu IP rozsah¶

Ano: uložte rozsahy do lookupu typu lookup/ipaddressrange (dva IP klíče: začátek a konec rozsahu). Jednoduchý IP lookup (lookup/ipaddress) je pro CIDR nebo start/end bloky špatně.

Příklad deklarace (Knihovna /Lookups/):

---
define:
  type: lookup/ipaddressrange
  name: m365ipranges
  label: Microsoft 365 IP ranges
  description_title: Published Microsoft 365 service IP ranges used as detection exceptions

keys:
  - name: start
    type: ip
  - name: end
    type: ip

fields:
  name:
    type: str

Vytvořte lookup v UI se stejným názvem a přidejte položky jako páry start/end (z publikovaného seznamu IP Microsoftu). Volitelné name může označit produkt nebo oblast služby.

Detaily typu: IP address range lookup.

2. Výjimka v pravidle: IP není v lookupu¶

Stejný whitelist vzor: !NOT kolem !IN + !LOOKUP. Příklad pro destination:

predicate:
  !AND
  # … další podmínky detekce …
  - !IN
    what: destination.ip
    where: !EVENT
  - !NOT
    what:
      !IN
      what: !ITEM EVENT destination.ip
      where:
        !LOOKUP
        what: m365ipranges

Pro source.ip změňte názvy polí stejným způsobem. Zkratka:

- !NOT
  what:
    !LOOKUP.CONTAINS
    what: !ITEM EVENT destination.ip
    in: m365ipranges

Členství proti IP rozsahovému lookupu uspěje, když IP události leží uvnitř uloženého rozsahu start/end (CIDR v predikátu sami nerozepisujete).

3. Aktuální rozsahy (volitelné feedy)¶

Ručně / CSV: vložte nebo importujte rozsahy do lookupu, když Microsoft seznam aktualizuje.
Feed: pokud z API získáte prefixy jako CIDR (nebo podobně), feed může rozsahový lookup automaticky obnovovat. Viz příklad Netbox prefixů: Threat intelligence feedy: Netbox prefixy.

Stejný vzor funguje pro libovolného dodavatele nebo povolenou sadu subnetů (Azure, AWS, partnerské sítě), nejen Microsoft 365.

Zkratka: `!LOOKUP.CONTAINS`¶

Některá pravidla používají !LOOKUP.CONTAINS místo !IN s where: !LOOKUP. Chování je stejné: test, zda je hodnota v pojmenovaném lookupu.

# Alert jen pokud uživatel NENÍ na autorizovaném sudo seznamu
- !NOT
  what:
    !LOOKUP.CONTAINS
    what: !ITEM EVENT user.name
    in: sudousers

# Alert pokud cíl je známý DB server A zdroj není povolen
- !LOOKUP.CONTAINS
  what: !ITEM EVENT destination.ip
  in: databaseservers
- !NOT
  what:
    !LOOKUP.CONTAINS
    what: !ITEM EVENT source.ip
    in: alloweddbsegments

Cast při rozdílných typech klíčů¶

Klíče lookupu mají deklarovaný typ (str, ip atd.). Pokud je pole události číslo (např. port) a lookup ukládá řetězce, před kontrolou použijte cast:

- !IN
  what:
    !CAST
    what: !ITEM EVENT destination.port
    type: str
  where:
    !LOOKUP
    what: unusualports

Složené klíče (`!TUPLE`)¶

Lookupy s více klíči (např. země + datum v holidays) potřebují !TUPLE ve stejném pořadí jako deklarace. Viz Použití složeného klíče v pravidlech.

Whitelisty vs blacklisty¶

Neexistuje samostatný typ lookupu „whitelist“ nebo „blacklist“. Role vychází z toho, jak pravidlo seznam používá:

Role	Myšlenka predikátu	Příklady z knihovny
Whitelist (povolit / ignorovat)	`!NOT` + členství v lookupu	`excludedipaddresses`, `sudousers`, `alloweddbsegments`, `safecountries`, vlastní IP rozsahy (např. `m365ipranges`)
Blacklist / watchlist (alert při přítomnosti)	členství v lookupu	`torexitnodes`, `vpnexitnodes`, `ransomwareextensions`, `breakglassaccounts`, `maliciousipaddresses`
Rozsah / inventář	členství definuje koho pravidlo zajímá	`admins`, `serviceaccounts`, `admingroups`, `zones`

V jednom pravidle můžete kombinovat obojí. Suspicious Connection vyžaduje source.ip v zones a destination.ip mimo zones (provoz opouštějící interní rozsahy).

Praktické tipy¶

Při změně množiny uživatelů nebo IP upravujte položky lookupu v UI spíš než pravidlo.
Udržujte whitelist klíče přesné; chybějící záznam často znamená šum, navíc záznam může skrýt skutečné detekce.
Slaďte hodnoty klíčů s testovaným polem události (user.name vs user.id, ISO kódy zemí, tečkované IP).
Pro IP rozsahy a privátní geografii používejte IP/geo lookupy. Viz Geolokační vyhledávání a IP address lookups.

Běžné lookupy v detekčních pravidlech¶

Tyto názvy se často objevují v TeskaLabs common correlation library. Naplňte je pro tenant, aby dodávaná pravidla fungovala podle očekávání.

Lookup	Typická role	Použití
`admins`	Rozsah	Pravidla pro admin autentizaci a privilegia
`breakglassaccounts`	Watchlist	Použití emergency / break-glass účtů
`serviceaccounts`	Rozsah / watchlist	Interaktivní nebo neobvyklé použití servisních účtů
`defaultaccounts`	Watchlist	Aktivita vestavěných / výchozích účtů
`disabledaccounts`	Stavový seznam	Neúspěšná přihlášení na disabled účty (některá pravidla také aktualizují)
`sudousers`	Whitelist	Autorizovaní sudo uživatelé (alert, když není v seznamu)
`excludedipaddresses`	Whitelist	IP vyloučené ze sweep / scan detekcí
`zones`	Inventář / geo	Interní IP rozsahy; firewall pravidla překračující zóny
`safecountries`	Whitelist	Očekávané ISO kódy zemí pro přihlášení
`holidays`	Whitelist / kalendář	Složené klíče (např. země + datum) pro logiku mimo pracovní dobu
`unusualports`	Watchlist	Nestandardní porty
`torexitnodes` / `vpnexitnodes`	Blacklist	Provoz se známými exit nodes
`ransomwareextensions`	Blacklist	Ransomware související přípony souborů
`domainprivilegedgroups` / `admingroups` / `privilegedlocalgroups` / `monitoredgroups`	Rozsah	Detekce změn členství ve skupinách
`criticalservices`	Rozsah	Zastavení / změna kritických služeb
`activevpnusers`	Stavový seznam	Kdo je aktuálně na VPN (zapisují VPN login/logout pravidla)

Deklarace těchto lookupů jsou pod /Lookups v knihovně. Mnoho se vytvoří automaticky (default: true) s malou sadou default_items; nahraďte nebo rozšiřte pro své prostředí.

Aktualizace lookupů z detekcí¶

Pravidla mohou při spuštění zapisovat obsah lookupu pomocí lookup trigger:

trigger:
  - lookup: activevpnusers
    key: !ITEM EVENT user.name
  - lookup: activevpnusers
    delete: !ITEM EVENT user.name

Příklady v knihovně:

VPN login / logout udržují activevpnusers.
Disable / enable účtu udržují disabledaccounts.
Start / dokončení scheduled task udržují scheduledtasks (složený klíč s !TUPLE).

Používejte pro krátkodobý stav, který konzumují jiná pravidla. Pro dlouhodobé allow/deny seznamy, které vlastní analytici, preferujte UI Lookups (nebo CSV import) místo kódování seznamu v pravidle.

Testování pravidel s lookupy¶

Při validaci detekčního pravidla v Knihovně nebo s correlator builderem predikáty volající lookupy (!LOOKUP.CONTAINS, !IN s !LOOKUP atd.) potřebují v čase testu data lookupu. Nemusíte plnit produkční lookup soubory ani spoléhat na ZooKeeper pro offline testy pravidel.

Přidejte blok lookups do každého pojmenovaného případu pod top-level sekcí test pravidla. Deklarace lookupu musí už existovat v Knihovně pod /Lookups/ (název, typy klíčů, pole). Testovací případ dodá jen řádky pro daný běh.

test:
  alice_is_allowed:
    lookups:
      allowed_events:
        alice:
          reason: whitelisted
        bob:
          reason: blocked

    input:
      - user.name: alice
        "@timestamp": 142446461673537536
        tenant: default
        _id: 1

    output:
      tenant: default
      # … očekávaný complex / trigger výstup …

Část	Význam
Název lookupu na top level (`allowed_events`)	Název lookupu bez přípony tenantu
Vnitřní klíč (`alice`)	Klíč záznamu lookupu
Vnitřní hodnota	Pole záznamu podle deklarace v `/Lookups/`

Pro složené klíče použijte seznam záznamů s explicitním _id ve stejném pořadí jako klíče deklarace:

lookups:
  UserList:
    - _id: [tenant1, alice]
      role: admin

Poznámky k chování:

Pokud testovací případ nedefinuje lookups, synchronní lookupy se načtou z produkční cesty builderu (lookup.base_path, typicky /lookups). Použijte, když chcete otestovat reálná data tenantu.
Pokud jakýkoli případ v pravidle definuje lookups, builder použije pro ty testy dočasnou složku lookupů.
Podporované pro seed testů: generické lookupy s keys a fields (stejná struktura jako lookup builder služba).
Nepodporované v seed testů: lookup/ipaddressrange a lookup/macaddressrange (použijte produkční lookup soubory nebo mockujte predikát jinak).
Lookup triggery (- lookup: pod trigger:) jsou při testech pravidel stále mockované: zápisy se logují, ale neaplikují na seedovaný lookup pro další události v tomže případu.

Pro úplnou strukturu sekce test (input, output, časové značky, _id) viz Test (volitelné, pro validaci pravidla).

Související čtení¶

Predikáty: stavba SP-Lang filtrů
Triggery: akce událostí a notifikací (lookup triggery detailně v Referenci)
Co je detekce?
Reference Lookups: typy, deklarace, buildery
Lookup trigger: set / delete / add / sub
Threat intelligence feedy: feedy plnící IOC lookupy