Description:

A lookup service that provides several types of enrichment information for IP addresses. The service is configured by providing a MaxMind Database file and specifying which types of enrichment should be provided for an IP Address or Hostname. Each type of enrichment is a separate lookup, so configuring the service to provide all of the available enrichment data may be slower than returning only a portion of the available enrichments. In order to use this service, a lookup must be performed using key of ‘ip’ and a value that is a valid IP address or hostname. View the Usage of this component and choose to view Additional Details for more information, such as the Schema that pertains to the information that is returned.

Tags:

lookup, enrich, ip, geo, ipgeo, maxmind, isp, domain, cellular, anonymous, tor

Properties:

In the list below, the names of required properties appear in bold. Any other properties (not in bold) are considered optional. The table also indicates any default values, and whether a property supports the Expression Language Guide.

Name	Default Value	Allowable Values	Description
MaxMind Database File			Path to Maxmind IP Enrichment Database File Supports Expression Language: true
Lookup Geo Enrichment	true	true false	Specifies whether or not information about the geographic information, such as cities, corresponding to the IP address should be returned
Lookup ISP	false	true false	Specifies whether or not information about the Information Service Provider corresponding to the IP address should be returned
Lookup Domain Name	false	true false	Specifies whether or not information about the Domain Name corresponding to the IP address should be returned. If true, the lookup will contain second-level domain information, such as foo.com but will not contain bar.foo.com
Lookup Connection Type	false	true false	Specifies whether or not information about the Connection Type corresponding to the IP address should be returned. If true, the lookup will contain a 'connectionType' field that (if populated) will contain a value of 'Dialup', 'Cable/DSL', 'Corporate', or 'Cellular'
Lookup Anonymous IP Information	false	true false	Specifies whether or not information about whether or not the IP address belongs to an anonymous network should be returned.

State management:

This component does not store state.

Restricted:

This component is not restricted.

Summary:

The IPLookupService is powered by a MaxMind database and can return several different types of enrichment information about a given IP address. Below is the schema of the Record that is returned by this service (in Avro Schema format). The schema is for a single record that consists of several fields: geo, isp, domainName, connectionType, and anonymousIp. Each of these fields is nullable and will be populated only if the IP address that is searched for has the relevant information in the MaxMind database and if the Controller Service is configured to return such information. Because each of the fields requires a separate lookup in the database, it is advisable to retrieve only those fields that are of value.

{
  "name": "enrichmentRecord",
  "namespace": "nifi",
  "type": "record",
  "fields": [
    {
      "name": "geo",
      "type": ["null", {
        "name": "cityGeo",
        "type": "record",
        "fields": [
		  { "name": "city", "type": ["null", "string"] },
		  { "name": "accuracy", "type": ["null", "int"], "doc": "The radius, in kilometers, around the given location, where the IP address is believed to be" },
		  { "name": "metroCode", "type": ["null", "int"] },
		  { "name": "timeZone", "type": ["null", "string"] },
		  { "name": "latitude", "type": ["null", "double"] },
		  { "name": "longitude", "type": ["null", "double"] },
		  { "name": "country", "type": ["null", {
			"type": "record",
			"name": "country",
			"fields": [
			  { "name": "name", "type": "string" },
			  { "name": "isoCode", "type": "string" }
			]
		  }] },
			{ "name": "subdivisions", "type": {
			  "type": "array",
			  "items": {
				"type": "record",
				"name": "subdivision",
				"fields": [
				  { "name": "name", "type": "string" },
				  { "name": "isoCode", "type": "string" }
				]
			  }
			}
		  },
		  { "name": "continent", "type": ["null", "string"] },
		  { "name": "postalCode", "type": ["null", "string"] }
		]
	  }]
	},
	{
	  "name": "isp",
	  "type": ["null", {
		"name": "ispEnrich",
		"type": "record",
		"fields": [
		  { "name": "name", "type": ["null", "string"] },
		  { "name": "organization", "type": ["null", "string"] },
		  { "name": "asn", "type": ["null", "int"] },
		  { "name": "asnOrganization", "type": ["null", "string"] }
		]
	  }]
	},
	{
	  "name": "domainName",
	  "type": ["null", "string"]
	},
	{
	  "name": "connectionType",
	  "type": ["null", "string"],
	  "doc": "One of 'Dial up', 'Cable/DSL', 'Corporate', 'Cellular'"
	},
	{
	  "name": "anonymousIp",
	  "type": ["null", {
		"name": "anonymousIpType",
		"type": "record",
		"fields": [
		  { "name": "anonymous", "type": "boolean" },
		  { "name": "anonymousVpn", "type": "boolean" },
		  { "name": "hostingProvider", "type": "boolean" },
		  { "name": "publicProxy", "type": "boolean" },
		  { "name": "torExitNode", "type": "boolean" }
		]
	  }]
	}
  ]
}

While this schema is fairly complex, it is a single record with 5 fields. This makes it quite easy to update an existing schema to allow for this record, by adding a new field to an existing schema and pasting in the schema above as the type.
For example, suppose that we have an existing schema that is as simple as:

{
  "name": "ipRecord",
  "namespace": "nifi",
  "type": "record",
  "fields": [
	{ "name": "ip", "type": "string" }
  ]
}

Now, let’s suppose that we want to add a new field named enrichment to the above schema. Further, let’s say that we want the new enrichment field to be nullable. We can do so by copying and pasting our enrichment schema from above thus:

{
  "name": "ipRecord",
  "namespace": "nifi",
  "type": "record",
  "fields": [
	{ "name": "ip", "type": "string" },
	{ "name": "enrichment", "type": ["null",
	  Paste Enrichment Schema Here
	]
	}
  ]
}