Land rapid7#2484, @zeroSteiner's refactoring for CmdStager

Author: jvazquez-r7

lib/msf/core/exploit/cmdstager.rb

@@ -5,93 +5,315 @@
 
 module Msf
 
-###
-#
 # This mixin provides an interface to generating cmdstagers
-#
-###
 module Exploit::CmdStager
 
   include Msf::Exploit::EXE
 
+  # Constant for stagers - used when creating an stager instance.
+  STAGERS = {
+    :bourne => Rex::Exploitation::CmdStagerBourne,
+    :debug_asm => Rex::Exploitation::CmdStagerDebugAsm,
+    :debug_write => Rex::Exploitation::CmdStagerDebugWrite,
+    :echo => Rex::Exploitation::CmdStagerEcho,
+    :printf => Rex::Exploitation::CmdStagerPrintf,
+    :vbs => Rex::Exploitation::CmdStagerVBS,
+    :vbs_adodb => Rex::Exploitation::CmdStagerVBS,
+    :tftp => Rex::Exploitation::CmdStagerTFTP
+  }
+
+  # Constant for decoders - used when checking the default flavor decoder.
+  DECODERS = {
+    :debug_asm => File.join(Msf::Config.install_root, "data", "exploits", "cmdstager", "debug_asm"),
+    :debug_write => File.join(Msf::Config.install_root, "data", "exploits", "cmdstager", "debug_write"),
+    :vbs => File.join(Msf::Config.install_root, "data", "exploits", "cmdstager", "vbs_b64"),
+    :vbs_adodb => File.join(Msf::Config.install_root, "data", "exploits", "cmdstager", "vbs_b64_adodb")
+  }
+
+  attr_accessor :stager_instance
+  attr_accessor :cmd_list
+  attr_accessor :flavor
+  attr_accessor :decoder
+  attr_accessor :exe
+
+  # Creates an instance of an exploit that uses an CMD Stager and register the
+  # datastore options provided by the mixin.
   #
-  # Creates an instance of an exploit that uses an CmdStager overwrite.
-  #
+  # @param info [Hash] Hash containing information to initialize the exploit.
+  # @return [Msf::Module::Exploit] the exploit module.
   def initialize(info = {})
     super
-    @cmd_list = nil
-    @stager_instance = nil
+
+    flavors = module_flavors
+    flavors = STAGERS.keys if flavors.empty?
+    flavors.unshift('auto')
+
+    register_advanced_options(
+      [
+        OptEnum.new('CMDSTAGER::FLAVOR', [false, 'The CMD Stager to use.', 'auto', flavors]),
+        OptString.new('CMDSTAGER::DECODER', [false, 'The decoder stub to use.'])
+      ], self.class)
   end
 
 
+  # Executes the command stager while showing the progress. This method should
+  # be called from exploits using this mixin.
   #
-  # Execute the command stager while showing the progress
-  #
+  # @param opts [Hash] Hash containing configuration options. Also allow to
+  #   send opts to the Rex::Exploitation::CmdStagerBase constructor.
+  # @option opts :flavor [Symbol] The CMD Stager to use.
+  # @option opts :decoder [Symbol] The decoder stub to use.
+  # @option opts :delay [Float] Delay between command executions.
+  # @return [void]
   def execute_cmdstager(opts = {})
-    cmd_list = generate_cmdstager(opts)
+    self.cmd_list = generate_cmdstager(opts)
 
-    execute_cmdstager_begin(opts)
+    stager_instance.setup(self)
 
-    sent = 0
-    total_bytes = 0
-    cmd_list.each { |cmd| total_bytes += cmd.length }
+    begin
+      execute_cmdstager_begin(opts)
 
-    delay = opts[:delay]
-    delay ||= 0.25
+      sent = 0
+      total_bytes = 0
+      cmd_list.each { |cmd| total_bytes += cmd.length }
 
-    cmd_list.each do |cmd|
-      execute_command(cmd, opts)
-      sent += cmd.length
+      delay = opts[:delay]
+      delay ||= 0.25
 
-      # In cases where a server has multiple threads, we want to be sure that
-      # commands we execute happen in the correct (serial) order.
-      ::IO.select(nil, nil, nil, delay)
+      cmd_list.each do |cmd|
+        execute_command(cmd, opts)
+        sent += cmd.length
 
