Ptrace 0.9.1

data/README

@@ -0,0 +1,105 @@
+
+			  	Ptrace
+
+A Ruby C extension (and gem) for the POSIX ptrace facility.
+
+NOTE: This is currently alpha software, and is released only to publish the
+      API of the module. This should not be used in production software, as
+      many features are incomplete.
+
+BUILD
+-----
+
+The standard C extension build process is used:
+
+	bash# ruby extconf.rb
+	bash# make
+
+Note that the Ruby headers must be installed. On Ubuntu, these are in the
+ruby-dev or ruby1.9-dev package.
+
+
+The gem is built using the standard gem build command:
+
+	bash# gem build Ptrace.gemspec
+
+
+The top-level Makefile supports each of these builds with the commands
+'make' and 'make gem'.
+
+	bash# make
+	# builds C extension
+	bash# make gem
+	# builds the gem
+
+
+
+EXAMPLES
+
+Extended examples are provided in the 'examples' directory. The following
+code snippets give a brief overview of using the Ptrace extension.
+
+  # attach to process
+  pid = 10167	# just an example, use a real PID!
+  tgt = Ptrace::Target.attach(pid)
+  # terminate process
+  tgt.kill
+
+  # launch process 
+  cmd = './a.out'
+  tgt = Ptrace::Target.launch cmd
+  # detach
+  tgt.detach
+
+  # step first 10 instructions, printing general registers
+  tgt = Ptrace::Target.launch cmd
+  10.times do |i|
+    puts "DEBUGGER STEP #{i}"
+    # print registers
+    tgt.regs.read.each { |name, val| puts "%s: %016X" % name, val }
+    tgt.step
+  end
+  # continue process
+  tgt.cont
+
+  
+  # print register contents on syscall in/out
+  tgt = Ptrace::Target.launch cmd
+  cont = true
+  while cont
+    begin
+      tgt.syscall
+      puts "IN: #{tgt.regs.read.inspect}"
+      tgt.syscall
+      puts "OUT: #{tgt.regs.read.inspect}"
+    rescue Ptrace::InvalidProcessError
+      cont = false
+    end
+
+  end
+
+  # step first ten instructions, printing bytes at EIP and ESP
+  tgt = Ptrace::Target.launch cmd
+  10.times do |i|
+  sleep 1
+    begin
+      tgt.step
+
+      regs = tgt.regs.read
+      ip = (regs.include? 'rip') ? regs['rip'] : regs['eip']
+      puts ("DEBUGGER STEP %d: %X in %d" % [i, ip, tgt.pid])
+
+      v = tgt.text.peek(ip)
+      bytes = [v, v >> 8, v >> 12, v >> 16].map { |byte| byte & 0xFF }
+      puts "    BYTES AT EIP: #{bytes.map{ |byte| "%02X" % byte }.join(' ')}"
+
+      esp_name = (regs.include? 'rsp') ? 'rsp' : 'esp'
+      v = tgt.data.peek(regs[esp_name])
+      bytes = [v, v >> 8, v >> 12, v >> 16].map { |byte| byte & 0xFF }
+      puts "    BYTES AT ESP: #{bytes.map{ |byte| "%02X" % byte }.join(' ')}"
+
+      # Modify ESP, just because we can
+      puts "    ...WRITING ESP..."
+      tgt.data.poke(regs[esp_name], v + 0x100)
+  end
+  tgt.cont

data/examples/kill.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'Ptrace'
+
+if __FILE__ == $0
+
+  cmd = ARGV.join(' ')
+
+  tgt = Ptrace::Target.launch cmd
+  puts "launched CMD #{tgt.pid}"
+  puts "Killing..."
+  tgt.kill
+  puts "Done."
+end

