IP address lookups¶

TeskaLabs LogMan.io offers an optimized set of lookups for IP addresses, called IP Lookups.

There are always three steps to enable IP 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)

IP address to geographical location lookup¶

IP Geo Location is when, based on IP address range such as 192.168.1.1 to 192.168.1.10, you want to obtain the geographic location of the IP address such as city name, latitude, longitude etc.

Built-in IP address to geographical location lookup

When the IP address from the event does not match any of the provided geo lookups, the default public IP lookup provided by TeskaLabs LogMan.io will be used.

In LogMan.io, go to the Library.
In the Library, go to the folder /Lookups.
Create a new lookup declaration for your lookup, like "ipgeolookup.yaml" with a YAML extension
Add the following declaration:
```
define:
  type: lookup/ipaddressrange
  name: ipgeolookup
  group: geo

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

fields:
  location:
    type: geopoint
    value:
      lat: 50.0643081
      lon: 14.443938

  city_name:
    type: str
```
Make sure the type is always lookup/ipaddressrange.

Change the name in the define section to your lookup name.

The group is used then in the enrichment process to locate all lookups that share the same group. The value is a unique identifier of the group (use case), here: geo

Keep the keys as they are in order to specify ranges.

To fields, add names and types of the lookup attributes. Here in the example there is only city, but there can also be location (geolocation latitude and longitude) etc:
```
fields:
  name:
    type: str
  continent_name:
    type: str
  city_name:
    type: str
  location:
    type: geopoint
```
When using the Elastic Common Schema (ECS), all available geo fields that can be used are specified in the documentation: https://www.elastic.co/guide/en/ecs/current/ecs-geo.html

The value attribute will be used as default.

Currently, these types are supported: str, fp64, si32, geopoint, and ip
Save
In LogMan.io, go to Lookups.
Create a new lookup with the same name as above, i.e. "ipgeolookup". Specify two keys with the names: range1, range2.
Create records in the lookup with the ranges as keys and fields as specified above (in the example, there is only city in the value dictionary stored in the lookup).
Add the following enricher to the LogMan.io Parsec rule that should utilize the lookup:
```
define:
  type: enricher/ip
  group: geo

  schema:
    ecs:
      postfix: geo.
```
Specify the group of the lookups to be used in the group attribute. It should be the same as the group mentioned above in the lookup declaration. Tenants are resolved automatically.

The enrichment is done on every field that has the type ip in the schema.

Postfix specifies the postfix for the attribute:

If input is source.ip

Then output is source.geo.<NAME_OF_THE_ATTRIBUTE>

When it comes to default public GEO lookup (see above), the following items are filled by default:
```
  city_name:
    type: str
  country_iso_code:
    type: str
  location:
    type: geopoint
  region_name:
    type: str
```

IP address range lookup¶

The 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:
  ...

Use case: Private IP address to zone enrichment¶

