You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Provides virtual machine level API such as saving and restoring the current execution state.
25
-
- Supports cross architecture and platform debugging capabilities.
26
-
- Built-in debugger with reverse debugging capability.
27
-
- Allows dynamic hot patch on-the-fly running code, including the loaded library.
28
-
- True framework in Python, making it easy to build customized security analysis tools on top.
11
+
# Qiling Framework
12
+
13
+
Qiling is an advanced binary emulation framework that allows you to emulate and sandbox code in an isolated environment across multiple platforms and architectures. Built on top of Unicorn Engine, Qiling provides a higher-level framework that understands operating system contexts, executable formats, and dynamic linking.
14
+
15
+
## Table of Contents
16
+
17
+
-[Features](#features)
18
+
-[Appearance](#Appearance)
19
+
-[Use Cases](#use-cases)
20
+
-[Quick Start](#quick-start)
21
+
-[Installation](#installation)
22
+
-[Basic Usage](#basic-usage)
23
+
-[Qiling vs. Other Emulators](#qiling-vs-other-emulators)
24
+
-[Qiling vs. Unicorn Engine](#qiling-vs-unicorn-engine)
25
+
-[Qiling vs. QEMU User Mode](#qiling-vs-qemu-user-mode)
Qiling is backed by [Unicorn Engine](http://www.unicorn-engine.org).
59
-
60
-
Visit our [website](https://www.qiling.io) for more information.
61
-
62
-
---
63
-
#### License
64
-
65
-
This program is free software; you can redistribute it and/or modify
66
-
it under the terms of the GNU General Public License as published by
67
-
the Free Software Foundation; either version 2 of the License, or
68
-
(at your option) any later version.
69
-
70
-
---
71
-
72
-
#### Qiling vs. other Emulators
73
-
74
-
There are many open-source emulators, but two projects closest to Qiling
75
-
are [Unicorn](http://www.unicorn-engine.org) & [QEMU user mode](https://qemu.org).
76
-
This section explains the main differences of Qiling against them.
77
-
78
-
##### Qiling vs. Unicorn engine
77
+
Qiling has been presented at various international conferences, showcasing its versatility in:
79
78
80
-
Built on top of Unicorn, but Qiling & Unicorn are two different animals.
79
+
- Binary analysis and reverse engineering.
80
+
- Malware analysis and sandboxing.
81
+
- Firmware analysis and emulation.
82
+
- Security research and vulnerability discovery.
83
+
- CTF challenges and exploit development.
81
84
82
-
- Unicorn is just a CPU emulator, so it focuses on emulating CPU instructions,
83
-
that can understand emulator memory.
84
-
Beyond that, Unicorn is not aware of higher level concepts, such as dynamic
85
-
libraries, system calls, I/O handling or executable formats like PE, Mach-O
86
-
or ELF. As a result, Unicorn can only emulate raw machine instructions,
87
-
without Operating System (OS) context.
88
-
- Qiling is designed as a higher level framework, that leverages Unicorn to
89
-
emulate CPU instructions, but can understand OS: it has executable format
90
-
loaders (for PE, Mach-O & ELF currently), dynamic linkers (so we can
91
-
load & relocate shared libraries), syscall & IO handlers. For this reason,
92
-
Qiling can run executable binary without requiring its native OS.
93
-
94
-
##### Qiling vs. QEMU user mode
95
-
96
-
QEMU user mode does a similar thing to our emulator, that is, to emulate whole
97
-
executable binaries in a cross-architecture way.
98
-
However, Qiling offers some important differences against QEMU user mode:
85
+
For more details on Qiling's use cases, blog posts, and related work, please refer to [Qiling's use case, blog and related work](https://github.com/qilingframework/qiling/issues/134).
99
86
100
-
- Qiling is a true analysis framework,
101
-
that allows you to build your own dynamic analysis tools on top (in Python).
102
-
Meanwhile, QEMU is just a tool, not a framework.
103
-
- Qiling can perform dynamic instrumentation, and can even hot patch code at
104
-
runtime. QEMU does neither.
105
-
- Not only working cross-architecture, Qiling is also cross-platform.
106
-
For example, you can run Linux ELF file on top of Windows.
107
-
In contrast, QEMU user mode only runs binary of the same OS, such as Linux
108
-
ELF on Linux, due to the way it forwards syscall from emulated code to
109
-
native OS.
110
-
- Qiling supports more platforms, including Windows, macOS, Linux & BSD. QEMU
111
-
user mode can only handle Linux & BSD.
87
+
## Quick Start
112
88
113
-
---
89
+
### Installation
114
90
115
-
#### Installation
91
+
Qiling requires Python 3.8 or newer. You can install it using pip:
116
92
117
-
Please see [setup guide](https://docs.qiling.io/en/latest/install/) file for how to install Qiling Framework.
93
+
```bash
94
+
pip install qiling
95
+
```
118
96
119
-
---
97
+
For more detailed installation instructions and dependencies, please refer to the [official documentation](https://github.com/qilingframework/qiling/wiki/Installation).
120
98
121
-
#### Examples
99
+
###Basic Usage
122
100
123
-
The example below shows how to use Qiling framework in the most
124
-
straightforward way to emulate a Windows executable.
101
+
The example below shows how to use Qiling framework in the most straightforward way to emulate a Windows executable.
125
102
126
103
```python
127
104
from qiling import Qiling
@@ -135,8 +112,30 @@ if __name__ == "__main__":
135
112
ql.run()
136
113
```
137
114
138
-
- The following example shows how a Windows crackme may be patched dynamically
139
-
to make it always display the “Congratulation” dialog.
115
+
## Qiling vs. Other Emulators
116
+
117
+
There are many open-source emulators, but two projects closest to Qiling are [Unicorn](http://www.unicorn-engine.org) & [QEMU user mode](https://qemu.org). This section explains the main differences of Qiling against them.
118
+
119
+
### Qiling vs. Unicorn Engine
120
+
121
+
Built on top of Unicorn, but Qiling & Unicorn are two different animals.
122
+
123
+
-**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, Mach-O or ELF. As a result, Unicorn can only emulate raw machine instructions, without Operating System (OS) context.
124
+
-**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, 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.
125
+
126
+
### Qiling vs. QEMU User Mode
127
+
128
+
QEMU user mode does a similar thing to our emulator, that is, to emulate whole executable binaries in a cross-architecture way.
129
+
However, Qiling offers some important differences against QEMU user mode:
130
+
131
+
-**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.
132
+
-**Qiling can perform dynamic instrumentation**, and can even hot patch code at runtime. QEMU does neither.
133
+
- 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.
134
+
-**Qiling supports more platforms**, including Windows, macOS, Linux & BSD. QEMU user mode can only handle Linux & BSD.
135
+
136
+
## Examples
137
+
138
+
- The following example shows how a Windows crackme may be patched dynamically to make it always display the “Congratulation” dialog.
140
139
141
140
```python
142
141
from qiling import Qiling
@@ -177,15 +176,13 @@ The below YouTube video shows how the above example works.
177
176
178
177
#### Emulating ARM router firmware on Ubuntu x64 host
179
178
180
-
Qiling Framework hot-patches and emulates an ARM router's `/usr/bin/httpd` on
181
-
an x86_64 Ubuntu host.
179
+
Qiling Framework hot-patches and emulates an ARM router's `/usr/bin/httpd` on an x86_64 Ubuntu host.
182
180
183
-
[](https://www.youtube.com/watch?v=e3_T3KLh2NU)
181
+
[](https://www.youtube.com/watch?v=e3_T3KLhNUs)
184
182
185
183
#### Qiling's IDA Pro Plugin: Instrument and Decrypt Mirai's Secret
186
184
187
-
This video demonstrates how Qiling's IDA Pro plugin can make IDA Pro run with
188
-
Qiling instrumentation engine.
185
+
This video demonstrates how Qiling's IDA Pro plugin can make IDA Pro run with Qiling instrumentation engine.
189
186
190
187
[](http://www.youtube.com/watch?v=ZWMWTq2WTXk)
191
188
@@ -195,63 +192,62 @@ Solving a simple CTF challenge with Qiling Framework and IDA Pro
195
192
196
193
[](https://www.youtube.com/watch?v=SPjVAt2FkKA)
$ ./qltool run -f examples/rootfs/x86_windows/bin/x86_hello.exe --rootfs examples/rootfs/x86_windows/ --console False --json
242
235
```
243
-
---
244
236
237
+
## Contributing
245
238
246
-
#### Contact
239
+
We welcome contributions from the community! If you're interested in contributing to Qiling Framework, please check out our [GitHub repository](https://github.com/qilingframework/qiling) and look for open issues or submit a pull request.
247
240
248
-
Get the latest info from our website https://www.qiling.io
via Twitter [@qiling_io](https://twitter.com/qiling_io).
243
+
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 version 2 of the License, or (at your option) any later version.
252
244
253
-
---
245
+
## Contact
246
+
247
+
Get the latest info from our website [https://www.qiling.io](https://www.qiling.io)
0 commit comments