contrast-agent 3.8.4 → 6.9.0

data/lib/contrast/agent/reporting/settings/protect_server_feature.rb

@@ -0,0 +1,227 @@
+# 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'
+require 'contrast/agent/reporting/settings/bot_blocker'
+require 'contrast/agent/reporting/settings/ip_filter'
+require 'contrast/agent/reporting/settings/log_enhancer'
+require 'contrast/agent/reporting/settings/rule_definition'
+require 'contrast/agent/reporting/settings/syslog'
+require 'contrast/agent/reporting/settings/helpers'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This module will hold all the settings from the TS responce
+      module Settings
+        # Application level settings for the Protect featureset.
+        # Used for the FeatureSet TS response
+        class ProtectServerFeature
+          PROTECT_RULES_KEYS = %i[
+            cmd_injection method_tampering nosql_injection path_traversal redos reflected_xss sql_injection
+            ssrf unsafe_file_upload untrusted_deserialization xxe
+          ].cs__freeze
+          # Indicate if the protect feature set is enabled for this server or not.
+          #
+          # @return enabled [Boolean]
+          def enabled?
+            @_enabled
+          end
+
+          # Set the enabled
+          #
+          # @param enabled [Boolean]
+          # @return enabled [Boolean]
+          def enabled= enabled
+            @_enabled = enabled
+          end
+
+          # When false, the agent should not track observations.
+          # when true, the agent should track observed usage of protect URLs
+          #  { enable: true }
+          #
+          # @return observability [Boolean]
+          def observability
+            @_observability
+          end
+
+          # @param enable [Boolean]
+          # @return observability [Boolean]
+          def observability= enable
+            @_observability = enable
+          end
+
+          # Indicate if the bot protection feature set is enabled for this server or not.
+          #
+          # @return bot_blocker [Contrast::Agent::Reporting::Settings::BotBlocker]
+          def bot_blocker
+            @_bot_blocker ||= Contrast::Agent::Reporting::Settings::BotBlocker.new
+          end
+
+          # The IP addresses for which to disable protection.
+          #
+          # @return ip_allowlist [Array<Contrast::Agent::Reporting::Settings::IpFilter>, []]
+          #   expires [Integer] The time after which the filter is no longer valid.
+          #   ip      [String] The IP or range of IPs to which this message pertains.
+          #   name    [String] The user defined name of the filter.
+          #   uuid    [String] The identifier of the filter as defined by TeamServer.
+          def ip_allowlist
+            @_ip_allowlist ||= []
+          end
+
+          # set ip_allowlist
+          #
+          # @param allowlist [array<IpFilter>] of IpFilter: {
+          #   expires [Integer] The time after which the filter is no longer valid.
+          #   ip      [String] The IP or range of IPs to which this message pertains.
+          #   name    [String] The user defined name of the filter.
+          #   uuid    [String] The identifier of the filter as defined by TeamServer.
+          # }
+          # @return ip_allowlist [Array<Contrast::Agent::Reporting::Settings::IpFilter>]
+          def ip_allowlist= allowlist
+            Contrast::Agent::Reporting::Settings::Helpers.array_to_iv(Contrast::Agent::Reporting::Settings::IpFilter,
+                                                                      ip_allowlist,
+                                                                      allowlist)
+          end
+
+          # The IP addresses for which to disable protection.
+          #
+          # @return ip_denylist [Array<IpFilter>, []]
+          #                     expires [Integer] The time after which the filter is no longer valid.
+          #                     ip      [String] The IP or range of IPs to which this message pertains.
+          #                     name    [String] The user defined name of the filter.
+          #                     uuid    [String] The identifier of the filter as defined by TeamServer.
+          def ip_denylist
+            @_ip_denylist ||= []
+          end
+
+          # set ip_denylist
+          #
+          # @param denylist [array] of IpFilter: {
+          #   expires [Integer] The time after which the filter is no longer valid.
+          #   ip      [String] The IP or range of IPs to which this message pertains.
+          #   name    [String] The user defined name of the filter.
+          #   uuid    [String] The identifier of the filter as defined by TeamServer.
+          # }
+          # @return ip_denylist [Array<Contrast::Agent::Reporting::Settings::IpFilter>]
+          def ip_denylist= denylist
+            Contrast::Agent::Reporting::Settings::Helpers.array_to_iv(Contrast::Agent::Reporting::Settings::IpFilter,
+                                                                      ip_denylist,
+                                                                      denylist)
+          end
+
+          # All of the apis to add new logging calls to the application at runtime.
+          #
+          # @return log_enhancers [Array<Contrast::Agent::Reporting::Settings::LogEnhancer>, []]
+          def log_enhancers
+            @_log_enhancers ||= []
+          end
+
+          # All of the apis to add new logging calls to the application at runtime.
+          #
+          # @param log_enhancers_array [Array<LogEnhancers>] of LogEnhancers: {
+          #    api     [String]  The method signature to instrument, as understood by the agent.
+          #    format  [String]  The format of the message to log.
+          #    id      [Integer] The identifier of the enhancer as defined by TeamServer.
+          #    level   [String] The level at which to log this message. Trace as 0 and Error as 4.
+          #                     [ TRACE, DEBUG, INFO, WARN, ERROR ]
+          #    name    [String] The user defined name of the enhancer.
+          #    type    [String] The type of log message to generate. Audit as 0, Security as 2.
+          #                     [ AUDIT, ERROR, SECURITY ]
+          # }
+          # @return log_enhancers [Array<Contrast::Agent::Reporting::Settings::LogEnhancer>]
+          def log_enhancers= log_enhancers_array
+            Contrast::Agent::Reporting::Settings::Helpers.array_to_iv(Contrast::Agent::Reporting::Settings::LogEnhancer,
+                                                                      log_enhancers,
+                                                                      log_enhancers_array)
+          end
+
+          # The keywords and patterns required for the input analysis of each rule with that capability.
+          #
+          # @return rule_definition_list [Array<Contrast::Agent::Reporting::Settings::RuleDefinition>]
+          def rule_definition_list
+            @_rule_definition_list ||= []
+          end
+
+          # The keywords and patterns required for the input analysis of each rule with that capability.
+          #
+          # @param list [Array<RuleDefinition>] Array of RuleDefinition: {
+          #   keywords [Array] The words to search for in input that indicate an attack.{
+          #                     caseSensitive [Boolean]
+          #                     id            [String]
+          #                     score         [Integer] The impact of matching this entry; higher meaning more
+          #                                             likely to be an attack
+          #                     value         [String] }
+          #   name   [String] 	AssessRuleID
+          #   patterns [Array] A word or pattern whose presence in an input represents an attack {
+          #                     caseSensitive [Boolean]
+          #                     id            [String]
+          #                    score          [Integer] The impact of matching this entry; higher meaning more
+          #                                            likely to be an attack
+          #                    value          [String] }
+          # }
+          # @return rule_definition_list [Array<Contrast::Agent::Reporting::Settings::RuleDefinition>]
+          def rule_definition_list= list
+            Contrast::Agent::Reporting::Settings::Helpers.array_to_iv(
+                Contrast::Agent::Reporting::Settings::RuleDefinition,
+                rule_definition_list,
+                list)
+          end
+
+          # Transforms ServerSettings hash rules to definition_list
+          #
+          # @param rules [Hash]
+          def rules_to_definition_list rules
+            return unless rules&.cs__is_a?(Hash)
+
+            definition_list = []
+            rules.slice(*PROTECT_RULES_KEYS).each_pair do |key, rule|
+              new_entry = Contrast::Agent::Reporting::Settings::RuleDefinition.new
+              new_entry.name = Contrast::Agent::Reporting::Settings::Helpers.to_rule_id(key)
+              new_entry.patterns = rule[:patterns]
+              new_entry.keywords = rule[:keywords]
+              definition_list << new_entry
+            end
+            @_rule_definition_list = definition_list
+          end
+
+          # Controls for the syslogging feature in the agent.
+          #
+          # @return syslog [Contrast::Agent::Reporting::Settings::Syslog]
+          def syslog
+            @_syslog ||= Contrast::Agent::Reporting::Settings::Syslog.new
+          end
+
+          # The protect response should be structured like this:
+          # protect{ enable, observability, rules, log_enhancers }
+          # instead we receive all the data under the protect:
+          # the rules array is merged under protect and the ruleDefinition
+          # list is separate:
+          # "defend" : {
+          #       "botBlockers" : [],
+          #       "enabled" : true,
+          #       "logEnhancers" : [],
+          #       "ipDenylist" : [],
+          #       "ipAllowlist" : [],
+          #       "syslog" : {},
+          #       "ruleDefinitionList" : [{...}],
+          #       "bot-blocker" : false
+          #     },
+          def to_controlled_hash
+            {
+                botBlockers: bot_blocker.bots.map(&:to_controlled_hash),
+                enabled: enabled?,
+                observability: observability, # used with ServerSettings only
+                logEnhancers: log_enhancers.map(&:to_controlled_hash),
+                ipDenylist: ip_denylist.map(&:to_controlled_hash),
+                ipAllowlist: ip_allowlist.map(&:to_controlled_hash),
+                syslog: syslog.settings_blank? ? nil : syslog.to_controlled_hash, # used with ServerSettings only
+                ruleDefinitionList: rule_definition_list.map(&:to_controlled_hash),
+                'bot-blocker': bot_blocker.to_controlled_hash
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/settings/reaction.rb

@@ -0,0 +1,39 @@
+# 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/settings/log_enhancer'
+
+module Contrast
+  module Agent
+    module Reporting
+      module Settings
+        # Reaction the agent should take based on a state in TS.
+        class Reaction
+          attr_accessor :level, :operation, :message
+
+          # used to check the parameters and also before reactions settings update
+          OPERATIONS = %w[NOOP DISABLE].cs__freeze
+
+          # Reaction the agent should take based on a state in TS.
+          #
+          # @param level [String] The level at which the agent should log this reaction[ERROR, WARN, INFO, DEBUG, TRACE]
+          # @param message [String] A message to log when receiving this reaction.
+          # @param operation [String] What to do in response to this reaction.[NOOP, DISABLE]
+          def initialize level, operation, message
+            @level = level if Contrast::Agent::Reporting::Settings::LogEnhancer::LOG_LEVELS.include?(level)
+            @operation = operation if OPERATIONS.include?(operation)
+            @message = message if message.is_a?(String)
+          end
+
+          def to_controlled_hash
+            {
+                message: message,
+                level: level,
+                operation: operation
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/settings/rule_definition.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 'contrast/agent/reporting/settings/helpers'
+require 'contrast/agent/reporting/settings/keyword'
+
+module Contrast
+  module Agent
+    module Reporting
+      module Settings
+        # The keywords and patterns required for the input analysis of each rule with that capability.
+        class RuleDefinition
+          ATTRIBUTES = %i[name keywords patterns].cs__freeze
+
+          # For the ServerSettings this name is not used instead it is used as key to the keywords and patterns
+          # arrays. It is used in the agent startup message.
+          #
+          # @return name [String] Name of the rule
+          attr_accessor :name
+
+          # The words to search for in input that indicate an attack
+          #
+          # @return [array<Contrast::Agent::Reporting::Settings::Keyword>]
+          def keywords
+            @_keywords ||= []
+          end
+
+          # A word or pattern whose presence in an input represents an attack
+          #
+          # @return [array<Contrast::Agent::Reporting::Settings::Pattern>]
+          def patterns
+            @_patterns ||= []
+          end
+
+          # Set keywords.
+          #
+          # @param keywords_array [Array]
+          # @return [array<Contrast::Agent::Reporting::Settings::Keyword>]
+          def keywords= keywords_array
+            Contrast::Agent::Reporting::Settings::Helpers.array_to_iv(Contrast::Agent::Reporting::Settings::Keyword,
+                                                                      keywords,
+                                                                      keywords_array)
+          end
+
+          # Set patterns.
+          #
+          # @param patterns_array [Array]
+          # @return [array<Contrast::Agent::Reporting::Settings::Pattern>]
+          def patterns= patterns_array
+            Contrast::Agent::Reporting::Settings::Helpers.array_to_iv(Contrast::Agent::Reporting::Settings::Pattern,
+                                                                      patterns,
+                                                                      patterns_array)
+          end
+
+          def to_controlled_hash
+            {
+                name: name, # rubocop:disable Security/Module/Name
+                keywords: keywords.map(&:to_controlled_hash),
+                patterns: patterns.map(&:to_controlled_hash)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/settings/sampling.rb

@@ -0,0 +1,46 @@
+# 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
+      module Settings
+        # Sampling controls for the Assess Features provided by TeamServer
+        class Sampling
+          # @return [Integer] The number of baseline requests to take before switching to sampling for the window.
+          attr_reader :baseline
+          # @return [Boolean] If the sampling feature should be used or not.
+          attr_reader :enabled
+          # @return [Integer] The number of requests to skip before observing during the sampling window after the
+          #   baseline.
+          attr_reader :request_frequency
+          # @return [Integer] The number of responses to skip before observing during the sampling window after the
+          #  baseline.
+          attr_reader :response_frequency
+          # @return [Integer] The length of time for which the sample period is valid, in ms.
+          attr_reader :window_ms
+
+          def initialize hsh
+            @baseline = hsh[:baseline]
+            @enabled = hsh[:enabled]
+            @request_frequency = hsh[:frequency]
+            @response_frequency = hsh[:responseFrequency]
+            @window_ms = hsh[:window]
+          end
+
+          def to_controlled_hash
+            {
+                baseline: baseline,
+                enabled: enabled,
+                frequency: request_frequency,
+                responseFrequency: response_frequency,
+                window: window_ms
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/settings/sanitizer.rb

@@ -0,0 +1,38 @@
+# 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
+      module Settings
+        # The sanitizers defined by the user for use by the agent on this server for this organization.
+        class Sanitizer
+          ATTRIBUTES = %i[uuid api tags rules].cs__freeze
+
+          # @return uuid [String]
+          attr_accessor :uuid
+          # @return api [String]
+          attr_accessor :api
+          # @return uuid [Array<String>]
+          attr_accessor :tags
+          # @return uuid [Array<String>]
+          attr_accessor :rules
+
+          def initialize
+            @tags = []
+            @rules = []
+          end
+
+          def to_controlled_hash
+            {
+                api: api,
+                rules: rules,
+                tags: tags,
+                uuid: uuid
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/settings/security_logger.rb

@@ -0,0 +1,77 @@
+# 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/settings/syslog'
+
+module Contrast
+  module Agent
+    module Reporting
+      module Settings
+        # this class will hold the security logger settings.
+        class SecurityLogger
+          def initialize
+            @blank = true
+          end
+
+          # check to see if object is being used
+          #
+          # @return [Boolean]
+          def settings_blank?
+            @blank
+          end
+
+          # Set the state of settings
+          #
+          # @return [Boolean]
+          def not_blank!
+            @blank = false
+          end
+
+          # The level at which the agent should log. Overridden by agent.logger.level
+          # if set in a local configuration
+          #
+          # @return log_level [String] [ ERROR, WARN, INFO, DEBUG, TRACE ]
+          def log_level
+            @_log_level ||= Contrast::Utils::ObjectShare::EMPTY_STRING
+          end
+
+          # set the log level
+          #
+          # @param log_level [String]
+          # @return log_level [String] [ ERROR, WARN, INFO, DEBUG, TRACE ]
+          def log_level= log_level
+            @_log_level = log_level if log_level.is_a?(String)
+          end
+
+          # Where to log the agent's log file, if set by the user. Overridden by agent.logger.path
+          # if set in a local configuration.
+          #
+          # @return log_file [String] path
+          def log_file
+            @_log_file ||= Contrast::Utils::ObjectShare::EMPTY_STRING
+          end
+
+          # Set the log file
+          #
+          # @param log_file [String] path
+          # @return log_file [String] path
+          def log_file= log_file
+            @_log_file = log_file if log_file.is_a?(String)
+          end
+
+          def syslog
+            @_syslog ||= Contrast::Agent::Reporting::Settings::Syslog.new
+          end
+
+          def to_controlled_hash
+            {
+                level: log_level,
+                path: log_file,
+                syslog: syslog.to_controlled_hash
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/settings/sensitive_data_masking.rb

@@ -0,0 +1,118 @@
+# 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/settings/sensitive_data_masking_rule'
+
+module Contrast
+  module Agent
+    module Reporting
+      # This module will hold all the settings from the TS responce
+      module Settings
+        # Protect level settings for the sensitive_data_masking_policy.
+        # Configuration of the masking parameters will be delivered dynamically from TeamServer
+        # during an ApplicationSettings response from requests to TS endpoints that return that
+        # structure.
+        # https://contrast.atlassian.net/wiki/spaces/~699189087/pages/807960614/Sensitive+Data+Masking+Design
+        class SensitiveDataMasking
+          # Policy flag to enable the use of masking on request body
+          # Here is set to defaults to true.
+          #
+          # @return true | false
+          def mask_http_body?
+            @_mask_http_body
+          end
+
+          # Set the flag for request body masking
+          #
+          # @param bool [Boolean]
+          # @return true | false
+          def mask_http_body= bool
+            @_mask_http_body = bool.nil? ? true : !!bool
+          end
+
+          # Policy flag to enable the use of masking on attack vector.
+          # Here is set to defaults to false.
+          #
+          # @return true | false
+          def mask_attack_vector?
+            @_mask_attack_vector
+          end
+
+          # Set the flag for using masking on attack vector
+          #
+          # @param bool [Boolean]
+          # @return true | false
+          def mask_attack_vector= bool
+            @_mask_attack_vector = !!bool
+          end
+
+          # Rules to follow when using the masking
+          #
+          # @return rules [Array<Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule>, []]
+          def rules
+            @_rules ||= Contrast::Agent::Reporting::Settings::RulesArray.new
+          end
+
+          # Assign rules array
+          #
+          # @param rules [Array<Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule>]
+          # @return rules [Array<Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule>, []]
+          def rules= rules
+            @_rules = rules if rules_array?(rules)
+          end
+
+          # Build rules from hash
+          #
+          # @param settings_rules [Hash] Response settings under Settings/sensitive_data_masking_policy/rules
+          # @return rules [Array<Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule>, nil
+          def build_rules_form_settings settings_rules
+            return if settings_rules.nil? || settings_rules.empty?
+
+            settings_rules.each do |rule|
+              instance = Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule.new
+              instance.rule_id = rule[:id]
+              instance.keywords = rule[:keywords]
+              rules << instance
+            end
+            rules
+          end
+
+          def to_controlled_hash
+            {
+                rules: rules.map(&:to_controlled_hash),
+                mask_attack_vector: mask_attack_vector?,
+                mask_http_body: mask_http_body?
+            }
+          end
+
+          private
+
+          # Determine if parameter is array of Rules.
+          #
+          # @param array [Array<Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule>] Array of keywords.
+          # @return true | false
+          def rules_array? array
+            return false unless array.is_a?(Array)
+
+            array.all?(Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule)
+          end
+        end
+
+        # Simple validation class for Rules Array.
+        class RulesArray < Array
+          # Do not push anything except Rules instances.
+          # :<< method is called on object directly so this
+          # will make sure the data pushed is as expected.
+          #
+          # @param item [Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule]
+          # @return itself [Array<Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule>]
+          def << item
+            return itself unless item.instance_of?(Contrast::Agent::Reporting::Settings::SensitiveDataMaskingRule)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contrast/agent/reporting/settings/sensitive_data_masking_rule.rb

@@ -0,0 +1,65 @@
+# 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 module will hold all the settings from the TS responce
+      module Settings
+        # Protect level settings for the sensitive_data_masking_policy Rule entry.
+        class SensitiveDataMaskingRule
+          # Id for this rule.
+          #
+          # @return rule_id [String] Name of parameter to mask.
+          def rule_id
+            @_rule_id ||= Contrast::Utils::ObjectShare::EMPTY_STRING
+          end
+
+          # Set the rule name.
+          #
+          # @param id [String] Name of parameter to mask.
+          # @return rule_id [String]
+          def rule_id= id
+            @_rule_id = id.to_s
+          end
+
+          # Array of keywords to mask values for the rule_id.
+          #
+          # @return keywords [Array<String>] set of keywords
+          def keywords
+            @_keywords ||= []
+          end
+
+          # Set keywords array.
+          #
+          # @param words_array [Array<String>]
+          # @return keywords [Array<String>] set of keywords
+          def keywords= words_array
+            @_keywords = words_array if string_array?(words_array)
+          end
+
+          def to_controlled_hash
+            {
+                id: rule_id,
+                keywords: keywords
+            }
+          end
+
+          private
+
+          # Determine if a array is array of strings.
+          #
+          # @param array [Array<String] Array of keywords.
+          # @return true | false
+          def string_array? array
+            return false unless array.is_a?(Array) && array.any?
+
+            array.all?(String)
+          end
+        end
+      end
+    end
+  end
+end