logstash-filter-geoip 7.2.9-java → 7.2.12-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ecdee3ba977a4923a88d89927163eb43a2b737d9af69e2b24bfbaeaa1287d0b
-  data.tar.gz: c10294af62a93666ba5d625c9c616aaad9567abfeb43947cfbadf87e499715c5
+  metadata.gz: 8016c2fb0b715fc6452e41ab3d36598c5fab654317362b52dc7974aba5d1dbe0
+  data.tar.gz: 9e97baedf9827069590d33a18999118401f42565e90304b127e4ab0eba111740
 SHA512:
-  metadata.gz: 892a4be2007c2627465150171d0888d4b42fe2c68d2ecc3030ffeade4332bbcc5a4660c17f834a7c5961700295f6c87e873fb44e0ed4995a9503b536809e166b
-  data.tar.gz: d8a405d1edb7970e7558d9c9679a9d18b4fe8539ea3bf53f84d28ce4e1bd0683ebabe631ef002c7214664b6b9657b98cacc3744673a0058048dba74f000866d8
+  metadata.gz: 8985a3708143ff541037379491ec98c592766a0fd6d06dd43247cbea8b2675c754475fd37300eebd247c2cd2562174acdb3f3fd19057a716550969988b560b9b
+  data.tar.gz: 5dd029823bab8ff4c816b379e9f1fe258c62a81058fda64e18f0a93d12e475750b5b62ea6bc1b5edfbe385eb93b9cfcd135389f5aa3f73518203362cdf6178ba

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 7.2.12
+  - [DOC] Add `http_proxy` environment variable for GeoIP service endpoint. The feature is included in 8.1.0, and was back-ported to 7.17.2 [#207](https://github.com/logstash-plugins/logstash-filter-geoip/pull/207) 
+
+## 7.2.11
+  - Improved compatibility with the Elastic Common Schema [#206](https://github.com/logstash-plugins/logstash-filter-geoip/pull/206)
+    - Added support for ECS's composite `region_iso_code` (`US-WA`), which _replaces_ the non-ECS `region_code` (`WA`) as a default field with City databases. To get the stand-alone `region_code` in ECS mode, you must include it in the `fields` directive. 
+    - [DOC] Improve ECS-related documentation
+
+## 7.2.10
+  - [DOC] Air-gapped environment requires both ASN and City databases [#204](https://github.com/logstash-plugins/logstash-filter-geoip/pull/204)
+
 ## 7.2.9
   - Fix: red CI in Logstash 8.0 [#201](https://github.com/logstash-plugins/logstash-filter-geoip/pull/201)
   - Update Log4j dependency to 2.17.1

data/docs/index.asciidoc

@@ -75,21 +75,25 @@ TIP: When possible, allow Logstash to access the internet to download databases
 [id="plugins-{type}s-{plugin}-manage_update"]
 ==== Manage your own database updates
 
-**Use a proxy endpoint**
+**Use an HTTP proxy**
 
 If you can't connect directly to the Elastic GeoIP endpoint, consider setting up
-a secure proxy. You can then specify the proxy endpoint URL in the
-`xpack.geoip.download.endpoint` setting in `logstash.yml` file.
+an HTTP proxy server. You can then specify the proxy with `http_proxy` environment variable.
+
+[source,sh]
+----
+export http_proxy="http://PROXY_IP:PROXY_PORT"
+----
 
 **Use a custom endpoint (air-gapped environments)**
 
 If you work in air-gapped environment and can't update your databases from the Elastic endpoint,
 You can then download databases from MaxMind and bootstrap the service.
 
-. Download your `.mmdb` database files from the
+. Download both `GeoLite2-ASN.mmdb` and `GeoLite2-City.mmdb` database files from the
 http://dev.maxmind.com/geoip/geoip2/geolite2[MaxMind site].
 
-. Copy your database files to a single directory.
+. Copy both database files to a single directory.
 
 . https://www.elastic.co/downloads/elasticsearch[Download {es}].
 
@@ -169,14 +173,57 @@ Example response:
 }
 --------------------------------------------------
 
+[id="plugins-{type}s-{plugin}-field-mapping"]
+==== Field mapping
+
+When this plugin is run with <<plugins-{type}s-{plugin}-ecs_compatibility>> disabled, the MaxMind DB's fields are added directly to the <<plugins-{type}s-{plugin}-target>>.
+When ECS compatibility is enabled, the fields are structured to fit into an ECS shape.
+
+[cols="3,5,3"]
+|===========================
+| Database Field Name | ECS Field | Example
+
+| `ip`               | `[ip]`                     | `12.34.56.78`
+
+| `city_name`        | `[geo][city_name]`         | `Seattle`
+| `country_name`     | `[geo][country_name]`      | `United States`
+| `continent_code`   | `[geo][continent_code]`    | `NA`
+| `continent_name`   | `[geo][continent_name]`    | `North America`
+| `country_code2`    | `[geo][country_iso_code]`  | `US`
+| `country_code3`    | _N/A_                      | `US`
+
+                                                    _maintained for legacy
+                                                    support, but populated
+                                                    with 2-character country
+                                                    code_
+
+| `postal_code`      | `[geo][postal_code]`       | `98106`
+| `region_name`      | `[geo][region_name]`       | `Washington`
+| `region_code`      | `[geo][region_code]`       | `WA`
+| `region_iso_code`* | `[geo][region_iso_code]`   | `US-WA`
+| `timezone`         | `[geo][timezone]`          | `America/Los_Angeles`
+| `location`*        | `[geo][location]`          | `{"lat": 47.6062, "lon": -122.3321}"`
+| `latitude`         | `[geo][location][lat]`     | `47.6062`
+| `longitude`        | `[geo][location][lon]`     | `-122.3321`
+
+| `domain`           | `[domain]`                 | `example.com`
+
+| `asn`              | `[as][number]`             | `98765`
+| `as_org`           | `[as][organization][name]` | `Elastic, NV`
+
+| `isp`              | `[mmdb][isp]`              | `InterLink Supra LLC`
+| `dma_code`         | `[mmdb][dma_code]`         | `819`
+| `organization`     | `[mmdb][organization]`     | `Elastic, NV`
+|===========================
+
+NOTE: `*` indicates a composite field, which is only populated if GeoIP lookup result contains all components.
+
 ==== Details
 
-A `[geoip][location]` field is created if
-the GeoIP lookup returns a latitude and longitude. The field is stored in
-http://geojson.org/geojson-spec.html[GeoJSON] format. Additionally,
-the default Elasticsearch template provided with the
-{logstash-ref}/plugins-outputs-elasticsearch.html[elasticsearch output] maps
-the `[geoip][location]` field to an {ref}/geo-point.html[Elasticsearch Geo_point datatype].
+When using a City database, the enrichment is aborted if no latitude/longitude pair is available.
+
+The `location` field combines the latitude and longitude into a structure called https://datatracker.ietf.org/doc/html/rfc7946[GeoJSON].
+When you are using a default <<plugins-{type}s-{plugin}-target>>, the templates provided by the {logstash-ref}/plugins-outputs-elasticsearch.html[elasticsearch output] map the field to an {ref}/geo-point.html[Elasticsearch Geo_point datatype].
 
 As this field is a `geo_point` _and_ it is still valid GeoJSON, you get
 the awesomeness of Elasticsearch's geospatial query, facet and filter functions
@@ -242,16 +289,16 @@ number of cache misses and waste memory.
 ===== `database`
 
   * Value type is <<path,path>>
-  * If not specified, the database defaults to the GeoLite2 City database that ships with Logstash.
+  * If not specified, the database defaults to the `GeoLite2 City` database that ships with Logstash.
 
-The path to MaxMind's database file that Logstash should use. The default database is GeoLite2-City.
-GeoLite2-City, GeoLite2-Country, GeoLite2-ASN are the free databases from MaxMind that are supported.
-GeoIP2-City, GeoIP2-ISP, GeoIP2-Country are the commercial databases from MaxMind that are supported.
+The path to MaxMind's database file that Logstash should use.
+The default database is `GeoLite2-City`.
+This plugin supports several free databases (`GeoLite2-City`, `GeoLite2-Country`, `GeoLite2-ASN`)
+and a selection of commercially-licensed databases (`GeoIP2-City`, `GeoIP2-ISP`, `GeoIP2-Country`).
 
-Database auto-update applies to default distribution. When `database` points to user's database path,
-auto-update will be disabled.
-See
-<<plugins-{type}s-{plugin}-database_license,Database License>> for more information.
+Database auto-update applies to the default distribution.
+When `database` points to user's database path, auto-update is disabled.
+See <<plugins-{type}s-{plugin}-database_license,Database License>> for more information.
 
 [id="plugins-{type}s-{plugin}-default_database_type"]
 ===== `default_database_type`
@@ -270,13 +317,10 @@ This plugin now includes both the GeoLite2-City and GeoLite2-ASN databases.  If
 
 An array of geoip fields to be included in the event.
 
-Possible fields depend on the database type. By default, all geoip fields
-are included in the event.
+Possible fields depend on the database type.
+By default, all geoip fields from the relevant database are included in the event.
 
-For the built-in GeoLite2 City database, the following are available:
-`city_name`, `continent_code`, `country_code2`, `country_code3`, `country_name`,
-`dma_code`, `ip`, `latitude`, `location`, `longitude`, `postal_code`, `region_code`,
-`region_name` and `timezone`.
+For a complete list of available fields and how they map to an event's structure, see <<plugins-{type}s-{plugin}-field-mapping,field mapping>>.
 
 [id="plugins-{type}s-{plugin}-ecs_compatibility"]
 ===== `ecs_compatibility`
@@ -284,7 +328,7 @@ For the built-in GeoLite2 City database, the following are available:
 * Value type is <<string,string>>
 * Supported values are:
 ** `disabled`: unstructured geo data added at root level
-** `v1`, `v8`: uses fields that are compatible with Elastic Common Schema (for example, `[client][geo][country_name]`)
+** `v1`, `v8`: use fields that are compatible with Elastic Common Schema. Example: `[client][geo][country_name]`. See <<plugins-{type}s-{plugin}-field-mapping,field mapping>> for more info. 
 * Default value depends on which version of Logstash is running:
 ** When Logstash provides a `pipeline.ecs_compatibility` setting, its value is used as the default
 ** Otherwise, the default value is `disabled`.

data/logstash-filter-geoip.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
 
   s.name            = 'logstash-filter-geoip'
-  s.version         = '7.2.9'
+  s.version         = '7.2.12'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "Adds geographical information about an IP address"
   s.description     = "This gem is a Logstash plugin required to be installed on top of the Logstash core pipeline using $LS_HOME/bin/logstash-plugin install gemname. This gem is not a stand-alone program"

data/spec/filters/geoip_ecs_spec.rb

@@ -27,6 +27,10 @@ describe LogStash::Filters::GeoIP do
         end
 
         context "with city database" do
+          # example.com, has been static for 10+ years
+          # and has city-level details
+          let(:ip) { "93.184.216.34" }
+
           let(:options) { common_options }
 
           it "should return geo in target" do
@@ -36,15 +40,23 @@ describe LogStash::Filters::GeoIP do
             expect( event.get ecs_select[disabled: "[#{target}][country_code2]", v1: "[#{target}][geo][country_iso_code]"] ).to eq 'US'
             expect( event.get ecs_select[disabled: "[#{target}][country_name]", v1: "[#{target}][geo][country_name]"] ).to eq 'United States'
             expect( event.get ecs_select[disabled: "[#{target}][continent_code]", v1: "[#{target}][geo][continent_code]"] ).to eq 'NA'
-            expect( event.get ecs_select[disabled: "[#{target}][location][lat]", v1: "[#{target}][geo][location][lat]"] ).to eq 37.751
-            expect( event.get ecs_select[disabled: "[#{target}][location][lon]", v1: "[#{target}][geo][location][lon]"] ).to eq -97.822
+            expect( event.get ecs_select[disabled: "[#{target}][location][lat]", v1: "[#{target}][geo][location][lat]"] ).to eq 42.1596
+            expect( event.get ecs_select[disabled: "[#{target}][location][lon]", v1: "[#{target}][geo][location][lon]"] ).to eq -70.8217
+            expect( event.get ecs_select[disabled: "[#{target}][city_name]", v1: "[#{target}][geo][city_name]"] ).to eq 'Norwell'
+            expect( event.get ecs_select[disabled: "[#{target}][dma_code]", v1: "[#{target}][mmdb][dma_code]"] ).to eq 506
+            expect( event.get ecs_select[disabled: "[#{target}][region_name]", v1: "[#{target}][geo][region_name]"] ).to eq 'Massachusetts'
 
             if ecs_select.active_mode == :disabled
               expect( event.get "[#{target}][country_code3]" ).to eq 'US'
+              expect( event.get "[#{target}][region_code]" ).to eq 'MA'
+              expect( event.get "[#{target}][region_iso_code]" ).to be_nil
             else
               expect( event.get "[#{target}][geo][country_code3]" ).to be_nil
               expect( event.get "[#{target}][country_code3]" ).to be_nil
+              expect( event.get "[#{target}][geo][region_iso_code]" ).to eq 'US-MA'
+              expect( event.get "[#{target}][region_code]" ).to be_nil
             end
+            puts event.to_hash.inspect
           end
         end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logstash-filter-geoip
 version: !ruby/object:Gem::Version
-  version: 7.2.9
+  version: 7.2.12
 platform: java
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-05 00:00:00.000000000 Z
+date: 2022-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement