_
                                                                   | \
            ,---------------------------------,                  _/   >
           |      1                            \____         __/     /
           |       \                                \      _/        \
           |        \                3               '-,  |        ,-'
    ______ |         \_             / \                 \_/       /
   / ____/_|  ____  / /   ____  ___/  _\__  ____  ____  / /_  ____|_  ___  _____
  / / __/ _ \/ __ \/ / \ / __ \/ __ \/ __ \/ __ \/ __ \/ / / / /_  / / _ \/ ___/
 / /_/ /  __/ /_/ / /___/ /_/ / /_/ / /_/ / / / / /_/ / / /_/ / / /_/  __/ /
 \____/\___/\____/_____/\____/\__, /\____/_/ /_/\__,_/_/\__, / /___/\___/_/
            \             \  /____/        \           /____/  /
             |_            \ /              \                 /
               \            2                \               /
                ----.                         \             /
                    '-,_                       4            \
                        `-----,                   ,-------,  \
                               \,~.      ,---^---'         |  \
                                   \    /                   \  |
                                    \  |                     \_|
                                     `-'                    

GeoLogonalyzer is a utility to perform location and metadata lookups on source IP addresses of remote access logs. This analysis can identify anomalies based on speed of required travel, distance, hostname changes, ASN changes, VPN client changes, etc.

GeoLogonalyzer extracts and processes changes in logon characteristics to reduce analysis requirements. For example, if a user logs on 500 times from 1.1.1.1 and then 1 time from 2.2.2.2, GeoLogonalyzer will create one line of output that shows information related to the change such as:

• Detected anomalies
• Data Center Hosting information identified
• Location information
• ASN information
• Time and distance metrics

---

Preparation

MaxMind Databases

1. Make a free account for MaxMind GeoLite at https://www.maxmind.com/en/geolite2/signup
2. Download the 'GeoLite2 City - MaxMind DB binary' from https://www.maxmind.com/en/accounts/current/geoip/downloads
3. Be sure to download <GeoLite2-City_YYYYMMDD.tar.gz> and <GeoLite2-ASN_YYYYMMDD.tar.gz>
4. Extract the MMDB files from the tar.gz files.
5. Place them in the same folder as GeoLogonalyzer.py

Python

If you need to use the python source code (such as for modifiying configurations, adding custom log parsing, or running on *nix/OSX), you will need to install the following dependencies which you may not already have:

netaddr
python-geoip-python3
win_inet_pton
geopy
geoip2>=2.9.0
importlib-metadata

A pip requirements.txt is provided for your convenience.

pip install -r requirements.txt

Constants Configuration

The following constants can be modified when running the Python source code to suite your analysis needs:

| Constant Name | Default Value | Description | |---------------|---------------|-------------| | RESERVED_IP_COORDINATES | (0, 0) | Default Lat\Long coordinates for IP addresses identified as reserved | | FAR_DISTANCE | 500 | Threshold in miles for determining if two logons are "far" away from eachother | | FAST_MPH | 500 | Threshold in miles per hour for determining if two logons are "geoinfeasible" based on distance and time |

Input

CSV (Default)

By default, Geologonalyzer supports time sorted remote access logs in the following CSV format:

YYYY-MM-DD HH:MM:SS,user,10.10.10.10,hostname(optional),VPN client (optional)

Example CSV input.csv file (created entirely for demonstration purposes):

2017-11-23 10:05:02, Meghan, 72.229.28.185, Meghan-Laptop, CorpVPNClient
2017-11-23 11:06:03, Meghan, 72.229.28.185, Meghan-Laptop, CorpVPNClient
2017-11-23 12:00:00, Meghan, 72.229.28.185, Meghan-Laptop, CorpVPNClient
2017-11-23 13:00:00, Meghan, 72.229.28.185, Meghan-Laptop, CorpVPNClient
2017-11-24 10:07:05, Meghan, 72.229.28.185, Meghan-Tablet, OpenSourceVPNClient
2017-11-24 17:00:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-24 17:15:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-24 17:30:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-24 20:00:00, Meghan, 104.175.79.199, android, AndroidVPNClient
2017-11-24 21:00:00, Meghan, 104.175.79.199, android, AndroidVPNClient
2017-11-25 17:00:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-25 17:05:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-25 17:10:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-25 17:11:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-25 19:00:00, Harry, 101.0.64.1, andy-pc, OpenSourceVPNClient
2017-11-26 10:00:00, Meghan, 72.229.28.185, Meghan-Laptop, CorpVPNClient
2017-11-26 17:00:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-27 10:00:00, Meghan, 72.229.28.185, Meghan-Laptop, CorpVPNClient
2017-11-27 17:00:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-28 10:00:00, Meghan, 72.229.28.185, Meghan-Laptop, CorpVPNClient
2017-11-28 17:00:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient
2017-11-29 10:00:00, Meghan, 72.229.28.185, Meghan-Laptop, CorpVPNClient
2017-11-29 17:00:00, Harry, 97.105.140.66, Harry-Laptop, CorpVPNClient

Custom Log Formats

If you have a log format that is difficult to convert to CSV, GeoLogonalyzer supports custom log format parsing through modification of the "get_custom_details" function.

For this function, input will be a line of text, and output must contain:

return time, ip_string, user, hostname, client

Here is a Juniper PulseSecure log format and the sample code to extract required fields:

# Example Juniper Firewall Input line (wrapped on new lines):
#   Mar 12 10:59:33 FW_JUNIPER <FW_IP> PulseSecure: id=firewall time="2018-03-12 10:59:33" pri=6
#   fw=<FW_IP> vpn=<VPN_NAME> user=System realm="" roles="" type=mgmt proto= src=<SRC_IP> dst=

# Example function to fill in for "get_custom_details(line):
  # Create regex match object to find data
  juniper_2_ip_user_mo = re.compile("(time=\")([\d\ \-\:]{19})(\" .*)( user\=)(.*?)"
                                    "( realm.*? src=)(.*?)( )")

  # Match the regex
  ip_user_match = re.search(juniper_2_ip_user_mo, line)

  # Extract timestamp and convert to datetime object from "2017-03-30 00:22:42" format
  time = datetime.strptime(ip_user_match.group(2).strip(), '%Y-%m-%d %H:%M:%S')

  # Extract username and source IP (not the <FW_IP>
  user = ip_user_match.group(5).strip()
  ip_string = ip_user_match.group(7).strip()

  # Set empty hostname and client since they were not included in input
  hostname = ""
  client = ""

  return time, ip_string, user, hostname, client

---

Execution Syntax

The following command will parse the input.csv shown above and save results to output.csv:

GeoLogonalyzer --csv input.csv --output output.csv

---

Output

The output.csv file will include the following column headers:

| Column Header | Description | |-------------|-----------| | User | Username of logons compared | | Anomalies | Flags for anomalies detailed in "Automatic Anomaly Detection" section below | | 1st Time | Time of 1st compared logon | | 1st IP | IP Address of 1st compared logon | | 1st DCH | Datacenter hosting information of 1st compared logon | | 1st Country | Country associated with IP address of 1st compared logon | | 1st Region | Region associated with IP address of 1st compared logon | | 1st Coords | Lat/Long coordinates associated with IP address of 1st compared logon | | 1st ASN # | ASN number associated with IP address of 1st compared logon | | 1st ASN Name | ASN name associated with IP address of 1st compared logon | | 1st VPN Client | VPN client name associated with 1st compared logon | | 1st Hostname | Hostname associated with 1st compared logon | | 1st Streak | Count of logons by user from 1st compared source IP address before change | | 2nd Time | Time of 2nd compared logon | | 2nd IP | IP Address of 2nd compared logon | | 2nd DCH | Datacenter hosting information of 2nd compared logon | | 2nd Country | Country associated with IP address of 2nd compared logon | | 2nd Region | Region associated with IP address of 2nd compared logon | | 2nd Coords | Lat/Long coordinates associated with IP address of 2nd compared logon | | 2nd ASN # | ASN number associated with IP address of 2nd compared logon | | 2nd ASN Name | ASN name associated with IP address of 2nd compared logon | | 2nd VPN Client | VPN client name associated with 2nd compared logon | | 2nd Hostname | Hostname associated with 2nd compared logon | | Miles Diff | Difference in miles between two associated coordinates of two compared IP addresses | | Seconds Diff | Difference in time between two compared authentications | | Miles/Hour | Speed required to physically move from 1st logon location to 2nd logon location by time difference between compared logons. Miles Diff / Seconds Diff |

---

Analysis Tips

1. Unless otherwise configured (as described above), RFC1918 and other reserved IP addresses are assigned a geolocation of (0,0) which is located in the Atlantic Ocean near Africa which will skew results. a. Use the --skip_rfc1918 command line parameter to completely skip any reserved source IP address such