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.
1---2name: qiling3description: 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.4license: MIT5---67# Qiling89Qiling 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.1011## Use Qiling when1213- the target is PE, ELF, Mach-O, UEFI, DOS, shellcode, or a supported MCU-style sample14- you need to fake files, registry keys, environment, argv, syscalls, or APIs15- dynamic unpacking/decryption needs OS calls but not real hardware16- anti-debug checks should be bypassed without a real debugger17- you want instruction/basic-block/memory/API/syscall hooks1819Prefer 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.2021## Quick checks2223```bash24qltool run -f ./rootfs/bin/target --rootfs ./rootfs25qltool run -f ./sample.exe --rootfs ./rootfs/x8664_windows --json26qltool code --os linux --arch arm --format hex -f shellcode.hex27```2829Rootfs matters. Missing DLLs, dylibs, registry hives, interpreters, or Linux userspace files are environment gaps, not necessarily target bugs.3031## Task-local harness pattern3233When `qltool` is too small, create a temporary harness in the analysis workspace. Keep it minimal:3435- set `argv`, `rootfs`, `env`, `archtype`, `ostype`, endian, and Thumb mode explicitly36- map only required host files into the guest namespace37- hook one syscall/API/address at a time38- log arguments and return values before patching them39- stop at a clear success signal or timeout4041Do not build a large reusable framework before one dynamic question is proven.4243## Hooking decisions4445| Missing behavior | Good Qiling response |46|---|---|47| file path missing | map or create the exact path observed in logs |48| registry/config missing | provide minimal key/value expected by the target |49| unsupported API/syscall | hook only if it is environmental, not the behavior under study |50| decryption routine | hook output buffer or stop after the routine |51| anti-debug/time/randomness | patch return value and label it as an analysis fake |52| network API | log parameters first; emulate response only when protocol content is not the question |5354## Evidence5556- command or harness options57- rootfs/source of OS assets58- list of hooks and fake return values59- stdout/stderr/log output60- dumped memory/config after runtime transformation61- reason Qiling is sufficient or why escalation is needed6263## Common boundaries6465- Qiling is not a complete OS or hardware simulator.66- Some syscalls/APIs are unimplemented; that is a normal pivot point.67- Windows and macOS targets often need legally obtained runtime assets from matching systems.68- CPU-level success under Qiling does not prove kernel, driver, or peripheral behavior.69
AeonDave