contrast-agent 4.14.1 → 5.0.0

data/lib/contrast/agent/reporting/reporting_events/finding_request.rb

@@ -0,0 +1,121 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Finding class which will include all the needed information for the new reporting system to
+      # relay this information in the Finding/Trace messages. These findings are used by TeamServer to construct the
+      # vulnerability information for the assess feature. They represent those parts of the application, either through
+      # configuration, method invocation, or dataflow, which are determined to be insecure.
+      #
+      # @attr_accessor events [Array<Contrast::Agent::Assess::ContrastEvent>] if a dataflow based finding, the
+      #   representation of those method calls which constitute a dangerous code path.
+      # @attr_accessor properties [Hash<String,String>] a set of values that TeamServer can use to provide more context
+      #   to the user when rendering the finding. For some findings, a specific set of keys and values are required.
+      # @attr_accessor request [Contrast::Agent::Request, nil] the request, if any, in which this finding occurred
+      # @attr_accessor hash_code [String] the unique identifier of this finding.
+      # @attr_reader rule_id [String] the name of the rule violated; must match those in TeamServer.
+      class FindingRequest
+        attr_reader :body, :headers, :method, :parameters, :port, :protocol, :query_string, :uri, :version
+
+        class << self
+          # @param request [Contrast::Api::Dtm::HttpRequest,Contrast::Agent::Request]
+          # @return [Contrast::Agent::Reporting::FindingRequest]
+          def convert request
+            report = new
+            if request.cs__is_a?(Contrast::Agent::Request)
+              report.attach_data(request)
+            else
+              report.attach_dtm_data(request)
+            end
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Request to attach what is required for reporting to TeamServer to this
+        # Contrast::Agent::Reporting::FindingRequest
+        #
+        # @param request [Contrast::Agent::Request]
+        def attach_data request
+          @body = request.body
+          @headers = {}
+          request.headers.each_pair do |key, value|
+            next unless key && value
+
+            # We need to change from the uppercase _ format to capitalized - format.
+            header = key.split('_')
+            header.each(&:capitalize!)
+            header = header.join('-')
+            headers[header] = value.split
+          end
+          @method = request.request_method
+          @parameters = {}
+          request.parameters.each_pair do |key, value|
+            @parameters[key] = value
+          end
+          @port = request.port || 0
+          @protocol = request.scheme
+          @query_string = request.query_string
+          @uri = request.normalized_uri
+          @version = request.version
+        end
+
+        # Parse the data from a Contrast::Api::Dtm::HttpRequest to attach what is required for reporting to TeamServer
+        # to this Contrast::Agent::Reporting::FindingRequest
+        #
+        # @param request_dtm [Contrast::Api::Dtm::HttpRequest]
+        def attach_dtm_data request_dtm
+          @body = request_dtm.request_body_binary
+          @headers = {}
+          request_dtm.request_headers.each_pair do |key, value|
+            next unless key && value
+
+            # We need to change from the uppercase _ format to capitalized - format.
+            header = key.split('_')
+            header.each(&:capitalize!)
+            header = header.join('-')
+            headers[header] = value.split
+          end
+          @method = request_dtm.method # rubocop:disable Security/Object/Method
+          @parameters = {}
+          request_dtm.normalized_request_params.each_value do |pair|
+            @parameters[pair.key] = pair.values
+          end
+          @port = nil
+          @protocol = request_dtm.protocol
+          @query_string = request_dtm.query_string
+          @uri = request_dtm.uri
+          @version = request_dtm.version
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {
+              body: body,
+              headers: headers,
+              method: method, # rubocop:disable Security/Object/Method
+              parameters: parameters,
+              port: port || 0,
+              protocol: protocol,
+              queryString: query_string,
+              uri: uri,
+              version: version
+          }
+        end
+
+        def validate
+          unless cs__method && !cs__method.empty?
+            raise(ArgumentError, "#{ self } did not have a proper method. Unable to continue.")
+          end
+          raise(ArgumentError, "#{ self } did not have a proper uri. Unable to continue.") unless uri && !uri.empty?
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/finding_signature.rb

