Struct Emu 

pub struct Emu {

    pub maps: Maps,
    pub hooks: Hooks,
    pub exp: u64,
    pub break_on_alert: bool,
    pub bp: Breakpoints,
    pub cfg: Config,
    pub colors: Colors,
    pub pos: u64,
    pub max_pos: Option<u64>,
    pub force_break: bool,
    pub force_reload: bool,
    pub tls_callbacks: Vec<u64>,
    pub instruction: Option<Instruction>,
    pub decoder_position: usize,
    pub memory_operations: Vec<MemoryOperation>,
    pub main_thread_cont: u64,
    pub gateway_return: u64,
    pub is_running: Arc<AtomicU32>,
    pub break_on_next_cmp: bool,
    pub break_on_next_return: bool,
    pub filename: String,
    pub enabled_ctrlc: bool,
    pub run_until_ret: bool,
    pub running_script: bool,
    pub banzai: Banzai,
    pub mnemonic: String,
    pub linux: bool,
    pub now: Instant,
    pub skip_apicall: bool,
    pub its_apicall: Option<u64>,
    pub last_instruction_size: usize,
    pub pe64: Option<PE64>,
    pub pe32: Option<PE32>,
    pub rep: Option<u64>,
    pub tick: usize,
    pub trace_file: Option<File>,
    pub base: u64,
    pub formatter: IntelFormatter,
    pub heap_addr: u64,
    pub rng: RefCell<ThreadRng>,
    pub threads: Vec<ThreadContext>,
    pub current_thread_id: usize,
    pub global_locks: GlobalLocks,
    pub instruction_cache: InstructionCache,
    pub definitions: HashMap<u64, Definition>,
    pub stored_contexts: HashMap<String, StoredContext>,
    pub entropy: f64,
    pub heap_management: Option<Box<O1Heap>>,
}

Fields

maps: Maps

hooks: Hooks

exp: u64

break_on_alert: bool

bp: Breakpoints

cfg: Config

colors: Colors

pos: u64

max_pos: Option<u64>

force_break: bool

force_reload: bool

tls_callbacks: Vec<u64>

instruction: Option<Instruction>

decoder_position: usize

memory_operations: Vec<MemoryOperation>

main_thread_cont: u64

gateway_return: u64

is_running: Arc<AtomicU32>

break_on_next_cmp: bool

break_on_next_return: bool

filename: String

enabled_ctrlc: bool

run_until_ret: bool

running_script: bool

banzai: Banzai

mnemonic: String

linux: bool

now: Instant

skip_apicall: bool

its_apicall: Option<u64>

last_instruction_size: usize

pe64: Option<PE64>

pe32: Option<PE32>

rep: Option<u64>

tick: usize

trace_file: Option<File>

base: u64

formatter: IntelFormatter

heap_addr: u64

rng: RefCell<ThreadRng>

threads: Vec<ThreadContext>

current_thread_id: usize

global_locks: GlobalLocks

instruction_cache: InstructionCache

definitions: HashMap<u64, Definition>

stored_contexts: HashMap<String, StoredContext>

entropy: f64

heap_management: Option<Box<O1Heap>>

Implementations

impl Emu

pub fn show_definition(&mut self)

impl Emu

pub fn enable_banzai(&mut self)

Enable banzai mode, in this mode on the windows api of 32bits, if the called api is not implemented will try to fix the stack (because knows the number of params of every api) and will continue the emulation.

pub fn disable_banzai(&mut self)

Disable the banzai mode, if the emualted code call an unimplemented 32bits winapis, the emulation will stop.

pub fn banzai_add(&mut self, name: &str, nparams: i32)

Add windows 32bits apis to the banzai mode, with this info mwemu will know how to continue the emulating inf this api is found and is not implemented.

impl Emu

pub fn call_stack(&self) -> &Vec<(u64, u64)>

pub fn call_stack_mut(&mut self) -> &mut Vec<(u64, u64)>

impl Emu

pub fn set_config(&mut self, cfg: Config)

Set a custom config, normally used only from commandline tool main.rs

