Skip to content

Quick Start Guide

Jump to bottom
xwings edited this page Jul 6, 2025 · 3 revisions

Quick Start Guide

This guide will walk you through the essential steps to get up and running with Qiling Framework.

1. Installation

First, ensure you have Qiling installed. If not, refer to the Installation guide.

2. Emulating a simple binary

The most common use case for Qiling is to emulate a binary. Here's a simple example for a Linux executable.

C Code (hello.c):

#include <stdio.h>
#include <unistd.h>

int main() {
    printf("Hello from the emulated program!\n");
    write(1, "This is a syscall!\n", 20);
    return 0;
}

Compilation:

# For x86_64 Linux
gcc -o hello_x86_64 hello.c

# For ARM64 Linux
aarch64-linux-gnu-gcc -o hello_aarch64 hello.c

Qiling Python Script (emulate.py):

from qiling import Qiling
from qiling.const import QL_VERBOSE

if __name__ == "__main__":
    # Path to the binary you want to emulate
    # Make sure you have the correct rootfs for the target architecture
    # For example, 'qiling/examples/rootfs/x8664_linux'
    binary_path = 'hello_x86_64'
    rootfs_path = 'path/to/your/rootfs/x8664_linux'

    # Initialize Qiling
    ql = Qiling([binary_path], rootfs_path, verbose=QL_VERBOSE.OFF)

    # Run the emulation
    ql.run()

Execution:

python emulate.py

You should see the output from both printf and the write syscall.

3. Hooking

Qiling's real power comes from its hooking capabilities. You can intercept and modify execution at various points.

Example: Hooking an address

from qiling import Qiling
from qiling.const import QL_VERBOSE

def my_hook(ql):
    print("Hook triggered at the entry point!")
    # You can inspect registers, memory, etc.
    # For example, print the value of RAX
    print(f"RAX = {ql.reg.rax:#x}")

if __name__ == "__main__":
    binary_path = 'hello_x86_64'
    rootfs_path = 'path/to/your/rootfs/x8664_linux'

    ql = Qiling([binary_path], rootfs_path, verbose=QL_VERBOSE.OFF)

    # Get the entry point of the binary
    entry_point = ql.loader.elf_entry

    # Set a hook at the entry point
    ql.hook_address(my_hook, entry_point)

    # Run the emulation
    ql.run()

4. Interacting with the Emulated System

You can use the Qiling API to interact with the emulated filesystem, memory, and registers.

Example: Writing a file to the emulated filesystem

from qiling import Qiling
from qiling.const import QL_VERBOSE

if __name__ == "__main__":
    binary_path = '/bin/ls'
    rootfs_path = 'path/to/your/rootfs/x8664_linux'

    # Initialize Qiling to run 'ls /my_new_dir'
    ql = Qiling([binary_path, '/my_new_dir'], rootfs_path, verbose=QL_VERBOSE.OFF)

    # Create a directory in the emulated filesystem
    ql.fs.mkdir('/my_new_dir', 0o755)

    # Write a file inside the new directory
    ql.fs.write('/my_new_dir/my_file.txt', b'Hello from Qiling!')

    # Run the emulation
    ql.run()

This is just a glimpse of what you can do with Qiling. Explore the other sections of this wiki to learn about more advanced features.

Clone this wiki locally