qiling - A True Instrumentable Binary Emulation Framework

项目说明

![Documentation Status]()
![Downloads]()
Qiling's use case, blog and related work

Qiling is an ad binary emulation framework, with the following features:

Emulate multi-platforms: Windows, macOS, Linux, Android, BSD, UEFI, DOS, MBR.

Emulate multi-architectures: 8086, X86, X86_64, ARM, ARM64, MIPS, RISC-.

Support multiple file formats: PE, Mach-O, ELF, COM, MBR.

Support Windows Driver (.sys), Linux Kernel Module (.ko) & macOS Kernel (.kext) via Demigod.

Emulates & sandbox code in an isolated en.

Provides a fully configurable sandbox.

Provides in-depth memory, register, OS level and filesystem level API.

Fine-grain instrumentation: allows hooks at levels

(instruction/basic-block/memory-access/exception/syscall/IO/etc.)

Provides machine level API such as saving and restoring the current execution state.

Supports cross architecture and platform debugging capabilities.

Built-in debugger with reverse debugging capability.

Allows dynamic hot patch 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 also made its way to international conferences.

2022:

Black Hat, EU

Black Hat, MEA

2021:

Black Hat, USA

Hack In The Box, Amsterdam

Black Hat, Asia

2020:

Black Hat, Europe

Black Hat, USA

Black Hat, USA (Demigod)

Black Hat, Asia

Hack In The Box, Lockdown 001

Hack In The Box, Lockdown 002

Hack In The Box, Cyberweek

Nullcon

2019:

DEFCON, USA

Hitcon

Zeronights

Qiling is backed by Unicorn Engine.

Visit our website for more information.

---
#### License

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either 2 of the License, or
(at your option) any later .

---

#### Qiling Emulators

There are many open-source emulators, but two projects closest to Qiling
are Unicorn & QEMU user mode.
This section explains the main differences of Qiling against them.

##### Qiling 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 le, such as dynamic
libraries, system calls, I/O handling or executable formats like PE, Mach-O
or ELF. As a result, Unicorn can only emulate raw machine instructions,
without Operating System (OS) context.

Qiling is designed as a higher le, that le Unicorn to

emulate CPU instructions, but can understand OS: it has executable format
loaders (for PE, Mach-O & ELF currently), 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 user mode

QEMU user mode does a similar thing to our emulator, that is, to emulate whole
executable binaries in a cross-architecture way.
However, Qiling offers some important differences against QEMU user mode:

Qiling is a true analysis framework,

that allows you to build your own dynamic analysis tools on top (in Python).
Meanwhile, QEMU is just a tool, not a framework.

Qiling can perform dynamic instrumentation, and can even hot patch code at

runtime. QEMU does neither.

Not only working cross-architecture, Qiling is also cross-platform.

For example, you can run Linux ELF file on top of Windows.
In contrast, QEMU user mode only runs 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

user mode can only handle Linux & BSD.

---

#### Installation

Please see setup guide file for how to install Qiling Framework.

---

#### Examples

The example below shows how to use Qiling framework in the most
straightforward way to emulate a Windows executable.

The following example shows how a Windows crackme may be patched dynamically

to make it always display the “Congratulation” dialog.

The below YouTube video shows how the abo works.

#### Emulating ARM router firmware on Ubuntu x64 host

Qiling Framework hot-patches and emulates an ARM router's /usr/bin/httpd on
an x86_64 Ubuntu host.

![Qiling Tutorial: Emulating and Fuzz ARM router firmware]()

#### Qiling's IDA Pro Plugin: Instrument and Decrypt Mirai's Secret

This video demonstrates how Qiling's IDA Pro plugin can make IDA Pro run with
Qiling instrumentation engine.

![Qiling's IDA Pro Plugin: Instrument and Decrypt Mirai's Secret]()

#### GDB server with IDA Pro demo

Solving a simple CTF challenge with Qiling Framework and IDA Pro

![Solving a simple CTF challenge with Qiling Framework and IDA Pro]()

#### Emulating MBR

Qiling Framework emulates MBR

![Qiling DEMO: Emulating MBR]()

---

#### Qltool

Qiling also provides a friendly tool named qltool to quickly emulate shellcode & executable binaries.

Installing Qiling with pip also installs the qltool command, including
qltool qltui for the terminal UI. In a source checkout, use ./qltool as
shown below. Example binaries and rootfs files must be downloaded separately.

With qltool, easy execution can be performed:

With shellcode:

With binary file:

With binary and GDB debugger enabled:

With code co collection (UEFI only for now):

With JSON output (Windows, mainly):

---

#### Contact

Get the latest info from our website

Contact us at email ,
.

---

#### Core de, Key Contributors and etc.

Please refer to CREDITS.md.

项目信息

开发语言：Python

Star 数：6120

技术要点

该项目属于病毒分析方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A True Instrumentable Binary Emulation Framework展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。