-      progress(total_bytes, sent)
-    end
+        # In cases where a server has multiple threads, we want to be sure that
+        # commands we execute happen in the correct (serial) order.
+        ::IO.select(nil, nil, nil, delay)
+
+        progress(total_bytes, sent)
+      end
 
-    execute_cmdstager_end(opts)
+      execute_cmdstager_end(opts)
+    ensure
+      stager_instance.teardown(self)
+    end
   end
 
 
-  #
   # Generates a cmd stub based on the current target's architecture
-  # and operating system.
+  # and platform.
   #
+  # @param opts [Hash] Hash containing configuration options. Also allow to
+  #   send opts to the Rex::Exploitation::CmdStagerBase constructor.
+  # @option opts :flavor [Symbol] The CMD Stager to use.
+  # @option opts :decoder [Symbol] The decoder stub to use.
+  # @param pl [String] String containing the payload to execute
+  # @return [Array] The list of commands to execute
+  # @raise [ArgumentError] raised if the cmd stub can not be generated
   def generate_cmdstager(opts = {}, pl = nil)
-    pl ||= payload.encoded
+    select_cmdstager(opts)
 
-    @exe = generate_payload_exe
+    self.exe = generate_payload_exe(:code => pl)
 
-    @stager_instance = create_stager(@exe)
-    cmd_list = @stager_instance.generate(opts)
+    self.stager_instance = create_stager
+    cmd_list = stager_instance.generate(opts_with_decoder(opts))
 
-    if (cmd_list.nil? or cmd_list.length < 1)
+    if (cmd_list.nil? || cmd_list.length < 1)
       print_error("The command stager could not be generated")
       raise ArgumentError
     end
 
-    @cmd_list = cmd_list
+    cmd_list
   end
 
-
-  #
-  # Show the progress of the upload
+  # Show the progress of the upload while cmd staging
   #
+  # @param total [Float] The total number of bytes to send
+  # @param sent [Float] The number of bytes sent
+  # @return [void]
   def progress(total, sent)
     done = (sent.to_f / total.to_f) * 100
     percent = "%3.2f%%" % done.to_f
     print_status("Command Stager progress - %7s done (%d/%d bytes)" % [percent, sent, total])
   end
 