You can use the IP-to-zone lookup when, based on IP address range such as 192.168.1.1 to 192.168.1.10, you want to obtain the zone name, floor name and other information (like a company's building, if it is a private or public zone etc.) etc.

Hint

Use IP-to-zone lookups for private IP address enrichment.

In LogMan.io, go to the Library.
In Library, go to the folder /Lookups.
Create a new lookup declaration for your lookup, like "ipzonelookup.yaml" with a YAML file extension
Add the following declaration:
```
define:
  type: lookup/ipaddressrange
  name: ipzonelookup
  group: zone

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

fields:
  location:
    type: geopoint
    value:
      lat: 50.0643081
      lon: 14.443938

  zone_name:
    type: str
    value: myzone

  floor_name:
    type: str
```
Make sure the type is always lookup/ipaddressrange.

Change the name in define section to your lookup name.

The group is used then in the enrichment process to locate all lookups that share the same group. The value is a unique identifier of the group (use case), here: zone

Keep the keys as they are in order to specify ranges.

To fields, add names and types of the lookup attributes. Here in the example there is only floor name, but there can also be room name, company name etc.:

yaml fields: floor_name: type: str

The value attribute will be used as default.

Currently, these types are supported: str, fp64, si32, geopoint, and ip
Save
In LogMan.io, go to Lookups.
Create a new lookup with the same name as above, i.e. "ipzonelookup". Specify two keys with the names: range1, range2.
Create records in the lookup with the ranges as keys and fields as specified above (in the example, there is only floor in the value dictionary stored in the lookup).
Add the following enricher LogMan.io Parsec rule that should utilize the lookup:
```
define:
  type: enricher/ip
  group: floor

  schema:
    ecs:
      prefix: lmio.ipenricher.
      postfix: zone.
```
Specify the group of the lookups to be used in the group attribute. It should be the same as the group mentioned above in the lookup declaration. Tenants are resolved automatically.

The enrichment is done on every field that has the type ip in the schema.

Prefix specifies the prefix, and postfix specifies the postfix for the attribute:

If input is source.ip, then output is lmio.ipenricher.source.zone.<NAME_OF_THE_ATTRIBUTE>

Single IP address lookup¶

The 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:
  ...

Use case: Bad IP addresses lookup¶

You can use bad IP enrichment when, based on a single IP address such as 192.168.1.1, you want to obtain the information about the IP's risk score, etc.

In LogMan.io, go to the Library.
In the Library, go to the folder /Lookups.
Create a new lookup declaration for your lookup, like "badips.yaml" with a YAML file extension.
Add the following declaration:
```
---
define:
  type: lookup/ipaddress
  name: badips
  group: bad

keys:
  - name: sourceip
    type: ip

fields:
  base:
    type: si32
```
Make sure the type is always lookup/ipaddress.

Change the name in define section to your lookup name.

The group is used then in the enrichment process to locate all lookups that share the same group. The value is a unique identifier of the group (use case), here: bad

Keep one key in keys section with the type ip. The name should not contain periods or any other special characters.

To fields, add names and types of the lookup attribute. Here in the example there is base as integer, but there can also be other security-related fields from https://www.elastic.co/guide/en/ecs/current/ecs-vulnerability.html:
```
fields:
  base:
    type: si32
```
Currently, these types are supported: str, fp64, si32, geopoint, and ip
Save
In LogMan.io, go to "Lookups".
Create a new lookup with the same name as above, i. e. badips. Specify the IP address as key.
Create records in the lookup with the IP address as the key and fields as specified above (in the example, there is only base in the value dictionary stored in the lookup).
Add the following enricher LogMan.io Parsec rule that should utilize the lookup:
```
define:
  type: enricher/ip
  group: bad

schema:
  ecs:
    # https://www.elastic.co/guide/en/ecs/current/ecs-vulnerability.html
    prefix: lmio.vulnerability.
    postfix: score.
```
Specify the group of the lookups to be used in the group attribute. It should be the same as the group mentioned above in the lookup declaration. Tenants are resolved automatically.

The enrichment is done on every fields, that have type ip in the schema.

Prefix is added to the field with the resolved attributes to be used for futher mapping:

If input is source.ip

Then output is lmio.vulnerability.source.score.<NAME_OF_THE_ATTRIBUTE>

Based on the attribute and the subsequent mapping, a correlation with a notification trigger can be added to /Correlators to notify about the bad IP with score's base being higher than a threshold:

---
define:
  name: Bad IP Notification
  description: Bad IP Notification
  type: correlator/window

predicate:
  !AND
  - !IN
    what: source.ip
    where: !EVENT
  - !GT
    - !ITEM EVENT lmio.vulnerability.source.score.base
    - 2

evaluate:
  dimension: [tenant, source.ip]
  by: "@timestamp"  # Name of event field with an event time
  resolution: 60  # unit is second
  saturation: 10  # unit is resolution

analyze:
  window: hopping  # that is default
  aggregate: sum  # that is default
  span: 2  # 2 * resolution from evaluate = my time window
  test:
    !GE
    - !ARG
    - 1

trigger:
  - event:
      !DICT
      type: "{str:any}"
      with:
        message: "Bad IP Notification"
        events: !ARG EVENTS
        source.ip: !ITEM EVENT source.ip
        event.dataset: correlation

  - notification:
      type: email
      to: [logman@example.co]
      template: "/Templates/Email/Notification.md"
      variables:
        !DICT
        type: "{str:any}"
        with:
          name: Bad IP Notification
          events: !ARG EVENTS
          dimension: !ITEM EVENT source.ip

Use case: IP address to asset enriment¶

Use IP-to-asset enrichment when, based on a single IP address such as 192.168.1.1, you want to obtain the information from the prepared lookup about asset information, device, host etc.

In LogMan.io, go to the Library.
In Library, go to the folder /Lookups.
Create a new lookup declaration for your lookup, like "ipassetlookup.yaml" with YAML extension
Add the following declaration:
```
---
define:
  type: lookup/ipaddress
  name: ipassetlookup
  group: asset

keys:
  - name: sourceip
    type: ip

fields:
  asset:
    type: str
```
Make sure the type is always lookup/ipaddress.

Change the name in define section to your lookup name.

The group is used then in the enrichment process to locate all lookups that share the same group. The value is a unique identifier of the group (use case), here: asset

Keep one key in keys section with the type ip. The name should not contain dots or any other special characters.

To fields, add names and types of the lookup attribute. Here in the example is the asset and hostname:
```
fields:
  asset:
    type: str
  hostname:
    type: str
```
Currently, these types are supported: str, fp64, si32, geopoint and ip
Save
In LogMan.io, go to Lookups.
Create a new lookup with the same name as above, i. e. "ipassetlookup". Specify the IP address as the key.
Create records in the lookup with the IP address as the key and fields as specified above.
Add the following enricher to the LogMan.io Parsec rule that should utilize the lookup:
```
---
define:
  type: enricher/ip
  group: asset

  schema:
    ecs:
      prefix: lmio.ipenricher.
```
Specify the group of the lookups to be used in the group attribute. It should be the same as the group mentioned above in the lookup declaration. Tenants are resolved automatically.

The enrichment is done on every field that has the type ip in the schema.

Prefix is added to the field with the resolved attributes to be used for futher mapping:

If input is source.ip, then output is lmio.ipenricher.source.<NAME_OF_THE_ATTRIBUTE>