Skip to main content
Version: 2.6

Lookups

This menu [Settings > Configuration > Mapping > Lookups] can be used to create custom Lookups that may be applied in different places in the system.

Lookup is querying an additional database , CSV files, or it‘s own database with the specified value in order to map it or complete the data in a netflow session or alert with additional information. Lookups create their own fields in the system

The Lookups created in the system are listed in a table with the following columns:

Name - unique lookup name

Status - lookup status Active/Inactive

Type - Lookup type. There are five predefined types of lookups in the system: Asn, Country, CSV file, CSV file subnet, SNMP Interface

Privacy - privacy status icon

Created By - the name of the user who created the lookup

Modified By - the name of the user who last modified the lookup

Modification Time - last modification time

Shared - users who shared the object

Tags - assigned tags

Action

  • Edit - edit Lookup
  • Duplicate - creating an editable copy of the selected
  • Delete - delete Lookup
info

The Action button does not appear for system preinstalled objects.


As it was written above, the system implements six predefined types of lookups, which are listed in the table below.

Lookup typeInput keysOutput keysDescription
Asnipas.number, as.orgA system lookup for mapping IP Addresses to AS Names and AS Numbers.
CompoundA lookup that contains data from other lookups.
Countryipcontinent.code, continent.name, country.name, country.codeA system lookup for mapping IP Addresses to Country.
CSV fileA lookup built on the basis of the content of the.csv file.
SNMP InterfaceA system lookup based on SNMP poller designed for mapping Exporter IP and Exporter Interface to Interface Name, Interface Speed, Interface Description, Device Name, Device Description, Device Location.
SubnetA lookup based on CSV and designed for grouping CIDR.

Pressing the New lookup button starts the wizard to create a Lookup.

