Skip to content

Quick Start Guide

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

Quick Start Guide

Get up and running with Qiling Framework in minutes with this streamlined guide.

🚀 5-Minute Setup

1. Install Qiling

# Install via pip (recommended)
pip install qiling

# Or install from source
git clone https://github.com/qilingframework/qiling.git
cd qiling
pip install -e .

2. Download Rootfs

# Download pre-built rootfs
wget https://github.com/qilingframework/rootfs/releases/download/4.0.0/rootfs.tar.gz
tar -xzf rootfs.tar.gz

3. Your First Emulation

# hello_qiling.py
from qiling import Qiling

# Emulate a Linux binary
ql = Qiling(['rootfs/x8664_linux/bin/x8664_hello'], 'rootfs/x8664_linux')
ql.run()

Output:

Hello World!

🎉 Congratulations! You just emulated your first binary with Qiling!

📚 Essential Examples

Basic Binary Analysis

from qiling import Qiling
from qiling.const import QL_VERBOSE

# Analyze a binary with detailed output
ql = Qiling(['rootfs/x8664_linux/bin/x8664_hello'], 
           'rootfs/x8664_linux',
           verbose=QL_VERBOSE.DEBUG)
ql.run()

Shellcode Emulation

from qiling import Qiling
from qiling.const import QL_ARCH, QL_OS

# Emulate shellcode directly
shellcode = b"\x48\x31\xc0\x48\x31\xff\x48\x31\xf6\x48\x31\xd2\x48\xff\xc0\x48\x89\xc7\x48\xff\xc0\x0f\x05"

ql = Qiling(code=shellcode, 
           archtype=QL_ARCH.X8664, 
           ostype=QL_OS.LINUX)
ql.run()

API Hooking

from qiling import Qiling

def my_puts(ql, address, params):
    print(f"[HOOK] puts() called with: {params}")
    return len(params[0])

ql = Qiling(['rootfs/x8664_linux/bin/x8664_hello'], 'rootfs/x8664_linux')
ql.set_api('puts', my_puts)
ql.run()

Memory Analysis

from qiling import Qiling

ql = Qiling(['rootfs/x8664_linux/bin/x8664_hello'], 'rootfs/x8664_linux')

# Hook memory reads
def mem_read_hook(ql, access, address, size, value):
    print(f"[MEM READ] 0x{address:x} -> 0x{value:x}")

ql.hook_mem_read(mem_read_hook)
ql.run()

🎯 Common Use Cases

1. Malware Analysis

from qiling import Qiling

# Analyze Windows malware
ql = Qiling(['malware.exe'], 'rootfs/x86_windows')

# Hook CreateFile to monitor file operations
def hook_createfile(ql, address, params):
    filename = params['lpFileName']
    print(f"[MALWARE] Accessing file: {filename}")
    return 1

ql.set_api('CreateFileW', hook_createfile)
ql.run()

2. Reverse Engineering

from qiling import Qiling

ql = Qiling(['crackme.exe'], 'rootfs/x86_windows')

# Hook at specific address to bypass checks
def bypass_check(ql):
    ql.arch.regs.eax = 1  # Force success
    print("[BYPASS] License check bypassed!")

ql.hook_address(bypass_check, 0x401234)
ql.run()

3. Vulnerability Research

from qiling import Qiling

# Fuzz a binary by hooking input functions
def fuzz_input(ql, address, params):
    # Return crafted input
    return b"A" * 1000  # Buffer overflow payload

ql = Qiling(['vulnerable_app'], 'rootfs/x8664_linux')
ql.set_api('gets', fuzz_input)
ql.run()

🔧 Configuration Essentials

Environment Variables

from qiling import Qiling

# Set custom environment
env = {
    'PATH': '/bin:/usr/bin',
    'HOME': '/home/user',
    'LANG': 'en_US.UTF-8'
}

ql = Qiling(['binary'], 'rootfs/x8664_linux', env=env)
ql.run()

Command Line Arguments

from qiling import Qiling

# Pass arguments to the binary
argv = ['binary', '--flag', 'value', 'input.txt']

ql = Qiling(argv, 'rootfs/x8664_linux')
ql.run()

Custom Memory Layout

from qiling import Qiling

ql = Qiling(['binary'], 'rootfs/x8664_linux')

# Map custom memory regions
ql.mem.map(0x10000000, 0x1000, info="custom_region")
ql.mem.write(0x10000000, b"Hello from custom memory!")

ql.run()

🏗️ Architecture Support