pub fn set_base_address(&mut self, addr: u64)

change default base address, code map will be loaded there.

pub fn set_stack_address(&mut self, addr: u64)

pub fn set_verbose(&mut self, n: u32)

Set verbose level. 0: only will print syscalls and api name called. 1: same than 0 and also some messages like undefined behaviours or polymorfic code etc. 2: same than 1 and also will print the assembly code, this will make it much slower. 3: same than 2 but also in the case of a rep prefix will see every rep iteration.

impl Emu

pub fn enable_ctrlc(&mut self)

Do enable the Control + C handling, for spawning console.

pub fn disable_ctrlc(&mut self)

Do disable the Control + C handling, it will not be handled and will interrupt the program.

pub fn disable_console(&mut self)

Disable the console mode, it will not be spawned automatically.

pub fn enable_console(&mut self)

Enable the console mode, it will spawned automatically in some situations.

pub fn spawn_console(&mut self)

Do spawn a console, for user interaction with the current emulation state. Command h for help.

pub fn spawn_console_at(&mut self, exp: u64)

Spawn a console on the instruction number, ie: 1 after emulating first instruction.

pub fn spawn_console_at_addr(&mut self, addr: u64)

Spawn a console the first time the specified address is reached.

impl Emu

pub fn disassemble(&mut self, addr: u64, amount: u32) -> String

Disassemble an amount of instruccions on an specified address. This not used on the emulation engine, just from console, but the api could be used programatilcally.

impl Emu

pub fn featured_regs32(&self)

display 32bits main registers

pub fn featured_regs64(&self)

display 64bits main registers

pub fn show_instruction_comment( &mut self, color: &str, ins: &Instruction, comment: &str, )

pub fn show_instruction(&mut self, color: &str, ins: &Instruction)

pub fn show_instruction_ret( &mut self, color: &str, ins: &Instruction, addr: u64, )

pub fn show_instruction_pushpop( &mut self, color: &str, ins: &Instruction, value: u64, )

pub fn show_instruction_taken(&mut self, color: &str, ins: &Instruction)

pub fn show_instruction_not_taken(&mut self, color: &str, ins: &Instruction)

impl Emu

pub fn veh(&self) -> u64

pub fn set_veh(&mut self, value: u64)

pub fn uef(&self) -> u64

pub fn set_uef(&mut self, value: u64)

pub fn eh_ctx(&self) -> u32

pub fn set_eh_ctx(&mut self, value: u32)

pub fn seh(&self) -> u64

pub fn set_seh(&mut self, value: u64)

pub fn exception(&mut self, ex_type: ExceptionType)

Trigger an exception. If it has to be handled initiate contex tand jump to the programmed error routine. Support SEH, VEH and UEF

impl Emu

pub fn stop(&mut self)

pub fn call32(&mut self, addr: u64, args: &[u32]) -> Result<u32, MwemuError>

Call a 32bits function at addr, passing argument in an array of u64 but will cast to u32. The calling convention is stack, like winapi32.

pub fn call64(&mut self, addr: u64, args: &[u64]) -> Result<u64, MwemuError>

Call 64bits function at addr using Microsoft x64 ABI, passing argument in an array of u64. The calling convention is registers rcx/rdx/r8/r9 and then stack. Like windows64. Dont use for linux64 syscall like convention, for this is linux_call64()

pub fn linux_call64( &mut self, addr: u64, args: &[u64], ) -> Result<u64, MwemuError>

Call a 64bits function at addr, passing arguments in an array of u64. The calling convention is registers RDI, RSI, RDX, RCX, R8, R9 and then stack. Like linux64.

pub fn run_until_ret(&mut self) -> Result<u64, MwemuError>

Start emulation until a ret instruction is found. It will return the address or MwemuError.

pub fn step(&mut self) -> bool

Emulate a single step from the current point. This doesn’t reset the emu.pos, which marks the number of emulated instructions and points to the current emulation moment. Automatically dispatches to single or multi-threaded execution based on cfg.enable_threading.

pub fn update_entropy(&mut self)

