crabstone 3.0.3 → 4.0.4

data/lib/crabstone/cs_version.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+require 'crabstone/constants'
+require 'crabstone/version'
+
+module Crabstone
+  module_function
+
+  # Since some constants/structures are different in different Capstone versions,
+  # some scripts in Crabstone use this method to require the version-sensitive Ruby scripts.
+  # @param [String] path_tpl
+  # @return [Boolean]
+  # @example
+  #   version_require 'crabstone/binding/%v/structs'
+  #   # equivalent to "require 'crabstone/binding/4/structs'" if Capstone is version 4.
+  def version_require(path_tpl)
+    version_compatitable!
+    path = path_tpl.gsub('%v', cs_major_version.to_s)
+    require path
+  end
+
+  # Get the major version of capstone library.
+  #
+  # @return [Integer]
+  #   Returns the major version of Capstone.
+  def cs_major_version
+    cs_version.first
+  end
+
+  # @return [(Integer, Integer)]
+  def cs_version
+    return @cs_version if defined?(@cs_version)
+
+    maj = FFI::MemoryPointer.new(:int)
+    min = FFI::MemoryPointer.new(:int)
+    Binding.cs_version(maj, min)
+    @cs_version = [maj.read_int, min.read_int]
+  end
+
+  # Checks the cs_major is less or equal to Crabstone::VERSION.
+  def version_compatitable!
+    @version_compatitable ||=
+      cs_major_version <= Crabstone::BINDING_MAJ && cs_major_version >= 3
+    maj, min = cs_version
+    raise "FATAL: Crabstone v#{VERSION} doesn't support binding Capstone v#{maj}.#{min}" unless @version_compatitable
+  end
+
+  # @private
+  module Binding
+    extend FFI::Library
+    ffi_lib ['capstone', 'libcapstone.so.4', 'libcapstone.so.3']
+
+    attach_function :cs_version, %i[pointer pointer], :uint
+  end
+end

data/lib/crabstone/disassembler.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+require 'crabstone/binding'
+require 'crabstone/cs_version'
+require 'crabstone/error'
+require 'crabstone/instruction'
+
+module Crabstone
+  class Disassembler
+    SYNTAX = {
+      intel: 1,
+      att: 2,
+      no_regname: 3 # for PPC only
+    }.freeze
+
+    DETAIL = {
+      true => 3, # trololol
+      false => 0
+    }.freeze
+
+    SKIPDATA = {
+      true => 3, # trololol
+      false => 0
+    }.freeze
+
+    attr_reader :arch, :mode, :csh, :syntax, :decomposer
+
+    def initialize(arch, mode)
+      @arch = arch
+      @mode = mode
+      @p_csh = FFI::MemoryPointer.new(:ulong_long)
+      safe { Binding.cs_open(arch, mode, @p_csh) }
+
+      @csh = @p_csh.read_ulong_long
+    end
+
+    # After you close the engine, don't use it anymore. Can't believe I even
+    # have to write this.
+    #
+    # @return [void]
+    def close
+      safe { Binding.cs_close(@p_csh) }
+    end
+
+    def syntax=(new_stx)
+      Crabstone::Error.raise!(ErrOption) unless SYNTAX[new_stx]
+      set_raw_option(OPT_SYNTAX, SYNTAX[new_stx])
+      @syntax = new_stx
+    end
+
+    # @param [Boolean] new_val
+    def decomposer=(new_val)
+      Crabstone::Error.raise!(ErrOption) unless DETAIL[new_val]
+      set_raw_option(OPT_DETAIL, DETAIL[new_val])
+      @decomposer = new_val
+    end
+
+    def version
+      Crabstone.cs_version
+    end
+
+    def diet?
+      DIET_MODE
+    end
+
+    def errno
+      Binding.cs_errno(@csh)
+    end
+
+    def skipdata(mnemonic = '.byte')
+      cfg = Binding::SkipdataConfig.new
+      cfg[:mnemonic] = FFI::MemoryPointer.from_string(mnemonic.to_s)
+
+      if block_given?
+        cfg[:callback] = FFI::Function.new(
+          :size_t,
+          %i[pointer size_t size_t pointer]
+        ) do |code, sz, offset, _|
+          code = code.read_array_of_uchar(sz).pack('c*')
+          begin
+            Integer(yield(code, offset))
+          rescue StandardError
+            warn "Error in skipdata callback: #{$ERROR_INFO}"
+            # It will go on to crash, but now at least there's more info :)
+          end
+        end
+      end
+
+      set_raw_option(OPT_SKIPDATA_SETUP, cfg.pointer.address)
+      set_raw_option(OPT_SKIPDATA, SKIPDATA[true])
+    end
+
+    def skipdata_off
+      set_raw_option(OPT_SKIPDATA, SKIPDATA[false])
+    end
+
+    def reg_name(regid)
+      Crabstone::Error.raise!(ErrDiet) if DIET_MODE
+      name = Binding.cs_reg_name(csh, regid)
+      Crabstone::Error.raise!(ErrCsh) unless name
+      name
+    end
+
+    # @return [Array<Crabstone::Instruction>]
+    def disasm(code, offset, count = 0)
+      return [] if code.empty?
+
+      insn_ptr   = FFI::MemoryPointer.new(:pointer)
+      insn_count = Binding.cs_disasm(
+        @csh,
+        code,
+        code.bytesize,
+        offset,
+        count,
+        insn_ptr
+      )
+      Crabstone::Error.raise_errno!(errno) if insn_count.zero?
+
+      convert_disasm_result(insn_ptr, insn_count).tap { Binding.free(insn_ptr.read_pointer) }
+    end
+
+    def set_raw_option(opt, val)
+      safe { Binding.cs_option(csh, opt, val) }
+    end
+
+    private
+
+    # Convert the insn_ptr from cs_disasm into Ruby instruction objects.
+    # @param [FFI::MemoryPointer] insn_ptr
+    # @param [Integer] insn_count
+    # @return [Array<Crabstone::Instruction>]
+    def convert_disasm_result(insn_ptr, insn_count)
+      insn_sz = Binding::Instruction.size
+      Array.new(insn_count) do |i|
+        cs_insn_ptr = Binding.malloc(insn_sz)
+        Binding.memcpy(cs_insn_ptr, insn_ptr.read_pointer + i * insn_sz, insn_sz)
+        Crabstone::Instruction.new(@csh, Binding::Instruction.new(cs_insn_ptr), @arch)
+      end
+    end
+
+    def safe
+      yield.tap { |res| Crabstone::Error.raise_errno!(res) unless res.zero? }
+    end
+  end
+end

