logstash-filter-geoip 7.2.10-java → 7.2.11-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e7b28476c126af68bc29d44c7d64ec15aa5e09eed39c45a53d1c52d62f6c2c4
-  data.tar.gz: 6679da72cdaf947fccaf8140a82019668bf6c099f708638fdcf15e0dde8701a6
+  metadata.gz: 4e1f0799be232e80ed3db8f0d31b4131c921d549183d2f47678af3fd9cdfd21f
+  data.tar.gz: e656dd5cd6440d13af48a7193f26962c4236267fcf2afd9bc0a9f4f8e8c5e3e5
 SHA512:
-  metadata.gz: fc1051fee22e58527e8e091108f9e24d5f314ea92357817bf700765863c6bb320bca5f59835f1a873bb40f4f26df9c1847c18babdc1ebccb94d9f0e60d916f03
-  data.tar.gz: 694bbeeec97b179ccc6d52d5c94a56dfbe693c4bef95a44cbaadaa9bda2bc84b8e6c0eb5b6e73a8b94fb8930a649e59fa4a0f3206b4616baedabcf90015e0372
+  metadata.gz: eadc947645031bd5539ac42e910da0c1230d2137936eec668f23da4e6de6e55b5ceaa2a6eb1cf0b7699a43d61c03c1e6df95b51681e61d3983471070d1cac9aa
+  data.tar.gz: 9a5ee36471512f5724ebc7013d3d21bce6d64db50ac6874f8c45d2e8a8facbad14a428e4ea2857cbeb20d438e363dbcdad79a6133b851c98c575a82da0e91a1f

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 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)
 

data/docs/index.asciidoc

@@ -169,14 +169,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 +285,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 +313,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 +324,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.10'
+  s.version         = '7.2.11'
   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.10
+  version: 7.2.11
 platform: java
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-14 00:00:00.000000000 Z
+date: 2022-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement