emonti-jdi_hook 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2009-05-15
+
+* 1 major enhancement
+  * Birthday!

data/README.rdoc

@@ -0,0 +1,85 @@
+jdi_hook
+    by Eric Monti
+    http://github.com/emonti/jdi_hook
+
+== DESCRIPTION:
+
+JdiHook is a ruby-scriptable Java debugger based on and around Sun's Java 
+Debugging Interface (JDI) API.
+
+== FEATURES/PROBLEMS:
+
+* JdiHook aims to provide a scriptable engine around Sun's Java Debugging 
+  Interface (JDI) using JRuby. The uses of such an engine are intentionally 
+  open-ended, but the initial rationale was the need for custom instrumentation 
+  and dynamic analysis tools for Java applications with a reverse engineering 
+  and vulnerability testing mindset.
+
+* You already use JAD or JODE for class decompiling, but you need a quick and 
+  painless way to observe call trees, hit traces, and other target behaviors 
+  during runtime. Create bespoke Java runtime debugging scripts just like you 
+  would using PyDbg or Ragweed on a native target.
+
+== SYNOPSIS:
+
+  require 'rubygems'
+  require 'jdi_hook'
+
+  # Start a java target class. Kind of equivalent to running 'jdb HelloWorld'
+  vm = JdiHook.command_line_launch("HelloWorld")
+
+  # Instantiate and attach debugging event handler. MethodTracer is geared
+  # for attaching hooks to method entry and exit events.
+  dbg = JdiHook::MethodTracer.new vm, :redirect_stdio => true
+
+  # Define some handlers for Java method entry and exit events to dump
+  # some information about the method invocation. Event handlers for 
+  # MethodTracer are supplied as Ruby Proc objects (or blocks if you will)
+  en_proc = lambda {|this, evt| puts " [*] " << this.notify_entry(evt.method) }
+  ex_proc = lambda {|this, evt| puts " [*] " << this.notify_exit(evt.method) }
+
+  # Configure some event hooks to fire on regex pattern matches by method name
+  dbg.meth_hooks = { 
+    /\.main$/ => { :on_entry => en_proc, :on_exit => ex_proc },
+    /.*/      => { :on_entry => en_proc },
+  }
+
+  # "Continue" the target from the debugger
+  dbg.go
+
+
+== REQUIREMENTS:
+
+* A JRE (recommend Sun JDK version 1.6+) - http://java.sun.com/javase/downloads/
+* jruby - http://jruby.org
+
+== INSTALL:
+
+* jruby -S gem sources -a http://gems.github.com # only have to do this once
+* jruby -S gem install emonti-rbkb
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Eric Monti - Matasano Security
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,31 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'jdi_hook'
+
+task :default => 'spec:run'
+
+PROJ.name = 'jdi_hook'
+PROJ.authors = 'Eric Monti'
+PROJ.email = 'emonti@matasano.com'
+PROJ.url = 'http://github.com/emonti/jdi_hook'
+PROJ.version = JdiHook::VERSION
+PROJ.rubyforge.name = 'jdi_hook'
+PROJ.readme_file = 'README.rdoc'
+
+PROJ.spec.opts << '--color'
+
+# EOF

