geomodel is an extension to MozDef designed to trend authentication events over time for users, and identify potentially malicious account usage by comparing authentication events to an established GeoIP model for the user.

Over time, the system builds a model for a user containing known localities that user typically authenticates from. By default, a locality is defined as a region with a radius of 500km, but is configurable.

Authentication events that occur from an address Geo-located to a region that is outside the established localities for the user (e.g., not within 500km of any known login region) results in a new entry for the user, and a corresponding event notification in MozDef.

Events have associated severity values. If a new locality is identified for the user, the event has a severity of 1. Additionally, if the new locality was also in a new country, it has a severity of 2.

In addition to identifying new localities, geomodel will also analyze data for a given user to identify authentication occuring within a time window from locations that exceed a certain distance apart. For example, if authentication is seen occuring for a user from 2 locations that are over 2000km apart, and they occurred less than 4 hours apart, a severity 3 event will be created.

Authentication events are expired from the model after 30 days by default. This can be configured to increase or reduce the lifetime of data in the model for a user.

geomodel uses an ES index to store state information across intervals and runs for each user. Each known principal/user is represented by a document in this index, and these documents are updated over time. ES is the only backend supported for state storage, however the interfaces have been abstracted so others can be added as required.

geomodel uses a plugin system to indicate which events should be queried from the MozDef ES data store, and if required normalize the events. The plugins configuration option in the configuration file indicates the directory that contains the plugins.

Plugins are python scripts that read a JSON document on STDIN, parse the data if required, and return a geomodel.pluginResult JSON document via STDOUT. The JSON document that is sent on STDIN is a geomodel.pluginRequest struct, which essentially just contains the raw JSON events queried from MozDef.

Plugins contain certain comment lines that are parsed by geomodel when the plugin is loaded.

# @@ okta
# @T _type okta
# @T category okta

At least one @@ line is required, and at least one @T line is required. @@ indicates the name of the plugin generating data, and will be used in any MozDef events as required. @T adds a terms query to the plugin. In the previous example, geomodel will feed data into the plugin from MozDef that is returned using a query where _type matches okta, and category matches okta.

Once the plugins inform geomodel how to query MozDef, geomodel runs the queries and pipes and returned events into the plugins according to the state interval specified in the configuration file. The plugin results are returned to geomodel where the system incorporates the data into the existing ES state index, and creates any required events.

See plugins included in repo for examples.

When a new location is identified for a user in the model, an event is generated and sent to MozDef. The following is an example summary field in this event.

user@host.com NEWLOCATION Taipei, Taiwan access from 118.160.1.187 (test)
[deviation:12.5] last activity was from San Francisco, United States (10371 km away)
within hour before