metasm 1.0.0

data/samples/dbg-apihook.rb

@@ -0,0 +1,228 @@
+#    This file is part of Metasm, the Ruby assembly manipulation suite
+#    Copyright (C) 2006-2009 Yoann GUILLOT
+#
+#    Licence is LGPL, see LICENCE in the top-level directory
+
+
+#
+# This sample defines an ApiHook class, that you can subclass to easily hook functions
+# in a debugged process. Your custom function will get called whenever an API function is,
+# giving you access to the arguments, you can also take control just before control returns
+# to the caller.
+# See the example in the end for more details.
+# As a standalone application, it hooks WriteFile in the 'notepad' process, and make it
+# skip the first two bytes of the buffer.
+#
+
+require 'metasm'
+
+class ApiHook
+	# rewrite this function to list the hooks you want
+	# return an array of hashes
+	def setup
+		#[{ :function => 'WriteFile', :abi => :stdcall },	# standard function hook
+		# { :module => 'Foo.dll', :rva => 0x2433,		# arbitrary code hook
+		#   :abi => :fastcall, :hookname => 'myhook' }]		# hooks named pre_myhook/post_myhook
+	end
+
+	# initialized from a Debugger or a process description that will be debugged
+	# sets the hooks up, then run_forever
+	def initialize(dbg)
+		if not dbg.kind_of? Metasm::Debugger
+			process = Metasm::OS.current.find_process(dbg)
+			raise 'no such process' if not process
+			dbg = process.debugger
+		end
+		dbg.loadallsyms
+		@dbg = dbg
+		setup.each { |h| setup_hook(h) }
+		init_prerun if respond_to?(:init_prerun)	# allow subclass to do stuff before main loop
+		@dbg.run_forever
+	end
+
+	# setup one function hook
+	def setup_hook(h)
+		pre  =  "pre_#{h[:hookname] || h[:function]}"
+		post = "post_#{h[:hookname] || h[:function]}"
+
+		@nargs = h[:nargs] || method(pre).arity if respond_to?(pre)
+
+		if target = h[:address]
+		elsif target = h[:rva]
+			modbase = @dbg.modulemap[h[:module]]
+			raise "cant find module #{h[:module]} in #{@dbg.modulemap.join(', ')}" if not modbase
+			target += modbase[0]
+		else
+			target = h[:function]
+		end
+
+		@dbg.bpx(target) {
+			catch(:finish) {
+				@cur_abi = h[:abi]
+				@ret_longlong = h[:ret_longlong]
+				if respond_to? pre
+					args = read_arglist
+					send pre, *args
+				end
+				if respond_to? post
+					@dbg.bpx(@dbg.func_retaddr, true) {
+						retval = read_ret
+						send post, retval, args
+					}
+				end
+			}
+		}
+	end
+
+	# retrieve the arglist at func entry, from @nargs & @cur_abi
+	def read_arglist
+		nr = @nargs
+		args = []
+
+		if (@cur_abi == :fastcall or @cur_abi == :thiscall) and nr > 0
+			args << @dbg.get_reg_value(:ecx)
+			nr -= 1
+		end
+
+		if @cur_abi == :fastcall and nr > 0
+			args << @dbg.get_reg_value(:edx)
+			nr -= 1
+		end
+
+		nr.times { |i| args << @dbg.func_arg(i) }
+
+		args
+       	end
+
+	# retrieve the function returned value
+	def read_ret
+		ret = @dbg.func_retval
+		if @ret_longlong
+			ret = (ret & 0xffffffff) | (@dbg[:edx] << 32)
+		end
+		ret
+	end
+
+	# patch the value of an argument
+	# only valid in pre_hook
+	# nr starts at 0
+	def patch_arg(nr, value)
+		case @cur_abi
+		when :fastcall
+			case nr
+			when 0
+				@dbg.set_reg_value(:ecx, value)
+				return
+			when 1
+				@dbg.set_reg_value(:edx, value)
+				return
+			else
+				nr -= 2
+			end
+		when :thiscall
+			case nr
+			when 0
+				@dbg.set_reg_value(:ecx, value)
+				return
+			else
+				nr -= 1
+			end
+		end
+
+		@dbg.func_arg_set(nr, value)
+	end
+
+	# patch the function return value
+	# only valid post_hook
+	def patch_ret(val)
+		if @ret_longlong
+			@dbg.set_reg_value(:edx, (val >> 32) & 0xffffffff)
+			val &= 0xffffffff
+		end
+		@dbg.func_retval_set(val)
+	end
+
+	# skip the function call
+	# only valid in pre_hook
+	def finish(retval)
+		patch_ret(retval)
+		@dbg.ip = @dbg.func_retaddr
+		case @cur_abi
+		when :fastcall
+			@dbg[:esp] += 4*(@nargs-2) if @nargs > 2
+		when :thiscall
+			@dbg[:esp] += 4*(@nargs-1) if @nargs > 1
+		when :stdcall
+			@dbg[:esp] += 4*@nargs
+		end
+		@dbg.sp += @dbg.cpu.size/8
+		throw :finish
+	end
+end
+
+
+
+if __FILE__ == $0
+
+# this is the class you have to define to hook
+# 
+# setup() defines the list of hooks as an array of hashes
+# for exported functions, simply use :function => function name
+# for arbitrary hook, :module => 'module.dll', :rva => 0x1234, :hookname => 'myhook' (call pre_myhook/post_myhook)
+# :abi can be :stdcall (windows standard export), :fastcall or :thiscall, leave empty for cdecl
+# if pre_<function> is defined, it is called whenever the function is entered, via a bpx (int3)
+# if post_<function> is defined, it is called whenever the function exists, with a bpx on the return address setup at func entry
+# the pre_hook receives all arguments to the original function
+#  change them with patch_arg(argnr, newval)
+#  read memory with @dbg.memory_read_int(ptr), or @dbg.memory[ptr, length]
+#  skip the function call with finish(fake_retval) (!) needs a correct :abi & param count !
+# the post_hook receives the function return value
+#  change it with patch_ret(newval)
+class MyHook < ApiHook
+	def setup
+		[{ :function => 'WriteFile', :abi => :stdcall }]
+	end
+
+	def init_prerun
+		puts "hooks ready, save a file in notepad"
+	end
+
+	def pre_WriteFile(handle, pbuf, size, pwritten, overlap)
+		# we can skip the function call with this
+		#finish(28)
+
+		# spy on the api / trace calls
+		bufdata = @dbg.memory[pbuf, size]
+		puts "writing #{bufdata.inspect}"
+
+		# but we can also mess with the args
+		# ex: skip first 2 bytes of the buffer
+		patch_arg(1, pbuf+2)
+		patch_arg(2, size-2)
+	end
+
+	def post_WriteFile(retval, arglistcopy)
+		# we can patch the API return value with this
+		#patch_retval(42)
+
+		# finish messing with the args: fake the nrofbyteswritten
+		handle, pbuf, size, pwritten, overlap = arglistcopy
+		written = @dbg.memory_read_int(pwritten)
+		if written == size
+			# if written everything, patch the value so that the program dont detect our intervention
+			@dbg.memory_write_int(pwritten, written+2)
+		end
+
+		puts "write retval: #{retval}, written: #{written} bytes"
+	end
+end
+
+# name says it all
+Metasm::WinOS.get_debug_privilege
+
+# run our Hook engine on a running 'notepad' instance
+MyHook.new('notepad')
+
+# the script ends when notepad exits
+
+end