data/lib/crabstone/error.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# XXX: Auto-gerneate this file?
+# Error classes might be added in a newer Capstone version,
+# but this should not be frequent, currently this file is updated manually.
+
+module Crabstone
+  # @private
+  class Error < StandardError; end
+
+  class ErrArch < Error; end
+
+  class ErrCsh < Error; end
+
+  class ErrHandle < Error; end
+
+  class ErrMem < Error; end
+
+  class ErrMode < Error; end
+
+  class ErrOK < Error; end
+
+  class ErrOption < Error; end
+
+  class ErrDetail < Error; end
+
+  class ErrMemSetup < Error; end
+
+  class ErrVersion < Error; end
+
+  class ErrDiet < Error; end
+
+  class ErrSkipData < Error; end
+
+  class ErrX86ATT < Error; end
+
+  class ErrX86Intel < Error; end
+
+  class ErrX86MASM < Error; end
+
+  class Error
+    ERRNO = {
+      0 => ErrOK,
+      1 => ErrMem,
+      2 => ErrArch,
+      3 => ErrHandle,
+      4 => ErrCsh,
+      5 => ErrMode,
+      6 => ErrOption,
+      7 => ErrDetail,
+      8 => ErrMemSetup,
+      9 => ErrVersion,
+      10 => ErrDiet,
+      11 => ErrSkipData,
+      12 => ErrX86ATT,
+      13 => ErrX86Intel,
+      14 => ErrX86MASM
+    }.freeze
+
+    def self.raise_errno!(errno)
+      err_klass = ERRNO[errno]
+      raise 'Internal Error: Tried to raise unknown errno' unless err_klass
+
+      err_str = Binding.cs_strerror(errno)
+      raise err_klass, err_str
+    end
+
+    def self.raise!(klass)
+      raise "Invalid error class: #{klass}" unless klass.superclass == self
+
+      raise_errno!(ERRNO.invert[klass])
+    end
+  end
+end

