qilingframework · xwings · Apr 11, 2026 · Apr 11, 2026 · Apr 12, 2026 · Apr 12, 2026
diff --git a/.gitignore b/.gitignore
@@ -70,3 +70,7 @@ poetry.toml
 
 # LSP config files
 pyrightconfig.json
+
+# AI
+CLAUDE.md
+.claude
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-[![Documentation Status](https://github.com/qilingframework/qiling/wiki)](https://github.com/qilingframework/qiling/wiki)
+[![Documentation Status](https://readthedocs.org/projects/qilingframework/badge/?version=latest)](https://docs.qiling.io)
 [![Downloads](https://pepy.tech/badge/qiling)](https://pepy.tech/project/qiling)
 [![Chat on Telegram](https://img.shields.io/badge/Chat%20on-Telegram-brightgreen.svg)](https://t.me/qilingframework)
 
@@ -8,43 +8,24 @@
 <img width="150" height="150" src="https://raw.githubusercontent.com/qilingframework/qiling/master/docs/qiling2_logo_small.png">
 </p>
 
-# Qiling Framework
-
-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.
-
-## Table of Contents
-
-- [Features](#features)
-- [Appearance](#Appearance)
-- [Use Cases](#use-cases)
-- [Quick Start](#quick-start)
-  - [Installation](#installation)
-  - [Basic Usage](#basic-usage)
-- [Qiling vs. Other Emulators](#qiling-vs-other-emulators)
-  - [Qiling vs. Unicorn Engine](#qiling-vs-unicorn-engine)
-  - [Qiling vs. QEMU User Mode](#qiling-vs-qemu-user-mode)
-- [Examples](#examples)
-- [Qltool](#qltool)
-- [Contributing](#contributing)
-- [License](#license)
-- [Contact](#contact)
-- [Core Developers & Contributors](#core-developers--contributors)
-
-## Features
-
-- **Multi-platform Emulation**: Windows, macOS, Linux, Android, BSD, UEFI, DOS, MBR.
-- **Multi-architecture Emulation**: 8086, X86, X86_64, ARM, ARM64, MIPS, RISC-V, PowerPC.
-- **Multiple File Format Support**: PE, Mach-O, ELF, COM, MBR.
-- **Kernel Module Emulation**: Supports Windows Driver (.sys), Linux Kernel Module (.ko) & macOS Kernel (.kext) via [Demigod](https://groundx.io/demigod/).
-- **Isolated Sandboxing**: Emulates & sandboxes code in an isolated environment with a fully configurable sandbox.
-- **In-depth API**: Provides in-depth memory, register, OS level, and filesystem level API.
-- **Fine-grain Instrumentation**: Allows hooks at various levels (instruction/basic-block/memory-access/exception/syscall/IO/etc.).
-- **Virtual Machine Level API**: Supports saving and restoring the current execution state.
-- **Debugging Capabilities**: Supports cross-architecture and platform debugging, including a built-in debugger with reverse debugging capability.
-- **Dynamic Hot Patching**: Allows dynamic hot patching of on-the-fly running code, including loaded libraries.
-- **Python Framework**: A true framework in Python, making it easy to build customized security analysis tools.
-
-## Appearance
+[Qiling's use case, blog and related work](https://github.com/qilingframework/qiling/issues/134)
+
+Qiling is an advanced 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-V, PowerPC.
+- Support multiple file formats: PE, Mach-O, ELF, COM, MBR.
+- Support Windows Driver (.sys), Linux Kernel Module (.ko) & macOS Kernel (.kext) via [Demigod](https://groundx.io/demigod/).
+- Emulates & sandbox code in an isolated environment.
+- Provides a fully configurable sandbox.
+- Provides in-depth memory, register, OS level and filesystem level API.
+- Fine-grain instrumentation: allows hooks at various levels
+  (instruction/basic-block/memory-access/exception/syscall/IO/etc.)
+- Provides virtual 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 various international conferences.
 
@@ -68,37 +49,79 @@ Qiling also made its way to various international conferences.
 - [Nullcon](https://nullcon.net/website/goa-2020/speakers/kaijern-lau.php)
 
 2019:
+
 - [DEFCON, USA](https://www.defcon.org/html/defcon-27/dc-27-demolabs.html#QiLing)
 - [Hitcon](https://hitcon.org/2019/CMT/agenda)
 - [Zeronights](https://zeronights.ru/report-en/qiling-io-advanced-binary-emulation-framework/)
 
-## Use Cases
 
-Qiling has been presented at various international conferences, showcasing its versatility in:
+Qiling is backed by [Unicorn Engine](http://www.unicorn-engine.org).
 
-- Binary analysis and reverse engineering.
-- Malware analysis and sandboxing.
-- Firmware analysis and emulation.
-- Security research and vulnerability discovery.
-- CTF challenges and exploit development.
+Visit our [website](https://www.qiling.io) for more information.
 
-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).
+---
+#### License
 
-## Quick Start
+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.
 
-### Installation
+---
 
-Qiling requires Python 3.8 or newer. You can install it using pip:
+#### Qiling vs. other Emulators
 
-```bash
-pip install qiling
-```
+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.
+
+##### 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, 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 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.
+
+##### 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.
 
-For more detailed installation instructions and dependencies, please refer to the [official documentation](https://github.com/qilingframework/qiling/wiki/Installation).
+---
+
+#### Installation
+
+Please see [setup guide](https://github.com/qilingframework/qiling/wiki/Installation) file for how to install Qiling Framework.
+
+---
 
-### Basic Usage
+#### Examples
 
-The example below shows how to use Qiling framework in the most straightforward way to emulate a Windows executable.
+The example below shows how to use Qiling framework in the most
+straightforward way to emulate a Windows executable.
 
 ```python
 from qiling import Qiling
@@ -112,30 +135,8 @@ if __name__ == "__main__":
     ql.run()
 ```
 
-## Qiling vs. Other Emulators
-
-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.
-
-### 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, 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 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.
-
-### 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.
-
-## Examples
-
-- The following example shows how a Windows crackme may be patched dynamically to make it always display the “Congratulation” dialog.
+- The following example shows how a Windows crackme may be patched dynamically
+  to make it always display the “Congratulation” dialog.
 
 ```python
 from qiling import Qiling
@@ -176,13 +177,15 @@ The below YouTube video shows how the above example 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 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](https://github.com/qilingframework/theme.qiling.io/blob/master/source/img/fuzzer.jpg?raw=true)](https://www.youtube.com/watch?v=e3_T3KLhNUs)
+[![Qiling Tutorial: Emulating and Fuzz ARM router firmware](https://github.com/qilingframework/theme.qiling.io/blob/master/source/img/fuzzer.jpg?raw=true)](https://www.youtube.com/watch?v=e3_T3KLh2NU)
 
 #### 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.
+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](http://img.youtube.com/vi/ZWMWTq2WTXk/0.jpg)](http://www.youtube.com/watch?v=ZWMWTq2WTXk)
 
@@ -192,62 +195,63 @@ Solving a simple CTF challenge with Qiling Framework and IDA Pro
 
 [![Solving a simple CTF challenge with Qiling Framework and IDA Pro](https://i.ytimg.com/vi/SPjVAt2FkKA/0.jpg)](https://www.youtube.com/watch?v=SPjVAt2FkKA)
 
+
 #### Emulating MBR
 
 Qiling Framework emulates MBR
 
 [![Qiling DEMO: Emulating MBR](https://github.com/qilingframework/theme.qiling.io/blob/master/source/img/mbr.png?raw=true)](https://github.com/qilingframework/theme.qiling.io/blob/master/source/img/mbr.png?raw=true)
 
-## Qltool
+---
+
+#### Qltool
 
 Qiling also provides a friendly tool named `qltool` to quickly emulate shellcode & executable binaries.
 
 With qltool, easy execution can be performed:
 
+
 With shellcode:
 
-```bash
+```
 $ ./qltool code --os linux --arch arm --format hex -f examples/shellcodes/linarm32_tcp_reverse_shell.hex
 ```
 
 With binary file:
 
-```bash
+```
 $ ./qltool run -f examples/rootfs/x8664_linux/bin/x8664_hello --rootfs  examples/rootfs/x8664_linux/
 ```
 
 With binary and GDB debugger enabled:
 
-```bash
+```
 $ ./qltool run -f examples/rootfs/x8664_linux/bin/x8664_hello --gdb 127.0.0.1:9999 --rootfs examples/rootfs/x8664_linux
 ```
 
 With code coverage collection (UEFI only for now):
 
-```bash
+```
 $ ./qltool run -f examples/rootfs/x8664_efi/bin/TcgPlatformSetupPolicy --rootfs examples/rootfs/x8664_efi --coverage-format drcov --coverage-file TcgPlatformSetupPolicy.cov
 ```
 
 With JSON output (Windows, mainly):
 
-```bash
+```
 $ ./qltool run -f examples/rootfs/x86_windows/bin/x86_hello.exe --rootfs  examples/rootfs/x86_windows/ --console False --json
 ```
+---
 
-## Contributing
-
-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.
-
-## 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 version 2 of the License, or (at your option) any later version.
+#### Contact
 
-## Contact
+Get the latest info from our website https://www.qiling.io
 
-Get the latest info from our website [https://www.qiling.io](https://www.qiling.io)
+Contact us at email info@qiling.io,
+via Twitter [@qiling_io](https://twitter.com/qiling_io).
 
-Contact us at email [info@qiling.io](mailto:info@qiling.io), or via Twitter [@qiling_io](https://twitter.com/qiling_io).
+---
 
-## Core Developers & Contributors
+#### Core developers, Key Contributors and etc.
 
-Please refer to [CREDITS.md](https://github.com/qilingframework/qiling/blob/dev/CREDITS.md).
+Please refer to [CREDITS.md](https://github.com/qilingframework/qiling/blob/dev/CREDITS.md).
diff --git a/TODO b/TODO