class Unicorn::Uc

Overview

Unicorn engine class

Defined in:

Constructors

Instance Method Summary

Constructor Detail

def self.new(arch : Int32, mode : Int32) #

Create new instance of unicorn engine.

  • arch: architecture type (UC_ARCH_*)
  • mode: hardware mode. This is combined of UC_MODE_*

Instance Method Detail

def close #

Close a Unicorn engine instance.


def emu_start(begin_addr : Int, end_addr : Int, timeout : Int = 0, count : Int = 0) #

Emulate machine code in a specific duration of time.

  • begin_addr: address where emulation starts
  • end_addr: address where emulation stops (i.e when this address is hit)
  • timeout: duration to emulate the code (in microseconds). When this value is 0, we will emulate the code in infinite time, until the code is finished.
  • count: the number of instructions to be emulated. When this value is 0, we will emulate all the code available, until the code is finished.

def emu_stop #

Stop the emulation


def finalize #

Close a Unicorn engine instance.


def hook_block(begin_addr : Int = 1, end_addr = 0, &callback : UInt64, UInt64 -> ) : UcLib::UcHook #

Add hook to trace basic blocks..

If start < end, the callback is called only if related address is in range.

The block is of the form { |address, size| }

Returns UcLib::UcHook that can be used in #hook_del to remove the hook.


def hook_code(begin_addr : Int = 1, end_addr = 0, &callback : UInt64, UInt64 -> ) : UcLib::UcHook #

Add hook to trace instructions.

If start < end, the callback is called only if related address is in range.

The block is of the form { |address, size| }

Returns UcLib::UcHook that can be used in #hook_del to remove the hook.


def hook_del(handle : UcLib::UcHook) #

Unregister (remove) a hook callback.

  • handle: Value returned by one of the hook functions

def hook_insn_in(begin_addr : Int = 1, end_addr = 0, &callback : UInt64, UInt64 -> UInt64) : UcLib::UcHook #

Add hook to trace X86 in instruction

If start < end, the callback is called only if related address is in range.

The block is of the form { |port, size| value }

Returns UcLib::UcHook that can be used in #hook_del to remove the hook.


def hook_insn_out(begin_addr : Int = 1, end_addr = 0, &callback : UInt64, UInt64, UInt64 -> ) : UcLib::UcHook #

Add hook to trace X86 out instruction

If start < end, the callback is called only if related address is in range.

The block is of the form { |port, size, value| }

Returns UcLib::UcHook that can be used in #hook_del to remove the hook.


def hook_intr(begin_addr : Int = 1, end_addr = 0, &callback : UInt64 -> ) : UcLib::UcHook #

Add hook to trace interrupts.

If start < end, the callback is called only if related address is in range.


def hook_mem(type : Int, begin_addr : Int = 1, end_addr = 0, &callback : UInt64, UInt64, UInt64, UInt64 -> Bool?) : UcLib::UcHook #

Add hook to trace memory read/write

If start < end, the callback is called only if related address is in range.

The block is of the form { |address, size| }

Returns UcLib::UcHook that can be used in #hook_del to remove the hook.


def hook_syscall(begin_addr : Int = 1, end_addr = 0, &callback : -> ) : UcLib::UcHook #

Add hook to trace syscall.

If start < end, the callback is called only if related address is in range.


def mem_map(address : Int, size : Int, perms : Int = UC_PROT_ALL) #

Map memory in for emulation.

  • address: Starting address of the new memory region to be mapped in.
  • size: Size of the new memory region to be mapped in.
  • perms: Permissions for the newly mapped region.

Both address and size must be multiple of 4KB, or this will raise the exception UcError(error: UC_ERR_ARG).


def mem_protect(address : Int, size : Int, perms : Int) #

Set memory permissions for emulation memory.

  • address: Starting address of the new memory region to be modified
  • size: Size of the memory region to be modified.
  • perms: New permissions for the mapped region.

Both address and size must be multiple of 4KB, or this will raise the exception UcError(error: UC_ERR_ARG).


def mem_read(address : Int, size : Int) : Array(UInt8) #

Read a range of bytes in memory.

  • address: starting memory address of bytes to get.
  • size: size of memory to read.

def mem_regions : Array(Tuple(UInt64, UInt64, UInt32)) #

Retrieve all memory regions mapped by #mem_map.

Each region is represented by a tuple of the form {begin_addr, end_addr, permissions}


def mem_unmap(address : Int, size : Int) #

Unmap a region of emulation memory.

  • address: Starting address of the memory region to be unmapped.
  • size: size of the memory region to be modified.

Both address and size must be multiple of 4KB, or this will raise the exception UcError(error: UC_ERR_ARG).


def mem_write(address : Int, code : Array(UInt8)) #

Write to a range of bytes in memory.

  • address: starting memory address of bytes to set.
  • code: data to be written to memory.

def mem_write(address : Int, code : String) #

Write to a range of bytes in memory from a String.

  • address: starting memory address of bytes to set.
  • code: data to be written to memory.

def reg_read(reg : Int) : Int #

Read register value.


def reg_write(reg : Int, value : Int) #

Write to register.