contrast-agent 3.9.1 → 6.15.3

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

@@ -0,0 +1,74 @@
+# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
+# frozen_string_literal: true
+
+require 'contrast/agent/reporting/settings/helpers'
+
+module Contrast
+  module Agent
+    module Reporting
+      module Settings
+        # The words to search for in input that indicate an attack
+        class Keyword
+          ATTRIBUTES = %i[id value case_sensitive score prohibited_features mandatory_features].cs__freeze
+
+          # @return id [String]
+          attr_accessor :id
+          # @return value [string]
+          attr_accessor :value
+          # @return case_sensitive [Boolean]
+          attr_accessor :case_sensitive
+          # @return score [Integer] The impact of matching this entry;
+          # higher meaning more likely to be an attack
+          attr_accessor :score
+
+          # Disable this pattern or keyword if agent implements one of
+          # the specified features
+          #
+          # @return [Array<String>]
+          def prohibited_features
+            @_prohibited_features ||= []
+          end
+
+          # Disable this pattern or keyword if agent implements one of
+          # the specified features
+          #
+          # @return [Array<String>]
+          def mandatory_features
+            @_mandatory_features ||= []
+          end
+
+          # Set the features.
+          #
+          # @param features [Array]
+          # @return [Array<String>]
+          def prohibited_features= features
+            @_prohibited_features = features if features.is_a?(Array)
+          end
+
+          # Set the features.
+          #
+          # @param features [Array]
+          # @return [Array<String>]
+          def mandatory_features= features
+            @_mandatory_features = features if features.is_a?(Array)
+          end
+
+          def to_controlled_hash
+            {
+                id: id,
+                value: value,
+                caseSensitive: case_sensitive,
+                score: score,
+                prohibitedFeatures: prohibited_features,
+                mandatoryFeatures: mandatory_features
+            }
+          end
+        end
+
+        #  A word or pattern whose presence in an input represents an attack
+        class Pattern < Keyword
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# Copyright (c) 2023 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
+        # All of the apis to add new logging calls to the application at runtime
+        class LogEnhancer
+          ATTRIBUTES = %i[id api format level name type].cs__freeze
+          LOG_LEVELS = %w[TRACE DEBUG INFO WARN ERROR].cs__freeze
+          TYPES = %w[AUDIT ERROR SECURITY].cs__freeze
+
+          # @return api [String]  The method signature to instrument, as understood by the agent.
+          attr_accessor :api
+          # @return format [String] The format of the message to log.
+          attr_accessor :format
+          # @return id [Integer] The identifier of the enhancer as defined by TeamServer.
+          attr_accessor :id
+          # @return name [String] The user defined name of the enhancer.
+          attr_accessor :name
+
+          # @return level [String] The level at which to log this message. Trace as 0 and Error as 4.
+          # [ TRACE, DEBUG, INFO, WARN, ERROR ]
+          def level
+            @_level ||= Contrast::Utils::ObjectShare::EMPTY_STRING
+          end
+
+          # @param new_level [String] new level to set.
+          # @return level [String] The level at which to log this message. Trace as 0 and Error as 4.
+          # [ TRACE, DEBUG, INFO, WARN, ERROR ]
+          def level= new_level
+            @_level = new_level if LOG_LEVELS.include?(new_level)
+          end
+
+          # @return type [String] The type of log message to generate. Audit as 0, Security as 2.
+          # [ AUDIT, ERROR, SECURITY ]
+          def type
+            @_type ||= Contrast::Utils::ObjectShare::EMPTY_STRING
+          end
+
+          # @param new_type [String] new type to set.
+          # @return type [String] The type of log message to generate. Audit as 0, Security as 2.
+          # [ AUDIT, ERROR, SECURITY ]
+          def type= new_type
+            @_type = new_type if TYPES.include?(new_type)
+          end
+
+          def to_controlled_hash
+            {
+                id: id,
+                api: api,
+                format: format,
+                name: name, # rubocop:disable Security/Module/Name
+                level: level,
+                type: type
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# Copyright (c) 2023 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/protect_rule'
+require 'contrast/agent/reporting/settings/virtual_patch'
+
+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
+        class Protect
+          # modes set by NG endpoints; block at perimeter needs to be check against the blockAtEntry boolean value
+          NG_PROTECT_RULES_MODE = %w[OFF MONITORING BLOCKING].cs__freeze
+          # The settings for each protect rule for this application
+          #
+          # @return protection_rules [Array<protectRule>] protectRule: {
+          #   blockAtEntry [Boolean] If in block mode, to block at perimeter or not.
+          #   id           [String] The id of a rule in Contrast.
+          #   mode         [String] The mode that this rule should run in. [OFF, MONITORING, BLOCKING] }
+          def protection_rules
+            @_protection_rules ||= []
+          end
+
+          # @return [Hash<String,Contrast::Agent::Reporting::Settings::ProtectRule>] map of rule, by id, to
+          #   configuration
+          def rule_settings
+            @_rule_settings ||= {}
+          end
+
+          # Set the protection_rules array
+          #
+          # @param protection_rules [Array<protectRule>] protectRule: {
+          #   blockAtEntry [Boolean] If in block mode, to block at perimeter or not.
+          #   id           [String] The id of a rule in Contrast.
+          #   mode         [String] The mode that this rule should run in. [OFF, MONITORING, BLOCKING] }
+          # @return protection_rules [Array<protectRule>] protectRule: {
+          #   blockAtEntry [Boolean] If in block mode, to block at perimeter or not.
+          #   id           [String] The id of a rule in Contrast.
+          #   mode         [String] The mode that this rule should run in. [OFF, MONITORING, BLOCKING] }
+          def protection_rules= protection_rules
+            @_protection_rules = protection_rules if protection_rules.is_a?(Array)
+          end
+
+          # The virtual patches to apply for this application
+          #
+          # @return [Array<Contrast::Agent::Reporting::Settings::VirtualPatch>]
+          def virtual_patches
+            @_virtual_patches ||= []
+          end
+
+          # Set the virtual patches array
+          #
+          # @param virtual_patches [Array<VirtualPatch>] Array of VirtualPatch: {
+          #   name       [String] The name of the Virtual Patch
+          #   headers    [Array] The headers that must be present in the request to result in the request being blocked
+          #   parameters [Array] The parameters that must be present in the request
+          #                       to result in the request being blocked.
+          #   urls       [Array] The urls that must be present in the request to result in the request being blocked.
+          #   uuids      [String] The UUID of the Virtual Patch }
+          # @return virtual_patches [Array<VirtualPatch>] Array of VirtualPatch: {
+          #   name       [String] The name of the Virtual Patch
+          #   headers    [Array] The headers that must be present in the request to result in the request being blocked
+          #   parameters [Array] The parameters that must be present in the request
+          #                       to result in the request being blocked.
+          #   urls       [Array] The urls that must be present in the request to result in the request being blocked.
+          #   uuids      [String] The UUID of the Virtual Patch }
+          def virtual_patches= virtual_patches
+            @_virtual_patches = virtual_patches if virtual_patches.is_a?(Array)
+          end
+
+          # Converts settings into Agent Settings understandable hash {RULE_ID => MODE}
+          #
+          # @return rules [Hash<RULE_ID => MODE>, nil] Hash with rule_id as key and mode as value
+          def protection_rules_to_settings_hash
+            return {} if protection_rules.empty?
+
+            modes_by_id = {}
+            protection_rules.each do |rule|
+              setting_mode = rule[:mode] || rule['mode']
+              api_mode = if NG_PROTECT_RULES_MODE.include?(setting_mode)
+                           case setting_mode
+                           when NG_PROTECT_RULES_MODE[1]
+                             :MONITOR
+                           when NG_PROTECT_RULES_MODE[2]
+                             if rule[:blockAtEntry] || rule['blockAtEntry']
+                               :BLOCK_AT_PERIMETER
+                             else
+                               :BLOCK
+                             end
+                           else
+                             :NO_ACTION
+                           end
+                         else
+                           # modes set by newer settings endpoints are of [OFF MONITOR BLOCK BLOCK_AT_PERIMETER] and
+                           # can just be cast to symbols
+                           setting_mode.to_sym
+                         end
+
+              id = rule[:id] || rule['id']
+              modes_by_id[id] = api_mode
+            end
+            modes_by_id
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# Copyright (c) 2023 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
+        # Settings for each protect rule
+        class ProtectRule
+          # @return [Symbol] the configured mode of the rule; OFF, MONITOR, BLOCK
+          attr_accessor :mode
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,227 @@
+# Copyright (c) 2023 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 ng_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) 2023 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) 2023 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) 2023 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