# Copyright (c) 2023 Contrast Security, Inc. See https://www.contrastsecurity.com/enduser-terms-0317a for more details.
# frozen_string_literal: true

module Contrast
  module Agent
    module Protect
      module Rule
        # Module to hold base builder methods used by Contrast::Agent::Protect::Rule::Base class.
        module Builders
          # A given input, candidate_string, was determined to violate a
          # protect rule and did exploit the application, or at least made it
          # to exploitable code in the case where we blocked the attack. As
          # such, we need to build a result to report this violation to
          # TeamServer.
          #
          # @param context [Contrast::Agent::RequestContext] the context of the
          #   request in which this input is evaluated.
          # @param ia_result [Contrast::Agent::Reporting::InputAnalysis] the
          #   analysis of the input that was determined to be an attack
          # @param result [Contrast::Agent::Reporting::AttackResult, nil] previous
          #   attack result for this rule, if one exists, in the case of
          #   multiple inputs being found to violate the protection criteria
          # @param candidate_string [String] the value of the input which may
          #   be an attack
          # @param kwargs [Hash] key - value pairs of context individual rules
          #   need to build out details to send to the TeamServer to tell the
          #   story of the attack
          # @return [Contrast::Agent::Reporting::AttackResult] the attack result from
          #   this input
          def build_attack_with_match context, ia_result, result, candidate_string, **kwargs
            result ||= build_attack_result(context)
            append_sample(context, ia_result, result, candidate_string, **kwargs)
            update_successful_attack_response(context, ia_result, result, candidate_string)

            result
          end

          # A given input, candidate_string, was determined to violate a
          # protect rule but did not exploit the application. As such, we need
          # to build a result to report this violation to TeamServer.
          #
          # @param context [Contrast::Agent::RequestContext, nil] the context of the
          #   request in which this input is evaluated.
          # @param ia_result [Contrast::Agent::Reporting::InputAnalysis] the
          #   analysis of the input that was determined to be an attack
          # @param result [Contrast::Agent::Reporting::AttackResult, nil] previous
          #   attack result for this rule, if one exists, in the case of
          #   multiple inputs being found to violate the protection criteria
          # @param kwargs [Hash, nil] key - value pairs of context individual rules
          #   need to build out details to send to TeamServer to tell the
          #   story of the attack
          # @return [Contrast::Agent::Reporting::AttackResult] the attack result from
          #   this input
          def build_attack_without_match context, ia_result, result, **kwargs
            result ||= build_attack_result(context)
            append_sample(context, ia_result, result, nil, **kwargs)
            update_perimeter_attack_response(context, ia_result, result)

            result
          end

          # Set up an attack result for the current rule
          #
          # @param _context  [Contrast::Agent::RequestContext] the context of
          #   the current request
          # @return [Contrast::Agent::Reporting::AttackResult]
          def build_attack_result _context
            result = Contrast::Agent::Reporting::AttackResult.new
            result.rule_id = rule_name
            result
          end

          # Override if rule can make use of the candidate string or kwargs to
          # build rasp rule sample.
          #
          # @param context [Contrast::Agent::RequestContext]
          # @param ia_result [Contrast::Agent::Reporting::Settings::InputAnalysisResult] the analysis of the input that
          #   was determined to be an attack
          # @param _candidate_string [String] potential attack value/ input containing attack value
          # @param _kwargs [Hash]
          # @return [Contrast::Agent::Reporting::RaspRuleSample]
          def build_sample context, ia_result, _candidate_string, **_kwargs
            build_base_sample(context, ia_result)
          end

          # @param context [Contrast::Agent::RequestContext]
          # @param ia_result [Contrast::Agent::Reporting::Settings::InputAnalysisResult] the analysis of the input that
          #   was determined to be an attack
          # @return [Contrast::Agent::Reporting::RaspRuleSample]
          def build_base_sample context, ia_result
            Contrast::Agent::Reporting::RaspRuleSample.build(context, ia_result)
          end

          # Used to build and report semantic rules.
          #
          # @param context [Contrast::Agent::RequestContext] current request contest
          # @param potential_attack_string [String]
          def build_violation context, potential_attack_string
            result = build_attack_result(context)
            append_sample(context, nil, result, potential_attack_string)
            update_successful_attack_response(context, nil, result, potential_attack_string)
            return unless result

            result
          end
        end
      end
    end
  end
end