commit 223a742cb974d880c75814e2ab035ada17bb57f8 Author: Patrick Kelley Date: Wed May 7 14:07:52 2025 -0400 Initial diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3a89a7b --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +BSD 3-Clause License + +Copyright (c) 2020, Brim Security, Inc. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..a93ebde --- /dev/null +++ b/README.md @@ -0,0 +1,49 @@ +# geoip-conn - Add geolocation fields to `conn` logs + +## Summary + +If you have Zeek compiled with +[GeoLocation support](https://docs.zeek.org/en/current/customizations.html#address-geolocation-and-as-lookups), +this package will add a nested record called `geo` to the `conn` log that +contains fields for each originating and responding IP that describe: + +* Country code +* Region +* City +* Latitude +* Longitude +* Autonomous System Number +* Autonomous System Organization + +A [GeoLite2](https://dev.maxmind.com/geoip/geoip2/geolite2/) geolocation +database is included with the package for out-of-the-box functionality. + +## Attributions + +This package includes GeoLite2 data created by MaxMind, available from +https://www.maxmind.com. + +This package was inspired by an old Zeek script +[conn-add-geodata.bro](https://github.com/zeek/bro-scripts/blob/master/conn-add-geodata.bro) +which unfortunately lacks author or license information. Before creating this +package, a [thread on public Zeek Slack](https://zeekorg.slack.com/archives/CSZBXF6TH/p1594235715230000) +was initiated in an attempt to hunt down the author, but no definitive answer +was found. This package goes further by being delivered as a +[Zeek package](https://github.com/zeek/packages) and by adding fields for +more than just country info. + +## About the included GeoLite2 database + +Per [MaxMind documentation](https://support.maxmind.com/hc/en-us/articles/4407625342875-Upgrade-from-GeoLite2), the free +GeoLite2 database is less accurate than the paid GeoIP2 +version. While the author of this package has not attempted it, the docs +indicate that the paid version should work as a "drop-in replacement". + +The MaxMind docs also indicate the database is updated weekly, every Tuesday. +All attempts will be made to keep the database version in this repo current. +However, if you're concerned about accuracy, you may want to create your own +MaxMind login and keep your local copy up to date. + +If you delete the database files `GeoLite2-City.mmdb` and `GeoLite2-ASN.mmdb` that come with this +package, Zeek will fall back to looking for databases in default locations. See +[zeek/zeek#3547](https://github.com/zeek/zeek/pull/3547) for details. diff --git a/smoketest.sh b/smoketest.sh new file mode 100755 index 0000000..eb62481 --- /dev/null +++ b/smoketest.sh @@ -0,0 +1,28 @@ +#!/bin/bash -ex + +# On a newly-opened PR, I've seen $GITHUB_SHA gets populated with a commit +# that can't actually be checked out. The Action passes us a value for the +# latest commit SHA for the source branch to cover that case, so use that +# instead when it's there. +if [ -z "$PULL_REQUEST_HEAD_SHA" ]; then + PACKAGE_SHA="$GITHUB_SHA" +else + PACKAGE_SHA="$PULL_REQUEST_HEAD_SHA" +fi + +# Install the latest binary feature release build of Zeek per instructions at +# https://software.opensuse.org//download.html?project=security%3Azeek&package=zeek +echo 'deb http://download.opensuse.org/repositories/security:/zeek/xUbuntu_20.04/ /' | sudo tee /etc/apt/sources.list.d/security:zeek.list +curl -fsSL https://download.opensuse.org/repositories/security:zeek/xUbuntu_20.04/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/security_zeek.gpg > /dev/null +sudo apt-get update +sudo apt-get -y install zeek python3-setuptools + +# Add Zeek Package Manager and current revision of the geoip-conn package +pip3 install zkg wheel +export PATH="/opt/zeek/bin:$PATH" +zkg autoconfig +zkg install --force geoip-conn --version "$PACKAGE_SHA" +echo '@load packages' | tee -a /opt/zeek/share/zeek/site/local.zeek + +# Do a lookup of an IP that's known to have a stable location. +zeek -e "print lookup_location(199.83.220.115);" local | grep "San Francisco" diff --git a/zeek/GeoLite2-ASN.mmdb b/zeek/GeoLite2-ASN.mmdb new file mode 100644 index 0000000..40af68f Binary files /dev/null and b/zeek/GeoLite2-ASN.mmdb differ diff --git a/zeek/GeoLite2-City.mmdb b/zeek/GeoLite2-City.mmdb new file mode 100644 index 0000000..123da94 Binary files /dev/null and b/zeek/GeoLite2-City.mmdb differ diff --git a/zeek/__load__.zeek b/zeek/__load__.zeek new file mode 100644 index 0000000..00fc0b0 --- /dev/null +++ b/zeek/__load__.zeek @@ -0,0 +1 @@ +@load ./geoip-conn.zeek diff --git a/zeek/geoip-conn.zeek b/zeek/geoip-conn.zeek new file mode 100644 index 0000000..19095f5 --- /dev/null +++ b/zeek/geoip-conn.zeek @@ -0,0 +1,80 @@ +##! Populate geolocation fields in the connection logs. +##! This package includes GeoLite2 data created by MaxMind, available from +##! https://www.maxmind.com + +module Conn; + +# The following redef ensuers the .mmdb included with this package is used +# out-of-the-box. If you delete that file, Zeek will fall back to looking in +# default locations. See this link for paths: +# +# https://github.com/zeek/zeek/blob/09483619ef0839cad189f22c4d5be3d66cedcf55/src/zeek.bif#L3964-L3971 + +redef mmdb_dir = @DIR; + +export { + type GeoInfo: record { + country_code: string &optional &log; + region: string &optional &log; + city: string &optional &log; + latitude: double &optional &log; + longitude: double &optional &log; + as_number: count &optional &log; + as_org: string &optional &log; + }; + + type GeoPair: record { + orig: GeoInfo &optional &log; + resp: GeoInfo &optional &log; + }; + + redef record Conn::Info += { + geo: GeoPair &optional &log; + }; +} + +event connection_state_remove(c: connection) + { + local orig_geo: GeoInfo; + local orig_loc = lookup_location(c$id$orig_h); + if ( orig_loc?$country_code ) + orig_geo$country_code = orig_loc$country_code; + if ( orig_loc?$region ) + orig_geo$region = orig_loc$region; + if ( orig_loc?$city ) + orig_geo$city = orig_loc$city; + if ( orig_loc?$latitude ) + orig_geo$latitude = orig_loc$latitude; + if ( orig_loc?$longitude ) + orig_geo$longitude = orig_loc$longitude; + local orig_as_info = lookup_autonomous_system(c$id$orig_h); + if ( orig_as_info?$number ) + orig_geo$as_number = orig_as_info$number; + if ( orig_as_info?$organization ) + orig_geo$as_org = orig_as_info$organization; + + local resp_geo: GeoInfo; + local resp_loc = lookup_location(c$id$resp_h); + if ( resp_loc?$country_code ) + resp_geo$country_code = resp_loc$country_code; + if ( resp_loc?$region ) + resp_geo$region = resp_loc$region; + if ( resp_loc?$city ) + resp_geo$city = resp_loc$city; + if ( resp_loc?$latitude ) + resp_geo$latitude = resp_loc$latitude; + if ( resp_loc?$longitude ) + resp_geo$longitude = resp_loc$longitude; + local resp_as_info = lookup_autonomous_system(c$id$resp_h); + if ( resp_as_info?$number ) + resp_geo$as_number = resp_as_info$number; + if ( resp_as_info?$organization ) + resp_geo$as_org = resp_as_info$organization; + + local geo_pair: GeoPair; + geo_pair$orig = orig_geo; + geo_pair$resp = resp_geo; + + c$conn$geo = geo_pair; + + } diff --git a/zkg.meta b/zkg.meta new file mode 100644 index 0000000..3c81a2f --- /dev/null +++ b/zkg.meta @@ -0,0 +1,6 @@ +[package] +script_dir = zeek +description = Adds additional fields to the conn.log for the data obtained via Zeek's GeoLocation feature (https://docs.zeek.org/en/current/frameworks/geoip.html). +tags = conn, geolocation, logging +version = 1.0.0 +