For example, to create CSV file type Lookup, perform the following steps:

  • In the first window, specify the type (see table above)

  • Enter a name for the Lookup

  • Data file

    • Edit csv button
      • File preview
      • Specify Delimeter, Quote Chart and Escape character (Default values are [comma, quotation mark, quotation mark]
      • Choose the previously prepared CSV file and load it. Then confirm the operation by pressing the Apply file button.

Privacy - assigning privileges

  • Private - accessible to the owner
  • Public - visible to all, but You can grant permission:
    • DELETE
    • EDIT
  • Shared - accessible to one or more selected User roles. Available privileges are:
    • Delete
    • Edit
    • View

Country and asn Lookup

The lookup which can be used to search data in the "GeoLite2-ASN.mmdb" and "GeoLite2-Country.mmdb" files. The lookup enables to search of dates from "BGP Autonomous System" ("GeoLite2-ASN.mmdb") and "Country" ("GeoLite2-Country.mmdb") by ip key.

Input keys

Key nameTypeDescription
IPIpAddress

Output keys for Country

Key nameTypeDescription
continentContinentFull Continent object (MaxMind)
continent.codeStringContinent code
continent.nameStringContinent full name
countryCountryFull Country object (MaxMind)
country.nameStringCountry full name
country.codeStringCountry code
registered.countryCountryull Country object (MaxMind)
registered.country.codeString
registered.country.nameString
represented.countryCountryull Country object (MaxMind)
represented.country.nameString
represented.country.codeString
full.responseCountryResponseFull CountryResponse object (MaxMind)

Output keys for ASN

Key nameTypeDescription
as.numberintAS Number
as.orgStringThe name of the organization assigned to the AS number
full.responseAsnResponseFull CountryResponse object (AsnResponse)

country lookup


CSV File Lookup

The lookup is created with a given csv file as a data source for search.

Name

The lookup name.

Description

The description of the lookup.

Edit file

In the csv file, the data will be searched by keys.

Adding the file, you must set four parameters:

Param nameDescription
DelimiterData fields delimiter file row.
QueoteCharThe char which is a prefix and suffix for text values.
EscapeCharThe char which is not interpreted in text values.
File (button)Chose the csv file

Active

Switched off - the lookup is not available.

Switched on - the lookup is available.

Tags

Mark a lookup with a specified tag.

Input keys

Key nameTypeDescription
the first column of a file

Output keys

Key nameTypeDescription
2..N column of a file

Compound Lookup

Add/Edit a new lookup of type compound, which searches by key(s) executing a sequence of one or many lookups. The data of the first key found is returned, so the order of added lookups is important.

Edit/Add compund lookup

Active

Switched off - the lookup is not available.

Switched on - the lookup is available.

Name

The lookup name.

Description

The description of the lookup.

Add key

The list of keys (columns) of the lookup to search by.

Add lookup

Add lookup data sources for search. Can be one or more lookups. For each source (lookup), we must define a mapping between source columns and current lookup keys (columns). The flag "Active" set to "off" means that the lookup will not be taken to account in the search execution sequence.

Tags

Mark a lookup with specified tags.

Example

We want to create a lookup "ColorsAndBirds" with a content of data from two "simple" lookup files, "Colors" and "Birds".

The content of the lookup csv file "Colors":

ipColorcolorNameflowInBytesattrib
172.169.34.5Yellow45643a-b-b
192.168.0.23Green45643b-x
87.98.0.23Blue45643d-a-b

The content of the lookup csv file "Birds":

ipBirdnameBsourceChannel
198.132.45.46SparrowTXR30
10.0.0.1EagleIPP28
192.168.12.23RavenINTERNAL
10.0.1.2NightingaleINTERNAL

The lookup will have two keys "ip" and "name. We identified data (values) for those columns in "Colors" and "Birds" under the different column names, so we need a mapping between a source column name and a lookup column. The mapping is optional, a key is not mapped in a specified lookup, then the search by the key for that lookup will be ignored.

Mapping:

source.column"ColorsAndBirds" key
Colors.ipColorip
Colors.colorNamename
Birds.ipBirdip
Birds.nameBname

The following compound lookup definition:

creates a compound lookup "ColorsAndBirds" with the keys->values to search by:

ipnameothe columns...
172.169.34.5YellowColors.*
192.168.0.23GreenColors.*
87.98.0.23BlueColors.*
198.132.45.46SparrowBirds.*
10.0.0.1EagleBirds.*
192.168.12.23RavenBirds.*
10.0.1.2NightingaleBirds.*

so, if for example, the lookup key is "192.168.0.23","Green", then we get data from the corresponding row in Colors lookup.


SNMP Interface Lookup:

The lookup with a data source from SNMP

Name

The lookup name.

Description

The description of the lookup.

Polling settings

ParameterT Description
Poll unresolved interfaces data everyNumber of query repeats in case no results were returned.
Refresh existing interfaces data everyThe refresh interval of existing data.
Default credentials EDEDFor each version of SNMP (v1, v2c, and v3), we can set security credentials params.

Input keys

Key nameTypeDescription
exporterIntList of StringsThe interfaces SNMP ID's taken from metrics.
exporterIpStringThe IP address of the host/exporter.

Output keys

Key nameTypeDescription
if.nameStringThe name of an interface.
if.speedintThe interface speed in bits per sec.
if.descStringThe interface description.
dev.nameStringThe name of a device.
dev.descStringThe Device description.
dev.locStringThe device location.

Subnet Lookup:

Lookup checking whether an IP address belongs to a subnet. The data is loaded from a CSV file where the first column contains the subnet definitions.

Name

The lookup name.

Description

The description of the lookup.

Mode

ParameterDescription
overlappingThe subnets can be comprised in itself and the result is a list of all matched to the IP. The list can be empty.
properThe subnets can't be comprised, and the result is exactly one found subnet or null.

Input keys

Key nameTypeDescription
the first column of a fileMixed (IpAddress, String)Requires to be a valid representation of the IP address.

Output keys

The output keys depend on the columns in the input CSV file.

Key nameTypeDescription

Lookup examples

CSV File Lookup example

  1. Go to [Settings > Configuration > Mapping > Lookups] and click Add lookup

image-20230328112819184

  1. Choose the lookup type

image-20230328112031005

  1. Complete the configuration settings for a new lookup

image-20230328112643063

Parameter NameDescription
NameLookup name
DescriptionLookup description
Data FilePlace to select the .csv file to import data. Once the CSV File lookup is created, you can view its entries by pressing the „Edit csv” button.
ActiveEnabled/Disabled rule
TagsTags assigned to the lookup
PrivacyObject access permission:
- Private (Only the creator can view this item)
- Public (Anyone in my organization can view this item, Anyone can also Delete
  1. Choose a csv file

image-20230328112916724

  1. Load a csv file

image-20230328112938896

  1. Choose a data type for imported data

image-20230328115531534

  1. Review lookup settings and click Save

image-20230328113804180

  1. Usage the lookup in a filter

image-20230328113829572


Subnet Lookup example

image-20230328114543952

image-20230328114558038


SNMP interface Lookup example

image-20230328114625831

image-20230328114638384

image-20230328114648390