Skip to content

IP Lookups

There are always three steps when using IP Lookups:

1.) Create a lookup declaration (i. e. its description)

2.) Create lookup items (i. e. its content)

3.) Add an ip enricher utilizing the lookup (its group)

IP GEO Location

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.

Public IP addresses: When the IP address from the event does not match any of the provided geo lookups, the default public IP lookup provided by LogMan.io will be used filling the core ECS GEO fields except continent_name, continent_code, postal_code, region_iso_code and timezone (see below): https://www.elastic.co/guide/en/ecs/current/ecs-geo.html

1.) In LogMan.io, go to "Library".

2.) In Library, go to "/Lookups"

3.) Create a new lookup declaration for your lookup, like "ipgeolookup.yaml" with YAML extension

4.) 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 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 ECS schema, 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.

So far, only these types are supported: str, fp64, si32, geopoint and ip

5.) Save

6.) In LogMan.io, go to "Lookups".

7.) Create a new lookup with the same name as above, i. e. ipgeolookup. Specify two keys with the names: range1, range2.

8.) 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).

9.) Add the following enricher to the parser 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 fields, that have 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
  country_name:
    type: str
  location:
    type: geopoint
  region_name:
    type: str

IP to Zone

IP to Zone is 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.

1.) In LogMan.io, go to "Library".

2.) In Library, go to "/Lookups"

3.) Create a new lookup declaration for your lookup, like "ipzonelookup.yaml" with YAML extension

4.) 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:

fields:
  floor_name:
    type: str

The value attribute will be used as default.

So far, only these types are supported: str, fp64, si32, geopoint and ip

5.) Save

6.) In LogMan.io, go to "Lookups".

7.) Create a new lookup with the same name as above, i. e. ipzonelookup. Specify two keys with the names: range1, range2.

8.) 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).

9.) Add the following enricher to the parser 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 fields, that have 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>

Bad IP Enrichment

BAD IP Enrichment is when, based on a single IP address such as 192.168.1.1, you want to obtain the information about IP's risk score etc.

1.) In LogMan.io, go to "Library".

2.) In Library, go to "/Lookups"

3.) Create a new lookup declaration for your lookup, like "badips.yaml" with YAML extension

4.) 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 dots 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

So far, only these types are supported: str, fp64, si32, geopoint and ip

5.) Save

6.) In LogMan.io, go to "Lookups".

7.) Create a new lookup with the same name as above, i. e. badips. Specify the IP address as key.

8.) 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).

9.) Add the following enricher to the parser 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>

10.) 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

IP to Asset

IP to Asset enrichment is 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.

1.) In LogMan.io, go to "Library".

2.) In Library, go to "/Lookups"

3.) Create a new lookup declaration for your lookup, like "ipassetlookup.yaml" with YAML extension

4.) 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

So far, only these types are supported: str, fp64, si32, geopoint and ip

5.) Save

6.) In LogMan.io, go to "Lookups".

7.) Create a new lookup with the same name as above, i. e. ipassetlookup. Specify the IP address as key.

8.) Create records in the lookup with the IP address as the key and fields as specified above.

9.) Add the following enricher to the parser 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 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.ipenricher.source.<NAME_OF_THE_ATTRIBUTE>