Skip to content

FAQ

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

Frequently Asked Questions

General Questions

What is Qiling Framework?

Qiling is an advanced binary emulation framework that allows you to emulate binary code across different platforms and architectures. It's built on top of Unicorn Engine and provides high-level APIs for dynamic analysis, debugging, and fuzzing.

How is Qiling different from other emulators?

  • Higher-level abstraction: Unlike Unicorn, Qiling understands OS concepts, file systems, and system calls
  • Cross-platform capability: Run Linux binaries on Windows, Windows binaries on Linux, etc.
  • Built for analysis: Designed specifically for security research and reverse engineering
  • Python framework: Easy to script and extend
  • Rich instrumentation: Fine-grained hooks at multiple levels

What platforms and architectures does Qiling support?

Platforms:

  • Linux
  • Windows
  • macOS
  • FreeBSD
  • UEFI
  • DOS
  • QNX
  • MCU (Microcontrollers)

Architectures:

  • x86 (32-bit)
  • x86-64 (64-bit)
  • ARM (32-bit)
  • ARM64 (64-bit)
  • MIPS
  • 8086
  • Cortex-M
  • RISC-V (32/64-bit)
  • PowerPC

Installation Issues

Why do I get "No module named 'qiling'" error?

This usually means Qiling isn't installed or you're not in the correct virtual environment:

# Check if Qiling is installed
pip list | grep qiling

# Install Qiling
pip install qiling

# If using virtual environment, activate it first
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

Unicorn Engine installation fails on macOS

On macOS 10.14+, install from source:

git clone https://github.com/unicorn-engine/unicorn
cd unicorn
./make.sh
sudo ./make.sh install
cd bindings/python
sudo make install

Why can't Qiling find my binary's dependencies?

Ensure your rootfs contains all necessary libraries:

# Check what libraries your binary needs
# Linux
ldd /path/to/binary

# macOS  
otool -L /path/to/binary

# Windows
dumpbin /dependents binary.exe

Copy missing libraries to the appropriate rootfs directory.

Usage Questions

How do I emulate a Windows binary without Windows DLLs?

You need to obtain Windows DLLs legally. If you have a Windows license:

  1. Use the provided dllscollector.bat script on a Windows system
  2. Copy the collected DLLs to your Qiling rootfs
  3. Alternatively, use Docker with pre-configured DLLs

Why does my emulation stop immediately?

Common causes:

  • Missing entry point
  • Incorrect architecture/OS detection
  • Missing dependencies
  • Unsupported syscalls

Debug with verbose output:

ql = Qiling(argv, rootfs, verbose=QL_VERBOSE.DEBUG)

How do I handle unsupported syscalls?

Implement custom syscall handlers:

def my_custom_syscall(ql, *args):
    print("Custom syscall handler")
    return 0

ql.os.set_syscall("unsupported_call", my_custom_syscall)

Can I emulate shellcode?

Yes, use shellcode emulation mode:

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

shellcode = b'\x48\x31\xc0...'  # Your shellcode
ql = Qiling(code=shellcode, 
           archtype=QL_ARCH.X8664, 
           ostype=QL_OS.LINUX)
ql.run()

Performance Questions

My emulation is very slow. How can I speed it up?

  1. Enable library caching (Windows): libcache=True
  2. Use appropriate verbosity: verbose=QL_VERBOSE.OFF
  3. Focus emulation scope: Use begin/end parameters
  4. Optimize hooks: Only hook what you need
  5. Use persistent mode for fuzzing

How much memory does Qiling use?

Memory usage depends on:

  • Target binary size
  • Emulated memory layout
  • Number of loaded libraries
  • Hook complexity

Monitor with:

import psutil
process = psutil.Process()
print(f"Memory usage: {process.memory_info().rss / 1024 / 1024:.2f} MB")

Debugging Questions

How do I debug my Qiling script?

  1. Enable verbose output: verbose=QL_VERBOSE.DEBUG
  2. Use built-in debugger: ql.debugger = "qdb"
  3. Add instruction hooks: Track execution flow
  4. Use GDB server: ql.debugger = "gdb:localhost:9999"

Why doesn't my breakpoint trigger?

  • Verify the address is correct
  • Check if code is actually executed
  • Ensure proper address format (virtual vs. physical)
  • Use instruction hooks to verify execution

