HowTo Geolocate NST API Reference

NST Geolocation API Overview

While the NST system provides many different and specialized geolocation renderings, it also provides a generic set of APIs to allow you to plot IPv4 addresses on a map. In general, this is accomplished as follows:

• You set up your NST system such that is enabled to geolocate IPv4 addresses.
• You produce a file (or stream) containing a list of IPv4 addresses.
• You feed your list of IPv4 addresses into one of the NST rendering engines.
• You get a rendering of your geolocated IPv4 addresses.

NST Geolocation APIs

URL (Google Maps)

Strengths/Weaknesses

• Extremely simple to implement.
• Highly interactive.
• Requires web browser and access to a NST system configured for geolocation.
• Does not scale well. Both the length of a URL string and the number of locations you can plot on Google Maps can be a limiting factor (not a good solution if you have thousands of IPv4 addresses to plot).
• Optional host name resolution is fairly quick.

URL API Reference

This is a extremely simple API, you start with a base URL of (change the 192.168.1.143 to the IP address of your NST system):

https://192.168.1.143/nstwui/apps/geo/map.html

The above URL will simply pull up a empty Google Map. However, the web page which renders the map also accepts the following parameters (all are optional):

NstMapIpList=IP0[+IP1[+IP2...]]

This parameter allows you to tell the page what IPv4 address you would like to have geolocated. Each IPv4 address in the list is separated by a + symbol (which corresponds to the escaped space character).

NstMapResolve=true|false

This parameter can be used to turn on (or off) name resolution. If name resolution is enabled, the names will be shown when you click on the markers on the map and pull up the information balloon.

NstMapFullScreen=true|false

If this parameter is set to true, then the map will be opened in Full Screen mode (you will only see the map in the browser window - there will be no scroll bar).

NstMapFitScreen=true|false

If this parameter set to true, then the map will be opened in Fit Screen mode (you will the map and the control area in the browser window - there will be a scroll bar).

NstMapMarkerDefault=NUMBER

This parameter controls which marker symbol is used for the IPv4 addresses that are plotted on the map. It is essentially a index (starting from 0) corresponding to the available markers shown under the Options panel.

NstMapMarkerMoved=NUMBER

This parameter controls which marker symbol is used for the IPv4 addresses that have been moved (dragged by the user) the map. It is essentially a index (starting from 0) corresponding to the available markers shown under the Options panel.

NstMapShowShadows=true|false

This controls whether or not marker shadows are shown.

NstMapAutoCenter=true|false

This parameter controls whether or not the map should try to center itself on one of the markers. This is typically only useful when you know you are plotting exactly one marker.

NstMapTypeId=hybrid|roadmap|terrain|satellite|sparse

This parameter can be used to force the initial type of map shown to the end user.

NstMapZoom=NUMBER

This parameter can be used to force the initial zoom level in the range of 0 to 15 where 0 is zoomed all the way out and 15 is zoomed all the way in.

NstMapCenterLat=LATITUDE

This parameter can be used to force the initial latitude (in the range of -90.0 to 90.0) for the location that the map will center on.

NstMapCenterLon=LONGITUDE

This parameter can be used to force the initial longitude (in the range of -180.0 to 180.0) for the location that the map will center on.

NOTE: You will typically omit all but the NstMapIpList parameter and let everything else default to the user's preferences.

Example URL

The following builds a URL string which uses the NST system 192.168.1.143 to render three IPv4 addresses (108.107.15.248, 109.154.109.210, and 98.251.209.196) on a web page (we also included the NstMapResolve parameter to force name resolution lookup for the IPv4 addresses passed):

https://192.168.1.143/nstwui/apps/geo/map.html?NstMapResolve=true&NstMapIpList=108.107.15.248+109.154.109.210+98.251.209.196

If your NST system is set up for geolocation, you should be able to:

• Copy/paste the above URL into your browser.
• Change the 192.168.1.143 to the IP address of your NST system.
• Press the enter key.
• See the three IPv4 addresses plotted on a Google Map.

You should be able change the three IPv4 addresses assigned to the NstMapIpList parameter in the URL shown above to your own custom set of IPv4 addresses.

Example Commands

Typing in IPv4 addresses by hand gets old quick. So let's take a look at a real world example where we:

• Extract a list of IPv4 addresses from a log file.
• Use a few commands to build our URL.
• Open the URL in the Google Chrome browser.

For this example, we will extract some IPv4 addresses from a Apache access file. Here is a snippet of the log file we will be extracting the IPv4 addresses from:

66.92.170.40 - - [03/May/2011:09:16:53 -0600] "GET /nst/images/nstwiki_110x32.gif HTTP/1.1" 200 2443 "http://www.networksecuritytoolkit.org/nst/" "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.60 Safari/534.24"
66.92.170.40 - - [03/May/2011:09:16:53 -0600] "GET /nst/images/nstpro_110x32.gif HTTP/1.1" 200 2375 "http://www.networksecuritytoolkit.org/nst/" "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.60 Safari/534.24"
66.92.170.40 - - [03/May/2011:09:16:53 -0600] "GET /nstpro/images/npc_conv_ge_thumb.png HTTP/1.1" 200 58331 "http://www.networksecuritytoolkit.org/nst/" "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.60 Safari/534.24"

This is a easy log file to extract the IPv4 addresses from. We'll simply combine the use of the awk command (to print the first word of each line) with the use of the sort command to filter out duplicates:

[pkb@rice ~]$ gzip -dc < /tmp/access_log.gz | awk -- '{ print $1; }' | sort -u >| /tmp/ip-list.txt
[pkb@rice ~]$ wc /tmp/ip-list.txt
 564  564 7923 /tmp/ip-list.txt
[pkb@rice ~]$ 

The following takes a list of 564 IPv4 addresses found above and builds a very long URL. It then opens the URL using Google Chrome:

[pkb@rice ~]$ MAP_URL="https://192.168.1.143/nstwui/apps/geo/map.html?NstMapResolve=true&NstMapIpList=";
[pkb@rice ~]$ SEP="${MAP_URL}"; URL="";
[pkb@rice ~]$ for ip in $(cat /tmp/ip-list.txt); do URL="${URL}${SEP}${ip}"; SEP="+"; done
[pkb@rice ~]$ google-chrome "${URL}"
Created new window in existing browser session.
[pkb@rice ~]$ 

Here is what shows up in the browser from running the commands shown above:

Geolocating IPv4 Using A URL

KML Output (Google Earth)

***Note: Section Under Construction***

Mercator (Bitmap Image)

***Note: Section Under Construction***