Land #5615, Updated YARD Documentation for EXE.rb

lib/msf/util/exe.rb

@@ -21,14 +21,16 @@ require 'digest/sha1'
 require 'msf/core/exe/segment_injector'
 require 'msf/core/exe/segment_appender'
 
-  ##
+  # Generates a default template
   #
-  # Helper functions common to multiple generators
+  # @param  opts [Hash] The options hash
-  #
+  # @option opts [String] :template, the template type for the executable
-  ##
+  # @option opts [String] :template_path, the path for the template
-
+  # @option opts [Bool] :fallback, If there are no options set, default options will be used
+  # @param  exe  [String] Template type. If undefined, will use the default.
+  # @param  path [String] Where you would like the template to be saved.
   def self.set_template_default(opts, exe = nil, path = nil)
-    # If no path specified, use the default one.
+    # If no path specified, use the default one
     path ||= File.join(Msf::Config.data_directory, "templates")
 
     # If there's no default name, we must blow it up.
@@ -60,6 +62,10 @@ require 'msf/core/exe/segment_appender'
     end
   end
 
+  # self.read_replace_script_template
+  #
+  # @param filename [String] Name of the file
+  # @param hash_sub [Hash]
   def self.read_replace_script_template(filename, hash_sub)
     template_pathname = File.join(Msf::Config.data_directory, "templates",
                                   "scripts", filename)
@@ -68,12 +74,15 @@ require 'msf/core/exe/segment_appender'
     template % hash_sub
   end
 
-  ##
-  #
   # Executable generators
   #
-  ##
+  # @param arch       [Array<String>] The architecture of the system (i.e :x86, :x64)
-
+  # @param plat       [String] The platform (i.e Linux, Windows, OSX)
+  # @param code       [String]
+  # @param opts       [Hash]   The options hash
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @return           [String]
+  # @return           [NilClass]
   def self.to_executable(framework, arch, plat, code = '', opts = {})
     if arch.index(ARCH_X86)
 
@@ -154,9 +163,10 @@ require 'msf/core/exe/segment_appender'
   end
 
   # Clears the DYNAMIC_BASE flag for a Windows executable
-  # @param exe [String] The raw executable to be modified by the method
+  #
-  # @param pe [Rex::PeParsey::Pe] Use Rex::PeParsey::Pe.new_from_file
+  # @param  exe  [String] The raw executable to be modified by the method
-  # @return [String] the modified executable
+  # @param  pe   [Rex::PeParsey::Pe] Use Rex::PeParsey::Pe.new_from_file
+  # @return      [String] the modified executable
   def self.clear_dynamic_base(exe, pe)
     c_bits = ("%32d" %pe.hdr.opt.DllCharacteristics.to_s(2)).split('').map { |e| e.to_i }.reverse
     c_bits[6] = 0 # DYNAMIC_BASE
@@ -169,6 +179,16 @@ require 'msf/core/exe/segment_appender'
     exe
   end
 
+  # self.to_win32pe
+  #
+  # @param  framework [Msf::Framework]
+  # @param  code      [String]
+  # @param  opts      [Hash]
+  # @option opts      [String] :sub_method
+  # @option opts      [String] :inject, Code to inject into the exe
+  # @option opts      [String] :template
+  # @option opts      [Symbol] :arch, Set to :x86 by default
+  # @return           [String]
   def self.to_win32pe(framework, code, opts = {})
 
     # For backward compatability, this is roughly equivalent to 'exe-small' fmt
@@ -313,6 +333,12 @@ require 'msf/core/exe/segment_appender'
     exe
   end
 
+  # self.to_winpe_only
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @param arch       [String] Default is "x86"
   def self.to_winpe_only(framework, code, opts = {}, arch="x86")
     arch = ARCH_X64 if arch == ARCH_X86_64
 
@@ -378,6 +404,11 @@ require 'msf/core/exe/segment_appender'
     exe
   end
 
+  # self.to_win32pe_old
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param  code      [String]
+  # @param  opts      [Hash]
   def self.to_win32pe_old(framework, code, opts = {})
 
     payload = code.dup
@@ -431,9 +462,8 @@ require 'msf/core/exe/segment_appender'
 
   # Splits a string into a number of assembly push operations
   #