How do I examine memory during emulation?

# Read memory
data = ql.mem.read(address, size)

# Write memory  
ql.mem.write(address, data)

# Check if memory is mapped
if ql.mem.is_mapped(address):
    print("Memory is mapped")

# Get memory layout
mapinfo = ql.mem.get_mapinfo()

Hooking Questions

What's the difference between different hook types?

  • Code hooks: Called for every instruction
  • Block hooks: Called for each basic block
  • Memory hooks: Called for memory access
  • Address hooks: Called at specific addresses
  • API hooks: Called for system APIs

How do I hook Windows APIs?

def hook_createfile(ql, lpFileName, *args):
    filename = ql.os.utils.read_wstring(lpFileName)
    print(f"CreateFile: {filename}")
    return None  # Call original

ql.set_api("CreateFileW", hook_createfile)

Can I modify program behavior with hooks?

Yes, hooks can:

  • Change register values
  • Modify memory contents
  • Skip function calls
  • Redirect execution flow
  • Implement custom APIs

Error Handling

What does "QlErrorFileNotFound" mean?

The binary or a required file couldn't be found:

  • Check file paths
  • Verify file permissions
  • Ensure rootfs structure is correct

How do I handle "QlMemoryMappedError"?

This indicates memory mapping issues:

  • Check if memory range is already mapped
  • Verify memory alignment
  • Ensure sufficient virtual address space

What causes "QlErrorExecutionStop"?

Emulation stopped unexpectedly:

  • Unhandled exception in target
  • Unsupported instruction
  • Memory access violation
  • Timeout reached

Advanced Topics

Can I emulate kernel modules?

Yes, Qiling supports:

  • Linux kernel modules (.ko)
  • Windows drivers (.sys)
  • macOS kernel extensions (.kext)

Use with appropriate rootfs and kernel environment setup.

How do I implement custom file systems?

from qiling.os.posix import QlPosixFileOperations

class CustomFileOps(QlPosixFileOperations):
    def custom_open(self, path, flags, mode):
        # Custom file opening logic
        return super().open(path, flags, mode)

ql.add_fs_mapper("/custom", CustomFileOps)

Can I run multithreaded programs?

Yes, enable multithreading support:

ql = Qiling(argv, rootfs, multithread=True)

How do I save and restore execution state?

# Save state
state = ql.save()

# Restore state
ql.restore(state)

# Or use context manager
with ql.save_and_restore():
    # Modifications here are automatically restored
    ql.run()

Integration Questions

Can I use Qiling with IDA Pro?

Yes, Qiling provides IDA Pro integration:

from qiling.extensions.idaplugin import ql_ida_plugin

How do I integrate with other tools?

Qiling can be integrated with:

  • Radare2: r2pipe integration
  • GDB: Remote debugging protocol
  • AFL++: Fuzzing framework
  • Ghidra: Script integration
  • Custom tools: Python API

Can I use Qiling in automated pipelines?

Yes, Qiling is designed for automation:

  • Scriptable Python API
  • Command-line tools
  • Docker support
  • CI/CD integration

Troubleshooting

My script hangs during emulation

  • Set execution timeout: ql.run(timeout=1000000)
  • Check for infinite loops
  • Verify emulation constraints
  • Use debugger to identify hanging point

Emulation crashes with segmentation fault

  • Enable debug output
  • Check memory layout
  • Verify instruction execution
  • Use memory access hooks to trace issue

Results are inconsistent between runs

  • Check for uninitialized memory usage
  • Verify deterministic initialization
  • Look for race conditions (multithreading)
  • Ensure proper state cleanup

Getting Help

Where can I get support?

  • GitHub Issues: Report bugs and feature requests
  • Telegram Chat: Real-time community support
  • Documentation: Comprehensive guides and examples
  • Stack Overflow: Tag questions with 'qiling'

How do I report a bug?

  1. Check existing issues first
  2. Provide minimal reproduction case
  3. Include Qiling version and platform info
  4. Add relevant error messages and logs
  5. Specify expected vs. actual behavior

How can I contribute?

  • Code contributions: Submit pull requests
  • Documentation: Improve guides and examples
  • Testing: Report bugs and test new features
  • Community: Help other users in forums

Where can I find examples?

Clone this wiki locally