mirror of
https://github.com/zeek/zeek.git
synced 2025-10-15 04:58:21 +00:00
1ae7d3b349
This updates the "lookup_location" and "lookup_asn" BIFs to use libmaxminddb. The motivation for this is that MaxMind is discontinuing GeoLite Legacy databases: no updates after April 1, 2018, no downloads after January 2, 2019. It's also noted that all GeoIP Legacy databases may be discontinued as they are superseded by GeoIP2.
148 lines
4.7 KiB
ReStructuredText
148 lines
4.7 KiB
ReStructuredText
|
|
.. _geolocation:
|
|
|
|
===========
|
|
GeoLocation
|
|
===========
|
|
|
|
.. rst-class:: opening
|
|
|
|
During the process of creating policy scripts the need may arise
|
|
to find the geographic location for an IP address. Bro had support
|
|
for the `GeoIP library <http://www.maxmind.com/app/c>`__ at the
|
|
policy script level from release 1.3 to 2.5.X to account for this
|
|
need. Starting with release 2.6 GeoIP support requires `libmaxminddb
|
|
<https://github.com/maxmind/libmaxminddb/releases>`__.
|
|
To use this functionality, you need to first install the libmaxminddb
|
|
software, and then install the GeoLite2 city database before building
|
|
Bro.
|
|
|
|
.. contents::
|
|
|
|
Install libGeoIP
|
|
----------------
|
|
|
|
Before building Bro, you need to install libmaxminddb.
|
|
|
|
* FreeBSD:
|
|
|
|
.. console::
|
|
|
|
sudo pkg install libmaxminddb
|
|
|
|
* RPM/RedHat-based Linux:
|
|
|
|
.. console::
|
|
|
|
sudo yum install libmaxminddb-devel
|
|
|
|
* DEB/Debian-based Linux:
|
|
|
|
.. console::
|
|
|
|
sudo apt-get install libmaxminddb-dev
|
|
|
|
* Mac OS X:
|
|
|
|
You need to install from your preferred package management system
|
|
(e.g. MacPorts, Fink, or Homebrew). The name of the package that you need
|
|
may be libmaxminddb, maxminddb, or libmaxminddb-dev, depending on which
|
|
package management system you are using.
|
|
|
|
|
|
GeoLite2-City Database Installation
|
|
-----------------------------------
|
|
|
|
Bro can use the city or country database. The city database includes cities
|
|
and regions in addition to countries.
|
|
|
|
`Download <http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz>`__
|
|
the GeoLite2 city binary database:
|
|
|
|
.. console::
|
|
|
|
wget http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz
|
|
tar zxf GeoLite2-City.tar.gz
|
|
|
|
Next, the file "GeoLite2-City_YYYYMMDD/GeoLite2-City.mmdb" needs to be renamed
|
|
and put in the GeoIP database directory. This directory should already exist
|
|
and will vary depending on which platform and package you are using. For
|
|
FreeBSD, use ``/usr/local/share/GeoIP``. For Linux, use ``/usr/share/GeoIP``
|
|
or ``/var/lib/GeoIP`` (choose whichever one already exists).
|
|
|
|
.. console::
|
|
|
|
mv <extracted subdir>/GeoLite2-City.mmdb <path_to_database_dir>/GeoLite2-City.mmdb
|
|
|
|
Testing
|
|
-------
|
|
|
|
Before using the GeoIP functionality, it is a good idea to verify that
|
|
everything is setup correctly. After installing libmaxminddb and the GeoIP
|
|
city database, and building Bro, you can quickly check if the GeoIP
|
|
functionality works by running a command like this:
|
|
|
|
.. console::
|
|
|
|
bro -e "print lookup_location(8.8.8.8);"
|
|
|
|
If you see an error message similar to "Failed to open GeoIP location
|
|
database", then you may need to either rename or move your GeoIP
|
|
location database file. Bro looks for location database files in the
|
|
following order by default:
|
|
|
|
/usr/share/GeoIP/GeoLite2-City.mmdb
|
|
/var/lib/GeoIP/GeoLite2-City.mmdb
|
|
/usr/local/share/GeoIP/GeoLite2-City.mmdb
|
|
/usr/local/var/GeoIP/GeoLite2-City.mmdb
|
|
/usr/share/GeoIP/GeoLite2-Country.mmdb
|
|
/var/lib/GeoIP/GeoLite2-Country.mmdb
|
|
/usr/local/share/GeoIP/GeoLite2-Country.mmdb
|
|
/usr/local/var/GeoIP/GeoLite2-Country.mmdb
|
|
|
|
If you see an error message similar to "Bro was not configured for GeoIP
|
|
support", then you either need to rebuild Bro and make sure it is linked
|
|
against libmaxminddb or else set the :bro:see:`mmdb_dir`` value
|
|
correctly. Normally, if libmaxminddb is installed correctly then it
|
|
should automatically be found when building Bro. If this doesn't
|
|
happen, then you may need to specify the path to the libmaxminddb
|
|
installation (e.g. ``./configure --with-geoip=<path>``).
|
|
|
|
Usage
|
|
-----
|
|
|
|
There is a built-in function that provides the GeoIP functionality:
|
|
|
|
.. code:: bro
|
|
|
|
function lookup_location(a:addr): geo_location
|
|
|
|
The return value of the :bro:see:`lookup_location` function is a record
|
|
type called :bro:see:`geo_location`, and it consists of several fields
|
|
containing the country, region, city, latitude, and longitude of the specified
|
|
IP address. Since one or more fields in this record will be uninitialized
|
|
for some IP addresses (for example, the country and region of an IP address
|
|
might be known, but the city could be unknown), a field should be checked
|
|
if it has a value before trying to access the value.
|
|
|
|
Example
|
|
-------
|
|
|
|
To show every ftp connection from hosts in Ohio, this is now very easy:
|
|
|
|
.. code:: bro
|
|
|
|
event ftp_reply(c: connection, code: count, msg: string, cont_resp: bool)
|
|
{
|
|
local client = c$id$orig_h;
|
|
local loc = lookup_location(client);
|
|
|
|
if (loc?$region && loc$region == "OH" && loc$country_code == "US")
|
|
{
|
|
local city = loc?$city ? loc$city : "<unknown>";
|
|
|
|
print fmt("FTP Connection from:%s (%s,%s,%s)", client, city,
|
|
loc$region, loc$country_code);
|
|
}
|
|
}
|
|
|