pub fn step_single_threaded(&mut self) -> bool

👎Deprecated since 0.1.0: Use step() instead, which automatically handles threading

Emulate a single step from the current point (single-threaded implementation). this don’t reset the emu.pos, that mark the number of emulated instructions and point to the current emulation moment. If you do a loop with emu.step() will have more control of the emulator but it will be slow. Is more convinient using run and run_to or even setting breakpoints.

pub fn step_multi_threaded(&mut self) -> bool

👎Deprecated since 0.1.0: Use step() instead, which automatically handles threading

Emulate a single step from the current point (multi-threaded implementation). this don’t reset the emu.pos, that mark the number of emulated instructions and point to the current emulation moment. If you do a loop with emu.step() will have more control of the emulator but it will be slow. Is more convinient using run and run_to or even setting breakpoints.

pub fn run_to(&mut self, end_pos: u64) -> Result<u64, MwemuError>

Run until a specific position (emu.pos) This don’t reset the emu.pos, will meulate from current position to selected end_pos included.

pub fn run(&mut self, end_addr: Option<u64>) -> Result<u64, MwemuError>

Start or continue emulation. For emulating forever: run(None) For emulating until an address: run(Some(0x11223344)) self.pos is not set to zero, can be used to continue emulation. Automatically dispatches to single or multi-threaded execution based on cfg.enable_threading.

pub fn run_multi_threaded( &mut self, end_addr: Option<u64>, ) -> Result<u64, MwemuError>

👎Deprecated since 0.1.0: Use run() instead, which automatically handles threading

Start or continue emulation (multi-threaded implementation). For emulating forever: run(None) For emulating until an address: run(Some(0x11223344)) self.pos is not set to zero, can be used to continue emulation.

pub fn run_single_threaded( &mut self, end_addr: Option<u64>, ) -> Result<u64, MwemuError>

👎Deprecated since 0.1.0: Use run() instead, which automatically handles threading

Start or continue emulation (single-threaded implementation). For emulating forever: run(None) For emulating until an address: run(Some(0x11223344)) self.pos is not set to zero, can be used to continue emulation.

impl Emu

pub fn pre_op_flags(&self) -> &Flags

pub fn pre_op_flags_mut(&mut self) -> &mut Flags

pub fn post_op_flags(&self) -> &Flags

pub fn post_op_flags_mut(&mut self) -> &mut Flags

pub fn eflags(&self) -> &Eflags

pub fn eflags_mut(&mut self) -> &mut Eflags

pub fn set_pre_op_flags(&mut self, flags: Flags)

pub fn set_post_op_flags(&mut self, flags: Flags)

pub fn flags(&self) -> &Flags

pub fn flags_mut(&mut self) -> &mut Flags

impl Emu

pub fn fls(&self) -> &Vec<u32>

pub fn fls_mut(&mut self) -> &mut Vec<u32>

impl Emu

pub fn sync_fpu_ip(&mut self)

pub fn fpu(&self) -> &FPU

pub fn fpu_mut(&mut self) -> &mut FPU

impl Emu

pub fn fs(&self) -> &BTreeMap<u64, u64>

pub fn fs_mut(&mut self) -> &mut BTreeMap<u64, u64>

impl Emu

pub fn new() -> Emu

pub fn init_stack32(&mut self)

This inits the 32bits stack, it’s called from init_cpu() and init()

pub fn init_stack64(&mut self)

This inits the 64bits stack, it’s called from init_cpu() and init()

pub fn init_stack64_tests(&mut self)

pub fn init_regs_tests(&mut self)

pub fn init_flags_tests(&mut self)

pub fn init_logger(&mut self)

pub fn init_win32(&mut self, clear_registers: bool, clear_flags: bool)

Initialize windows simulator, this does like init_cpu() but also setup the windows memory. This require having the map files in place, otherwise use just init_cpu() but emu32() and emu64() already call init_cpu() This is called from load_code if the code is a PE or shellcode. load_code_bytes() and other loading ways don’t call this, if you need windows simulation call this.

pub fn init_cpu(&mut self)

