Skip to content

Lookups in detections

Lookups are lists (and key/value tables) that detection rules use to decide whether an event should alert. As an analyst you mainly maintain the content of lookups and reference them in predicates so rules stay accurate without hard-coding usernames, IPs, or ports in YAML.

Typical uses:

  • Whitelists: suppress known-good activity (scanners, jump hosts, allowed network segments).
  • Blacklists / watchlists: focus on known-bad or high-interest entities (Tor exit nodes, ransomware extensions, break-glass accounts).
  • Inventory lists: mark who or what is in scope (admins, service accounts, privileged groups, internal zones).

For creating lookup declarations, types, and deployment, see the Lookups reference. For managing items in the UI, see User Manual: Lookups. Custom geolocation zones are covered in Geolocation lookups. Attaching a MaxMind .mmdb file is covered in Custom MaxMind enricher. Filling IOC lookups from external sources is covered in Threat intelligence feeds.

How lookups appear in rules

In correlation predicates, a lookup is almost always used as a membership test: is this field value a key in the lookup?

Match if the value is in the lookup (!IN + !LOOKUP)

Use this for watchlists and “in scope” lists (admins, IoCs, unusual ports):

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

This pattern is used widely in the common library (for example Administrator Logon Outside Business Hours, Break Glass Account Used, Traffic from Tor Exit Nodes).

Exclude if the value is in the lookup (whitelist)

Wrap the membership test in !NOT so listed entities do not trigger:

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

Network sweep / port sweep rules use excludedipaddresses this way so scanners and monitoring hosts do not raise false positives.

Shorthand: !LOOKUP.CONTAINS

Some rules use !LOOKUP.CONTAINS instead of !IN with where: !LOOKUP. Behaviour is the same idea: test whether a value is present in the named lookup.

# Alert only if the user is NOT on the authorized sudo list
- !NOT
  what:
    !LOOKUP.CONTAINS
    what: !ITEM EVENT user.name
    in: sudousers

# Alert if the destination is a known DB server AND the source is not allowed
- !LOOKUP.CONTAINS
  what: !ITEM EVENT destination.ip
  in: databaseservers
- !NOT
  what:
    !LOOKUP.CONTAINS
    what: !ITEM EVENT source.ip
    in: alloweddbsegments

Cast when key types differ

Lookup keys have a declared type (str, ip, and so on). If the event field is a number (for example a port) and the lookup stores strings, cast before the check:

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

Compound keys (!TUPLE)

Lookups with more than one key (for example country + date in holidays) need a !TUPLE in the same order as the declaration. See Using a compound key in rules.

Whitelists vs blacklists

There is no separate “whitelist” or “blacklist” lookup type. The role comes from how the rule uses the list:

Role Predicate idea Library examples
Whitelist (allow / ignore) !NOT + membership in the lookup excludedipaddresses, sudousers, alloweddbsegments, safecountries
Blacklist / watchlist (alert when present) membership in the lookup torexitnodes, vpnexitnodes, ransomwareextensions, breakglassaccounts, maliciousipaddresses
Scope / inventory membership defines who the rule cares about admins, serviceaccounts, admingroups, zones

You can combine both in one rule. Suspicious Connection requires source.ip in zones and destination.ip not in zones (traffic leaving internal ranges).

Practical tips

  • Prefer updating lookup items in the UI over editing the rule when the set of usernames or IPs changes.
  • Keep whitelist keys accurate; a missing entry often means noise, an extra entry can hide real detections.
  • Align key values with the event field you test (user.name vs user.id, ISO country codes, dotted IPs).
  • For IP ranges and private geography, use IP-range / geo lookups. See Geolocation lookups and IP address lookups.

Common lookups used by detection rules

These names appear frequently in the TeskaLabs common correlation library. Populate them for your tenant so shipped rules behave as intended.

Lookup Typical role Used for
admins Scope Admin authentication and privilege-related rules
breakglassaccounts Watchlist Emergency / break-glass account usage
serviceaccounts Scope / watchlist Interactive or unusual use of service accounts
defaultaccounts Watchlist Built-in / default account activity
disabledaccounts State list Failed logons against disabled accounts (also updated by some rules)
sudousers Whitelist Authorized sudo users (alert when not listed)
excludedipaddresses Whitelist IPs excluded from sweep / scan detections
zones Inventory / geo Internal IP ranges; zone-crossing firewall rules
safecountries Whitelist Expected country ISO codes for logons
holidays Whitelist / calendar Compound keys (for example country + date) for out-of-hours logic
unusualports Watchlist Non-standard ports
torexitnodes / vpnexitnodes Blacklist Traffic involving known exit nodes
ransomwareextensions Blacklist Ransomware-related file extensions
domainprivilegedgroups / admingroups / privilegedlocalgroups / monitoredgroups Scope Group membership change detections
criticalservices Scope Critical service stop / change
activevpnusers State list Who is currently on VPN (written by VPN login/logout rules)

Declarations for these lookups live under /Lookups in the library. Many are created automatically (default: true) with a small set of default_items; replace or extend them for your environment.

Updating lookups from detections

Rules can also write lookup content when they fire, using a lookup trigger:

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

Examples in the library:

  • VPN login / logout maintain activevpnusers.
  • Account disable / enable maintain disabledaccounts.
  • Scheduled task start / finish maintain scheduledtasks (compound key with !TUPLE).

Use this for short-lived state that other rules consume. For long-lived allow/deny lists that analysts own, prefer the Lookups UI (or CSV import) instead of encoding the list in the rule.