Lookups¶

Lookups are dictionaries of entities with attributes that are relevant either for parsing or for detection of cybersecurity incidents.

Lookups can be:

A simple list of suspicious IP addresses, active VPN connections, etc.
Dictionaries of user names with user attributes like user.id, user.email, etc.
Dictionaries of compound keys like IP address and user name combinations for monitoring user activity.

What do lookups do?

Lookups, being like dictionaries, contain additional useful information about the data you already have that can make your logs more informative and valuable.

A simple example:
Your organization has logs about sent emails, which include the email address of the sender. However, you want the logs in your LogMan.io UI to include the sender’s name, not just their email address. So, you have a lookup in which each item is an employee's email address with the employee's name associated. If you use this lookup in the enrichment part of the parsing process, the parser “looks up” the employee’s name based on their email address in this dictionary-like lookup and includes the employee’s name in the log.

Quickstart¶

In order to set up lookups:

Create a lookup declaration in the LogMan.io Library (the lookup description)
Create the lookup and its content in the Lookups section in the UI (the lookup content)
Add the lookup to the relevant parsing and/or correlation rules in the Library (the lookup application)

Note

Make sure all relevant components are deployed, see Deployment.

Declarations¶

All lookups are defined by their declarations stored in the /Lookups folder.

The naming convention for declarations is lookupname.yaml, for instance myuserlookup.yaml:

---
define:
    type: lookup
    name: myuserlookup

keys:
    - name: userid
      type: str

fields:
    username:
        type: str

In define, specify the lookup type, lookup name (tenant information will be added automatically), keys with their names (optional) and types and fields in the output record structure. The record structure is NOT based on a schema and should NOT contain periods.

Note

Names of keys and fields cannot contain special characters like a period, etc.

Lookup types¶

Generic lookups¶

Generic lookups serve to create list of keys or key-value pairs. The type in the declaration in the define section is just lookup:

---
define:
    type: lookup
    ...

When it comes to parsing, generic lookups can be used only in the standard enricher with the !LOOKUP expression.

For more information about generic Lookups, see Generic Lookups.

IP address lookups¶

IP address Range Lookup¶

IP address Range Lookup uses the IP address ranges, such as 192.168.1.1 to 192.168.1.10, as keys.

The declaration of an IP address range lookup must contain type lookup/ipaddressrange in the define section and two keys with type ip in the keys section:

define:
  type: lookup/ipaddressrange
  name: mylookup
  group: mygroup

keys:
  - name: range1
    type: ip
  - name: range2
    type: ip

fields:
  ...

Single IP address lookup¶

A single IP address lookup is a lookup that has exactly one IP address key with type ip that can be associated with an optional and variable number of attributes, defined by none or multiple values under fields.

In order to use single IP lookups together with the following enrichers, the type of the lookup in the define section must always be lookup/ipaddress.

---
define:
  type: lookup/ipaddress
  name: mylookup
  group: mygroup

keys:
  - name: sourceip
    type: ip

fields:
  ...

For more information about IP address lookups, see IP Address Lookups.