The minimum initializations necessary to emualte asm with no OS simulation.

pub fn init_linux64(&mut self, dyn_link: bool)

Initialize linux simulation, it’s called from load_code() if the sample is an ELF.

pub fn init_win32_mem32(&mut self)

This is called from init(), this setup the 32bits windows memory simulation.

pub fn init_tests(&mut self)

pub fn init_win32_mem64(&mut self)

This is called from init(), this setup the 64bits windows memory simulation.

impl Emu

pub fn set_rip(&mut self, addr: u64, is_branch: bool) -> bool

Redirect execution flow on 64bits. If the target address is a winapi, triggers it’s implementation.

pub fn set_eip(&mut self, addr: u64, is_branch: bool) -> bool

Redirect execution flow on 32bits. If the target address is a winapi, triggers it’s implementation.

impl Emu

pub fn load_pe32( &mut self, filename: &str, set_entry: bool, force_base: u32, ) -> (u32, u32)

Complex funtion called from many places and with multiple purposes. This is called from load_code() if sample is PE32, but also from load_library etc. Powered by pe32.rs implementation.

pub fn load_pe64( &mut self, filename: &str, set_entry: bool, force_base: u64, ) -> (u64, u32)

Complex funtion called from many places and with multiple purposes. This is called from load_code() if sample is PE64, but also from load_library etc. Powered by pe64.rs implementation.

pub fn load_elf64(&mut self, filename: &str)

Loads an ELF64 parsing sections etc, powered by elf64.rs This is called from load_code() if the sample is ELF64

pub fn load_code(&mut self, filename: &str)

Load a sample. It can be PE32, PE64, ELF32, ELF64 or shellcode. If its a shellcode cannot be known if is for windows or linux, it triggers also init() to setup windows simulator. For now mwemu also don’t know if shellcode is for 32bits or 64bits, in commandline -6 has to be selected for indicating 64bits, and from python or rust the emu32() or emu64() construtor dtermines the engine.

pub fn load_code_bytes(&mut self, bytes: &[u8])

Load a shellcode from a variable. This assumes that there is no headers like PE/ELF and it’s direclty code. Any OS simulation is triggered, but init() could be called by the user

impl Emu

pub fn set_maps_folder(&mut self, folder: &str)

For simulating a windows process space, select the folder with maps32 or maps64 depending upon the arch, do this before loading the binary.

pub fn get_base_addr(&self) -> Option<u64>

Get the base address of the code, if code map doesn’t exist yet will return None.

pub fn filename_to_mapname(&self, filename: &str) -> String

From a file-path this returns the filename with no path and no extension.

pub fn free(&mut self, name: &str)

Remove from the memory the map name provided.

pub fn alloc(&mut self, name: &str, size: u64, permission: Permission) -> u64

This find an empty space on the memory of selected size and also creates a map there.

impl Emu

pub fn memory_operand_to_address(&mut self, operand: &str) -> u64

This is not used on the emulation. It’s part of a feature like reading or wirtting like it was asm “dword ptr [rax + 0x123]”

pub fn memory_read(&mut self, operand: &str) -> Option<u64>

This is not used on the emulation. It’s a feature to read memory based on an string like “dword ptr [rax + 0x1234]” Unperfect but cool feautre, don’t alow all the combinations possible. Not sure if this features will be removed. The emulator uses much more eficient ways to decode the operands than this.

pub fn memory_write(&mut self, operand: &str, value: u64) -> bool

This is not used on the emulation. It’s a feature to write memory based on an string like “dword ptr [rax + 0x1234]” Unperfect but cool feautre, don’t alow all the combinations possible. Not sure if this features will be removed. The emulator uses much more eficient ways to decode the operands than this.

pub fn get_size(&self, operand: &str) -> u8

This is not used on the emulation. It’s just for a memory reading feature. The emulation uses much more efficient ways to decode

impl Emu

pub fn get_jump_value( &mut self, ins: &Instruction, noperand: u32, ) -> Option<u64>

Decode the jump parameter

pub fn get_operand_value( &mut self, ins: &Instruction, noperand: u32, do_derref: bool, ) -> Option<u64>

