dstruct 0.0.1

data/lib/rex/post/meterpreter/extensions/stdapi/railgun/multicall.rb

@@ -0,0 +1,319 @@
+# -*- coding: binary -*-
+# Copyright (c) 2010, patrickHVE@googlemail.com
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * The names of the author may not be used to endorse or promote products
+#       derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL patrickHVE@googlemail.com BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'pp'
+require 'enumerator'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/api_constants'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/tlv'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll_helper'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/buffer_item'
+
+module Rex
+module Post
+module Meterpreter
+module Extensions
+module Stdapi
+module Railgun
+
+# A easier way to call multiple functions in a single request
+class MultiCaller
+
+    include DLLHelper
+
+    def initialize( client, parent, win_consts )
+      @parent = parent
+      @client = client
+
+      # needed by DLL helper
+      @win_consts = win_consts
+
+      if( @client.platform =~ /x64/i )
+        @native = 'Q<'
+      else
+        @native = 'V'
+      end
+    end
+
+    def call(functions)
+
+      request = Packet.create_request('stdapi_railgun_api_multi')
+      function_results = []
+      layouts          = []
+      functions.each do |f|
+        dll_name,funcname,args = f
+        dll_host = @parent.get_dll( dll_name )
+
+        if not dll_host
+          raise "DLL #{dll_name} has not been loaded"
+        end
+
+        function = dll_host.functions[funcname]
+        if not function
+          raise "DLL #{dll_name} function #{funcname} has not been defined"
+        end
+
+        raise "#{function.params.length} arguments expected. #{args.length} arguments provided." unless args.length == function.params.length
+        #puts "process_function_call(function.windows_name,#{PP.pp(args, "")})"
+
+        # We transmit the immediate stack and three heap-buffers:
+        # in, inout and out. The reason behind the separation is bandwidth.
+        # We don't want to transmit uninitialized data in or no-longer-needed data out.
+
+        # out-only-buffers that are ONLY transmitted on the way BACK
+        out_only_layout = {} # paramName => BufferItem
+        out_only_size_bytes = 0
+        #puts " assembling out-only buffer"
+        function.params.each_with_index do |param_desc, param_idx|
+          #puts " processing #{param_desc[1]}"
+
+          # Special case:
+          # The user can choose to supply a Null pointer instead of a buffer
+          # in this case we don't need space in any heap buffer
+          if param_desc[0][0,1] == 'P' # type is a pointer
+            if args[param_idx] == nil
+              next
+            end
+          end
+
+          # we care only about out-only buffers
+          if param_desc[2] == "out"
+            raise "error in param #{param_desc[1]}: Out-only buffers must be described by a number indicating their size in bytes " unless args[param_idx].class == Fixnum
+            buffer_size = args[param_idx]
+            # bump up the size for an x64 pointer
+            if( @native == 'Q<' and buffer_size == 4 )
+              args[param_idx] = 8
+              buffer_size = args[param_idx]
+            end
+
+            if( @native == 'Q<' )
+              raise "Please pass 8 for 'out' PDWORDS, since they require a buffer of size 8" unless buffer_size == 8
+            elsif( @native == 'V' )
+              raise "Please pass 4 for 'out' PDWORDS, since they require a buffer of size 4" unless buffer_size == 4
+            end
+
+            out_only_layout[param_desc[1]] = BufferItem.new(param_idx, out_only_size_bytes, buffer_size, param_desc[0])
+            out_only_size_bytes += buffer_size
+          end
+        end
+
+        tmp = assemble_buffer("in", function, args)
+        in_only_layout = tmp[0]
+        in_only_buffer = tmp[1]
+
+        tmp = assemble_buffer("inout", function, args)
+        inout_layout = tmp[0]
+        inout_buffer = tmp[1]
+
+
+        # now we build the stack
+        # every stack dword will be described by two dwords:
+        # first dword describes second dword:
+        #	0 - literal,
+        #	1 = relative to in-only buffer
+        #	2 = relative to out-only buffer
+        #	3 = relative to inout buffer
+
+        # (literal numbers and pointers to buffers we have created)
+        literal_pairs_blob = ""
+        #puts " assembling literal stack"
+        function.params.each_with_index do |param_desc, param_idx|
+          #puts "  processing (#{param_desc[0]}, #{param_desc[1]}, #{param_desc[2]})"
+          buffer = nil
+          # is it a pointer to a buffer on our stack
+          if ["PDWORD", "PWCHAR", "PCHAR", "PBLOB"].include? param_desc[0]
+            #puts "   pointer"
+            if args[param_idx] == nil # null pointer?
+              buffer = [0].pack(@native) # type: DWORD  (so the dll does not rebase it)
+              buffer += [0].pack(@native) # value: 0
+            elsif param_desc[2] == "in"
+              buffer = [1].pack(@native)
+              buffer += [in_only_layout[param_desc[1]].addr].pack(@native)
+            elsif param_desc[2] == "out"
+              buffer = [2].pack(@native)
+              buffer += [out_only_layout[param_desc[1]].addr].pack(@native)
+            elsif param_desc[2] == "inout"
+              buffer = [3].pack(@native)
+              buffer += [inout_layout[param_desc[1]].addr].pack(@native)
+            else
+              raise "unexpected direction"
+            end
+          else
+            #puts "   not a pointer"
+            # it's not a pointer
+            buffer = [0].pack(@native)
+            case param_desc[0]
+              when "LPVOID", "HANDLE"
+                num     = param_to_number(args[param_idx])
+                buffer += [num].pack(@native)
+              when "DWORD"
+                num     = param_to_number(args[param_idx])
+                buffer += [num % 4294967296].pack(@native)
+              when "WORD"
+                num     = param_to_number(args[param_idx])
+                buffer += [num % 65536].pack(@native)
+              when "BYTE"
+                num     = param_to_number(args[param_idx])
+                buffer += [num % 256].pack(@native)
+              when "BOOL"
+                case args[param_idx]
+                  when true
+                    buffer += [1].pack('V')
+                  when false
+                    buffer += [0].pack('V')
+                  else
+                    raise "param #{param_desc[1]}: true or false expected"
+                end
+              else
+                raise "unexpected type for param #{param_desc[1]}"
+            end
+          end
+
+          #puts "   adding pair to blob"
+          literal_pairs_blob += buffer
+          #puts "   buffer size %X" % buffer.length
+          #puts "   blob size so far: %X" % literal_pairs_blob.length
+        end
+
+        #puts "\n\nsending Stuff to meterpreter"
+
+        group = Rex::Post::Meterpreter::GroupTlv.new(TLV_TYPE_RAILGUN_MULTI_GROUP)
+        group.add_tlv(TLV_TYPE_RAILGUN_SIZE_OUT, out_only_size_bytes)
+        group.add_tlv(TLV_TYPE_RAILGUN_STACKBLOB, literal_pairs_blob)
+        group.add_tlv(TLV_TYPE_RAILGUN_BUFFERBLOB_IN, in_only_buffer)
+        group.add_tlv(TLV_TYPE_RAILGUN_BUFFERBLOB_INOUT, inout_buffer)
+        group.add_tlv(TLV_TYPE_RAILGUN_DLLNAME, dll_name )
+        group.add_tlv(TLV_TYPE_RAILGUN_FUNCNAME, function.windows_name)
+        request.tlvs << group
+
+        layouts << [inout_layout, out_only_layout]
+      end
+
+      call_results = []
+      res = @client.send_request(request)
+      res.each(TLV_TYPE_RAILGUN_MULTI_GROUP) do |val|
+        call_results << val
+      end
+
+      functions.each do |f|
+        dll_name,funcname,args = f
+        dll_host = @parent.get_dll( dll_name )
+        function = dll_host.functions[funcname]
+        response = call_results.shift
+        inout_layout, out_only_layout = layouts.shift
+
+        rec_inout_buffers = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_BUFFERBLOB_INOUT)
+        rec_out_only_buffers = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_BUFFERBLOB_OUT)
+        rec_return_value = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_RET)
+        rec_last_error = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_ERR)
+        rec_err_msg = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_MSG)
+
+        # Error messages come back with trailing CRLF, so strip it out
+        # if we do get a message.
+        rec_err_msg.strip! if not rec_err_msg.nil?
+
+        # The hash the function returns
+        return_hash = {
+          "GetLastError" => rec_last_error,
+          "ErrorMessage" => rec_err_msg
+        }
+
+        #process return value
+        case function.return_type
+          when "LPVOID", "HANDLE"
+            if( @native == 'Q<' )
+              return_hash["return"] = rec_return_value
+            else
+              return_hash["return"] = rec_return_value % 4294967296
+            end
+          when "DWORD"
+            return_hash["return"] = rec_return_value % 4294967296
+          when "WORD"
+            return_hash["return"] = rec_return_value % 65536
+          when "BYTE"
+            return_hash["return"] = rec_return_value % 256
+          when "BOOL"
+            return_hash["return"] = (rec_return_value != 0)
+          when "VOID"
+            return_hash["return"] = nil
+          else
+            raise "unexpected return type: #{function.return_type}"
+        end
+        #puts return_hash
+        #puts "out_only_layout:"
+        #puts out_only_layout
+
+
+        # process out-only buffers
+        #puts "processing out-only buffers:"
+        out_only_layout.each_pair do |param_name, buffer_item|
+          #puts "   #{param_name}"
+          buffer = rec_out_only_buffers[buffer_item.addr, buffer_item.length_in_bytes]
+          case buffer_item.datatype
+            when "PDWORD"
+              return_hash[param_name] = buffer.unpack('V')[0]
+            when "PCHAR"
+              return_hash[param_name] = asciiz_to_str(buffer)
+            when "PWCHAR"
+              return_hash[param_name] = uniz_to_str(buffer)
+            when "PBLOB"
+              return_hash[param_name] = buffer
+            else
+              raise "unexpected type in out-only buffer of #{param_name}: #{buffer_item.datatype}"
+          end
+        end
+        #puts return_hash
+
+        # process in-out buffers
+        #puts "processing in-out buffers:"
+        inout_layout.each_pair do |param_name, buffer_item|
+          #puts "   #{param_name}"
+          buffer = rec_inout_buffers[buffer_item.addr, buffer_item.length_in_bytes]
+          case buffer_item.datatype
+            when "PDWORD"
+              return_hash[param_name] = buffer.unpack('V')[0]
+            when "PCHAR"
+              return_hash[param_name] = asciiz_to_str(buffer)
+            when "PWCHAR"
+              return_hash[param_name] = uniz_to_str(buffer)
+            when "PBLOB"
+              return_hash[param_name] = buffer
+            else
+              raise "unexpected type in in-out-buffer of #{param_name}: #{buffer_item.datatype}"
+          end
+        end
+        #puts return_hash
+        #puts "finished"
+
+        function_results << return_hash
+      end
+      function_results
+    end
+    # process_multi_function_call
+
+  protected
+
+end # MultiCall
+
+end; end; end; end; end; end