data/samples/dbghelp.rb

@@ -0,0 +1,143 @@
+#    This file is part of Metasm, the Ruby assembly manipulation suite
+#    Copyright (C) 2006-2009 Yoann GUILLOT
+#
+#    Licence is LGPL, see LICENCE in the top-level directory
+
+# a preleminary attempt to use MS dbghelp.dll to retrieve PE symbols
+
+require 'metasm'
+
+dll = 'C:\\Program Files\\Debugging Tools For Windows (x86)\\dbghelp.dll'
+
+Metasm::DynLdr.new_api_c <<EOS, dll
+#define SYMOPT_CASE_INSENSITIVE         0x00000001
+#define SYMOPT_UNDNAME                  0x00000002
+#define SYMOPT_DEFERRED_LOADS           0x00000004
+#define SYMOPT_NO_CPP                   0x00000008
+#define SYMOPT_LOAD_LINES               0x00000010
+#define SYMOPT_OMAP_FIND_NEAREST        0x00000020
+#define SYMOPT_LOAD_ANYTHING            0x00000040
+#define SYMOPT_IGNORE_CVREC             0x00000080
+#define SYMOPT_NO_UNQUALIFIED_LOADS     0x00000100
+#define SYMOPT_FAIL_CRITICAL_ERRORS     0x00000200
+#define SYMOPT_EXACT_SYMBOLS            0x00000400
+#define SYMOPT_ALLOW_ABSOLUTE_SYMBOLS   0x00000800
+#define SYMOPT_IGNORE_NT_SYMPATH        0x00001000
+#define SYMOPT_INCLUDE_32BIT_MODULES    0x00002000
+#define SYMOPT_PUBLICS_ONLY             0x00004000
+#define SYMOPT_NO_PUBLICS               0x00008000
+#define SYMOPT_AUTO_PUBLICS             0x00010000
+#define SYMOPT_NO_IMAGE_SEARCH          0x00020000
+#define SYMOPT_SECURE                   0x00040000
+#define SYMOPT_NO_PROMPTS               0x00080000
+#define SYMOPT_DEBUG                    0x80000000
+
+typedef int BOOL;
+typedef char CHAR;
+typedef unsigned long DWORD;
+typedef unsigned __int64 DWORD64;
+typedef void *HANDLE;
+typedef unsigned __int64 *PDWORD64;
+typedef void *PVOID;
+typedef unsigned long ULONG;
+typedef unsigned __int64 ULONG64;
+typedef const CHAR *PCSTR;
+typedef CHAR *PSTR;
+
+struct _SYMBOL_INFO {
+	ULONG SizeOfStruct;
+	ULONG TypeIndex;
+	ULONG64 Reserved[2];
+	ULONG info;
+	ULONG Size;
+	ULONG64 ModBase;
+	ULONG Flags;
+	ULONG64 Value;
+	ULONG64 Address;
+	ULONG Register;
+	ULONG Scope;
+	ULONG Tag;
+	ULONG NameLen;
+	ULONG MaxNameLen;
+	CHAR Name[1];
+};
+typedef struct _SYMBOL_INFO *PSYMBOL_INFO;
+
+typedef __stdcall BOOL (*PSYM_ENUMERATESYMBOLS_CALLBACK)(PSYMBOL_INFO pSymInfo, ULONG SymbolSize, PVOID UserContext);
+
+__stdcall DWORD SymGetOptions(void);
+__stdcall DWORD SymSetOptions(DWORD SymOptions __attribute__((in)));
+__stdcall BOOL SymInitialize(HANDLE hProcess __attribute__((in)), PSTR UserSearchPath __attribute__((in)), BOOL fInvadeProcess __attribute__((in)));
+__stdcall DWORD64 SymLoadModule64(HANDLE hProcess __attribute__((in)), HANDLE hFile __attribute__((in)), PSTR ImageName __attribute__((in)), PSTR ModuleName __attribute__((in)), DWORD64 BaseOfDll __attribute__((in)), DWORD SizeOfDll __attribute__((in)));
+__stdcall BOOL SymSetSearchPath(HANDLE hProcess __attribute__((in)), PSTR SearchPathA __attribute__((in)));
+__stdcall BOOL SymFromAddr(HANDLE hProcess __attribute__((in)), DWORD64 Address __attribute__((in)), PDWORD64 Displacement __attribute__((out)), PSYMBOL_INFO Symbol __attribute__((in)) __attribute__((out)));
+__stdcall BOOL SymEnumSymbols(HANDLE hProcess __attribute__((in)), ULONG64 BaseOfDll __attribute__((in)), PCSTR Mask __attribute__((in)), PSYM_ENUMERATESYMBOLS_CALLBACK EnumSymbolsCallback __attribute__((in)), PVOID UserContext __attribute__((in)));
+EOS
+
+#SYMOPT = 4|0x80000	# defered_load no_prompt
+#Metasm::WinAPI.new_api dll, 'SymInitialize', 'III I'
+#Metasm::WinAPI.new_api dll, 'SymGetOptions', 'I'
+#Metasm::WinAPI.new_api dll, 'SymSetOptions', 'I I'
+#Metasm::WinAPI.new_api dll, 'SymSetSearchPath', 'IP I'
+#Metasm::WinAPI.new_api dll, 'SymLoadModule64', 'IIPIIII I'	# ???ull?
+#Metasm::WinAPI.new_api dll, 'SymFromAddr', 'IIIPP I'	# handle ull_addr poffset psym
+
+class Tracer < Metasm::WinDbgAPI
+	def initialize(*a)
+		super(*a)
+		loop
+		puts 'finished'
+	end
+
+	def handler_newprocess(pid, tid, info)
+		puts "newprocess: init symsrv"
+
+		h = @hprocess[pid]
+		dl = Metasm::DynLdr
+		dl.syminitialize(h, 0, 0)
+		dl.symsetoptions(dl.symgetoptions|dl::SYMOPT_DEFERRED_LOADS|dl::SYMOPT_NO_PROMPTS)
+		sympath = ENV['_NT_SYMBOL_PATH'] || 'srv**symbols*http://msdl.microsoft.com/download/symbols'
+		dl.symsetsearchpath(h, sympath.dup)	# dup cause ENV is frozen and make WinAPI raises
+
+		Metasm::WinAPI::DBG_CONTINUE
+	end
+
+	def handler_loaddll(pid, tid, info)
+		pe = Metasm::LoadedPE.load(@mem[pid][info.imagebase, 0x1000000])
+		pe.decode_header
+		pe.decode_exports
+		return if not pe.export
+		libname = pe.export.libname
+		puts "loaddll: #{libname} @#{'%x' % info.imagebase}"
+		h = @hprocess[pid]
+		dl = Metasm::DynLdr
+		dl.symloadmodule64(h, 0, libname, 0, info.imagebase, pe.optheader.image_size)
+		symstruct = [0x58].pack('L') + 0.chr*4*19 + [512].pack('L')	# sizeofstruct, ..., nameszmax
+		text = pe.sections.find { |s| s.name == '.text' }
+		# XXX should SymEnumSymbols, but win32api callbacks sucks
+		text.rawsize.times { |o|
+			sym = symstruct + 0.chr*512	# name concat'ed after the struct
+			off = 0.chr*8
+			if dl.symfromaddr(h, info.imagebase+text.virtaddr+o, off, sym) and off.unpack('L').first == 0
+				symnamelen = sym[19*4, 4].unpack('L').first
+				puts ' %x %s' % [text.virtaddr+o, sym[0x54, symnamelen]]
+			end
+			puts '  %x/%x' % [o, text.rawsize] if $VERBOSE and o & 0xffff == 0
+		}
+		puts
+	end
+end
+
+if $0 == __FILE__
+	Metasm::WinOS.get_debug_privilege
+	if ARGV.empty?
+		# display list of running processes if no target found
+		puts Metasm::WinOS.list_processes.sort_by { |pr_| pr_.pid }
+		abort 'target needed'
+	end
+	pid = ARGV.shift.dup
+	if pr = Metasm::WinOS.find_process(pid)
+		pid = pr.pid
+	end
+	Tracer.new pid
+end

