Skip to content

QlTool

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

QlTool: The Qiling Command-Line Interface

QlTool is a versatile command-line tool that provides a convenient way to use Qiling's emulation capabilities without writing any Python code. It's perfect for quick analysis, testing, and debugging tasks.

Basic Usage

The fundamental syntax for QlTool is:

qltool -f <executable> -r <rootfs> [options]
  • -f, --file: The executable binary to emulate.
  • -r, --rootfs: The path to the root filesystem for the target OS and architecture.

Example: Running a Linux binary

# Emulate an x86_64 Linux binary
qltool -f /bin/ls -r /path/to/rootfs/x8664_linux

Key Features and Options

QlTool offers a wide range of options to control the emulation environment.

Verbosity

You can control the level of detail in the output.

  • -v, --verbose: Show verbose output (e.g., syscalls).
  • -d, --debug: Show debug output (e.g., instruction tracing). This can be very noisy.

Example:

qltool -f /bin/date -r ... --verbose

Setting the Emulation Range

You can specify the start and end addresses for the emulation.

  • --begin <address>: The address to start execution from.
  • --end <address>: The address to stop execution at.
  • --count <number>: The maximum number of instructions to execute.

Example: Emulating a single function

qltool -f my_app -r ... --begin 0x401100 --end 0x401250

Debugging with GDB

QlTool can act as a GDB stub, allowing you to debug the emulated program with a GDB client.

  • -g, --gdb <port>: Start a GDB server on the specified port.

Example:

  1. Start QlTool with the GDB server:

    qltool -f my_app -r ... -g 1234

  2. Connect with GDB from another terminal:

    gdb
(gdb) target remote :1234
(gdb) b *0x401100
(gdb) c

Running Shellcode

QlTool can execute raw shellcode directly.

  • --shellcode: Specify that the input file is shellcode.
  • --arch <arch>: The architecture of the shellcode (e.g., x8664).
  • --os <os>: The target OS of the shellcode (e.g., linux).

Example: Running x86_64 Linux shellcode

# Create a file with the raw shellcode bytes
echo -ne "\x48\x31\xc0\xb0\x3c\x0f\x05" > exit.bin

# Execute it
qltool -f exit.bin --shellcode --arch x8664 --os linux

Environment Variables and Filesystem

  • --env <key=value>: Set an environment variable for the emulated process.
  • --map-rootfs <host_path>:<emulated_path>: Map a host directory to a path in the virtual filesystem.

Example:

qltool -f my_app -r ... --env "LD_PRELOAD=my_lib.so" --map-rootfs /tmp/data:/data

Output Formatting

  • --json: Output the results in JSON format, which is useful for scripting and integration with other tools.

QlTool is a powerful companion to the Qiling Framework, providing a quick and easy way to access its core functionality directly from the command line.

Clone this wiki locally