logstash-input-beats 6.4.3-java → 6.5.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3322088036b24926aec38be292358e7acc20eb2712c77c87eef414a6df97b4a
-  data.tar.gz: 75538f2efea9abd54cfdc27c24a0aebf746ee0c8217c78cf6d26d4b720ad8107
+  metadata.gz: 1801dd24702dc3b6d751e679ecdeb78b34b2ffc23ad5ec2e236f2642ba4a0ddd
+  data.tar.gz: '0879bc47974cef2918e5c2725458bca543f2beab38e9c8f523ba848e468eb0cd'
 SHA512:
-  metadata.gz: 2b62db7a6a10181a528abb921aef2b41566fbf11acafab8c96561a6a5e13988ad2d55629567713ac0caf78836f7bc4bea822a176b9a3a59b9900236350ef1e00
-  data.tar.gz: fcb8dc51118e1381ae85aeff139b6dbad681bf8757af001cd68a58a377c456907c160c8d78cd7fbac6b13605fa9be4bbe19052d60549b71535c8c04cd96ac43a
+  metadata.gz: d779990717562cb6db36423821e3471c0e8f582a06738a248c64346c54e1e0f38cea789146941dde2c2c784e2ca1daaac82418c9ba3cbd6029a7fd5b2643f323
+  data.tar.gz: e6c6c0164ff7c827e54ad51d71832c2b79eed3ad44452ec7cc9dad86475faf25c1127756425dbb1a1783eb8d7427b280acfdfcd8088b957b848b024f40e51b47

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 6.5.0
+ - An enrichment `enrich` option added to control ECS passthrough. `ssl_peer_metadata` and `include_codec_tag` configurations are deprecated and can be managed through the `enrich`  [#464](https://github.com/logstash-plugins/logstash-input-beats/pull/464)
+
+## 6.4.4
+ - Updates Netty dependency to 4.1.87 [#466](https://github.com/logstash-plugins/logstash-input-beats/pull/466)
+
 ## 6.4.3
   - [DOC] `executor_threads` default value explanation updated. [#461](https://github.com/logstash-plugins/logstash-input-beats/pull/461)
 

data/VERSION

@@ -1 +1 @@
-6.4.3
+6.5.0

data/docs/index.asciidoc

@@ -143,26 +143,65 @@ endif::[]
 
 
 [id="plugins-{type}s-{plugin}-ecs_metadata"]
-==== Event Metadata and the Elastic Common Schema (ECS)
+==== Event enrichment and the Elastic Common Schema (ECS)
 
-When decoding {plugin-uc} events, this plugin adds two fields related to the event:
-the deprecated `host` which contains the `hostname` provided by {plugin-uc} and the
-`ip_address` containing the remote address of the client's connection. When
-<<plugins-{type}s-{plugin}-ecs_compatibility,ECS compatibility mode>> is enabled
-these are now moved in ECS compatible namespace. Here's how
-<<plugins-{type}s-{plugin}-ecs_compatibility,ECS compatibility mode>> affects
-output.  
+When decoding {plugin-uc} events, this plugin enriches each event with metadata about the event's source, making this information available during further processing. 
+You can use the <<plugins-{type}s-{plugin}-enrich>> option to activate or deactivate individual enrichment categories.
 
-[cols="<l,<l,e,<e"]
+The location of these enrichment fields depends on whether <<plugins-{type}s-{plugin}-ecs_compatibility,ECS compatibility mode>> is enabled:
+
+- When ECS compatibility is _enabled_, enrichment fields are added in an ECS-compatible structure.
+- When ECS compatibility is _disabled_, enrichment fields are added in a way that is backward-compatible with this plugin, but is known to clash with the Elastic Common Schema.
+
+
+.`source_metadata`
+[cols="<l,<l,<e",caption="Enrichment category:"]
+|=======================================================================
+|ECS `v1`, `v8` |ECS `disabled` |Description
+
+|[@metadata][input][beats][host][name]
+|[host]
+|Name or address of the {plugin-singular} host
+
+|[@metadata][input][beats][host][ip]
+|[@metadata][ip_address]
+|IP address of the {plugin-uc} client that connected to this input
+|=======================================================================
+
+.`ssl_peer_metadata`
+[cols="<l,<l,<e",caption="Enrichment category:"]
+|=======================================================================
+|ECS `v1`, `v8` |ECS `disabled` |Description
+
+|[@metadata][tls_peer][status]
+|[@metadata][tls_peer][status]
+|Contains "verified" or "unverified" label; available when SSL is enabled.
+
+|[@metadata][input][beats][tls][version_protocol]
+|[@metadata][tls_peer][protocol]
+|Contains the TLS version used (such as `TLSv1.2`); available when SSL status is "verified"
+
+|[@metadata][input][beats][tls][client][subject]
+|[@metadata][tls_peer][subject]
+|Contains the identity name of the remote end (such as `CN=artifacts-no-kpi.elastic.co`); available when SSL status is "verified"
+
+|[@metadata][input][beats][tls][cipher]
+|[@metadata][tls_peer][cipher_suite]
+|Contains the name of cipher suite used (such as `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`); available when SSL status is "verified"
+|=======================================================================
+
+.`codec_metadata`
+[cols="<l,<l,<e",caption="Enrichment category:"]
 |=======================================================================
-|ECS `disabled` |ECS `v1`, `v8` |Availability |Description
-
-|[host]                  |[@metadata][input][beats][host][name]   |Always       |Name or address of the {plugin-singular} host
-|[@metadata][ip_address] |[@metadata][input][beats][host][ip]     |Always       |IP address of the {plugin-uc} client
-|[@metadata][tls_peer][status] | [@metadata][tls_peer][status] | When SSL related fields are populated | Contains "verified"/"unverified" labels in `disabled`, `true`/`false` in `v1`/`v8`
-|[@metadata][tls_peer][protocol] | [@metadata][input][beats][tls][version_protocol] | When SSL status is "verified" | Contains the TLS version used (e.g. `TLSv1.2`)
-|[@metadata][tls_peer][subject] | [@metadata][input][beats][tls][client][subject] | When SSL status is "verified" | Contains the identity name of the remote end (e.g. `CN=artifacts-no-kpi.elastic.co`)
-|[@metadata][tls_peer][cipher_suite] | [@metadata][input][beats][tls][cipher] | When SSL status is "verified" | Contains the name of cipher suite used (e.g. `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`)
+|ECS `v1`, `v8` |ECS `disabled` |Description
+
+|[tag]
+|[tag]
+|Contains `beats_input_codec_XXX_applied` where `XXX` is the name of the codec
+
+|[event][original]
+e|N/A
+|When ECS is enabled, even if `[event][original]` field does not already exist on the event being processed, this plugin's *default codec* ensures that the field is populated using the bytes as-processed.
 |=======================================================================
 
 [id="plugins-{type}s-{plugin}-options"]
@@ -177,9 +216,10 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-cipher_suites>> |<<array,array>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-client_inactivity_timeout>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-ecs_compatibility>> | <<string,string>>|No
+| <<plugins-{type}s-{plugin}-enrich>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-executor_threads>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-host>> |<<string,string>>|No
-| <<plugins-{type}s-{plugin}-include_codec_tag>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-include_codec_tag>> |<<boolean,boolean>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-port>> |<<number,number>>|Yes
 | <<plugins-{type}s-{plugin}-ssl>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-ssl_certificate>> |a valid filesystem path|No
@@ -187,7 +227,7 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-ssl_handshake_timeout>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-ssl_key>> |a valid filesystem path|No
 | <<plugins-{type}s-{plugin}-ssl_key_passphrase>> |<<password,password>>|No
-| <<plugins-{type}s-{plugin}-ssl_peer_metadata>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-ssl_peer_metadata>> |<<boolean,boolean>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-ssl_supported_protocols>> |<<array,array>>|No
 | <<plugins-{type}s-{plugin}-ssl_verify_mode>> |<<string,string>>, one of `["none", "peer", "force_peer"]`|No
 | <<plugins-{type}s-{plugin}-tls_max_version>> |<<number,number>>|__Deprecated__
@@ -239,14 +279,72 @@ Close Idle clients after X seconds of inactivity.
 
 Refer to <<plugins-{type}s-{plugin}-ecs_metadata,ECS mapping>> for detailed information.
 
+[id="plugins-{type}s-{plugin}-enrich"]
+===== `enrich`
+
+* Value type is <<string,string>>
+** A <<list,list>> can also be provided
+** Configures which enrichments are applied to each event
+** Default value is `[codec_metadata, source_metadata]` that may be extended in future versions of this plugin to include additional enrichments.
+** Supported values are:
++
+[cols="2l,5"]
+|=======================================================================
+|Enrichment | Description
+
+| codec_metadata    | Information about how the codec transformed a sequence of bytes into
+                      this Event, such as _which_ codec was used. Also, if no <<codec>> is
+                      explicitly specified, _excluding_ `codec_metadata` from `enrich` will
+                      disable `ecs_compatibility` for this plugin.
+| source_metadata   | Information about the _source_ of the event, such as the IP address
+                      of the inbound connection this input received the event from and the
+                      name of the Logstash host that processed the event
+| ssl_peer_metadata | Detailed information about the _SSL peer_ we received the event from,
+                      such as identity information from the SSL client certificate that was
+                      presented when establishing a connection to this input
+| all               | _alias_ to include _all_ available enrichments (including additional
+                      enrichments introduced in future versions of this plugin)
+| none              | _alias_ to _exclude_ all available enrichments. Note that, _explicitly_
+                      defining <<codec>> with this option will not disable the `ecs_compatibility`,
+                      instead it relies on pipeline or codec `ecs_compatibility` configuration.
+|=======================================================================
+
+
+**Example:**
+
+This configuration disables _all_ enrichments:
+
+["source",subs="attributes"]
+--------------------------------------------------
+input {
+  beats {
+    port => 5044
+    enrich => none
+  }
+}
+--------------------------------------------------
+
+Or, to explicitly enable _only_ `source_metadata` and `ssl_peer_metadata` (disabling all others):
+
+
+["source",subs="attributes"]
+--------------------------------------------------
+input {
+  beats {
+    port => 5044
+    enrich => [source_metadata, ssl_peer_metadata]
+  }
+}
+--------------------------------------------------
+
 [id="plugins-{type}s-{plugin}-executor_threads"]
 ===== `executor_threads`
 
   * Value type is <<number,number>>
-Default value is equal to the number of CPU cores (1 executor thread per CPU core).
+  * Default value is equal to the number of CPU cores (1 executor thread per CPU core).
 
-The number of threads to be used to process incoming beats requests.
-By default, the Beats Input creates a number of threads equal to the number of CPU cores.
+The number of threads to be used to process incoming {plugin-uc} requests.
+By default, the {plugin-uc} input creates a number of threads equal to the number of CPU cores.
 These threads handle incoming connections, reading from established sockets, and executing most of the tasks related to network connection management. 
 Parsing the Lumberjack protocol is offloaded to a dedicated thread pool.
 
@@ -268,6 +366,8 @@ The IP address to listen on.
 [id="plugins-{type}s-{plugin}-include_codec_tag"]
 ===== `include_codec_tag`
 
+deprecated[6.5.0, Replaced by <<plugins-{type}s-{plugin}-enrich>>]
+
   * Value type is <<boolean,boolean>>
   * Default value is `true`
 
@@ -357,6 +457,8 @@ SSL key passphrase to use.
 [id="plugins-{type}s-{plugin}-ssl_peer_metadata"]
 ===== `ssl_peer_metadata`
 
+deprecated[6.5.0, Replaced by <<plugins-{type}s-{plugin}-enrich>>]
+
   * Value type is <<boolean,boolean>>
   * Default value is `false`
 
@@ -416,7 +518,6 @@ The minimum TLS version allowed for the encrypted connections.
 The value must be one of the following: 1.1 for TLS 1.1, 1.2 for TLS 1.2, 1.3 for TLS 1.3
 
 
-
 [id="plugins-{type}s-{plugin}-common-options"]
 include::{include_path}/{type}.asciidoc[]
 

data/lib/logstash/inputs/beats/message_listener.rb

@@ -32,11 +32,14 @@ module LogStash module Inputs class Beats
 
     def onNewMessage(ctx, message)
       hash = message.getData
-      ip_address = ip_address(ctx)
 
-      unless ip_address.nil? || hash['@metadata'].nil?
-        set_nested(hash, @input.field_hostip, ip_address)
+      if @input.include_source_metadata?
+        ip_address = ip_address(ctx)
+        unless ip_address.nil? || hash['@metadata'].nil?
+          set_nested(hash, @input.field_hostip, ip_address)
+        end
       end
+
       target_field = extract_target_field(hash)
 
       extract_tls_peer(hash, ctx)

data/lib/logstash/inputs/beats.rb

@@ -6,6 +6,7 @@ require "logstash/codecs/multiline"
 require "logstash/util"
 require "logstash-input-beats_jars"
 require "logstash/plugin_mixins/ecs_compatibility_support"
+require 'logstash/plugin_mixins/plugin_factory_support'
 require 'logstash/plugin_mixins/event_support/event_factory_adapter'
 require_relative "beats/patch"
 
@@ -58,6 +59,8 @@ class LogStash::Inputs::Beats < LogStash::Inputs::Base
 
   include LogStash::PluginMixins::EventSupport::EventFactoryAdapter
 
+  include LogStash::PluginMixins::PluginFactorySupport
+
   config_name "beats"
 
   default :codec, "plain"
@@ -104,9 +107,9 @@ class LogStash::Inputs::Beats < LogStash::Inputs::Base
 
   # Enables storing client certificate information in event's metadata. You need 
   # to configure the `ssl_verify_mode` to `peer` or `force_peer` to enable this.
-  config :ssl_peer_metadata, :validate => :boolean, :default => false
+  config :ssl_peer_metadata, :validate => :boolean, :default => false, :deprecated => "use `enrich` option to configure which enrichments to perform"
 
-  config :include_codec_tag, :validate => :boolean, :default => true
+  config :include_codec_tag, :validate => :boolean, :default => true, :deprecated => "use `enrich` option to configure which enrichments to perform"
 
   # Time in milliseconds for an incomplete ssl handshake to timeout
   config :ssl_handshake_timeout, :validate => :number, :default => 10000
@@ -136,8 +139,22 @@ class LogStash::Inputs::Beats < LogStash::Inputs::Base
   # 1.0 for TLS 1.0, 1.1 for TLS 1.1, 1.2 for TLS 1.2
   config :tls_max_version, :validate => :number, :default => TLS.max.version, :deprecated => "Set 'ssl_supported_protocols' instead."
 
+  ENRICH_DEFAULTS = {
+    'source_metadata'   => true,
+    'codec_metadata'    => true,
+    'ssl_peer_metadata' => false,
+  }.freeze
+
+  ENRICH_ALL = ENRICH_DEFAULTS.keys.freeze
+  ENRICH_DEFAULT = ENRICH_DEFAULTS.select { |_,v| v }.keys.freeze
+  ENRICH_NONE = ['none'].freeze
+  ENRICH_ALIASES = %w(none all)
+
+  config :enrich, :validate => (ENRICH_ALL | ENRICH_ALIASES), :list => true
+
   attr_reader :field_hostname, :field_hostip
   attr_reader :field_tls_protocol_version, :field_tls_peer_subject, :field_tls_cipher
+  attr_reader :include_source_metadata
 
   def register
     # For Logstash 2.4 we need to make sure that the logger is correctly set for the
@@ -189,6 +206,23 @@ class LogStash::Inputs::Beats < LogStash::Inputs::Base
       @logger.warn("configured ssl_key => #{@ssl_key.inspect} will not be used") if @ssl_key
     end
 
+    active_enrichments = resolve_enriches
+
+    @include_source_metadata = active_enrichments.include?('source_metadata')
+    @include_codec_tag = original_params.include?('include_codec_tag') ? params['include_codec_tag'] : active_enrichments.include?('codec_metadata')
+    @ssl_peer_metadata = original_params.include?('ssl_peer_metadata') ? params['ssl_peer_metadata'] : active_enrichments.include?('ssl_peer_metadata')
+
+    # intentionally ask users to provide codec when they want to use the codec metadata
+    # second layer enrich is also a controller, provide enrich => ['codec_metadata' or/with 'source_metadata'] with codec if you override event original
+    unless active_enrichments.include?('codec_metadata')
+      if original_params.include?('codec')
+        @logger.warn("An explicit `codec` is specified but `enrich` does not include `codec_metadata`. ECS compatibility will remain aligned on the pipeline or codec's `ecs_compatibility` (enabled by default).")
+      else
+        @codec = plugin_factory.codec('plain').new('ecs_compatibility' => 'disabled')
+        @logger.debug('Disabling `ecs_compatibility` for the default codec since `enrich` configuration does not include `codec_metadata` and no explicit codec is set.')
+      end
+    end
+
     # Logstash 6.x breaking change (introduced with 4.0.0 of this gem)
     if @codec.kind_of? LogStash::Codecs::Multiline
       configuration_error "Multiline codec with beats input is not supported. Please refer to the beats documentation for how to best manage multiline data. See https://www.elastic.co/guide/en/beats/filebeat/current/multiline-examples.html"
@@ -246,7 +280,7 @@ class LogStash::Inputs::Beats < LogStash::Inputs::Base
   end
 
   def client_authentication_metadata?
-    @ssl_peer_metadata && ssl_configured? && client_authentification? 
+    @ssl_peer_metadata && ssl_configured? && client_authentification?
   end
 
   def client_authentication_required?
@@ -257,6 +291,10 @@ class LogStash::Inputs::Beats < LogStash::Inputs::Base
     @ssl_verify_mode == "force_peer" || @ssl_verify_mode == "peer"
   end
 
+  def include_source_metadata?
+    return @include_source_metadata
+  end
+
   private
 
   def new_ssl_handshake_provider(ssl_context_builder)
@@ -303,4 +341,21 @@ class LogStash::Inputs::Beats < LogStash::Inputs::Base
     error_details
   end
 
+  def resolve_enriches
+    deprecated_flags_provided = %w(ssl_peer_metadata include_codec_tag) & original_params.keys
+    if deprecated_flags_provided.any? && original_params.include?('enrich')
+      raise LogStash::ConfigurationError, "both `enrich` and (deprecated) #{deprecated_flags_provided.join(',')} were provided; use only `enrich`"
+    end
+
+    aliases_provided = ENRICH_ALIASES & (@enrich || [])
+    if aliases_provided.any? && @enrich.size > 1
+      raise LogStash::ConfigurationError, "when an alias is provided to `enrich`, it must be the only value given (got: #{@enrich.inspect}, including #{aliases_provided.size > 1 ? 'aliases' : 'alias'} #{aliases_provided.join(',')})"
+    end
+
+    return ENRICH_ALL if aliases_provided.include?('all')
+    return ENRICH_NONE if aliases_provided.include?('none')
+    return ENRICH_DEFAULT unless original_params.include?('enrich')
+
+    return @enrich
+  end
 end

data/lib/logstash-input-beats_jars.rb

@@ -1,6 +1,11 @@
 # AUTOGENERATED BY THE GRADLE SCRIPT. DO NOT EDIT.
 
 require 'jar_dependencies'
-require_jar('io.netty', 'netty-all', '4.1.65.Final')
+require_jar('io.netty', 'netty-buffer', '4.1.87.Final')
+require_jar('io.netty', 'netty-codec', '4.1.87.Final')
+require_jar('io.netty', 'netty-common', '4.1.87.Final')
+require_jar('io.netty', 'netty-transport', '4.1.87.Final')
+require_jar('io.netty', 'netty-handler', '4.1.87.Final')
+require_jar('io.netty', 'netty-transport-native-unix-common', '4.1.87.Final')
 require_jar('org.javassist', 'javassist', '3.24.0-GA')
-require_jar('org.logstash.beats', 'logstash-input-beats', '6.4.3')
+require_jar('org.logstash.beats', 'logstash-input-beats', '6.5.0')

data/lib/tasks/test.rake

@@ -28,7 +28,7 @@ namespace :test do
     end
 
     namespace :setup do
-      desc "Download lastest stable version of Logstash-forwarder"
+      desc "Download latest stable version of Logstash-forwarder"
       task :lsf do
         destination = File.join(VENDOR_PATH, "logstash-forwarder")
         FileUtils.rm_rf(destination)

data/logstash-input-beats.gemspec

@@ -29,6 +29,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'jar-dependencies', '~> 0.3', '>= 0.3.4'
   s.add_runtime_dependency 'logstash-mixin-ecs_compatibility_support', '~>1.3'
   s.add_runtime_dependency 'logstash-mixin-event_support', '~>1.0'
+  s.add_runtime_dependency 'logstash-mixin-plugin_factory_support', '~>1.0'
 
   s.add_development_dependency "flores", "~>0.0.6"
   s.add_development_dependency "rspec"

data/spec/inputs/beats_spec.rb

@@ -200,6 +200,187 @@ describe LogStash::Inputs::Beats do
         expect { plugin.register }.to raise_error(LogStash::ConfigurationError, "Multiline codec with beats input is not supported. Please refer to the beats documentation for how to best manage multiline data. See https://www.elastic.co/guide/en/beats/filebeat/current/multiline-examples.html")
       end
     end
+
+    context "enrich configuration" do
+      # We define a shared example for each enrichment type that can independently
+      # validate whether that enrichment is effectively enabled or disabled.
+      #  - "#{enrichment} enabled"
+      #  - "#{enrichment} disabled"
+
+      let(:registered_plugin) { plugin.tap(&:register) }
+
+      shared_examples "source_metadata enabled" do
+        it "is configured to enrich source metadata" do
+          expect(registered_plugin.include_source_metadata).to be true
+        end
+      end
+
+      shared_examples "source_metadata disabled" do
+        it "is configured to NOT enrich source metadata" do
+          expect(registered_plugin.include_source_metadata).to be false
+        end
+      end
+
+      shared_examples "include codec tag" do
+        it "is configured to include the codec tag" do
+          expect(registered_plugin.include_codec_tag).to be true
+        end
+      end
+
+      shared_examples "exclude codec tag" do
+        it "is configured to NOT include the codec tag" do
+          expect(registered_plugin.include_codec_tag).to be false
+        end
+      end
+
+      shared_examples "default codec configured to avoid metadata" do
+        it "configures the default codec to NOT enrich codec metadata" do
+          fail("spec setup error: not compatible with explicitly-given codec") if config.include?('codec')
+          # note: disabling ECS is an _implementation detail_ of how we prevent
+          # the codec from enriching the event with [event][original]
+          expect(registered_plugin.codec.original_params).to include('ecs_compatibility' => 'disabled')
+        end
+      end
+
+      shared_examples "codec is untouched" do
+        it "does NOT configure the codec to avoid enriching codec metadata" do
+          # note: disabling ECS is an _implementation detail_ of how we prevent
+          # the codec from enriching the event with [event][original], so we ensure
+          # the absence of the setting.
+          expect(registered_plugin.codec.original_params).to_not include('ecs_compatibility')
+        end
+      end
+
+      shared_examples "codec_metadata enabled" do
+        include_examples "include codec tag"
+        include_examples "codec is untouched"
+      end
+
+      shared_examples "codec_metadata disabled" do
+        include_examples "exclude codec tag"
+        include_examples "default codec configured to avoid metadata"
+
+        context "with an explicitly-provided codec" do
+          let(:config) { super().merge("codec" => "plain") }
+
+          include_examples "exclude codec tag"
+          include_examples "codec is untouched"
+        end
+      end
+
+      shared_examples "ssl_peer_metadata enabled" do
+        it "is configured to enrich ssl_peer_metadata" do
+          expect(registered_plugin.ssl_peer_metadata).to be_truthy
+        end
+      end
+
+      shared_examples "ssl_peer_metadata disabled" do
+        it "is configured to NOT enrich ssl_peer_metadata" do
+          expect(registered_plugin.ssl_peer_metadata).to be_falsey
+        end
+      end
+
+      shared_examples "reject deprecated enrichment flags" do
+        context "with deprecated `ssl_peer_metadata`" do
+          let(:config) { super().merge("ssl_peer_metadata" => true) }
+          it 'rejects the configuration with a helpful error message' do
+            expect { plugin.register }.to raise_exception(LogStash::ConfigurationError, "both `enrich` and (deprecated) ssl_peer_metadata were provided; use only `enrich`")
+          end
+        end
+        context "with deprecated `include_codec_tag`" do
+          let(:config) { super().merge("include_codec_tag" => false) }
+          it 'rejects the configuration with a helpful error message' do
+            expect { plugin.register }.to raise_exception(LogStash::ConfigurationError, "both `enrich` and (deprecated) include_codec_tag were provided; use only `enrich`")
+          end
+        end
+      end
+
+      context "when `enrich` is NOT provided" do
+        # validate defaults
+        include_examples "codec_metadata enabled"
+        include_examples "source_metadata enabled"
+        include_examples "ssl_peer_metadata disabled"
+
+        # validate interaction with deprecated settings
+        context "with deprecated `ssl_peer_metadata => true`" do
+          let(:config) { super().merge("ssl_peer_metadata" => true) }
+
+          # intended delta
+          include_examples "ssl_peer_metadata enabled"
+
+          # ensure no side-effects
+          include_examples "codec_metadata enabled"
+          include_examples "source_metadata enabled"
+        end
+
+        context "with deprecated `include_codec_tag => false`" do
+          let(:config) { super().merge("include_codec_tag" => false) }
+
+          # intended delta
+          include_examples "exclude codec tag"
+          include_examples "codec is untouched"
+
+          # ensure no side-effects
+          include_examples "source_metadata enabled"
+          include_examples "ssl_peer_metadata disabled"
+        end
+      end
+
+      # validate aliases
+      context "alias resolution" do
+        context "with alias `enrich => all`" do
+          let(:config) { super().merge("enrich" => "all") }
+
+          include_examples "codec_metadata enabled"
+          include_examples "source_metadata enabled"
+          include_examples "ssl_peer_metadata enabled"
+
+          include_examples "reject deprecated enrichment flags"
+        end
+
+        context "with alias `enrich => none`" do
+          let(:config) { super().merge("enrich" => "none") }
+
+          include_examples "codec_metadata disabled"
+          include_examples "source_metadata disabled"
+          include_examples "ssl_peer_metadata disabled"
+
+          include_examples "reject deprecated enrichment flags"
+        end
+      end
+
+      available_enrichments = %w(
+        codec_metadata
+        source_metadata
+        ssl_peer_metadata
+      )
+      shared_examples "enrich activations" do |enrich_arg|
+        activated = Array(enrich_arg)
+        context "with `enrich => #{enrich_arg}`" do
+          let(:config) { super().merge("enrich" => enrich_arg) }
+
+          available_enrichments.each do |enrichment|
+            include_examples "#{enrichment} #{activated.include?(enrichment) ? 'enabled' : 'disabled'}"
+          end
+
+          include_examples "reject deprecated enrichment flags"
+        end
+      end
+
+      # ensure explicit empty-list does not activate defaults
+      include_examples "enrich activations", []
+
+      # ensure single enrichment does not activate others
+      available_enrichments.each do |single_active_enrichment|
+        include_examples "enrich activations", single_active_enrichment   # single
+        include_examples "enrich activations", [single_active_enrichment] # list-of-one
+      end
+
+      # ensure any combination of two enrichment categories activates only those two
+      available_enrichments.combination(2) do |active_enrichments|
+        include_examples "enrich activations", active_enrichments
+      end
+    end
   end
 
   context "tls meta-data" do

data/spec/spec_helper.rb

@@ -12,4 +12,3 @@ $: << File.realpath(File.join(File.dirname(__FILE__), "..", "lib"))
 RSpec.configure do |config|
   config.order = :rand
 end
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logstash-input-beats
 version: !ruby/object:Gem::Version
-  version: 6.4.3
+  version: 6.5.0
 platform: java
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-17 00:00:00.000000000 Z
+date: 2023-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
@@ -134,6 +134,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  name: logstash-mixin-plugin_factory_support
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
     requirements:
@@ -292,9 +306,14 @@ files:
 - spec/support/integration_shared_context.rb
 - spec/support/logstash_test.rb
 - spec/support/shared_examples.rb
-- vendor/jar-dependencies/io/netty/netty-all/4.1.65.Final/netty-all-4.1.65.Final.jar
+- vendor/jar-dependencies/io/netty/netty-buffer/4.1.87.Final/netty-buffer-4.1.87.Final.jar
+- vendor/jar-dependencies/io/netty/netty-codec/4.1.87.Final/netty-codec-4.1.87.Final.jar
+- vendor/jar-dependencies/io/netty/netty-common/4.1.87.Final/netty-common-4.1.87.Final.jar
+- vendor/jar-dependencies/io/netty/netty-handler/4.1.87.Final/netty-handler-4.1.87.Final.jar
+- vendor/jar-dependencies/io/netty/netty-transport-native-unix-common/4.1.87.Final/netty-transport-native-unix-common-4.1.87.Final.jar
+- vendor/jar-dependencies/io/netty/netty-transport/4.1.87.Final/netty-transport-4.1.87.Final.jar
 - vendor/jar-dependencies/org/javassist/javassist/3.24.0-GA/javassist-3.24.0-GA.jar
-- vendor/jar-dependencies/org/logstash/beats/logstash-input-beats/6.4.3/logstash-input-beats-6.4.3.jar
+- vendor/jar-dependencies/org/logstash/beats/logstash-input-beats/6.5.0/logstash-input-beats-6.5.0.jar
 homepage: http://www.elastic.co/guide/en/logstash/current/index.html
 licenses:
 - Apache License (2.0)