Decode a selected operand and return its value (inmediate, register or memory) noperand: is (from 0 to n) and return do_derref: instructions like lea use memory, get the ref but dont derreference.

pub fn set_operand_value( &mut self, ins: &Instruction, noperand: u32, value: u64, ) -> bool

Set a value to an operand, normally noperand=0 If it’s a register modify the register, it can be memory also.

pub fn get_operand_xmm_value_128( &mut self, ins: &Instruction, noperand: u32, do_derref: bool, ) -> Option<u128>

Get a 128bits operand ie for xmm instructions.

pub fn set_operand_xmm_value_128( &mut self, ins: &Instruction, noperand: u32, value: u128, )

Set an operand of 128 bits, like xmm.

pub fn get_operand_ymm_value_256( &mut self, ins: &Instruction, noperand: u32, do_derref: bool, ) -> Option<U256>

pub fn set_operand_ymm_value_256( &mut self, ins: &Instruction, noperand: u32, value: U256, )

Set a 256bits value to an operand, usually ymm instructions.

pub fn get_operand_sz(&self, ins: &Instruction, noperand: u32) -> u32

Fetch the size in amount of bits of a specific operand (reg/mem/imm), if it’s a memory operation it depend on the dword ptr, qword ptr etc.

impl Emu

pub fn regs(&self) -> &Regs64

pub fn regs_mut(&mut self) -> &mut Regs64

pub fn set_pre_op_regs(&mut self, regs: Regs64)

pub fn set_post_op_regs(&mut self, regs: Regs64)

pub fn pre_op_regs(&self) -> &Regs64

pub fn pre_op_regs_mut(&mut self) -> &mut Regs64

pub fn post_op_regs(&self) -> &Regs64

pub fn post_op_regs_mut(&mut self) -> &mut Regs64

impl Emu

pub fn stack_push32(&mut self, value: u32) -> bool

Push a dword to the stack and dec the esp This will return false if stack pointer is pointing to non allocated place.

pub fn stack_push64(&mut self, value: u64) -> bool

Push a qword to the stack and dec the rsp. This will return false if stack pointer is pointing to non allocated place.

pub fn stack_pop32(&mut self, pop_instruction: bool) -> Option<u32>

Pop a dword from stack and return it, None if esp points to unmapped zone.

pub fn stack_pop64(&mut self, pop_instruction: bool) -> Option<u64>

Pop a qword from stack, return None if cannot read the rsp address.

impl Emu

pub fn current_thread(&self) -> &ThreadContext

pub fn current_thread_mut(&mut self) -> &mut ThreadContext

impl Emu

pub fn enable_threading(&mut self, enabled: bool)

Enable multi-threading support for the emulator. When enabled, the emulator will use thread scheduling for multiple threads. When disabled (default), it runs in single-threaded mode for backward compatibility.

pub fn is_threading_enabled(&self) -> bool

Check if multi-threading is enabled.

impl Emu

pub fn tls32(&self) -> &Vec<u32>

pub fn tls32_mut(&mut self) -> &mut Vec<u32>

pub fn tls64(&self) -> &Vec<u64>

pub fn tls64_mut(&mut self) -> &mut Vec<u64>

impl Emu

pub fn open_trace_file(&mut self)

pub fn capture_pre_op(&mut self)

pub fn capture_post_op(&mut self)

pub fn write_to_trace_file(&mut self)

dump the registers and memory write operations to file

impl Emu

pub fn handle_winapi(&mut self, addr: u64)

Call a winapi by addess.

pub fn update_ldr_entry_base(&mut self, libname: &str, base: u64)

For an existing linked DLL, this funcion allows to modify the base address on LDR entry.

pub fn link_library(&mut self, libname: &str) -> u64

Dynamic link a windows DLL from emu.cfg.maps_folder.

pub fn api_addr_to_name(&mut self, addr: u64) -> String

Resolve the winapi name having an address.

pub fn api_name_to_addr(&mut self, kw: &str) -> u64

Resolve the address of an api name keyword.