data/jdi_hook.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{jdi_hook}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Eric Monti"]
+  s.date = %q{2009-05-15}
+  s.description = %q{JdiHook is a ruby-scriptable Java debugger based on and around Sun's Java  Debugging Interface (JDI) API.}
+  s.email = %q{emonti@matasano.com}
+  s.extra_rdoc_files = ["History.txt", "README.rdoc"]
+  s.files = ["History.txt", "README.rdoc", "Rakefile", "jdi_hook.gemspec", "lib/jdi_hook.rb", "lib/jdi_hook/base_debugger.rb", "lib/jdi_hook/event_thread.rb", "lib/jdi_hook/method_tracer.rb", "lib/jdi_hook/stream_redirect_thread.rb", "samples/base_test.rb", "samples/meth_test.rb", "tasks/ann.rake", "tasks/bones.rake", "tasks/gem.rake", "tasks/git.rake", "tasks/notes.rake", "tasks/post_load.rake", "tasks/rdoc.rake", "tasks/rubyforge.rake", "tasks/setup.rb", "tasks/spec.rake", "tasks/svn.rake", "tasks/test.rake", "tasks/zentest.rake"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/emonti/jdi_hook}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{jdi_hook}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{JdiHook is a ruby-scriptable Java debugger based on and around Sun's Java  Debugging Interface (JDI) API}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<bones>, [">= 2.5.0"])
+    else
+      s.add_dependency(%q<bones>, [">= 2.5.0"])
+    end
+  else
+    s.add_dependency(%q<bones>, [">= 2.5.0"])
+  end
+end

data/lib/jdi_hook.rb

@@ -0,0 +1,166 @@
+
+module JdiHook
+  VERSION = '1.0.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+
+
+  include Java
+
+  include_class [
+    "com.sun.jdi.IncompatibleThreadStateException",
+    "com.sun.jdi.VMDisconnectedException",
+    "com.sun.jdi.InternalException",
+    "com.sun.jdi.event.ClassPrepareEvent",
+    "com.sun.jdi.event.MethodEntryEvent",
+    "com.sun.jdi.event.MethodExitEvent",
+    "com.sun.jdi.event.ModificationWatchpointEvent",
+    "com.sun.jdi.event.StepEvent",
+    "com.sun.jdi.event.ThreadDeathEvent",
+    "com.sun.jdi.event.VMDeathEvent",
+    "com.sun.jdi.event.VMDisconnectEvent",
+    "com.sun.jdi.event.VMStartEvent",
+    "com.sun.jdi.request.EventRequest",
+    "com.sun.jdi.request.StepRequest",
+    "java.io.InputStreamReader",
+    "java.lang.InterruptedException", 
+    "java.util.List",
+    "java.util.Map",
+  ]
+
+  ## Class sugar methods
+
+  # Shorthand for com.sun.jdi.Bootstrap.virtualMachineManager()
+  def self.vm_mgr
+    com.sun.jdi.Bootstrap.virtualMachineManager()
+  end
+
+  # Shorthand for com.sun.jdi.Bootstrap.virtualMachineManager.allConnectors()
+  def self.vm_connectors
+    vm_mgr.allConnectors()
+  end
+
+  # Launches a target VM by running it with commandline arguments and 
+  # attaches to it.
+  #
+  # Returns: instance of VirtualMachineImpl
+  #
+  # Arguments:
+  #   main = String or Array command line for class target
+  #   o = an optional Hash of parameters:
+  #     :options      = Additional options such as '-classic' (optional)
+  #     :home         = JAVA_HOME path (default: probably your JAVA_HOME)
+  #     :suspend      = whether to suspend the target on start (default: true)
+  #     :vmexec       = what to run through exec (default: java)
+  #     :quote        = the quote char for tokenizing args? (default: ")
+  def self.command_line_launch(main, o=nil)
+    o ||= {}
+    o[:main] = [*main].join(' ')
+    o[:options] = [*o[:options]].join(' ') if o[:options]
+    con, args = get_connector("com.sun.jdi.CommandLineLaunch", o)
+    return con.launch(args)
+  end
+
+  # Attaches to a running VM by process ID on the system.
+  #
+  # Note: Process attaching by pid only works if both the debugger and target 
+  # VM are Java 1.6 or higher.
+  #
+  # Returns: instance of VirtualMachineImpl
+  #
+  # Arguments:
+  #   pid = process ID to attach to
+  #   o = an optional Hash of parameters:
+  #     :timeout  = connection timeout? (optional)
+  def self.process_attach(pid, o=nil)
+    o ||= {}
+    o[:pid] = pid.to_s
+    con, args = get_connector("com.sun.jdi.ProcessAttach", o)
+    return con.attach(args)
+  end
+
+  # Attaches to a running VM by opening a TCP socket to the target
+  #
+  # Returns: instance of VirtualMachineImpl
+  #
+  # Arguments:
+  #   port = port to connect to
+  #   o = an optional Hash of parameters:
+  #     :hostname = host to connect to (default = localhost)
+  #     :timeout  = connection timeout? (optional)
+  def self.socket_attach(port, o=nil)
+    o ||= {}
+    o[:port] = port.to_i
+    con, args = get_connector("com.sun.jdi.SocketAttach", o)
+    return con.attach(args)
+  end
+
+  # Connects to a running VM by awaiting a connection via TCP socket
+  # the target initiates the connection to this listener.
+  #
+  # Returns: instance of VirtualMachineImpl
+  #
+  # Arguments:
+  #   port = port to listen on
+  #   o = an optional Hash of parameters:
+  #     :localAddress = address to listen on (default = 0.0.0.0)
+  #     :timeout      = connection timeout? (optional)
+  def self.socket_listen(port, o=nil)
+    o ||= {}
+    o[:port] = port.to_i
+    con, args = get_connector("com.sun.jdi.SocketListen", o)
+    return con.accept(args)
+  end
+
+  # Finds a connector of the given name from the virtual machine manager
+  # and prepares arguments based on its defaultArguments()
+  #
+  # Returns: an array containing the connector and prepared arguments
+  def self.get_connector(name, opts)
+    unless con=vm_connectors.find {|c| c.name == name}
+      raise "Can't get connector named #{name.inspect}'"
+    end
+    args = con.defaultArguments()
+    opts.each {|k,v| args.get(k.to_s).setValue(v) }
+    return [con, args]
+  end
+
+  ##### Cruft added by mr bones:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+end
+JdiHook.require_all_libs_relative_to(__FILE__)
+

data/lib/jdi_hook/base_debugger.rb

@@ -0,0 +1,119 @@
+module JdiHook
+  # This is a base wrapper class for setting up an event handler for event
+  # requests in a debugee target VM.
+  #
+  # Implementations should override the following callbacks: 
+  # create_event_requests, receive_event, and cleanup
+  class BaseDebugger
+    include_class [  
+      "java.lang.InterruptedException",
+      "com.sun.jdi.request.EventRequest",
+    ] 
+
+    attr_accessor :class_filters_exc, :class_filters_inc
+    attr_reader   :vm
+
+    DEFAULT_EXCLUDES = [
+      # Base java/sun stuff to exclude
+      "java.*", "javax.*", "sun.*", "com.sun.*", 
+      # several exclusions for jruby/jirb targets
+      "org.jruby.*", "jline.*", "ruby.*", "org.jcodings.*", "jruby.*", 
+      "org.joni.*"
+    ]
+
+    def initialize(vm, opts={})
+      @vm = vm
+      @class_filters_exc = opts[:class_filters_exc] || DEFAULT_EXCLUDES
+      @class_filters_inc = opts[:class_filters_inc] || Array.new
+      @debug_mode = opts[:debug_mode] || 0
+      @redirect_stdio = opts[:redirect_stdio]
+    end
+
+    # This method begins the debugging session setting up the event
+    # handler and 
+    def go
+      @vm.setDebugTraceMode(@debug_mode)
+      create_event_requests(@vm.eventRequestManager() )
+      @evt_thread = EventThread.new(self)
+      @evt_thread.start()
+      if @redirect_stdio
+        redirect_target_output($stdout, $stderr) 
+      end
+
+      begin
+        @vm.resume()
+        @evt_thread.join()
+      rescue InterruptedException => e
+        STDERR.puts "** Got InterruptedException: #{exc}"
+      ensure
+        cleanup()
+        @evt_thread = nil
+      end
+    end
+
+    # This method adds class exclusion and inclusion filters to an
+    # event request. It should be called from overridden create_event_requests
+    # implementations while setting up new event requests for the target VM.
+    def filter_classes(req)
+      if exc=@class_filters_exc
+        exc.each {|e| req.addClassExclusionFilter(e) }
+      end
+      if inc=@class_filters_inc
+        inc.each {|i| req.addClassFilter(i) }
+      end
+    end
+
+    # This is a callback to set up event requests.
+    # It is called with one argument 'mgr' which is the event request
+    # manager for the target VM.
+    def create_event_requests(mgr)
+      # stub
+    end
+
+    # This is a callback to dispatch incoming events
+    # override it to perform whatever specific actions you want based
+    # on the event type
+    def receive_event(event)
+      # stub
+    end
+
+    # This is a callback to handle the end of the debugging session
+    # override it to perform any cleanup tasks or wrap up.
+    def cleanup()
+      # stub
+    end
+
+    # This method starts and joins threads to redirect stderr and stdout from 
+    # the target process. Capturing IO this way from the target is generally
+    # only possible if the target is connected through a command line 
+    # launch connector.
+    #
+    # This method should only be called from the 'go' method after the
+    # primary event thread has been started but before it has been 
+    # joined.
+    def redirect_target_output(out=$stdout, err=$stderr)
+      if process = @vm.process()
+        unless @evt_thread and @evt_thread.connected
+          raise "the event thread has not yet been started"
+        end
+        out_thread = StreamRedirectThread.new("target stdout reader",
+                                               process.getInputStream(),
+                                               "Process STDOUT",
+                                               out)
+
+        err_thread = StreamRedirectThread.new("target stderr reader",
+                                               process.getErrorStream(),
+                                               "Process STDERR",
+                                               err)
+
+        out_thread.start()
+        err_thread.start()
+        out_thread.join()
+        err_thread.join()
+        return [out_thread, err_thread]
+      else
+        STDERR.puts "WARNING: can't redirect output on this target'"
+      end
+    end
+  end
+end

data/lib/jdi_hook/event_thread.rb

@@ -0,0 +1,68 @@
+module JdiHook
+  class EventThread < java.lang.Thread
+    include_class [
+      "java.lang.InterruptedException", 
+      "com.sun.jdi.VMDisconnectedException",
+      "com.sun.jdi.event.VMStartEvent",
+      "com.sun.jdi.event.VMDeathEvent",
+      "com.sun.jdi.event.VMDisconnectEvent",
+    ]
+
+    attr_reader :connected
+
+    def initialize( handler )
+      @handler = handler
+      @vm = handler.vm
+    end
+
+    def start(*args)
+      @connected = true
+      super(*args)
+    end
+
+    def run()
+      queue = @vm.eventQueue()
+      while @connected
+        begin
+          events = queue.remove
+          events.each do |evt|
+            @connected=false if evt.is_a? VMDisconnectEvent
+            @handler.receive_event(evt) if @handler.respond_to?(:receive_event)
+          end
+          events.resume()
+        rescue InterruptedException
+          # ignore
+        rescue VMDisconnectedException
+          # A VMDisconnectedException has happened while dealing with
+          # another event. We need to bail so that we terminate correctly. 
+          # XXX do we really need to do this?
+          @connected=false
+          break
+        end
+      end
+    end
+
+    # A VMDisconnectedException has happened while dealing with
+    # another event. We need to flush the event queue, dealing only
+    # with exit events (VMDeath, VMDisconnect) so that we terminate
+    # correctly.
+    def handleDisconnectedException
+      queue = @vm.eventQueue()
+      while @connected
+        begin
+          eventSet = queue.remove()
+          eventSet.each do |event|
+            if VMDeathEvent === event
+              vmDeathEvent(event)
+            elsif VMDisconnectEvent === event
+              vmDisconnectEvent(event)
+            end
+          end
+        rescue InterruptedException
+          # ignore
+        end
+      end
+    end
+
+  end
+end