@@ -0,0 +1,105 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/utils/object_share'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingSignature class which will include all the needed information for the new reporting
+      # system to relay this information in the Finding/Trace messages. These FindingObjects are used by TeamServer to
+      # construct the vulnerability information for the assess feature. They represent the signature of the method that
+      # was invoked in this event.
+      #
+      # @attr_reader arg_types [String] the types of the arguments in this event; may be different for each invocation
+      #   of the method.
+      # @attr_reader class_name [String] the name of the class of this object or the name itself if of Module type.
+      # @attr_reader constructor [Boolean] if the method is a constructor or not.
+      # @attr_reader expression_type [String] unused.
+      # @attr_reader flags [Integer] the Java flags.
+      # @attr_reader method_name [String] the name of the method.
+      # @attr_reader operator [String] unused.
+      # @attr_reader return_type [String] the type of the return in this event; may be different for each invocation of
+      #   the method.
+      # @attr_reader signature [String] the id of the Object this represents.
+      # @attr_reader void_method [Boolean] if the method is void or not; may be different for each invocation of the
+      #   method.
+      class FindingSignature
+        attr_reader :arg_types, :class_name, :constructor, :expression_type, :flags, :method_name, :operator,
+                    :return_type, :signature, :void_method
+
+        class << self
+          # @param event [Contrast::Agent::Assess::ContrastEvent] the event to build a signature for
+          # @return [Contrast::Agent::Reporting::FindingSignature]
+          def convert event
+            report = new
+            report.attach_data(event)
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Assess::ContrastEvent to attach what is required for reporting to
+        # TeamServer to this Contrast::Agent::Reporting::FindingSignature
+        #
+        # @param event [Contrast::Agent::Assess::ContrastEvent]
+        def attach_data event
+          node = event.policy_node
+          @arg_types = []
+          event.args&.each do |arg|
+            arg_types << type_name(arg)
+          end
+          @class_name = node.class_name
+          @constructor = node.method_name == :new || node.method_name == :initialize
+          # 8 is STATIC in Java... we have to placate them for now it has been requested that flags be removed since it
+          # isn't used
+          @flags = 8 unless policy_node.instance_method?
+          @method_name = node.method_name
+          @return_type = type_name(event.ret)
+          # if there's a ret, then this method isn't nil. not 100% full proof since you can return nil, but this is the
+          # best we've got currently.
+          @void_method = event.ret.nil? ||
+              event.ret.object.nil? ||
+              event.ret.object == Contrast::Utils::ObjectShare::NIL_STRING
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {
+              argTypes: arg_types,
+              className: class_name,
+              constructor: constructor,
+              # expressionType: expression_type, # This is unused by the Ruby agent
+              flags: flags.to_i,
+              methodName: method_name,
+              # operator: operator, # This is unused by the Ruby agent
+              returnType: return_type,
+              # signature: signature, # This is unused by the Ruby agent
+              voidMethod: void_method
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper argTypes. Unable to continue.") unless arg_types
+          raise(ArgumentError, "#{ self } did not have a proper constructor. Unable to continue.") if constructor.nil?
+        end
+
+        private
+
+        # While Ruby signatures do not require neither a return type and can return anything depending on inputs, code
+        # paths, etc, nor constant parameter types, TeamServer was designed with strongly typed languages (Java) in
+        # mind, so we need types in our signatures.
+        #
+        # @param contrast_object [Contrast::Agent::Assess::ContrastObject, nil] the object to find the type of
+        # @return [String] the name of the module of the ret_obj, or `nil`
+        def type_name contrast_object
+          contrast_object ? contrast_object.object_type : Contrast::Utils::ObjectShare::NIL_STRING
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/finding_stack.rb

@@ -0,0 +1,67 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingStack class which will include all the needed information for the new reporting system
+      # to relay this information in the Finding/Trace messages. These FindingStack are used by TeamServer to construct
+      # the vulnerability information for the assess feature. They represent the callstack at the time that each
+      # FindingEvent was generated.
+      #
+      # @attr_reader eval [String] unused
+      # @attr_reader file [String] the stack frame to show in TeamServer; the value of an entry in #caller
+      # @attr_reader line_number [String] unused
+      # @attr_reader method [String] unused
+      # @attr_reader signature [String] unused
+      # @attr_reader type [String] unused
+      class FindingStack
+        attr_reader :eval, :file, :line_number, :method, :signature, :type
+
+        AGENT_CLASS_MARKER = '/lib/contrast/'
+
+        class << self
+          # @param stack [Array<String>]
+          # @return [Contrast::Agent::Reporting::FindingStack,nil]
+          def convert stack
+            return unless stack
+            return if stack.include?(AGENT_CLASS_MARKER)
+
+            report = new
+            report.attach_data(stack)
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Assess::Tag to attach what is required for reporting to TeamServer to
+        # this Contrast::Agent::Reporting::FindingTaintRange
+        #
+        # @param stack [Array<String>]
+        def attach_data stack
+          @file = stack
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {
+              # eval: eval,
+              file: file # ,
+            # line_number: line_number, # This is unused by the Ruby agent
+            # method: method, # This is unused by the Ruby agent
+            # signature: signature, # This is unused by the Ruby agent
+            # type: type  # This is unused by the Ruby agent
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper hash. Unable to continue.") unless file && !file.empty?
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/finding_taint_range.rb

@@ -0,0 +1,58 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new FindingObject class which will include all the needed information for the new reporting system
+      # to relay this information in the Finding/Trace messages. These FindingTaintRanges are used by TeamServer to
+      # construct the vulnerability information for the assess feature. They represent those parts of the objects that
+      # are tracked because of a security relevant operation acting on them.
+      #
+      # @attr_reader range [String] the range (inclusive:exclusive), that this tag covers.
+      # @attr_reader tag [String] the type of action this tag represents.
+      class FindingTaintRange
+        attr_reader :range, :tag
+
+        class << self
+          # @param tag [Contrast::Agent::Assess::Tag] the tag to convert
+          # @return [Contrast::Agent::Reporting::FindingTaintRange]
+          def convert tag
+            report = new
+            report.attach_data(tag)
+            report
+          end
+        end
+
+        # Parse the data from a Contrast::Agent::Assess::Tag to attach what is required for reporting to TeamServer to
+        # this Contrast::Agent::Reporting::FindingTaintRange
+        #
+        # @param tag [Contrast::Agent::Assess::Tag] the tag to convert
+        def attach_data tag
+          @range = "#{ tag.start_idx }:#{ tag.end_idx }"
+          @tag = tag.label
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          {
+              range: range,
+              tag: tag
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper hash. Unable to continue.") unless hash && !hash.empty?
+          return unless value && !value.empty?
+
+          raise(ArgumentError, "#{ self } did not have a proper value. Unable to continue.")
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/library_discovery.rb

@@ -0,0 +1,93 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/api/dtm.pb'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Library Discovery class which will include all the needed information for the new
+      # reporting system to relay this information in the Application Update messages. These libraries are used by
+      # TeamServer to construct the dependency information for the SCA feature. They represent those gems that are
+      # included in the GemSpec, not necessarily those that have had files in them required.
+      #
+      # @attr_reader class_count [Integer] the number of files in the Gem which contain code.
+      # @attr_reader external_date [Integer] the time, in ms, when the Gem was published. Required for reporting.
+      # @attr_reader file [String] the name of the Gem. Required for reporting.
+      # @attr_reader hash [String] the Sha256 of the Gem, matching its hash in RubyGems. Required for reporting.
+      # @attr_reader internal_date [Integer] the time, in ms, when the Gem was published. Required for reporting.
+      # @attr_reader manifest [String] the YAML form of the Gem's specification.
+      # @attr_reader tags [String] Inventory tags set by the user via configuration.
+      # @attr_reader url [String] The homepage of the Gem.
+      # @attr_reader version [String] The version of the Gem.
+      class LibraryDiscovery
+        # required attributes
+        attr_reader :external_date, :file, :hash, :internal_date
+        # optional attributes
+        attr_reader :class_count, :manifest, :tags, :url, :version
+
+        class << self
+          # Convert a DTM for SpeedRacer to an Event for TeamServer.
+          #
+          # @param library_dtm [Contrast::Api::Dtm::Library]
+          # @return [Contrast::Agent::Reporting::LibraryDiscovery]
+          def convert library_dtm
+            report = new
+            report.attach_data(library_dtm)
+            report
+          end
+        end
+
+        # Attach the data from the protobuf models to this reporter so that it can be sent to TeamServer directly
+        #
+        # @param library_dtm [Contrast::Api::Dtm::Library]
+        def attach_data library_dtm
+          @class_count = library_dtm.class_count
+          @external_date = library_dtm.external_ms
+          @file = library_dtm.file_path
+          @hash = library_dtm.hash_code
+          @internal_date = library_dtm.internal_ms
+          @manifest = library_dtm.manifest
+          @tags = Contrast::INVENTORY.tags
+          @url = library_dtm.url
+          @version = library_dtm.version
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          msg = {
+              classCount: class_count,
+              externalDate: external_date,
+              file: file,
+              hash: hash,
+              internalDate: internal_date,
+              manifest: manifest,
+              url: url,
+              version: version
+          }
+          msg[:tags] = tags if tags
+          msg
+        end
+
+        # Ensure the required fields are present.
+        #
+        # @raise [ArgumentError]
+        def validate
+          unless external_date
+            raise(ArgumentError, "#{ self } did not have a proper external date. Unable to continue.")
+          end
+          unless internal_date
+            raise(ArgumentError, "#{ self } did not have a proper internal date. Unable to continue.")
+          end
+          raise(ArgumentError, "#{ self } did not have a proper file. Unable to continue.") unless file
+          raise(ArgumentError, "#{ self } did not have a proper hash. Unable to continue.") unless hash
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/library_usage_observation.rb

@@ -0,0 +1,50 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+module Contrast
+  module Agent
+    module Reporting
+      #
+      # @attr_accessor id - [String]  - Hash of library as identified by the agent
+      # @attr_accessor names Array[String] - List of file paths that have been loaded out of or executed by the library
+      #
+      class LibraryUsageObservation
+        attr_accessor :id, :names
+
+        class << self
+          # Convert a DTM for SpeedRacer to an Event for TeamServer.
+          #
+          # @param usage_dtm [Contrast::Api::Dtm::LibraryUsageUpdate]
+          # @return [Contrast::Agent::Reporting::LibraryUsageObservation]
+          def convert usage_dtm
+            observation = new
+            observation.attach_data(usage_dtm)
+            observation
+          end
+        end
+
+        def initialize
+          @names = []
+        end
+
+        def attach_data usage_dtm
+          @id = usage_dtm.hash_code
+          @names = usage_dtm.class_names.keys
+        end
+
+        def to_controlled_hash
+          validate
+          {
+              id: @id,
+              names: @names
+          }
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper id. Unable to continue.") unless id
+          raise(ArgumentError, "#{ self } did not have a proper names. Unable to continue.") if names.empty?
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/observed_library_usage.rb

@@ -0,0 +1,54 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/reporting_events/reporting_event'
+require 'contrast/agent/reporting/reporting_events/library_usage_observation'
+
+module Contrast
+  module Agent
+    module Reporting
+      # List of libraries that have been observed to have something loaded or executed.
+      #
+      # @attr_reader observations - Array[Contrast::Agent::Reporting::LibraryUsageObservation]
+      #                            - Hash of LibraryUsageObservations
+      class ObservedLibraryUsage < Contrast::Agent::Reporting::ReportingEvent
+        attr_reader :observations
+
+        class << self
+          # Convert a Hash of LibraryUsageUpdate DTMs for SpeedRacer to an Event for TeamServer.
+          #
+          # @param usages_dtm_hash Hash[Contrast::Api::Dtm::LibraryUsageUpdate]
+          # @return [Contrast::Agent::Reporting::ObservedLibraryUsage]
+          def convert usages_dtm_hash
+            report = new
+            report.attach_data(usages_dtm_hash)
+            report
+          end
+        end
+
+        def initialize
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints.library_usage
+          @observations = []
+          super
+        end
+
+        def to_controlled_hash
+          validate
+          { observations: @observations.map(&:to_controlled_hash) }
+        end
+
+        def attach_data usages_dtm_hash
+          usages_dtm_hash.each do |_key, value|
+            next unless value.class_names.any?
+
+            @observations << Contrast::Agent::Reporting::LibraryUsageObservation.convert(value)
+          end
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have observations. Unable to continue.") if observations.empty?
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/observed_route.rb

@@ -0,0 +1,66 @@
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'json'
+require 'contrast/components/logger'
+require 'contrast/agent/reporting/reporting_events/reporting_event'
+require 'contrast/utils/object_share'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This is the new Route Observation class which will include all the needed information for the new reporting
+      # system to relay this information in the Route Observation messages. These observations are used by TeamServer
+      # to construct the route coverage information for the assess feature. They represent those methods which map to
+      # externally accessible endpoints within the application, as registered to the application framework. This also
+      # includes the literal URL and HTTP Verb used to invoke them, as they must have been called at this point to be
+      # recorded.
+      #
+      # @attr_accessor signature [String] the method signature used to uniquely identify the coverage report.
+      # @attr_accessor url [String] the normalized URL used to access the method in the route.
+      # @attr_accessor verb [String] the HTTP Verb used  to access the method in the route.
+      # @attr_accessor agent_session_id_value [Integer] the session of this process, as determined from TeamServer on
+      #   application create.
+      # @attr_accessor sources [Array<Contrast::Agent::Reporting::TraceEventSource>] the sources of user input accessed
+      #   during this request. Used for remediation determinations in TeamServer.
+      class ObservedRoute < Contrast::Agent::Reporting::ReportingEvent
+        attr_accessor :sources, :agent_session_id_value, :signature, :verb, :url
+
+        def initialize
+          @event_endpoint = Contrast::Agent::Reporting::Endpoints.observed_route
+          @sources = []
+          @signature = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @verb = Contrast::Utils::ObjectShare::EMPTY_STRING
+          @url = Contrast::Utils::ObjectShare::EMPTY_STRING
+          super()
+        end
+
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
+          validate
+          rc_hash = {
+              session_id: @agent_session_id_value,
+              sources: @sources,
+              signature: @signature,
+              verb: @verb,
+              url: @url
+          }
+          rc_hash.delete(:verb) unless @verb
+          rc_hash
+        end
+
+        def validate
+          raise(ArgumentError, "#{ self } did not have a proper sources. Unable to continue.") if @sources.nil?
+          raise(ArgumentError, "#{ self } did not have a proper signature. Unable to continue.") unless signature
+          raise(ArgumentError, "#{ self } did not have a proper url. Unable to continue.") unless url
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/reporting_events/preflight.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# Copyright (c) 2022 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
 # frozen_string_literal: true
 
 require 'contrast/agent/reporting/reporting_events/reporting_event'
@@ -6,17 +6,31 @@ require 'contrast/agent/reporting/reporting_events/reporting_event'
 module Contrast
   module Agent
     module Reporting
-      # This class here will hold the needed preflights we will send for certain trace/traces
+      # This is the new Preflight class which will include all the needed information for the new reporting system
+      # to report a Preflight message to TeamServer. This message represents the identifying information of a
+      # collection of Findings/Traces, which TeamServer will use to determine if it requires the full information of
+      # any of the Findings/Traces to be reported.
+      #
+      # For our purposes, we'll only ever send one message per request; however, we must use an array to conform to the
+      # specification.
+      #
+      # @attr_reader messages [Array<Contrast::Agent::Reporting::PreflightMessage>]
       class Preflight < Contrast::Agent::Reporting::ReportingEvent
-        attr_accessor :messages
+        attr_reader :messages
 
         def initialize
-          super
-          @event_type = :preflight
+          @event_method = :PUT
+          @event_endpoint = "#{ Contrast::API.api_url }/api/ng/preflight/"
           @messages = []
+          super
         end
 
-        def to_controlled_hash **_args
+        # Convert the instance variables on the class, and other information, into the identifiers required for
+        # TeamServer to process the JSON form of this message.
+        #
+        # @return [Hash]
+        # @raise [ArgumentError]
+        def to_controlled_hash
           { messages: @messages }
         end
       end