
Qiling is an advanced binary emulation framework, with the following features:
- Cross platform: Windows, MacOS, Linux, BSD
- Cross architecture: X86, X86_64, Arm, Arm64, Mips
- Multiple file formats: PE, MachO, ELF
- Emulate & sandbox machine code in a isolated environment
- Provide high level API to setup & configure the sandbox
- Fine-grain instrumentation: allow hooks at various levels (instruction/basic-block/memory-access/exception/syscall/IO/etc)
- Allow dynamic hotpatch on-the-fly running code, including the loaded library
- True framework in Python, making it easy to build customized security analysis tools on top
Qiling is backed by Unicorn engine.
Visit our website https://www.qiling.io for more information.
Qiling vs other Emulators
There are many open source emulators, but two projects closest to Qiling are Unicorn & Qemu usermode. This section explains the main differences of Qiling against them.
Qiling vs Unicorn engine
Built on top of Unicorn, but Qiling & Unicorn are two different animals.
- Unicorn is just a CPU emulator, so it focuses on emulating CPU instructions, that can understand emulator memory. Beyond that, Unicorn is not aware of higher level concepts, such as dynamic libraries, system calls, I/O handling or executable formats like PE, MachO or ELF. As a result, Unicorn can only emulate raw machine instructions, without Operating System (OS) context.
- Qiling is designed as a higher level framework, that leverages Unicorn to emulate CPU instructions, but can understand OS: it has executable format loaders (for PE, MachO & ELF at the moment), dynamic linkers (so we can load & relocate shared libraries), syscall & IO handlers. For this reason, Qiling can run executable binary without requiring its native OS.
Qiling vs Qemu usermode
Qemu usermode does similar thing to our emulator, that is to emulate whole executable binaries in cross-architecture way. However, Qiling offers some important differences against Qemu usermode.
- Qiling is a true analysis framework, that allows you to build your own dynamic analysis tools on top (in friendly Python language). Meanwhile, Qemu is just a tool, not a framework.
- Qiling can perform dynamic instrumentation, and can even hotpatch code at runtime. Qemu does not do either.
- Not only working cross-architecture, Qiling is also cross-platform, so for example you can run Linux ELF file on top of Windows. In contrast, Qemu usermode only run binary of the same OS, such as Linux ELF on Linux, due to the way it forwards syscall from emulated code to native OS.
- Qiling supports more platforms, including Windows, MacOS, Linux & BSD. Qemu usermode can only handles Linux & BSD.
Install
Run below command line to install Qiling (Python3 is required).
python3 setup.py install
Examples
- Below example shows how to use Qiling framework to emulate a Windows EXE on a Linux machine.
from qiling import *
# sandbox to emulate the EXE
def my_sandbox(path, rootfs):
# setup Qiling engine
ql = Qiling(path, rootfs)
# now emulate the EXE
ql.run()
if __name__ == "__main__":
# execute Windows EXE under our rootfs
my_sandbox(["examples/rootfs/x86_windows/bin/x86-windows-hello.exe"], "examples/rootfs/x86_windows")
- Below example shows how to use Qiling framework to dynamically patch a Windows crackme, make it always display "Congratulation" dialog.
from qiling import *
def force_call_dialog_func(ql):
# get DialogFunc address
lpDialogFunc = ql.unpack32(ql.mem_read(ql.sp - 0x8, 4))
# setup stack memory for DialogFunc
ql.stack_push(0)
ql.stack_push(1001)
ql.stack_push(273)
ql.stack_push(0)
ql.stack_push(0x0401018)
# force EIP to DialogFunc
ql.pc = lpDialogFunc
def my_sandbox(path, rootfs):
ql = Qiling(path, rootfs)
# NOP out some code
ql.patch(0x004010B5, b'\x90\x90')
ql.patch(0x004010CD, b'\x90\x90')
ql.patch(0x0040110B, b'\x90\x90')
ql.patch(0x00401112, b'\x90\x90')
# hook at an address with a callback
ql.hook_address(0x00401016, force_call_dialog_func)
ql.run()
if __name__ == "__main__":
my_sandbox(["rootfs/x86_windows/bin/Easy_CrackMe.exe"], "rootfs/x86_windows")
The below Youtube video shows how the above example works.
Wannacry demo
- The below Youtube video shows how Qiling analyzes Wannacry malware.
Qltool
Qiling also provides a friendly tool named qltool
to quickly emulate shellcode & executable binaries.
To emulate a binary, run:
$ ./qltool run -f examples/rootfs/arm_linux/bin/arm32-hello --rootfs examples/rootfs/arm_linux/
To run shellcode, run:
$ ./qltool shellcode --os linux --arch x86 --asm -f examples/shellcodes/lin32_execve.asm
Contact
Get the latest info from out webiste https://www.qiling.io
Contact us at email [email protected], or via Twitter @qiling_io
任何疑问请联系麒麟框架官方微博
Core developers
- LAU kaijern (xwings) [email protected]
- NGUYEN Anh Quynh [email protected]
- DING tianZe (D1iv3) [email protected]
- SUN bowen (w1tcher) [email protected]
- CHEN huitao (null) [email protected]
- YU tong (sp1ke) [email protected]
Author

- Hakin9 is a monthly magazine dedicated to hacking and cybersecurity. In every edition, we try to focus on different approaches to show various techniques - defensive and offensive. This knowledge will help you understand how most popular attacks are performed and how to protect your data from them. Our tutorials, case studies and online courses will prepare you for the upcoming, potential threats in the cyber security world. We collaborate with many individuals and universities and public institutions, but also with companies such as Xento Systems, CATO Networks, EY, CIPHER Intelligence LAB, redBorder, TSG, and others.
Latest Articles
Blog2022.12.13What are the Common Security Weaknesses of Cloud Based Networks?
Blog2022.10.12Vulnerability management with Wazuh open source XDR
Blog2022.08.29Deception Technologies: Improving Incident Detection and Response by Alex Vakulov
Blog2022.08.25Exploring the Heightened Importance of Cybersecurity in Mobile App Development by Jeff Kalwerisky