1EMU(3) Library Functions Manual EMU(3)
2
6 libemu - emulate x86 shellcodes
7
9 #include <emu/emu.h>
10 #include <emu/emu_memory.h>
11 #include <emu/emu_cpu.h>
12 struct emu * emu_new ()
14 void emu_free (struct emu *e)
15 struct emu_memory * emu_memory_get (struct emu *e)
16 struct emu_logging * emu_logging_get (struct emu *e)
17 struct emu_cpu * emu_cpu_get (struct emu *e)
18 void emu_errno_set (struct emu *e, int err)
19 int emu_errno (struct emu *c)
20 void emu_strerror_set (struct emu *e,
21 const char *format,...)
22 const char * emu_strerror (struct emu *e)
23 void emu_memory_clear (struct emu_memory *em)
25 int32_t emu_memory_read_byte (struct emu_memory *m,
26 uint32_t addr, uint8_t *byte)
27 int32_t emu_memory_read_word (struct emu_memory *m,
28 uint32_t addr, uint16_t *word)
29 int32_t emu_memory_read_dword (struct emu_memory *m,
30 uint32_t addr, uint32_t *dword)
31 int32_t emu_memory_read_block (struct emu_memory *m,
32 uint32_t addr, void *dest, size_t len)
33 int32_t emu_memory_read_string (struct emu_memory *m,
34 uint32_t addr, struct emu_string *s, uint32_t maxsize)
35 int32_t emu_memory_write_byte (struct emu_memory *m,
36 uint32_t addr, uint8_t byte)
37 int32_t emu_memory_write_word (struct emu_memory *m,
38 uint32_t addr, uint16_t word)
39 int32_t emu_memory_write_dword (struct emu_memory *m,
40 uint32_t addr, uint32_t dword)
41 int32_t emu_memory_write_block (struct emu_memory *m,
42 uint32_t addr, void *src, size_t len)
43 void emu_memory_segment_select (struct emu_memory *m,
44 enum emu_segment s)
45 enum emu_segment emu_memory_segment_get (struct emu_memory *m)
46 int32_t emu_memory_alloc (struct emu_memory *m,
47 uint32_t *addr, size_t len)
48 uint32_t emu_memory_get_usage (struct emu_memory *m)
49 void emu_memory_mode_ro (struct emu_memory *m)
50 void emu_memory_mode_rw (struct emu_memory *m)
51 uint32_t emu_cpu_reg32_get (struct emu_cpu *cpu_p, enum emu_reg32 reg)
53 uint16_t emu_cpu_reg16_get (struct emu_cpu *cpu_p, enum emu_reg16 reg)
54 uint8_t emu_cpu_reg8_get (struct emu_cpu *cpu_p, enum emu_reg8 reg)
55 void emu_cpu_reg16_set (struct emu_cpu *cpu_p, enum emu_reg16 reg, uint16_t val)
56 void emu_cpu_reg32_set (struct emu_cpu *cpu_p, enum emu_reg32 reg, uint32_t val)
57 void emu_cpu_reg8_set (struct emu_cpu *cpu_p, enum emu_reg8 reg, uint8_t val)
58 uint32_t emu_cpu_eflags_get (struct emu_cpu *c)
59 void emu_cpu_eflags_set (struct emu_cpu *c, uint32_t val)
60 void emu_cpu_eip_set (struct emu_cpu *c, uint32_t eip)
61 uint32_t emu_cpu_eip_get (struct emu_cpu *c)
62 int32_t emu_cpu_parse (struct emu_cpu *c)
63 int32_t emu_cpu_step (struct emu_cpu *c)
64 int32_t emu_cpu_run (struct emu_cpu *c)
65 void emu_cpu_debug_print (struct emu_cpu *c)
66 int32_t emu_shellcode_test(struct emu *e, uint8_t *data, uint16_t size)
68 struct emu_env_w32 *emu_env_w32_new(struct emu *e)
70 void emu_env_w32_free(struct emu_env_w32 *env)
71 struct emu_env_w32_dll_export *emu_env_w32_eip_check(struct emu_env_w32 *env)
72 int32_t emu_env_w32_export_hook(struct emu_env_w32 *env,
73 const char *dllname,
74 const char *exportname,
75 int32_t (*fnhook) (struct emu_env_w32 *env, struct emu_env_w32_dll_export *ex)
76 );
77
81 libemu provides basic x86 emulation including memory access and regis‐
82 ters.
83
85 emu_new() is used to create a new emulation entity, use emu_free() to
86 free all associated memory. emu_memory_get() , emu_logging_get() and
87 emu_cpu_get() can be used to obtain pointers to different parts of the
88 emulation. For errorhandling, use emu_errno() or emu_strerror()
89 returning either a POSIX errno or a string describing the error. When
90 writing extensions emu_errno_set() and emu_strerror_set() will come
91 handy too.
92 The emu_memory is split up in pages, therefore there are functions to
94 access the memory without taking care of page borders. emu_mem‐
95 ory_read_byte() , emu_memory_read_word() , emu_memory_read_dword() ,
96 emu_memory_read_string() and emu_memory_read_block() can be used to
97 read values from the emu memory. emu_memory_read_string() will allo‐
98 cate the required memory for the string within the emu_string provided
99 by itself, as you won't be able to know the strings length, in all
100 other cases, the pointer to the location has to provide enough space to
101 write the data.
102 Once the emulation is created, code is written to the memory, we need
105 to set the registers to the initial values, the cpuflags to the start
106 values and EIP to the point where to start code execution. emu_cpu
107 provides functions to access all registers, the flags and EIP for read
108 and write. To access the 32bit registers use emu_cpu_reg32_get() and
109 emu_cpu_reg32_set() where reg is one of eax, ecx, edx, ebx, esp, ebp,
110 esi, edi. To access the 16bit registers use emu_cpu_reg16_get() and
111 emu_cpu_reg16_set() with ax, cx, dx, bx, sp, bp, si, di as valid values
112 for reg. In case of 8bit register access use emu_cpu_reg8_get() and
113 emu_cpu_reg8_set() with al, cl, dl, bl, ah, ch, dh, bh as values for
114 reg. Accessing the cpu's flags is possible using emu_cpu_eflags_get()
115 and emu_cpu_eflags_set(). Accessing EIP can be done using
116 emu_cpu_eip_set() and emu_cpu_eip_get(). Once everything is setup,
117 parse the first instruction using emu_cpu_parse() , on success it will
118 return 0, on failure use emu_strerror() to get a description of the
119 error. If parsing was successfull, step the first instruction using
120 emu_cpu_step().
121 If you want to detect shellcodes in buffers, use emu_shellcode_test() ,
123 the emu will copy the buffer to it's pages and try to detect a shell‐
124 code. If a possible shellcode gets detected, the guessed starting off‐
125 set is returned, else -1.
126 To be able to run shellcodes using windows api, one has to provide
128 parts of the windows process environment to the emulation, as well as
129 some kind of emulation for the used api calls. emu_env_w32_new() will
130 created a minimalistic process environment in e and using
131 emu_env_w32_eip_check() after step allows you intercepting calls to
132 exported api. If the return value of emu_env_w32_eip_check() is not
133 NULL, the dll exports information is returned, including the calls name
134 and hook. If you want to hook calls to api exports, use
135 emu_env_w32_export_hook().
136
139 Markus Koetter <nepenthesdev@gmail.com>
140 04 September 2007 EMU(3)