-  # @param string [String] string to be used
+  # @param string [String] String to be used
-  #
+  # @return       [String] null terminated string as assembly push ops
-  # @return [String] null terminated string as assembly push ops
   def self.string_to_pushes(string)
     str = string.dup
     # Align string to 4 bytes
@@ -455,6 +485,14 @@ require 'msf/core/exe/segment_appender'
     pushes
   end
 
+  # self.exe_sub_method
+  #
+  # @param  code [String]
+  # @param  opts [Hash]
+  # @option opts [Symbol] :exe_type
+  # @option opts [String] :service_exe
+  # @option opts [Boolean] :sub_method
+  # @return      [String]
   def self.exe_sub_method(code,opts ={})
     pe = self.get_file_contents(opts[:template])
 
@@ -504,6 +542,12 @@ require 'msf/core/exe/segment_appender'
     pe
   end
 
+  # self.to_win32pe_exe_sub
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @return           [String]
   def self.to_win32pe_exe_sub(framework, code, opts = {})
     # Allow the user to specify their own DLL template
     set_template_default(opts, "template_x86_windows.exe")
@@ -511,6 +555,12 @@ require 'msf/core/exe/segment_appender'
     exe_sub_method(code,opts)
   end
 
+  # self.to_win64pe
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @return           [String]
   def self.to_win64pe(framework, code, opts = {})
     # Allow the user to specify their own EXE template
     set_template_default(opts, "template_x64_windows.exe")
@@ -537,12 +587,12 @@ require 'msf/core/exe/segment_appender'
   # Embeds shellcode within a Windows PE file implementing the Windows
   # service control methods.
   #
-  # @param framework [Object]
+  # @param  framework   [Object]
-  # @param code [String] shellcode to be embedded
+  # @param  code        [String] shellcode to be embedded
-  # @option opts [Boolean] :sub_method use substitution technique with a
+  # @option opts        [Boolean] :sub_method use substitution technique with a
-  #   service template PE
+  #                                service template PE
-  # @option opts [String] :servicename name of the service, not used in
+  # @option opts        [String] :servicename name of the service, not used in
-  #   substituion technique
+  #                               substituion technique
   #
   # @return [String] Windows Service PE file
   def self.to_win32pe_service(framework, code, opts = {})
@@ -616,6 +666,16 @@ require 'msf/core/exe/segment_appender'
     end
   end
 
+  # self.to_win64pe_service
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :exe_type
+  # @option           [String] :service_exe
+  # @option           [String] :dll
+  # @option           [String] :inject
+  # @return           [String]
   def self.to_win64pe_service(framework, code, opts = {})
     # Allow the user to specify their own service EXE template
     set_template_default(opts, "template_x64_windows_svc.exe")
@@ -623,6 +683,15 @@ require 'msf/core/exe/segment_appender'
     exe_sub_method(code,opts)
   end
 
+  # self.to_win32pe_dll
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :exe_type
+  # @option           [String] :dll
+  # @option           [String] :inject
+  # @return           [String]
   def self.to_win32pe_dll(framework, code, opts = {})
     # Allow the user to specify their own DLL template
     set_template_default(opts, "template_x86_windows.dll")
@@ -635,6 +704,15 @@ require 'msf/core/exe/segment_appender'
     end
   end
 
+  # self.to_win64pe_dll
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :exe_type
+  # @option           [String] :dll
+  # @option           [String] :inject
+  # @return           [String]
   def self.to_win64pe_dll(framework, code, opts = {})
     # Allow the user to specify their own DLL template
     set_template_default(opts, "template_x64_windows.dll")
@@ -647,10 +725,14 @@ require 'msf/core/exe/segment_appender'
     end
   end
 
+  # Wraps an executable inside a Windows .msi file for auto execution when run
   #
-  #   Wraps an executable inside a Windows
+  # @param framework  [Msf::Framework]  The framework of you want to use
-  #    .msi file for auto execution when run
+  # @param exe        [String]
-  #
+  # @param opts       [Hash]
+  # @option opts      [String] :msi_template_path
+  # @option opts      [String] :msi_template
+  # @return [String]
   def self.to_exe_msi(framework, exe, opts = {})
     if opts[:uac]
       opts[:msi_template] ||= "template_windows.msi"
@@ -660,6 +742,13 @@ require 'msf/core/exe/segment_appender'
     replace_msi_buffer(exe, opts)
   end
 