data/examples/peekpoke.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+require 'Ptrace'
+
+if __FILE__ == $0
+
+  cmd = ARGV.join(' ')
+
+  tgt = Ptrace::Target.launch cmd
+  return if not tgt
+
+  puts "launched CMD #{cmd} as #{tgt.pid}"
+  10.times do |i|
+  sleep 1
+    begin
+      tgt.step
+
+      regs = tgt.regs.read
+      ip = (regs.include? 'rip') ? regs['rip'] : regs['eip']
+      puts ("DEBUGGER STEP %d: %X in %d" % [i, ip, tgt.pid])
+
+      v = tgt.text.peek(ip)
+      bytes = [v, v >> 8, v >> 12, v >> 16].map { |byte| byte & 0xFF }
+      puts "    BYTES AT EIP: #{bytes.map{ |byte| "%02X" % byte }.join(' ')}"
+
+      esp_name = (regs.include? 'rsp') ? 'rsp' : 'esp'
+      v = tgt.data.peek(regs[esp_name])
+      bytes = [v, v >> 8, v >> 12, v >> 16].map { |byte| byte & 0xFF }
+      puts "    BYTES AT ESP: #{bytes.map{ |byte| "%02X" % byte }.join(' ')}"
+
+      puts "    ...WRITING ESP..."
+      tgt.data.poke(regs[esp_name], v + 0x100)
+
+      regs = tgt.regs.read
+      v1 = tgt.data.peek(regs[esp_name])
+      bytes = [v1, v1 >> 8, v1 >> 12, v1 >> 16].map { |byte| byte & 0xFF }
+      puts "    BYTES AT EBP: #{bytes.map{ |byte| "%02X" % byte }.join(' ')}"
+
+      puts "    ...REVERTING ESP..."
+      tgt.data.poke(regs[esp_name], v)
+
+      regs = tgt.regs.read
+      v2 = tgt.data.peek(regs[esp_name])
+      bytes = [v2, v2 >> 8, v2 >> 12, v2 >> 16].map { |byte| byte & 0xFF }
+      puts "    BYTES AT EBP: #{bytes.map{ |byte| "%02X" % byte }.join(' ')}"
+    rescue Exception => e
+      puts e.message
+      puts e.backtrace.join("\n")
+    end
+  end
+  puts "DEBUGGER RESUME"
+  tgt.cont
+end

data/examples/regs.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# TODO : read, write regs
+
+require 'Ptrace'
+
+if __FILE__ == $0
+
+  cmd = ARGV.join(' ')
+
+  tgt = Ptrace::Target.launch cmd
+  return if not tgt
+
+  puts "launched CMD #{cmd} as #{tgt.pid}"
+  10.times do |i|
+  sleep 1
+    begin
+      tgt.step
+      regs = tgt.regs.read
+      ebx_name = (regs.include? 'rbx') ? 'rbx' : 'ebx'
+
+      v = regs[ebx_name]
+      puts "EBX ORIG : %016X" % v
+
+      tgt.regs[ebx_name] = v + 0x1000
+      tgt.regs.write
+
+      regs = tgt.regs.read
+      v1 = regs[ebx_name]
+      puts "EBX AFTER WRITE : %016X" % v1
+
+      tgt.regs[ebx_name] = v
+      tgt.regs.write
+
+      regs = tgt.regs.read
+      v2 = regs[ebx_name]
+      puts "EBX AFTER REVERT : %016X" % v2
+
+      # TODO: FPREGS
+
+    rescue Exception => e
+      puts e.message
+      puts e.backtrace.join("\n")
+    end
+  end
+  puts "DEBUGGER RESUME"
+  tgt.cont
+end

data/examples/syscall.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+require 'Ptrace'
+
+if __FILE__ == $0
+
+  cmd = ARGV.join(' ')
+
+  tgt = Ptrace::Target.launch cmd
+  puts "launched CMD #{tgt.pid}"
+  cont = true
+  while cont
+
+    begin
+      # test PT_SYSCALL directly
+      # call
+      tgt.syscall
+      puts "IN: #{tgt.regs.read.inspect}"
+
+      # ret
+      tgt.syscall
+      puts "OUT: #{tgt.regs.read.inspect}"
+
+      # test syscall wrapper
+      state = tgt.syscall_state
+      puts state.inspect
+    rescue Ptrace::InvalidProcessError
+      cont = false
+    end
+
+  end
+
+end