data/lib/rex/post/meterpreter/extensions/stdapi/railgun/platform_util.rb

@@ -0,0 +1,23 @@
+# -*- coding: binary -*-
+module Rex
+module Post
+module Meterpreter
+module Extensions
+module Stdapi
+module Railgun
+module PlatformUtil
+
+  X86_64 = :x86_64
+  X86_32 = :x86_32
+
+  def self.parse_client_platform(meterp_client_platform)
+    meterp_client_platform =~ /win64/ ? X86_64 : X86_32
+  end
+
+end # PlatformUtil
+end # Railgun
+end # Stdapi
+end # Extensions
+end # Meterpreter
+end # Post
+end # Rex

data/lib/rex/post/meterpreter/extensions/stdapi/railgun/railgun.rb

@@ -0,0 +1,301 @@
+# -*- coding: binary -*-
+# Copyright (c) 2010, patrickHVE@googlemail.com
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * The names of the author may not be used to endorse or promote products
+#       derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL patrickHVE@googlemail.com BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#
+# sf - Sept 2010 - Modified for x64 support and merged into the stdapi extension.
+#
+
+#
+# chao - June 2011 - major overhaul of dll lazy loading, caching, and bit of everything
+#
+
+require 'pp'
+require 'enumerator'
+
+require 'rex/post/meterpreter/extensions/stdapi/railgun/api_constants'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/tlv'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/util'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/win_const_manager'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/multicall'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll_wrapper'
+
+module Rex
+module Post
+module Meterpreter
+module Extensions
+module Stdapi
+module Railgun
+
+
+#
+# The Railgun class to dynamically expose the Windows API.
+#
+class Railgun
+
+  #
+  # Railgun::DLL's that have builtin definitions.
+  #
+  # If you want to add additional DLL definitions to be preloaded create a
+  # definition class 'rex/post/meterpreter/extensions/stdapi/railgun/def/'.
+  # Naming is important and should follow convention.  For example, if your
+  # dll's name was "my_dll"
+  # file name:    def_my_dll.rb
+  # class name:   Def_my_dll
+  # entry below: 'my_dll'
+  #
+  BUILTIN_DLLS = [
+    'kernel32',
+    'ntdll',
+    'user32',
+    'ws2_32',
+    'iphlpapi',
+    'advapi32',
+    'shell32',
+    'netapi32',
+    'crypt32',
+    'wlanapi',
+    'wldap32',
+    'version',
+    'psapi'
+  ].freeze
+
+  ##
+  # Returns a Hash containing DLLs added to this instance with #add_dll
+  # as well as references to any frozen cached dlls added directly in #get_dll
+  # and copies of any frozen dlls (added directly with #add_function)
+  # that the user attempted to modify with #add_function.
+  #
+  # Keys are friendly DLL names and values are the corresponding DLL instance
+  attr_accessor :dlls
+
+  ##
+  # Contains a reference to the client that corresponds to this instance of railgun
+  attr_accessor :client
+
+  ##
+  # These DLLs are loaded lazily and then shared amongst all railgun instances.
+  # For safety reasons this variable should only be read/written within #get_dll.
+  @@cached_dlls = {}
+
+  # if you are going to touch @@cached_dlls, wear protection
+  @@cache_semaphore = Mutex.new
+
+  def initialize(client)
+    self.client = client
+    self.dlls = {}
+  end
+
+  def self.builtin_dlls
+    BUILTIN_DLLS
+  end
+
+  #
+  # Return this Railgun's Util instance.
+  #
+  def util
+    if @util.nil?
+      @util = Util.new(self, client.platform)
+    end
+
+    return @util
+  end
+
+  #
+  # Return this Railgun's WinConstManager instance, initially populated with
+  # constants defined in ApiConstants.
+  #
+  def constant_manager
+    # Loads lazily
+    return ApiConstants.manager
+  end
+
+  #
+  # Read data from a memory address on the host (useful for working with
+  # LPVOID parameters)
+  #
+  def memread(address, length)
+
+    raise "Invalid parameters." if(not address or not length)
+
+    request = Packet.create_request('stdapi_railgun_memread')
+
+    request.add_tlv(TLV_TYPE_RAILGUN_MEM_ADDRESS, address)
+    request.add_tlv(TLV_TYPE_RAILGUN_MEM_LENGTH, length)
+
+    response = client.send_request(request)
+    if(response.result == 0)
+      return response.get_tlv_value(TLV_TYPE_RAILGUN_MEM_DATA)
+    end
+
+    return nil
+  end
+
+  #
+  # Write data to a memory address on the host (useful for working with
+  # LPVOID parameters)
+  #
+  def memwrite(address, data, length)
+
+    raise "Invalid parameters." if(not address or not data or not length)
+
+    request = Packet.create_request('stdapi_railgun_memwrite')
+
+    request.add_tlv(TLV_TYPE_RAILGUN_MEM_ADDRESS, address)
+    request.add_tlv(TLV_TYPE_RAILGUN_MEM_DATA, data)
+    request.add_tlv(TLV_TYPE_RAILGUN_MEM_LENGTH, length)
+
+    response = client.send_request(request)
+    if(response.result == 0)
+      return true
+    end
+
+    return false
+  end
+
+  #
+  # Adds a function to an existing DLL definition.
+  #
+  # If the DLL definition is frozen (ideally this should be the case for all
+  # cached dlls) an unfrozen copy is created and used henceforth for this
+  # instance.
+  #
+  def add_function(dll_name, function_name, return_type, params, windows_name=nil, calling_conv="stdcall")
+
+    unless known_dll_names.include?(dll_name)
+      raise "DLL #{dll_name} not found. Known DLLs: #{PP.pp(known_dll_names, "")}"
+    end
+
+    dll = get_dll(dll_name)
+
+    # For backwards compatibility, we ensure the dll is thawed
+    if dll.frozen?
+      # Duplicate not only the dll, but its functions as well. Frozen status will be lost
+      dll = Marshal.load(Marshal.dump(dll))
+
+      # Update local dlls with the modifiable duplicate
+      dlls[dll_name] = dll
+    end
+
+    dll.add_function(function_name, return_type, params, windows_name, calling_conv)
+  end
+
+  #
+  # Adds a DLL to this Railgun.
+  #
+  # The +windows_name+ is the name used on the remote system and should be
+  # set appropriately if you want to include a path or the DLL name contains
+  # non-ruby-approved characters.
+  #
+  # Raises an exception if a dll with the given name has already been
+  # defined.
+  #
+  def add_dll(dll_name, windows_name=dll_name)
+
+    if dlls.has_key? dll_name
+      raise "A DLL of name #{dll_name} has already been loaded."
+    end
+
+    dlls[dll_name] = DLL.new(windows_name, constant_manager)
+  end
+
+
+  def known_dll_names
+    return BUILTIN_DLLS | dlls.keys
+  end
+
+  #
+  # Attempts to provide a DLL instance of the given name. Handles lazy
+  # loading and caching.  Note that if a DLL of the given name does not
+  # exist, returns nil
+  #
+  def get_dll(dll_name)
+
+    # If the DLL is not local, we now either load it from cache or load it lazily.
+    # In either case, a reference to the dll is stored in the collection "dlls"
+    # If the DLL can not be found/created, no actions are taken
+    unless dlls.has_key? dll_name
+      # We read and write to @@cached_dlls and rely on state consistency
+      @@cache_semaphore.synchronize do
+        if @@cached_dlls.has_key? dll_name
+          dlls[dll_name] = @@cached_dlls[dll_name]
+        elsif BUILTIN_DLLS.include? dll_name
+          # I highly doubt this case will ever occur, but I am paranoid
+          if dll_name !~ /^\w+$/
+            raise "DLL name #{dll_name} is bad. Correct Railgun::BUILTIN_DLLS"
+          end
+
+          require 'rex/post/meterpreter/extensions/stdapi/railgun/def/def_' << dll_name
+          dll = Def.const_get('Def_' << dll_name).create_dll.freeze
+
+          @@cached_dlls[dll_name] = dll
+          dlls[dll_name] = dll
+        end
+      end
+
+    end
+
+    return dlls[dll_name]
+  end
+
+  #
+  # Fake having members like user32 and kernel32.
+  # reason is that
+  #   ...user32.MessageBoxW()
+  # is prettier than
+  #   ...dlls["user32"].functions["MessageBoxW"]()
+  #
+  def method_missing(dll_symbol, *args)
+    dll_name = dll_symbol.to_s
+
+    unless known_dll_names.include? dll_name
+      raise "DLL #{dll_name} not found. Known DLLs: #{PP.pp(known_dll_names, '')}"
+    end
+
+    dll = get_dll(dll_name)
+
+    return DLLWrapper.new(dll, client)
+  end
+
+  #
+  # Return a Windows constant matching +str+.
+  #
+  def const(str)
+    return constant_manager.parse(str)
+  end
+
+  #
+  # The multi-call shorthand (["kernel32", "ExitProcess", [0]])
+  #
+  def multi(functions)
+    if @multicaller.nil?
+      @multicaller = MultiCaller.new(client, self, ApiConstants.manager)
+    end
+
+    return @multicaller.call(functions)
+  end
+end
+
+end; end; end; end; end; end