+  #self.replace_msi_buffer
+  #
+  # @param pe     [String]
+  # @param opts   [String]
+  # @option       [String] :msi_template
+  # @option       [String] :msi_template_path
+  # @return       [String]
   def self.replace_msi_buffer(pe, opts)
     opts[:msi_template_path] ||= File.join(Msf::Config.data_directory, "templates")
 
@@ -708,6 +797,13 @@ require 'msf/core/exe/segment_appender'
     msi
   end
 
+  # self.to_osx_arm_macho
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String]
   def self.to_osx_arm_macho(framework, code, opts = {})
 
     # Allow the user to specify their own template
@@ -719,6 +815,13 @@ require 'msf/core/exe/segment_appender'
     mo
   end
 
+  # self.to_osx_ppc_macho
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String]
   def self.to_osx_ppc_macho(framework, code, opts = {})
 
     # Allow the user to specify their own template
@@ -730,6 +833,13 @@ require 'msf/core/exe/segment_appender'
     mo
   end
 
+  # self.to_osx_x86_macho
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String]
   def self.to_osx_x86_macho(framework, code, opts = {})
 
     # Allow the user to specify their own template
@@ -741,6 +851,13 @@ require 'msf/core/exe/segment_appender'
     mo
   end
 
+  # self.to_osx_x64_macho
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String]
   def self.to_osx_x64_macho(framework, code, opts = {})
     set_template_default(opts, "template_x64_darwin.bin")
 
@@ -751,12 +868,13 @@ require 'msf/core/exe/segment_appender'
     macho
   end
 
-  # @param [Hash] opts the options hash
+  # self.to_osx_app
-  # @option opts [String] :exe_name (random) the name of the macho exe file (never seen by the user)
+  # @param  opts [Hash] The options hash
-  # @option opts [String] :app_name (random) the name of the OSX app
+  # @option opts [Hash] :exe_name (random) the name of the macho exe file (never seen by the user)
-  # @option opts [String] :hidden (true) hide the app when it is running
+  # @option opts [Hash] :app_name (random) the name of the OSX app
-  # @option opts [String] :plist_extra ('') some extra data to shove inside the Info.plist file
+  # @option opts [Hash] :hidden (true) hide the app when it is running
-  # @return [String] zip archive containing an OSX .app directory
+  # @option opts [Hash] :plist_extra ('') some extra data to shove inside the Info.plist file
+  # @return      [String] zip archive containing an OSX .app directory
   def self.to_osx_app(exe, opts = {})
     exe_name    = opts.fetch(:exe_name) { Rex::Text.rand_text_alpha(8) }
     app_name    = opts.fetch(:app_name) { Rex::Text.rand_text_alpha(8) }
@@ -811,7 +929,13 @@ require 'msf/core/exe/segment_appender'
   # For user-provided templates, modifies the header to mark all executable
   # segments as writable and overwrites the entrypoint (usually _start) with
   # the payload.
-  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @param template   [String]
+  # @param code       [String]
+  # @param big_endian [Boolean]  Set to "false" by default
+  # @return           [String]
   def self.to_exe_elf(framework, opts, template, code, big_endian=false)
 
     # Allow the user to specify their own template
@@ -856,6 +980,12 @@ require 'msf/core/exe/segment_appender'
   end
 
   # Create a 32-bit Linux ELF containing the payload provided in +code+
+  #
+  # @param framework  [Msf::Framework]  The framework of you want to use
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_linux_x86_elf(framework, code, opts = {})
     default = true unless opts[:template]
 
@@ -894,42 +1024,96 @@ require 'msf/core/exe/segment_appender'
   end
 
   # Create a 32-bit BSD (test on FreeBSD) ELF containing the payload provided in +code+
+  #
+  # @param framework [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_bsd_x86_elf(framework, code, opts = {})
     to_exe_elf(framework, opts, "template_x86_bsd.bin", code)
   end
 
   # Create a 64-bit Linux ELF containing the payload provided in +code+
+  #
+  # @param framework [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_bsd_x64_elf(framework, code, opts = {})
     to_exe_elf(framework, opts, "template_x64_bsd.bin", code)
   end
 
   # Create a 32-bit Solaris ELF containing the payload provided in +code+
