qiling

name	qiling
description	Auth/lab ref: Qiling OS-layer binary emulation for PE/ELF/Mach-O/UEFI/shellcode with rootfs, syscall/API hooks, filesystem mapping, and runtime patching.
license	MIT
compatibility	Python Qiling framework; targets require matching rootfs/assets supplied by the task or Qiling examples.
metadata	{"version":"1.0","category":"tool"}

Qiling

Qiling sits between CPU-only emulation and full-system emulation: it loads executable formats, models OS APIs/syscalls, maps files, and lets the analyst hook behavior.

Use Qiling when

• the target is PE, ELF, Mach-O, UEFI, DOS, shellcode, or a supported MCU-style sample
• you need to fake files, registry keys, environment, argv, syscalls, or APIs
• dynamic unpacking/decryption needs OS calls but not real hardware
• anti-debug checks should be bypassed without a real debugger
• you want instruction/basic-block/memory/API/syscall hooks

Prefer QEMU user-mode when you only need faithful Linux syscall forwarding. Prefer full-system or board emulation when kernel, drivers, interrupts, or peripherals are central.

Quick checks

qltool run -f ./rootfs/bin/target --rootfs ./rootfs
qltool run -f ./sample.exe --rootfs ./rootfs/x8664_windows --json
qltool code --os linux --arch arm --format hex -f shellcode.hex

Rootfs matters. Missing DLLs, dylibs, registry hives, interpreters, or Linux userspace files are environment gaps, not necessarily target bugs.

Task-local harness pattern

When qltool is too small, create a temporary harness in the analysis workspace. Keep it minimal:

• set argv, rootfs, env, archtype, ostype, endian, and Thumb mode explicitly
• map only required host files into the guest namespace
• hook one syscall/API/address at a time
• log arguments and return values before patching them
• stop at a clear success signal or timeout

Do not build a large reusable framework before one dynamic question is proven.

Hooking decisions

Missing behavior	Good Qiling response
file path missing	map or create the exact path observed in logs
registry/config missing	provide minimal key/value expected by the target
unsupported API/syscall	hook only if it is environmental, not the behavior under study
decryption routine	hook output buffer or stop after the routine
anti-debug/time/randomness	patch return value and label it as an analysis fake
network API	log parameters first; emulate response only when protocol content is not the question

Evidence

• command or harness options
• rootfs/source of OS assets
• list of hooks and fake return values
• stdout/stderr/log output
• dumped memory/config after runtime transformation
• reason Qiling is sufficient or why escalation is needed

Common boundaries

• Qiling is not a complete OS or hardware simulator.
• Some syscalls/APIs are unimplemented; that is a normal pivot point.
• Windows and macOS targets often need legally obtained runtime assets from matching systems.
• CPU-level success under Qiling does not prove kernel, driver, or peripheral behavior.