Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 23 additions & 23 deletions docs/howto.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,39 +7,39 @@ Emulating a program or shellcode using Qiling requires a Qiling instance. Most o

### Initialization arguments for binary emulation

| Name | Type | Description
| :-- | :-- | :--
| `argv` | `Sequence[str]` | a sequence of command line arguments to emulate
| `rootfs` | `str` | the emulated filesystem root directory. all paths accessed by the emulated program will be based on this directory
| `env` (optional) | `MutableMapping[AnyStr, AnyStr]` | a dictionary of environment variables available for the emualted program
| Name | Type | Description |
|--------------------------|----------------------------------|-----|
| `argv` | `Sequence[str]` | a sequence of command line arguments to emulate |
| `rootfs` | `str` | the emulated filesystem root directory. all paths accessed by the emulated program will be based on this directory |
| `env` (optional) | `MutableMapping[AnyStr, AnyStr]` | a dictionary of environment variables available for the emualted program |

Notes:
- Qiling will automaticaly infer the target OS and architecture based on the target program
- Using the hosting system root directory as emulation rootfs is considered a bad practice and it is strictly **not recommended**

### Initialization arguments for shellcode emulation

| Name | Type | Description
| :-- | :-- | :--
| `code` | `bytes` | shellcode to emulate. that comes instead of `argv`
| `rootfs` (optional) | `str` | _refer to above table_
| `ostype` | `QL_OS` | sets target operating system: `LINUX`, `FREEBSD`, `MACOS`, `WINDOWS`, `UEFI`, `DOS`, `QNX`, `MCU`, or `BLOB`
| `archtype` | `QL_ARCH` | sets target architecture: `X86`, `X8664`, `ARM`, `ARM64`, `MIPS`, `A8086`, `CORTEX_M'`, `RISCV`, `RISCV64` or `PPC`
| `endian` (optional) | `bool` | indicates architecture endianess (relevant only to ARM and MIPS)
| `thumb` (optional) | `bool` | indicates ARM thumb mode (relevant only to ARM)
| Name | Type | Description |
|--------------------------|------------|------------ |
| `code` | `bytes` | shellcode to emulate. that comes instead of `argv` |
| `rootfs` (optional) | `str` | _refer to above table_ |
| `ostype` | `QL_OS` | sets target operating system: `LINUX`, `FREEBSD`, `MACOS`, `WINDOWS`, `UEFI`, `DOS`, `QNX`, `MCU`, or `BLOB` |
| `archtype` | `QL_ARCH` | sets target architecture: `X86`, `X8664`, `ARM`, `ARM64`, `MIPS`, `A8086`, `CORTEX_M'`, `RISCV`, `RISCV64` or `PPC` |
| `endian` (optional) | `bool` | indicates architecture endianess (relevant only to ARM and MIPS) |
| `thumb` (optional) | `bool` | indicates ARM thumb mode (relevant only to ARM) |

### Common initialization arguments

| Name | Type | Description
| :-- | :-- | :--
| `cputype` (optional) | `QL_CPU` | sets the underlying CPU model. this is used to make sure certain architectural features are available
| `verbose` (optional) | `QL_VERBOSE` | sets Qiling logging verbosity level (default: `QL_VERBOSE.DEFAULT`). for more details see [print section](https://docs.qiling.io/en/latest/print/)
| `profile` (optional) | `str` | path to profile file holding additional settings. for more details see [profile section](https://docs.qiling.io/en/latest/profile/)
| `log_devices` (optional) | `Collection[IO \| str]` | determines logging output devices: file streams and names are both supported. by default logging output goes to `stderr`
| `log_override` (optional) | `Logger` | used to override the default logger with a custom one
| `log_plain` (optional) | `bool` | indicates whether logger output should be colorful or plain. by default this is determined by the target log device and whether it supports colors
| `multithread` (optional) | `bool` | indicates whether the target should be emulated as a multi-threaded program
| `libcache` (optional) | `bool` | indicates whether libraries should be loaded from cache. this saves libraries parsing and relocating time on consequent runs. currently available only for Windows programs
| Name | Type | Description|
|---------------------------|-------------------------|------------|
| `cputype` (optional) | `QL_CPU` | sets the underlying CPU model. this is used to make sure certain architectural features are available |
| `verbose` (optional) | `QL_VERBOSE` | sets Qiling logging verbosity level (default: `QL_VERBOSE.DEFAULT`). for more details see [print section](https://docs.qiling.io/en/latest/print/) |
| `profile` (optional) | `str` | path to profile file holding additional settings. for more details see [profile section](https://docs.qiling.io/en/latest/profile/) |
| `log_devices` (optional) | `Collection[IO \| str]` | determines logging output devices: file streams and names are both supported. by default logging output goes to `stderr` |
| `log_override` (optional) | `Logger` | used to override the default logger with a custom one |
| `log_plain` (optional) | `bool` | indicates whether logger output should be colorful or plain. by default this is determined by the target log device and whether it supports colors |
| `multithread` (optional) | `bool` | indicates whether the target should be emulated as a multi-threaded program |
| `libcache` (optional) | `bool` | indicates whether libraries should be loaded from cache. this saves libraries parsing and relocating time on consequent runs. currently available only for Windows programs |

## Configuring the emulation environment
During its initialization Qiling infers the target OS and architecture, which now may be configured as necessary.
Expand Down