+  #
+  # @param framework [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_solaris_x86_elf(framework, code, opts = {})
     to_exe_elf(framework, opts, "template_x86_solaris.bin", code)
   end
 
   # Create a 64-bit Linux ELF containing the payload provided in +code+
+  #
+  # @param framework [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_linux_x64_elf(framework, code, opts = {})
     to_exe_elf(framework, opts, "template_x64_linux.bin", code)
   end
 
   # Create a 64-bit Linux ELF_DYN containing the payload provided in +code+
+  #
+  # @param framework [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_linux_x64_elf_dll(framework, code, opts = {})
     to_exe_elf(framework, opts, "template_x64_linux_dll.bin", code)
   end
 
+  # self.to_linux_mipsle_elf
+  #
+  # @param framework [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_linux_armle_elf(framework, code, opts = {})
     to_exe_elf(framework, opts, "template_armle_linux.bin", code)
   end
 
+  # self.to_linux_mipsle_elf
+  # Little Endian
+  # @param framework [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_linux_mipsle_elf(framework, code, opts = {})
     to_exe_elf(framework, opts, "template_mipsle_linux.bin", code)
   end
 
+  # self.to_linux_mipsbe_elf
+  # Big Endian
+  # @param framework [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]
+  # @option           [String] :template
+  # @return           [String] Returns an elf
   def self.to_linux_mipsbe_elf(framework, code, opts = {})
     to_exe_elf(framework, opts, "template_mipsbe_linux.bin", code, true)
   end
 
+  # self.to_exe_vba
+  #
+  # @param exes [String]
   def self.to_exe_vba(exes='')
     exe = exes.unpack('C*')
     hash_sub = {}
@@ -976,6 +1160,11 @@ require 'msf/core/exe/segment_appender'
     read_replace_script_template("to_exe.vba.template", hash_sub)
   end
 
+  # self.to_vba
+  #
+  # @param framework  [Msf::Framework]
+  # @param code       [String]
+  # @param opts       [Hash]    Unused
   def self.to_vba(framework,code,opts = {})
     hash_sub = {}
     hash_sub[:var_myByte]             = Rex::Text.rand_text_alpha(rand(7)+3).capitalize
@@ -1003,6 +1192,12 @@ require 'msf/core/exe/segment_appender'
     read_replace_script_template("to_mem.vba.template", hash_sub)
   end
 