Cross-Platform Emulation

from qiling import Qiling

# Emulate different architectures
architectures = [
    (['rootfs/x8664_linux/bin/x8664_hello'], 'rootfs/x8664_linux'),
    (['rootfs/x86_linux/bin/x86_hello'], 'rootfs/x86_linux'),
    (['rootfs/arm_linux/bin/arm_hello'], 'rootfs/arm_linux'),
    (['rootfs/mips32_linux/bin/mips32_hello'], 'rootfs/mips32_linux')
]

for argv, rootfs in architectures:
    try:
        ql = Qiling(argv, rootfs)
        ql.run()
        print(f"✓ {rootfs} emulation successful")
    except Exception as e:
        print(f"✗ {rootfs} emulation failed: {e}")

MCU Emulation

from qiling import Qiling
from qiling.const import QL_ARCH, QL_OS

# Emulate ARM Cortex-M firmware
firmware = open('firmware.bin', 'rb').read()

ql = Qiling(code=firmware, 
           archtype=QL_ARCH.CORTEX_M, 
           ostype=QL_OS.MCU,
           profile="stm32f103.ql")
ql.run()

🛠️ Essential Tools

Using QlTool

# Emulate with QlTool
qltool run -f rootfs/x8664_linux/bin/x8664_hello --rootfs rootfs/x8664_linux

# Code coverage
qltool run -f binary --rootfs rootfs --coverage drcov

# Trace execution
qltool run -f binary --rootfs rootfs --trace

# Debug mode
qltool run -f binary --rootfs rootfs --debug

Integration with Popular Tools

# GDB Integration
from qiling import Qiling

ql = Qiling(['binary'], 'rootfs/x8664_linux')
ql.debugger = "gdb:127.0.0.1:1234"  # GDB server
ql.run()

# Ghidra Integration
from qiling.extensions.ghidra import ghidra_bridge

bridge = ghidra_bridge(ql)
bridge.export_function_info()

📊 Performance Tips

Optimization for Speed

from qiling import Qiling

# Fast emulation mode
ql = Qiling(['binary'], 'rootfs/x8664_linux')
ql.multithread = True  # Enable multithreading
ql.timeout = 10        # Set timeout
ql.run()

Memory Optimization

from qiling import Qiling

# Memory-efficient emulation
ql = Qiling(['binary'], 'rootfs/x8664_linux')
ql.mem.pagesize = 4096  # Optimize page size
ql.libcache = True      # Enable library caching
ql.run()

🔍 Debugging Techniques

Interactive Debugging

from qiling import Qiling

ql = Qiling(['binary'], 'rootfs/x8664_linux')

# Set breakpoint at specific address
def breakpoint_handler(ql):
    print(f"[BREAK] Hit breakpoint at 0x{ql.arch.regs.rip:x}")
    print(f"[BREAK] EAX: 0x{ql.arch.regs.eax:x}")
    print(f"[BREAK] ESP: 0x{ql.arch.regs.esp:x}")
    # Interactive debugging here
    import pdb; pdb.set_trace()

ql.hook_address(breakpoint_handler, 0x401000)
ql.run()

Register Monitoring

from qiling import Qiling

def monitor_registers(ql, address, size):
    if address == 0x401000:
        print(f"[REGS] EAX: 0x{ql.arch.regs.eax:x}")
        print(f"[REGS] EBX: 0x{ql.arch.regs.ebx:x}")
        print(f"[REGS] ECX: 0x{ql.arch.regs.ecx:x}")
        print(f"[REGS] EDX: 0x{ql.arch.regs.edx:x}")

ql = Qiling(['binary'], 'rootfs/x8664_linux')
ql.hook_code(monitor_registers)
ql.run()

🎓 Next Steps

Now that you've mastered the basics, explore these advanced topics:

  1. Learning Path - Structured progression from beginner to expert
  2. Tutorials - Step-by-step guides for specific tasks
  3. API Reference - Complete API documentation
  4. Platform Guides - Platform-specific emulation techniques
  5. Use Case Guides - Real-world application examples

🆘 Getting Help

Common Issues:

  • Import Error: Make sure Qiling is installed correctly
  • Rootfs Not Found: Download the correct rootfs for your target
  • Emulation Fails: Check architecture and OS compatibility
  • Performance Issues: See Performance Tuning guide

Support Channels:

Community Resources:

Ready to dive deeper? Check out our Learning Path for a structured journey through Qiling Framework's capabilities!

Clone this wiki locally