+  # Selects the correct cmd stager and decoder stub to use
+  #
+  # @param opts [Hash] Hash containing the options to select te correct cmd
+  #   stager and decoder.
+  # @option opts :flavor [Symbol] The cmd stager to use.
+  # @option opts :decoder [Symbol] The decoder stub to use.
+  # @return [void]
+  # @raise [ArgumentError] raised if a cmd stager can not be selected or it
+  #   isn't compatible with the target platform.
+  def select_cmdstager(opts = {})
+    self.flavor = select_flavor(opts)
+    raise ArgumentError, "Unable to select CMD Stager" if flavor.nil?
+    raise ArgumentError, "The CMD Stager '#{flavor}' isn't compatible with the target" unless compatible_flavor?(flavor)
+    self.decoder = select_decoder(opts)
+  end
+
+
+  # Returns a hash with the :decoder option if possible
+  #
+  # @params opts [Hash] Input Hash.
+  # @return [Hash] Hash with the input data and a :decoder option when
+  #   possible.
+  def opts_with_decoder(opts = {})
+    return opts if opts.include?(:decoder)
+    return opts.merge(:decoder => decoder) if decoder
+    opts
+  end
+
+
+  # Create an instance of the flavored stager.
+  #
+  # @return [Rex::Exploitation::CmdStagerBase] The cmd stager to use.
+  # @raise [NoMethodError] raised if the flavor doesn't exist.
+  def create_stager
+    STAGERS[flavor].new(exe)
+  end
+
+  # Returns the default decoder stub for the input flavor.
+  #
+  # @param f [Symbol] the input flavor.
+  # @return [Symbol] the decoder.
+  # @return [nil] if there isn't a default decoder to use for the current
+  #   cmd stager flavor.
+  def default_decoder(f)
+    DECODERS[f]
+  end
+
+  # Selects the correct cmd stager decoder to use based on three rules: (1) use
+  # the decoder provided in input options, (2) use the decoder provided by the
+  # user through datastore options, (3) select the default decoder for the
+  # current cmd stager flavor if available.
+  #
+  # @param opts [Hash] Hash containing the options to select te correct
+  #   decoder.
+  # @option opts :decoder [String] The decoder stub to use.
+  # @return [String] The decoder.
+  # @return [nil] if a decoder can not be selected.
+  def select_decoder(opts = {})
+    return opts[:decoder] if opts.include?(:decoder)
+    return datastore['CMDSTAGER::DECODER'] unless datastore['CMDSTAGER::DECODER'].blank?
+    default_decoder(flavor)
+  end
+
+  # Selects the correct cmd stager to use based on three rules: (1) use the
+  # flavor provided in options, (2) use the flavor provided by the user
+  # through datastore options, (3) guess the flavor using the target platform.
+  #
+  # @param opts [Hash] Hash containing the options to select te correct cmd
+  #   stager
+  # @option opts :flavor [Symbol] The cmd stager flavor to use.
+  # @return [Symbol] The flavor to use.
+  # @return [nil] if a flavor can not be selected.
+  def select_flavor(opts = {})
+    return opts[:flavor].to_sym if opts.include?(:flavor)
+    unless datastore['CMDSTAGER::FLAVOR'].blank? or datastore['CMDSTAGER::FLAVOR'] == 'auto'
+      return datastore['CMDSTAGER::FLAVOR'].to_sym
+    end
+    guess_flavor
+  end
+
+  # Guess the cmd stager flavor to use using information from the module,
+  # target or platform.
+  #
+  # @return [Symbol] The cmd stager flavor to use.
+  # @return [nil] if the cmd stager flavor can not be guessed.
+  def guess_flavor
+    # First try to guess a compatible flavor based on the module & target information.
+    unless target_flavor.nil?
+      case target_flavor.class.to_s
+      when 'Array'
+        return target_flavor[0].to_sym
+      when 'String'
+        return target_flavor.to_sym
+      when 'Symbol'
+        return target_flavor
+      end
+    end
+
+    # Second try to guess a compatible flavor based on the target platform.
+    return nil unless target_platform.names.length == 1
+    c_platform = target_platform.names.first
+    case c_platform
+    when /linux/i
+      :bourne
+    when /osx/i
+      :bourne
+    when /unix/i
+      :bourne
+    when /win/i
+      :vbs
+    else
+      nil
+    end
+  end
+
+  # Returns all the compatible stager flavors specified by the module and each
+  # of it's targets.
+  #
+  # @return [Array] the list of all compatible cmd stager flavors.
+  def module_flavors
+    flavors = []
+    flavors += Array(module_info['CmdStagerFlavor']) if module_info['CmdStagerFlavor']
+    targets.each do |target|
+      flavors += Array(target.opts['CmdStagerFlavor']) if target.opts['CmdStagerFlavor']
+    end
+    flavors.uniq!
+    flavors.map { |flavor| flavor.to_s }
+  end
+
+  # Returns the compatible stager flavors for the current target or module.
   #
-  # Methods to override - not used internally
+  # @return [Array] the list of compatible cmd stager flavors.
+  # @return [Symbol] the compatible cmd stager flavor.
+  # @return [String] the compatible cmd stager flavor.
+  # @return [nil] if there isn't any compatible flavor defined.
+  def target_flavor
+    return target.opts['CmdStagerFlavor'] if target && target.opts['CmdStagerFlavor']
+    return module_info['CmdStagerFlavor'] if module_info['CmdStagerFlavor']
+    nil
+  end
+
+  # Answers if the input flavor is compatible with the current target or module.
+  #
+  # @param f [Symbol] The flavor to check
+  # @returns  [Boolean] true if compatible, false otherwise.
+  def compatible_flavor?(f)
+    return true if target_flavor.nil?
+    case target_flavor.class.to_s
+    when 'String'
+      return true if target_flavor == f.to_s
+    when 'Array'
+      target_flavor.each { |tr| return true if tr.to_sym == f }
+    when 'Symbol'
+      return true if target_flavor == f
+    end
+    false
+  end
+
+  # Code to execute before the cmd stager stub. This method is designed to be
+  # overriden by a module this mixin.
   #
+  # @param opts [Hash] Hash of configuration options.
   def execute_cmdstager_begin(opts)
   end
+
+  # Code to execute after the cmd stager stub. This method is designed to be
+  # overriden by a module this mixin.
+  #
+  # @param opts [Hash] Hash of configuration options.
   def execute_cmdstager_end(opts)
   end
 
-end
+  # Code to execute each command from the. This method is designed to be
+  # overriden by a module using this mixin.
+  #
+  # @param opts [Hash] Hash of configuration options.
+  def execute_command(cmd, opts)
+    raise NotImplementedError
+  end
 
 end
+end