--- name: "libemu" section: "3" platform: "linux" package: "libemu2" version: "0.2.0+git20120122-1.2+b1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/libemu" --- # libemu(3) emulate x86 shellcodes ## NAME libemu - emulate x86 shellcodes ## SYNOPSIS ``` #include #include #include ``` ``` ``` **struct emu \* emu\_new ()** **void emu\_free (struct emu \*e)** **struct emu\_memory \* emu\_memory\_get (struct emu \*e)** **struct emu\_logging \* emu\_logging\_get (struct emu \*e)** **struct emu\_cpu \* emu\_cpu\_get (struct emu \*e)** **void emu\_errno\_set (struct emu \*e, int err)** **int emu\_errno (struct emu \*c)** **void emu\_strerror\_set (struct emu \*e,** **const char \*format,...)** **const char \* emu\_strerror (struct emu \*e)** **void emu\_memory\_clear (struct emu\_memory \*em)** **int32\_t emu\_memory\_read\_byte (struct emu\_memory \*m,** **uint32\_t addr, uint8\_t \*byte)** **int32\_t emu\_memory\_read\_word (struct emu\_memory \*m,** **uint32\_t addr, uint16\_t \*word)** **int32\_t emu\_memory\_read\_dword (struct emu\_memory \*m,** **uint32\_t addr, uint32\_t \*dword)** **int32\_t emu\_memory\_read\_block (struct emu\_memory \*m,** **uint32\_t addr, void \*dest, size\_t len)** **int32\_t emu\_memory\_read\_string (struct emu\_memory \*m,** **uint32\_t addr, struct emu\_string \*s, uint32\_t maxsize)** **int32\_t emu\_memory\_write\_byte (struct emu\_memory \*m,** **uint32\_t addr, uint8\_t byte)** **int32\_t emu\_memory\_write\_word (struct emu\_memory \*m,** **uint32\_t addr, uint16\_t word)** **int32\_t emu\_memory\_write\_dword (struct emu\_memory \*m,** **uint32\_t addr, uint32\_t dword)** **int32\_t emu\_memory\_write\_block (struct emu\_memory \*m,** **uint32\_t addr, void \*src, size\_t len)** **void emu\_memory\_segment\_select (struct emu\_memory \*m,** **enum emu\_segment s)** **enum emu\_segment emu\_memory\_segment\_get (struct emu\_memory \*m)** **int32\_t emu\_memory\_alloc (struct emu\_memory \*m,** **uint32\_t \*addr, size\_t len)** **uint32\_t emu\_memory\_get\_usage (struct emu\_memory \*m)** **void emu\_memory\_mode\_ro (struct emu\_memory \*m)** **void emu\_memory\_mode\_rw (struct emu\_memory \*m)** **uint32\_t emu\_cpu\_reg32\_get (struct emu\_cpu \*cpu\_p, enum emu\_reg32 reg)** **uint16\_t emu\_cpu\_reg16\_get (struct emu\_cpu \*cpu\_p, enum emu\_reg16 reg)** **uint8\_t emu\_cpu\_reg8\_get (struct emu\_cpu \*cpu\_p, enum emu\_reg8 reg)** **void emu\_cpu\_reg16\_set (struct emu\_cpu \*cpu\_p, enum emu\_reg16 reg, uint16\_t val)** **void emu\_cpu\_reg32\_set (struct emu\_cpu \*cpu\_p, enum emu\_reg32 reg, uint32\_t val)** **void emu\_cpu\_reg8\_set (struct emu\_cpu \*cpu\_p, enum emu\_reg8 reg, uint8\_t val)** **uint32\_t emu\_cpu\_eflags\_get (struct emu\_cpu \*c)** **void emu\_cpu\_eflags\_set (struct emu\_cpu \*c, uint32\_t val)** **void emu\_cpu\_eip\_set (struct emu\_cpu \*c, uint32\_t eip)** **uint32\_t emu\_cpu\_eip\_get (struct emu\_cpu \*c)** **int32\_t emu\_cpu\_parse (struct emu\_cpu \*c)** **int32\_t emu\_cpu\_step (struct emu\_cpu \*c)** **int32\_t emu\_cpu\_run (struct emu\_cpu \*c)** **void emu\_cpu\_debug\_print (struct emu\_cpu \*c)** **int32\_t emu\_shellcode\_test(struct emu \*e, uint8\_t \*data, uint16\_t size)** **struct emu\_env\_w32 \*emu\_env\_w32\_new(struct emu \*e)** **void emu\_env\_w32\_free(struct emu\_env\_w32 \*env)** **struct emu\_env\_w32\_dll\_export \*emu\_env\_w32\_eip\_check(struct emu\_env\_w32 \*env)** **int32\_t emu\_env\_w32\_export\_hook(struct emu\_env\_w32 \*env,** **const char \*dllname,** **const char \*exportname,** **int32\_t (\*fnhook) (struct emu\_env\_w32 \*env, struct emu\_env\_w32\_dll\_export \*ex)** **);** ## DESCRIPTION libemu provides basic x86 emulation including memory access and registers. ## ROUTINES **emu\_new()** is used to create a new emulation entity, use **emu\_free()** to free all associated memory. **emu\_memory\_get()** , **emu\_logging\_get()** and **emu\_cpu\_get()** can be used to obtain pointers to different parts of the emulation. For errorhandling, use **emu\_errno()** or **emu\_strerror()** returning either a POSIX errno or a string describing the error. When writing extensions **emu\_errno\_set()** and **emu\_strerror\_set()** will come handy too. The **emu\_memory** is split up in pages, therefore there are functions to access the memory without taking care of page borders. **emu\_memory\_read\_byte()** , **emu\_memory\_read\_word()** , **emu\_memory\_read\_dword()** , **emu\_memory\_read\_string()** and **emu\_memory\_read\_block()** can be used to read values from the emu memory. **emu\_memory\_read\_string()** will allocate the required memory for the string within the **emu\_string** provided by itself, as you won't be able to know the strings length, in all other cases, the pointer to the location has to provide enough space to write the data. Once the emulation is created, code is written to the memory, we need to set the registers to the initial values, the cpuflags to the start values and EIP to the point where to start code execution. **emu\_cpu** provides functions to access all registers, the flags and EIP for read and write. To access the 32bit registers use **emu\_cpu\_reg32\_get()** and **emu\_cpu\_reg32\_set()** where *reg* is one of eax, ecx, edx, ebx, esp, ebp, esi, edi. To access the 16bit registers use **emu\_cpu\_reg16\_get()** and **emu\_cpu\_reg16\_set()** with ax, cx, dx, bx, sp, bp, si, di as valid values for *reg.* In case of 8bit register access use **emu\_cpu\_reg8\_get()** and **emu\_cpu\_reg8\_set()** with al, cl, dl, bl, ah, ch, dh, bh as values for *reg*. Accessing the cpu's flags is possible using **emu\_cpu\_eflags\_get()** and **emu\_cpu\_eflags\_set()**. Accessing EIP can be done using **emu\_cpu\_eip\_set()** and **emu\_cpu\_eip\_get()**. Once everything is setup, parse the first instruction using **emu\_cpu\_parse()** , on success it will return 0, on failure use **emu\_strerror()** to get a description of the error. If parsing was successfull, step the first instruction using **emu\_cpu\_step()**. If you want to detect shellcodes in buffers, use **emu\_shellcode\_test()** , the emu will copy the buffer to it's pages and try to detect a shellcode. If a possible shellcode gets detected, the guessed starting offset is returned, else -1. To be able to run shellcodes using windows api, one has to provide parts of the windows process environment to the emulation, as well as some kind of emulation for the used api calls. **emu\_env\_w32\_new()** will created a minimalistic process environment in *e* and using **emu\_env\_w32\_eip\_check()** after step allows you intercepting calls to exported api. If the return value of **emu\_env\_w32\_eip\_check()** is not NULL, the dll exports information is returned, including the calls name and hook. If you want to hook calls to api exports, use **emu\_env\_w32\_export\_hook()**. ## AUTHOR Markus Koetter \