+  # self.to_powershell_vba
+  #
+  # @param framework  [Msf::Framework]
+  # @param arch       [String]
+  # @param code       [String]
+  #
   def self.to_powershell_vba(framework, arch, code)
     template_path = File.join(Msf::Config.data_directory,
                               "templates",
@@ -1030,6 +1225,13 @@ require 'msf/core/exe/segment_appender'
     read_replace_script_template("to_powershell.vba.template", hash_sub)
   end
 
+  # self.to_exe_vba
+  #
+  # @param  exes  [String]
+  # @param  opts  [Hash]
+  # @option opts  [String] :delay
+  # @option opts  [String] :persists
+  # @option opts  [String] :exe_filename
   def self.to_exe_vbs(exes = '', opts = {})
     delay   = opts[:delay]   || 5
     persist = opts[:persist] || false
@@ -1062,6 +1264,10 @@ require 'msf/core/exe/segment_appender'
     read_replace_script_template("to_exe.vbs.template", hash_sub)
   end
 
+  # self.to_exe_asp
+  #
+  # @param exes [String]
+  # @param opts [Hash]    Unused
   def self.to_exe_asp(exes = '', opts = {})
     hash_sub = {}
     hash_sub[:var_bytes]   = Rex::Text.rand_text_alpha(rand(4)+4) # repeated a large number of times, so keep this one small
@@ -1073,12 +1279,14 @@ require 'msf/core/exe/segment_appender'
     hash_sub[:var_tempdir] = Rex::Text.rand_text_alpha(rand(8)+8)
     hash_sub[:var_tempexe] = Rex::Text.rand_text_alpha(rand(8)+8)
     hash_sub[:var_basedir] = Rex::Text.rand_text_alpha(rand(8)+8)
-
     hash_sub[:var_shellcode] = Rex::Text.to_vbscript(exes, hash_sub[:var_bytes])
-
     read_replace_script_template("to_exe.asp.template", hash_sub)
   end
 
+  # self.to_exe_aspx
+  #
+  # @param  exes [String]
+  # @option opts [Hash]
   def self.to_exe_aspx(exes = '', opts = {})
     hash_sub = {}
     hash_sub[:var_file]     = Rex::Text.rand_text_alpha(rand(8)+8)
@@ -1088,9 +1296,7 @@ require 'msf/core/exe/segment_appender'
     hash_sub[:var_tempexe]  = Rex::Text.rand_text_alpha(rand(8)+8)
     hash_sub[:var_iterator] = Rex::Text.rand_text_alpha(rand(8)+8)
     hash_sub[:var_proc] = Rex::Text.rand_text_alpha(rand(8)+8)
-
     hash_sub[:shellcode] = Rex::Text.to_csharp(exes,100,hash_sub[:var_file])
-
     read_replace_script_template("to_exe.aspx.template", hash_sub)
   end
 
@@ -1272,7 +1478,6 @@ require 'msf/core/exe/segment_appender'
   # @option opts (see to_war)
   # @return (see to_war)
   def self.to_jsp_war(exe, opts = {})
-
     # begin <payload>.jsp
     hash_sub = {}
     hash_sub[:var_hexpath]       = Rex::Text.rand_text_alpha(rand(8)+8)
@@ -1313,6 +1518,16 @@ require 'msf/core/exe/segment_appender'
   # at a specified location with read/execute permissions
   #    - the data will be loaded at: base+0x2065
   #    - default max size is 0x8000 (32768)
+  # @param  base [Integer] Default location set to base 0x12340000
+  # @param  data [String]
+  # @param  opts [Hash]
+  # @option      [String] :template
+  # @option      [String] :base_offset
+  # @option      [String] :timestamp_offset
+  # @option      [String] :text_offset
+  # @option      [String] :pack
+  # @option      [String] :uuid_offset
+  # @return      [String]
   def self.to_dotnetmem(base=0x12340000, data="", opts = {})
 
     # Allow the user to specify their own DLL template
@@ -1345,7 +1560,13 @@ require 'msf/core/exe/segment_appender'
     pe
   end
 
-
+  # self.encode_stub
+  #
+  # @param framework [Msf::Framework]
+  # @param arch     [String]
+  # @param code     [String]
+  # @param platform [String]
+  # @param badchars [String]
   def self.encode_stub(framework, arch, code, platform = nil, badchars = '')
     return code unless framework.encoders
     framework.encoders.each_module_ranked('Arch' => arch) do |name, mod|
@@ -1744,7 +1965,7 @@ require 'msf/core/exe/segment_appender'
 ;     pop eax                ; Skip
       pop eax                ; Skip
       popad                  ; Get our registers back
-;     sub esp, 44             ; Move stack pointer back past the handler
+;     sub esp, 44            ; Move stack pointer back past the handler
     ^
 
     stub_final = %Q^
@@ -1987,6 +2208,9 @@ require 'msf/core/exe/segment_appender'
     end
   end
 
+  # FMT Formats
+  # self.to_executable_fmt_formats
+  # @return [Array] Returns an array of strings
   def self.to_executable_fmt_formats
     [
       "asp",
@@ -2019,7 +2243,7 @@ require 'msf/core/exe/segment_appender'
 
   #
   # EICAR Canary
-  #
+  # @return [Boolean] Should return true
   def self.is_eicar_corrupted?
     path = ::File.expand_path(::File.join(
       ::File.dirname(__FILE__),"..", "..", "..", "data", "eicar.com")
@@ -2039,12 +2263,23 @@ require 'msf/core/exe/segment_appender'
     ret
   end
 
+  # self.get_file_contents
+  #
+  # @param perms  [String]
+  # @param file   [String]
+  # @return       [String]
   def self.get_file_contents(file, perms = "rb")
     contents = ''
     File.open(file, perms) {|fd| contents = fd.read(fd.stat.size)}
     contents
   end
 
+  # self.find_payload_tag
+  #
+  # @param mo       [String]
+  # @param err_msg  [String]
+  # @raise [RuntimeError] if the "PAYLOAD:" is not found
+  # @return         [Fixnum]
   def self.find_payload_tag(mo, err_msg)
     bo = mo.index('PAYLOAD:')
     unless bo