libemu – x86 Shellcode Emulation

libemu is a small library written in C offering basic x86 emulation and shellcode detection using GetPC heuristics. It is designed to be used within network intrusion/prevention detections and honeypots.

libemu supports:

With libemu one can:

About libemu

Why Did You Write libemu?

Even though many people published papers about detecting shellcodes using emulation, nobody published code. We decided to publish code instead of papers, making use of already existing knowledge, offering new techology to the open source community.

Why Not Use Bochs or qemu Instead?

Shellcode detection and execution has very specific requirements, so instead of stripping the not-required parts from an existing x86 emulator and trying to patch the required logic to profile shellcodes into, we decided to start from scratch.

Who Wrote libemu?

libemu was designed and written by Paul Baecher and Markus Koetter in 2007.

Downloading libemu


The tarballs are hosted within the nepenthes project's file release section.


git clone git://

Installing libemu

If you want to install libemu, there are two ways, either using bleeding edge from git, or stable releases from tarballs. The git version may not work, on the other hand problem bugs may already be fixed in git. We recommend using git. For information about retrieving a git snapshot or downloading a tarball refer to Downloading libemu.

Obtaining libemu via Git

Bulding from git requires the whole autoconf & automake family beeing installed on your computer. Once installed, run autoconf in the libemu git directory.

autoreconf -v -i
./configure --prefix=/opt/libemu
make install

Building from a Tarball

Installing using stable releases.

tar xfz libemu-VERSION.tar.gz
cd libemu-VERSION
./configure --prefix=/opt/libemu
make install

API Reference and Documentation

libemu comes with a manpage which you can also read online. For more details, please see the autogenerated API reference.

Example Programs


cpurun is a small utility allowing to write code to the emulations memory and executing the code written, basics.
View Code
Download Code


emunids is a small intrusion detection system using libnids for tcp stream reassembly and libemu to detect shellcodes in streams. Due too libnids bad performance it does not scale on links (much) faster than 2MBit/s, but it is still a good example howto use libemu.

View Code
Download Code


sctest is part of the libemu testsuite and very usefull when testing new features. Even though the code is historically tainted it may be a usefull source for those who want to setup shellcode emulation allowing win32 api calls and offering hooks on these calls. sctest is not the best example, the code is nerved by the logic for graphing the callflow, but for now it has to work.
View Code

Example Use Cases

SQL Slammer

In 2003 SQL Slammer made it to every major media. The worm, spreading autonomously using a single udp packet exploiting a flaw in Microsoft SQL Server, created enough traffic to take down parts of the internet. As of today, the worm still exists, and tries to infect yet unpatched servers. As SQL Slammer is pure assembly without any PE file overhead, we were able to create a callgraph using libemu.

sqlslammer callgraph

.dot file
large graph

Metasploit linux/x86/shell_bind_tcp

This is a linux shellcode, provided by the Metasploit Framework. The payload was constructed using

./msfpayload linux/x86/shell_bind_tcp r | \
./msfencode -a x86 -e x86/shikata_ga_nai -t raw
msf linux bindshell callgraph

.dot file
large graph

linkbot connectback filestransfer

A very intresting two stage shellcode which uses a stack cookie to verfiy the host downloading the file was actually attacked.
The second stage sends the attacker a cookie which was put on stack by the first stage, and receives a file afterwards. When the filetransfer is done, the received file gets executed.

linkbot connectback callgraph

.dot file
large graph

Hacking libemu

Win32 API Hooks

Hooking calls to (supported) windows dll's is very easy.
Look at sctest within the examples section to see how the user_hook_ExitThread is implemented and gets installed.

Adding Support For More DLLs

Currently libemu uses a static approach which DLLs can be loaded, as they are hardcoded within the Win32 environment.
To support a new DLL, you have to have a copy of the DKK, load the DLL into process memory in Windows, and dump the required sections. Then, these required sections have be written to memory in libemu once the DLL gets loaded. If you want to support a different DLL, contact us, we will add support for the DLL and extend this guide to allow others supporting their DLLs too.