data/lib/crabstone/instruction.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'crabstone/arch'
+require 'crabstone/binding'
+require 'crabstone/constants'
+require 'crabstone/error'
+
+module Crabstone
+  class Instruction
+    attr_reader :csh, :raw_insn
+
+    def initialize(csh, insn, arch)
+      @arch_module = Arch.module_of(arch)
+      @csh = csh
+      @raw_insn = insn
+      init_detail(insn[:detail]) if detailed?
+    end
+
+    def name
+      raise_if_diet
+      name = Binding.cs_insn_name(csh, id)
+      Crabstone::Error.raise!(ErrCsh) unless name
+      name
+    end
+
+    def group_name(grp)
+      raise_if_diet
+      name = Binding.cs_group_name(csh, Integer(grp))
+      Crabstone::Error.raise!(ErrCsh) unless name
+      name
+    end
+
+    # It's more informative to raise if CS_DETAIL is off than just return nil
+    def detailed?
+      !@raw_insn[:detail].pointer.null?
+    end
+
+    def detail
+      raise_unless_detailed
+      @detail
+    end
+
+    def regs_read
+      raise_unless_detailed
+      raise_if_diet
+      @regs_read
+    end
+
+    def regs_write
+      raise_unless_detailed
+      raise_if_diet
+      @regs_write
+    end
+
+    def groups
+      raise_unless_detailed
+      raise_if_diet
+      @groups
+    end
+
+    def group?(group_id)
+      raise_unless_detailed
+      raise_if_diet
+      Binding.cs_insn_group(csh, raw_insn, group_id)
+    end
+
+    def reads_reg?(reg)
+      raise_unless_detailed
+      raise_if_diet
+      Binding.cs_reg_read(csh, raw_insn, @arch_module.register(reg))
+    end
+
+    def writes_reg?(reg)
+      raise_unless_detailed
+      raise_if_diet
+      Binding.cs_reg_write(csh, raw_insn, @arch_module.register(reg))
+    end
+
+    # @return [{:regs_read => Array<Integer>, :regs_write => Array<Integer>}]
+    def regs_access
+      raise_unless_detailed
+      raise_if_diet
+
+      # XXX: Becare of if `typedef uint16_t cs_regs[64];` changes
+      regs_read = FFI::MemoryPointer.new(:uint16, 64)
+      regs_read_count = FFI::MemoryPointer.new(:uint8)
+      regs_write = FFI::MemoryPointer.new(:uint16, 64)
+      regs_write_count = FFI::MemoryPointer.new(:uint8)
+      err = Binding.cs_regs_access(csh, raw_insn, regs_read, regs_read_count, regs_write, regs_write_count)
+      Crabstone::Error.raise_errno(err) if err.nonzero?
+      {
+        regs_read: regs_read.read_array_of_short(regs_read_count.read_int8),
+        regs_write: regs_write.read_array_of_short(regs_write_count.read_int8)
+      }
+    end
+
+    def mnemonic
+      raise_if_diet
+      raw_insn[:mnemonic]
+    end
+
+    def op_str
+      raise_if_diet
+      raw_insn[:op_str]
+    end
+
+    def op_count(op_type = nil)
+      raise_unless_detailed
+      if op_type
+        Binding.cs_op_count(csh, raw_insn, op_type)
+      else
+        operands.size
+      end
+    end
+
+    def bytes
+      raw_insn[:bytes].first(raw_insn[:size])
+    end
+
+    # So an Instruction should respond to all the methods in Instruction, and
+    # all the methods in the Arch specific Instruction class. The methods /
+    # members that have special handling for detail mode or diet mode are
+    # handled above. The rest is dynamically dispatched below.
+    def method_missing(meth, *args)
+      # Dispatch to toplevel Instruction class ( this file )
+      return raw_insn[meth] if raw_insn.members.include?(meth)
+
+      # Nothing else is available without details.
+      unless detailed?
+        raise(
+          NoMethodError,
+          "Either CS_DETAIL is off, or #{self.class} doesn't implement #{meth}"
+        )
+      end
+      # Dispatch to the architecture specific Instruction ( in arch/ )
+      return @arch_insn.__send__(meth, *args) if @arch_insn.respond_to?(meth)
+      return @arch_insn[meth] if @arch_insn.members.include?(meth)
+
+      super
+    end
+
+    def respond_to_missing?(meth, include_private = true)
+      return true if raw_insn.members.include?(meth)
+      return super unless detailed?
+      return true if @arch_insn.respond_to?(meth)
+      return true if @arch_insn.members.include?(meth)
+
+      super
+    end
+
+    private
+
+    def raise_unless_detailed
+      Crabstone::Error.raise!(ErrDetail) unless detailed?
+    end
+
+    def raise_if_diet
+      Crabstone::Error.raise!(ErrDiet) if DIET_MODE
+    end
+
+    def init_detail(detail)
+      @detail     = detail
+      @arch_insn  = @detail[:arch][arch_field]
+      @regs_read  = @detail[:regs_read].first(@detail[:regs_read_count])
+      @regs_write = @detail[:regs_write].first(@detail[:regs_write_count])
+      @groups     = @detail[:groups].first(@detail[:groups_count])
+    end
+
+    # Find the field name of Architecture.
+    def arch_field
+      klass = @arch_module.const_get(:Instruction)
+      obj = Binding::Architecture.new
+      Binding::Architecture.members.find do |sym|
+        obj[sym].instance_of?(klass)
+      end
+    end
+  end
+end

data/lib/crabstone/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Crabstone
+  VERSION = '4.0.4'
+end