data/samples/disassemble-gui.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+#    This file is part of Metasm, the Ruby assembly manipulation suite
+#    Copyright (C) 2006-2009 Yoann GUILLOT
+#
+#    Licence is LGPL, see LICENCE in the top-level directory
+
+
+#
+# this script disassembles an executable (elf/pe) using the GTK front-end
+# use live:bla to open a running process whose filename contains 'bla'
+#
+# key binding (non exhaustive):
+#  Enter to follow a label (the current hilighted word)
+#  Esc to return to the previous position
+#  Space to switch between listing and graph views
+#  Tab to decompile (on already disassembled code)
+#  'c' to start disassembling from the cursor position
+#  'g' to go to a specific address (label/042h)
+#  'l' to list known labels
+#  'f' to list known functions
+#  'x' to list xrefs to current address
+#  'n' to rename a label (current word or current address)
+#  ctrl+'r' to run arbitrary ruby code in the context of the Gui objet (access to 'dasm', 'curaddr')
+#  ctrl+mousewheel to zoom in graph view ; also doubleclick on the background ('fit to window'/'reset zoom')
+#
+
+require 'metasm'
+require 'optparse'
+
+$VERBOSE = true
+
+# parse arguments
+opts = { :sc_cpu => 'Ia32' }
+OptionParser.new { |opt|
+	opt.banner = 'Usage: disassemble-gtk.rb [options] <executable> [<entrypoints>]'
+	opt.on('--no-data-trace', 'do not backtrace memory read/write accesses') { opts[:nodatatrace] = true }
+	opt.on('--debug-backtrace', 'enable backtrace-related debug messages (very verbose)') { opts[:debugbacktrace] = true }
+	opt.on('-P <plugin>', '--plugin <plugin>', 'load a metasm disassembler/debugger plugin') { |h| (opts[:plugin] ||= []) << h }
+	opt.on('-e <code>', '--eval <code>', 'eval a ruby code') { |h| (opts[:hookstr] ||= []) << h }
+	opt.on('--map <mapfile>', 'load a map file (addr <-> name association)') { |f| opts[:map] = f }
+	opt.on('--fast', 'dasm cli args with disassemble_fast_deep') { opts[:fast] = true }
+	opt.on('--decompile') { opts[:decompile] = true }
+	opt.on('--gui <gtk|win32|qt>') { |g| require 'metasm/gui/' + g }
+	opt.on('--cpu <cpu>', 'the CPU class to use for a shellcode (Ia32, X64, ...)') { |c| opts[:sc_cpu] = c }
+	opt.on('--exe <exe_fmt>', 'the executable file format to use (PE, ELF, ...)') { |c| opts[:exe_fmt] = c }
+	opt.on('--rebase <addr>', 'rebase the loaded file to <addr>') { |a| opts[:rebase] = Integer(a) }
+	opt.on('-c <header>', '--c-header <header>', 'read C function prototypes (for external library functions)') { |h| opts[:cheader] = h }
+	opt.on('-a', '--autoload', 'loads all relevant files with same filename (.h, .map..)') { opts[:autoload] = true }
+	opt.on('-v', '--verbose') { $VERBOSE = true }	# default
+	opt.on('-q', '--no-verbose') { $VERBOSE = false }
+	opt.on('-d', '--debug') { $DEBUG = $VERBOSE = true }
+}.parse!(ARGV)
+
+case exename = ARGV.shift
+when /^live:(.*)/
+	t = $1
+	t = t.to_i if $1 =~ /^[0-9]+$/
+	os = Metasm::OS.current
+	raise 'no such target' if not target = os.find_process(t) || os.create_process(t)
+	p target if $VERBOSE
+	w = Metasm::Gui::DbgWindow.new(target.debugger, "#{target.pid}:#{target.modules[0].path rescue nil} - metasm debugger")
+	dbg = w.dbg_widget.dbg
+when /^(tcp:|udp:)?..+:/
+	dbg = Metasm::GdbRemoteDebugger.new(exename, opts[:sc_cpu])
+	w = Metasm::Gui::DbgWindow.new(dbg, "remote - metasm debugger")
+else
+	w = Metasm::Gui::DasmWindow.new("#{exename + ' - ' if exename}metasm disassembler")
+	if exename
+		exe = w.loadfile(exename, opts[:sc_cpu], opts[:exe_fmt])
+		exe.disassembler.rebase(opts[:rebase]) if opts[:rebase]
+		if opts[:autoload]
+			basename = exename.sub(/\.\w\w?\w?$/, '')
+			opts[:map] ||= basename + '.map' if File.exist?(basename + '.map')
+			opts[:cheader] ||= basename + '.h' if File.exist?(basename + '.h')
+			(opts[:plugin] ||= []) << (basename + '.rb') if File.exist?(basename + '.rb')
+		end
+	end
+end
+
+ep = ARGV.map { |arg| (?0..?9).include?(arg[0]) ? Integer(arg) : arg }
+
+if exe
+	dasm = exe.init_disassembler
+
+	dasm.load_map opts[:map] if opts[:map]
+	dasm.parse_c_file opts[:cheader] if opts[:cheader]
+	dasm.backtrace_maxblocks_data = -1 if opts[:nodatatrace]
+	dasm.debug_backtrace = true if opts[:debugbacktrace]
+	dasm.disassemble_fast_deep(*ep) if opts[:fast]
+	dasm.callback_finished = lambda { w.dasm_widget.focus_addr w.dasm_widget.curaddr, :decompile ; dasm.decompiler.finalize } if opts[:decompile]
+elsif dbg
+	dbg.load_map opts[:map] if opts[:map]
+	opts[:plugin].to_a.each { |p| dbg.load_plugin(p) }
+end
+if dasm
+	w.display(dasm, ep)
+	opts[:plugin].to_a.each { |p| dasm.load_plugin(p) }
+end
+
+opts[:hookstr].to_a.each { |f| eval f }
+
+Metasm::Gui.main