From 1dd4d51cdfb3290331eda66be17acb890a45245f Mon Sep 17 00:00:00 2001 From: wargio Date: Thu, 1 Feb 2024 16:41:34 +0800 Subject: [PATCH] Rewrite of the configuration chapter. --- _quarto.yml | 3 +- src/SUMMARY.md | 138 ----- src/basic_commands/mapping_files.md | 2 +- src/configuration/build_variables.md | 33 ++ src/configuration/colors.md | 44 +- .../{rzpal.png => ecs_palette.png} | Bin src/configuration/evars.md | 555 +++++++++++------- src/configuration/files.md | 41 -- src/configuration/initial_scripts.md | 207 +++++++ src/configuration/intro.md | 112 ++-- src/crackmes/ioli/ioli_0x03.md | 6 +- src/crackmes/ioli/ioli_0x04.md | 2 +- src/crackmes/ioli/ioli_0x05.md | 2 +- src/crackmes/ioli/ioli_0x06.md | 6 +- src/crackmes/ioli/ioli_0x07.md | 8 +- src/crackmes/ioli/ioli_0x08.md | 4 +- src/crackmes/ioli/ioli_0x09.md | 2 +- src/debugger/apple.md | 4 +- src/first_steps/basic_debugger_session.md | 2 +- src/plugins/dev.md | 2 +- 20 files changed, 687 insertions(+), 486 deletions(-) delete mode 100644 src/SUMMARY.md create mode 100644 src/configuration/build_variables.md rename src/configuration/{rzpal.png => ecs_palette.png} (100%) delete mode 100644 src/configuration/files.md create mode 100644 src/configuration/initial_scripts.md diff --git a/_quarto.yml b/_quarto.yml index 1ab92229..cc43fbfb 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -37,7 +37,8 @@ book: - src/configuration/intro.md - src/configuration/colors.md - src/configuration/evars.md - - src/configuration/files.md + - src/configuration/initial_scripts.md + - src/configuration/build_variables.md - part: "Basic Commands" chapters: diff --git a/src/SUMMARY.md b/src/SUMMARY.md deleted file mode 100644 index 870ad738..00000000 --- a/src/SUMMARY.md +++ /dev/null @@ -1,138 +0,0 @@ -# Summary - -* [Introduction](README.md) - * [The Framework](first_steps/overview.md) - * [Downloading rizin](first_steps/getting_rizin.md) - * [Compilation and Portability](first_steps/compilation_portability.md) - * [Compilation on Windows](first_steps/windows_compilation.md) - * [Compilation on Android](first_steps/compilation_android.md) -* [First Steps](first_steps/intro.md) - * [Shell Command-line Options](first_steps/commandline_options.md) - * [Rizin Command-line](first_steps/commandline_rizin.md) - * [Expressions](first_steps/expressions.md) - * [Basic Debugger Session](first_steps/basic_debugger_session.md) - * [Contributing to rizin](first_steps/contributing.md) -* [Configuration](configuration/intro.md) - * [Colors](configuration/colors.md) - * [Configuration Variables](configuration/evars.md) - * [Files](configuration/files.md) -* [Basic Commands](basic_commands/intro.md) - * [Seeking](basic_commands/seeking.md) - * [Block Size](basic_commands/block_size.md) - * [Sections](basic_commands/sections.md) - * [Mapping Files](basic_commands/mapping_files.md) - * [Print Modes](basic_commands/print_modes.md) - * [Flags](basic_commands/flags.md) - * [Write](basic_commands/write.md) - * [Zoom](basic_commands/zoom.md) - * [Yank/Paste](basic_commands/yank_paste.md) - * [Comparing Bytes](basic_commands/comparing_bytes.md) - * [SDB](basic_commands/sdb.md) - * [Dietline](basic_commands/dietline.md) -* [Visual mode](visual_mode/intro.md) - * [Visual Disassembly](visual_mode/visual_disassembly.md) - * [Visual Assembler](visual_mode/visual_assembler.md) - * [Visual Configuration Editor](visual_mode/visual_configuration_editor.md) - * [Visual Panels](visual_mode/visual_panels.md) -* [Searching bytes](search_bytes/intro.md) - * [Basic Searches](search_bytes/basic_searches.md) - * [Configurating the Search](search_bytes/configurating_the_search.md) - * [Pattern Search](search_bytes/pattern_search.md) - * [Automation](search_bytes/automation.md) - * [Backward Search](search_bytes/backward_search.md) - * [Search in Assembly](search_bytes/search_in_assembly.md) - * [Searching for AES Keys](search_bytes/searching_aes_keys.md) -* [Disassembling](disassembling/intro.md) - * [Adding Metadata](disassembling/adding_metadata.md) - * [ESIL](disassembling/esil.md) -* [Analysis](analysis/intro.md) - * [Code Analysis](analysis/code_analysis.md) - * [Variables](analysis/variables.md) - * [Types](analysis/types.md) - * [Calling Conventions](analysis/calling_conventions.md) - * [Virtual Tables](analysis/vtables.md) - * [Syscalls](analysis/syscalls.md) - * [Emulation](analysis/emulation.md) - * [Symbols information](analysis/symbols.md) - * [Signatures](signatures/zignatures.md) - * [Graph commands](analysis/graphs.md) - * [CPU and platform profiles](analysis/cpu_platform_profiles.md) -* [Scripting](scripting/intro.md) - * [Loops](scripting/loops.md) - * [Macros](scripting/macros.md) - * [Rz-pipe](scripting/rz-pipe.md) -* [Debugger](debugger/intro.md) - * [Getting Started](debugger/getting_started.md) - * [Migration from ida, GDB or WinDBG](debugger/migration.md) - * [Registers](debugger/registers.md) - * [Memory Maps](debugger/memory_maps.md) - * [Heap](debugger/heap.md) - * [Files](debugger/files.md) - * [Reverse Debugging](debugger/revdebug.md) - * [Windows Messages](debugger/windows_messages.md) - * [macOS/iOS](debugger/apple.md) -* [Remote Access](remote_access/remoting_capabilities.md) - * [Remote GDB](remote_access/remote_gdb.md) - * [Remote WinDbg](remote_access/windbg.md) -* [Command Line Tools](tools/intro.md) - * [Rz-ax](tools/rz-ax/intro.md) - * [Rz-find](tools/rz-find/intro.md) - * [Rz-run](tools/rz-run/intro.md) - * [Rz-bin](tools/rz-bin/intro.md) - * [File Identification](tools/rz-bin/file_identification.md) - * [Entrypoint](tools/rz-bin/entrypoints.md) - * [Imports](tools/rz-bin/imports.md) - * [Exports](tools/rz-bin/exports.md) - * [Symbols (exports)](tools/rz-bin/symbols.md) - * [Libraries](tools/rz-bin/libraries.md) - * [Strings](tools/rz-bin/strings.md) - * [Program Sections](tools/rz-bin/program_sections.md) - * [Rz-diff](tools/rz-diff/intro.md) - * [Binary Diffing](tools/rz-diff/binary_diffing.md) - * [Rz-asm](tools/rz-asm/intro.md) - * [Assemble](tools/rz-asm/assemble.md) - * [Disassemble](tools/rz-asm/disassemble.md) - * [Configuration](tools/rz-asm/config.md) - * [Rz-gg](tools/rz-gg/rz-gg.md) - * [Language](tools/rz-gg/lang.md) - * [Rz-hash](tools/rz-hash/intro.md) - * [Rz-hash Tool](tools/rz-hash/rz-hash_tool.md) - * [Rz-pm](tools/rz-pm/intro.md) -* [Plugins](plugins/intro.md) - * [IO plugins](plugins/ioplugins.md) - * [Asm plugins](plugins/dev-asm.md) - * [Analysis plugins](plugins/dev-analysis.md) - * [Bin plugins](plugins/dev-bin.md) - * [Other plugins](plugins/dev-other.md) - * [Python plugins](plugins/python.md) - * [Debugging](plugins/debug.md) - * [Testing](plugins/testing.md) - * [Packaging](plugins/rz-pm.md) -* [Crackmes](crackmes/intro.md) - * [IOLI](crackmes/ioli/intro.md) - * [IOLI 0x00](crackmes/ioli/ioli_0x00.md) - * [IOLI 0x01](crackmes/ioli/ioli_0x01.md) - * [IOLI 0x02](crackmes/ioli/ioli_0x02.md) - * [IOLI 0x03](crackmes/ioli/ioli_0x03.md) - * [IOLI 0x04](crackmes/ioli/ioli_0x04.md) - * [IOLI 0x05](crackmes/ioli/ioli_0x05.md) - * [IOLI 0x06](crackmes/ioli/ioli_0x06.md) - * [IOLI 0x07](crackmes/ioli/ioli_0x07.md) - * [IOLI 0x08](crackmes/ioli/ioli_0x08.md) - * [IOLI 0x09](crackmes/ioli/ioli_0x09.md) - * [Avatao R3v3rs3 4](crackmes/avatao/01-reverse4/intro.md) - * [.rizin](crackmes/avatao/01-reverse4/rizin.md) - * [.first_steps](crackmes/avatao/01-reverse4/first_steps.md) - * [.main](crackmes/avatao/01-reverse4/main.md) - * [.vmloop](crackmes/avatao/01-reverse4/vmloop.md) - * [.instructionset](crackmes/avatao/01-reverse4/instructionset.md) - * [.bytecode](crackmes/avatao/01-reverse4/bytecode.md) - * [.outro](crackmes/avatao/01-reverse4/outro.md) - * [Hack The Box](crackmes/hackthebox/intro.md) - * [Find The Easy Pass](crackmes/hackthebox/find-the-easy-pass/intro.md) - * [identification](crackmes/hackthebox/find-the-easy-pass/identification.md) - * [find-the-valiation-routine](crackmes/hackthebox/find-the-easy-pass/find-the-validation-routine.md) - * [fire-up-the-debugger](crackmes/hackthebox/find-the-easy-pass/fire-up-the-debugger.md) - * [bonus](crackmes/hackthebox/find-the-easy-pass/bonus.md) -* [Reference Card](refcard/intro.md) -* [Acknowledgments](credits/credits.md) diff --git a/src/basic_commands/mapping_files.md b/src/basic_commands/mapping_files.md index ba96dcbe..973ec2e8 100644 --- a/src/basic_commands/mapping_files.md +++ b/src/basic_commands/mapping_files.md @@ -37,7 +37,7 @@ Usage: o[?] # Open files and handle opened files Prepare a simple layout: -```sh +```bash $ rz-bin -l /bin/ls [Linked libraries] libselinux.so.1 diff --git a/src/configuration/build_variables.md b/src/configuration/build_variables.md new file mode 100644 index 00000000..261cd5ca --- /dev/null +++ b/src/configuration/build_variables.md @@ -0,0 +1,33 @@ +## Build Variables + +When rizin is built from sources, some build variables will be hardcoded within the rizin libraries. + +These build variables can be accessed by executing the command `rizin -H` on a terminal. + +```bash +$ rizin -H +RZ_VERSION=X.Y.Z +RZ_PREFIX=/usr +RZ_EXTRA_PREFIX= +RZ_MAGICPATH=/usr/share/rizin/magic +RZ_INCDIR=/usr/include/librz +RZ_LIBDIR=/usr/lib +RZ_SIGDB=/usr/share/rizin/sigdb +RZ_EXTRA_SIGDB= +RZ_LIBEXT=so +RZ_CONFIGHOME=/home/username/.config/rizin +RZ_DATAHOME=/home/username/.local/share/rizin +RZ_CACHEHOME=/home/username/.cache/rizin +RZ_LIB_PLUGINS=/usr/lib/rizin/plugins +RZ_EXTRA_PLUGINS= +RZ_USER_PLUGINS=/home/username/.local/lib/rizin/plugins +RZ_IS_PORTABLE=0 +``` + +You can also view a specific build variable by executing `-H variable`. + +For example: +```bash +$ rizin -H RZ_USER_PLUGINS +/home/username/.local/lib/rizin/plugins +``` diff --git a/src/configuration/colors.md b/src/configuration/colors.md index 116e8f10..e4717b59 100644 --- a/src/configuration/colors.md +++ b/src/configuration/colors.md @@ -1,32 +1,38 @@ -## Colors +## Colors & Themes -Console access is wrapped in API that permits to show the output of any command as ANSI, W32 Console or HTML formats. This allows rizin's core to run inside environments with limited displaying capabilities, like kernels or embedded devices. It is still possible to receive data from it in your favorite format. +The console access is encapsulated in an API that enables displaying the output of any command in ANSI, W32 Console, or HTML formats. This functionality enables rizin to operate within environments with restricted display capabilities, such as kernels or embedded devices. You can still receive data from it in your preferred format. -To enable colors support by default, add a corresponding configuration option to the .rizin configuration file: -``` -$ echo 'e scr.color=1' >> ~/.rizinrc +The color option is referred to as `scr.color` and can be modified using the `e` command. The `scr.color` option offers support for four values: +- `e scr.color=0`: no colors (black and white) +- `e scr.color=1`: ANSI colors (16 basic ANSI colors) +- `e scr.color=2`: 256 colors (256 scale colors) +- `e scr.color=3`: truecolor (24bit true color) + +To change color support by default, include a corresponding configuration option in the `rizinrc` [initial script](initial_scripts.md). + +For example: + +```bash +# enable truecolor +$ echo "e scr.color=3" >> ~/.rizinrc ``` -Note that enabling colors is not a boolean option. Instead, it is a number because there are different color depth levels. This is: -* 0: black and white -* 1: 16 basic ANSI colors -* 2: 256 scale colors -* 3: 24bit true color +The inclusion of user-defined options is necessary because there is no standardized or portable method for terminal programs to inquire about the console for optimal configurations. This also applies to charset encodings, so Rizin allows manual selection. -The reason for having such user-defined options is because there's no standard or portable way for the terminal programs to query the console to determine the best configuration, same goes for charset encodings, so rizin allows you to choose that by hand. +Typically, serial consoles may function well with options `0` (no colors) or `1` (ANSI), while more moderns terminals might support up to `3` (truecolor). -Usually, serial consoles may work with 0 or 1, while xterms may support up to 3. RCons will try to find the closest color scheme for your theme when you choose a different them with the `eco` command. +Rizin will attempt to discover the closest color scheme for your theme when selecting a theme using the `eco` command. -It is possible to configure the color of almost any element of disassembly output. For *NIX terminals, rizin accepts color specification in RGB format. To change the console color palette use `ec` command. +It is feasible to configure the color of nearly any element in the disassembly output. For UNIX-like terminals, Rizin accepts color specifications in `RGB` format. To alter the console color palette, use the `ec` command. -Type `ec` to get a list of all currently used colors. Type `ecs` to show a color palette to pick colors from: +- Type `ec` to get a list of all currently used colors. +- Type `ecs` to display a color palette to pick colors. +- Type `ecr` to randomize the color palette. -![img](rzpal.png) +![ecs command](ecs_palette.png) ## Themes -You can create your own color theme, but rizin have its own predefined ones. Use the `eco` command to list or select them. - -After selecting one, you can compare between the color scheme of the shell and the current theme by pressing Ctrl-Shift and then right arrow key for the toggle. +You have the option to craft your custom color theme, although Rizin comes with its predefined ones. Utilize the `eco` command to view or choose from them (`eco `). -In visual mode use the `R` key to randomize colors or choose the next theme in the list. +In visual panel mode (command `V`), you can switch themes by pressing `R` (`Shift + R`, or uppercase R). If you enable `scr.randpal` by setting it to `true`, you can randomize the palette similar to what `ecr` does. diff --git a/src/configuration/rzpal.png b/src/configuration/ecs_palette.png similarity index 100% rename from src/configuration/rzpal.png rename to src/configuration/ecs_palette.png diff --git a/src/configuration/evars.md b/src/configuration/evars.md index d3b7d079..847d9051 100644 --- a/src/configuration/evars.md +++ b/src/configuration/evars.md @@ -1,293 +1,425 @@ -## Configuration Variables +## Evaluable Variables -Below is a list of the most frequently used configuration variables. You can get a complete list by issuing `e` command without arguments. For example, to see all variables defined in the "cfg" namespace, issue `e cfg.` (mind the ending dot). You can get help on any eval configuration variable by using `el cfg.` +Rizin incorporates "evaluable variables", which are configuration variables that influence the behavior of analysis, visuals, assembly, and more. -The `el` command to get help on all the evaluable configuration variables of rizin. As long as the output of this command is pretty large you can combine it with the internal grep `~` to filter for what you are looking for: +Below you can find a compilation of the most frequently used configuration variables. -``` -[0x00000000]> el~color - graph.gv.graph: Graphviz global style attributes. (bgcolor=white) - graph.gv.node: Graphviz node style. (color=gray, style=filled shape=box) - log.colors: Should the log output use colors (TODO) +Utilize the `el` command to list all the evaluable variables in Rizin. If the output is extensive, you can narrow it down by combining it with the internal grep `~` to filter for specific information or by appending the sub-space after the command, such as `el cfg`. + +Example: + +```bash +[0x00000000]> el scr.color scr.color: Enable colors (0: none, 1: ansi, 2: 256 colors, 3: truecolor) scr.color.args: Colorize arguments and variables of functions scr.color.bytes: Colorize bytes that represent the opcodes of the instruction scr.color.grep: Enable colors when using ~grep scr.color.ops: Colorize numbers and registers in opcodes scr.color.pipe: Enable colors when using pipes - scr.prompt.mode: Set prompt color based on vi mode - scr.rainbow: Shows rainbow colors depending of address - scr.randpal: Random color palette or just get the next one from 'eco' +[0x00000000]> el* scr.color +e scr.color=3 +e scr.color.args=true +e scr.color.bytes=true +e scr.color.grep=false +e scr.color.ops=true +e scr.color.pipe=false +[0x00000000]> e scr.color=2 ``` -The Visual mode has an eval browser that is accessible through the `Vbe` command. - ## Assembly Configuration -### asm.arch: `string` +This section provides instructions on altering the behavior of the assembler and disassembler. -Defines the target CPU architecture used for disassembling (`pd`, `pD` commands) and code analysis (`a` command). You can find the list of possible values by looking at the result of `e asm.arch=?` or `rz-asm -L`. -It is quite simple to add new architectures for disassembling and analyzing code. There is an interface for that. For x86, it is used to attach a number of third-party disassembler engines, including GNU binutils, Udis86 and a few handmade ones. +### asm.arch: `string` -### asm.bits: `int` +The `asm.arch` configuration variable establishes the target CPU architecture employed for disassembling (`pd`, `pD` commands) and code analysis (`a` command). The list of potential values can be retrieved by examining the output of `e asm.arch=?` or `rz-asm -L`. -Determines width in bits of registers for the current architecture. -Supported values: +Adding new architectures for disassembling and analyzing code is a straightforward process with a dedicated interface. For x86, this interface facilitates the integration of various third-party disassembler engines, such as GNU binutils, Udis86, and a selection of custom ones. -* 8 -* 16 -* 32 -* 64 +### asm.bits: `int` -Note that not all target architectures support all combinations for asm.bits. +The `asm.bits` configuration variable dictates the width in bits of registers for the current architecture. The supported values vary depending on the architecture, and you can explore them by using `rz-asm -L` or `e asm.bits=?`. ### asm.bytes: `bool` -Show or hide displaying of raw bytes of instructions. By default, it is turned off, resulting in a disassembly like: +When `asm.bytes` is set to `true`, it enables the display of raw bytes of instructions. By default, it is turned off, resulting in a disassembly format like shown below. When activated, the raw bytes will be shown alongside the instructions. -``` -[0x00005b20]> e asm.bytes -false -[0x00005b20]> pd 5 - 0x00005b20 endbr64 - 0x00005b24 xor ebp, ebp - 0x00005b26 mov r9, rdx - 0x00005b29 pop rsi - 0x00005b2a mov rdx, rsp -``` -When turned on, the raw bytes will be displayed along with the instructions: -``` -[0x00005b20]> e asm.bytes=true -[0x00005b20]> pd 5 +```bash +# you can disable this also via `e asm.bytes=false` +[0x00005fa0]> pd 5 @e:asm.bytes=false ;-- entry0: - ;-- rip: - 0x00005b20 f30f1efa endbr64 - 0x00005b24 31ed xor ebp, ebp - 0x00005b26 4989d1 mov r9, rdx - 0x00005b29 5e pop rsi - 0x00005b2a 4889e2 mov rdx, rsp + 0x00005fa0 endbr64 + 0x00005fa4 xor ebp, ebp + 0x00005fa6 mov r9, rdx + 0x00005fa9 pop rsi + 0x00005faa mov rdx, rsp +# you can enable this also via `e asm.bytes=true` +[0x00005fa0]> pd 5 @e:asm.bytes=true + ;-- entry0: + 0x00005fa0 f30f1efa endbr64 + 0x00005fa4 31ed xor ebp, ebp + 0x00005fa6 4989d1 mov r9, rdx + 0x00005fa9 5e pop rsi + 0x00005faa 4889e2 mov rdx, rsp ``` ### asm.cpu: `string` -You can use this configuration variable to define the CPU type. For example, if you had picked the architecture as AVR, you can choose your CPU type (ATmega1281, ATmega2561, etc) using `asm.cpu`. +The `asm.cpu` configuration variable enables you to specify the CPU type. For example, if you've chosen the architecture as AVR, you can designate your CPU type (e.g., ATmega1281, ATmega2561, etc.) using `asm.cpu`. To view all available CPU types of the selected architecture, you can use the command `e asm.cpu=?`. ### asm.platform: `string` -You can use this configuration variable to select the platform and it'll load up the corresponding -platform profile during analysis. See the section about [CPU and platform profiles](https://book.rizin.re/analysis/cpu_platform_profiles.html) for more information. +The `asm.platform` configuration variable allows you to choose the platform, and it will load the corresponding platform profile during analysis. Refer to the section about [CPU and platform profiles](../analysis/cpu_platform_profiles.md) for more information. ### asm.flags: `bool` -When set to "true", the disassembler view will have the flags column. +When `asm.flags` is set to `true`, the disassembler view will include the flags column. ### asm.fcn.size: `bool` -This variable is used to display the size of the function in the disassembly. By default, it is set to false and turning it on would result in a disassembly like the one below: - -``` -┌ 44: int main (char **argv); -│ ; var int32_t var_4h @ ebp-0x4 -│ ; arg char **argv @ esp+0x24 -│ 0x000011cd lea ecx, [argv] -│ 0x000011d1 and esp, 0xfffffff0 -``` -Here, `44` is the size of the function. +The `asm.fcn.size` variable is employed to show the size of the function in the disassembly. By default, it is set to false, and enabling it would lead to a disassembly format similar to the one below: + +```bash +# you can enable this also via `e asm.fcn.size=true` +[0x00004050]> pd 10 @e:asm.fcn.size=true + ; DATA XREF from entry0 @ 0x5fb8 +/ 7992: int main(int argc, char **argv, char **envp); +| stack: 31 (vars 31, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc + +``` +Here, `7992` is the size of the function. ### asm.lines.call: `bool` -If set to "true", draw lines at the left of the disassembly output (`pd`, `pD` commands) to graphically represent control flow changes (jumps and calls) that are targeted inside the current block. Also, see `asm.lines.out`. +When `asm.lines.call` is set to `true`, lines are drawn at the left of the disassembly output (`pd`, `pD` commands). These lines graphically represent control flow changes, such as jumps and calls, that are targeted inside the current block. Also, refer to `asm.lines.out`. ### asm.lines.out: `bool` -When set to "true", the disassembly view will also draw control flow lines that go outside of the block. +When `asm.lines.out` is set to `true`, the disassembly view will draw control flow lines that extend beyond the block. ### asm.offset: `bool` -Show or hide offsets for individual disassembled instructions. +The `asm.offset` configuration variable determines whether to show or hide offsets for individual disassembled instructions. ### asm.os: `string` -Selects a target operating system for the currently loaded binary. Usually, OS is automatically detected by Rizin (`rz-bin -rI`). Yet, `asm.os` can be used to switch to a different syscall table employed by another OS. +The `asm.os` configuration variable lets you select a target operating system for the currently loaded binary. Typically, the OS is automatically detected by Rizin (command `i` or via `rz-bin -I /path/to/bin`). However, `asm.os` can be employed to switch to a different syscall table used by another OS. ### asm.pseudo: `bool` -A boolean value to set the pseudo syntax in the disassembly. "False" indicates a native one, defined by the current architecture, "true" activates a pseudocode strings format. For example, it'll transform : +The `asm.pseudo` configuration variable is a boolean value used to set the pseudo syntax in the disassembly. When set to `false`, it indicates a native syntax defined by the current architecture. When set to `true`, it activates a pseudocode strings format; this feature can be beneficial when disassembling obscure architectures. + +```bash +# you can disable this also via `e asm.pseudo=false` +[0x00100508]> pd 10 @e:asm.pseudo=false + ;-- _start: +/ entry0(int64_t arg_18h, int64_t arg_8h, int64_t arg_10h, int64_t arg1, int64_t arg2, int64_t arg4, int64_t arg5); +| ; arg int64_t arg1 @ r3 +| ; arg int64_t arg2 @ r4 +| ; arg int64_t arg4 @ r6 +| ; arg int64_t arg5 @ r7 +| ; var int64_t var_1h @ stack - 0x1 +| ; arg int64_t arg_8h @ stack + 0x8 +| ; arg int64_t arg_10h @ stack + 0x10 +| ; arg int64_t arg_18h @ stack + 0x18 +| 0x00100508 lis r2, 0x1e ; start.S:65 ; 0x1e0000 +| ; sym..iplt +| 0x0010050c addi r2, r2, 0x7c00 +| 0x00100510 mr r9, r1 ; start.S:67 +| 0x00100514 rldicr r1, r1, 0, 0x3b ; start.S:69 +| 0x00100518 li r0, 0 ; start.S:70 +| 0x0010051c stdu r1, -0x80(r1) ; start.S:71 +| 0x00100520 mtlr r0 ; start.S:72 +| 0x00100524 std r0, 0(r1) ; start.S:73 +| 0x00100528 ld r8, -0x7ff0(r2) ; start.S:77 ; 0x194c40 +| ; sym..rodata +| ,=< 0x0010052c b 0x101048 ; start.S:80 +# you can enable this also via `e asm.pseudo=true` +[0x00100508]> pd 10 @e:asm.pseudo=true + ;-- _start: +/ entry0(int64_t arg_18h, int64_t arg_8h, int64_t arg_10h, int64_t arg1, int64_t arg2, int64_t arg4, int64_t arg5); +| ; arg int64_t arg1 @ r3 +| ; arg int64_t arg2 @ r4 +| ; arg int64_t arg4 @ r6 +| ; arg int64_t arg5 @ r7 +| ; var int64_t var_1h @ stack - 0x1 +| ; arg int64_t arg_8h @ stack + 0x8 +| ; arg int64_t arg_10h @ stack + 0x10 +| ; arg int64_t arg_18h @ stack + 0x18 +| 0x00100508 r2 = (0x1e << 16) ; start.S:65 ; 0x1e0000 +| ; sym..iplt +| 0x0010050c r2 += 0x7c00 +| 0x00100510 r9 = r1 ; start.S:67 +| 0x00100514 r1 = rol64(r1, 0) & 0x1f ; start.S:69 +| 0x00100518 r0 = 0 ; start.S:70 +| 0x0010051c [r1 - 0x80] = r1 ; start.S:71 +| 0x00100520 lr = r0 ; start.S:72 +| 0x00100524 [r1 + 0] = r0 ; start.S:73 +| 0x00100528 r8 = [r2 - 0x7ff0] ; start.S:77 ; 0x194c40 +| ; sym..rodata +| ,=< 0x0010052c goto 0x101048 ; start.S:80 ``` -│ 0x080483ff e832000000 call 0x8048436 -│ 0x08048404 31c0 xor eax, eax -│ 0x08048406 0205849a0408 add al, byte [0x8049a84] -│ 0x0804840c 83f800 cmp eax, 0 -│ 0x0804840f 7405 je 0x8048416 -``` -to - -``` -│ 0x080483ff e832000000 0x8048436 () -│ 0x08048404 31c0 eax = 0 -│ 0x08048406 0205849a0408 al += byte [0x8049a84] -│ 0x0804840c 83f800 var = eax - 0 -│ 0x0804840f 7405 if (!var) goto 0x8048416 -``` -It can be useful while disassembling obscure architectures. ### asm.sub.jmp: `bool` -Substitute jump, call and branch targets with function names in the disassembly. - -For example, when turned on, it'd display `jal 0x80001a40` as `jal fcn.80001a40` in the disassembly. +The `asm.sub.jmp` configuration variable substitutes jump, call, and branch targets with function names in the disassembly. For instance, when activated, it would display `jal 0x80001a40` as `jal fcn.80001a40` in the disassembly. ### asm.sub.reg: `bool` -Replace register names with arguments or their associated role alias. +asm.sub.reg Replace register names with arguments or their associated role alias. For example, if you have something like this: -``` -│ 0x080483ea 83c404 add esp, 4 -│ 0x080483ed 68989a0408 push 0x8049a98 -│ 0x080483f7 e870060000 call sym.imp.scanf -│ 0x080483fc 83c408 add esp, 8 -│ 0x08048404 31c0 xor eax, eax -``` -This variable changes it to: -``` -│ 0x080483ea 83c404 add SP, 4 -│ 0x080483ed 68989a0408 push 0x8049a98 -│ 0x080483f7 e870060000 call sym.imp.scanf -│ 0x080483fc 83c408 add SP, 8 -│ 0x08048404 31c0 xor A0, A0 +```bash +[0x00004050]> pd 4 @e:asm.sub.reg=false + ; DATA XREF from entry0 @ 0x5fb8 + ; DATA XREF from fcn.00015be0 @ 0x17078 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc +[0x00004050]> pd 4 @e:asm.sub.reg=true + ; DATA XREF from entry0 @ 0x5fb8 + ; DATA XREF from fcn.00015be0 @ 0x17078 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x0000405d push rbx +| 0x0000405e sub SP, 0xf8 +| 0x00004065 mov rbx, qword [A1] ; argv +| 0x00004068 mov dword [var_118h], A0 ; argc + ``` ### asm.sub.rel: `bool` -A boolean value that substitutes expressions relative to the Program Counter in the disassembly. When turned on, it shows the references as string references. - -For example: - -``` -0x5563844a0181 488d3d7c0e00. lea rdi, [rip + 0xe7c] ; str.argv__2d_:__s -``` -When turned on, this variable lets you display the above instruction as: +The `asm.sub.rel` configuration variable, when set to true, substitutes expressions relative to the Program Counter in the disassembly. When activated, it displays the references as string references. -``` -0x5563844a0181 488d3d7c0e00. lea rdi, str.argv__2d_:__s ; 0x5563844a1004 ; "argv[%2d]: %s\n" +```bash +[0x00004050]> pd 30 @e:asm.sub.rel=false ~lea +| ||| 0x000040bb lea rsi, [rip + 0x15f51] ; str..libs +[0x00004050]> pd 30 @e:asm.sub.rel=true ~lea +| ||| 0x000040bb lea rsi, str..libs ; 0x1a013 ; "/.libs/" ; const char *s2 ``` ### asm.sub.section: `bool` -Prefix offsets in the disassembly with the name of the section or map. - -That means, from something like: +The `asm.sub.section` configuration variable, when set, prefixes offsets in the disassembly with the name of the section or map. -``` +```bash +[0x00004050]> pd 30 @e:asm.sub.rel=false ~lea 0x000067ea 488d0def0c01. lea rcx, [0x000174e0] -``` -to the one below, when toggled on. -``` +[0x00004050]> pd 30 @e:asm.sub.rel=true ~lea 0x000067ea 488d0def0c01. lea rcx, [fmap.LOAD1.0x000174e0] ``` ### asm.sub.varonly: `bool` -Substitutes the variable expression with the local variable name. - -For example: `var_14h` as `rbp - var_14h`, in the disassembly. +The `asm.sub.varonly` configuration variable, when enabled, substitutes the variable expression with the local variable name. For instance, it would display `var_118h` as `rsp + var_118h` in the disassembly. + +```bash +[0x00004050]> pd 10 @e:asm.sub.varonly=false + ; DATA XREF from entry0 @ 0x5fb8 + ; DATA XREF from fcn.00015be0 @ 0x17078 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [rsp + var_118h], edi ; argc +[0x00004050]> pd 10 @e:asm.sub.varonly=true + ; DATA XREF from entry0 @ 0x5fb8 + ; DATA XREF from fcn.00015be0 @ 0x17078 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc +``` ### asm.syntax: `string` -Changes syntax flavor for disassembler between Intel and AT&T. At the moment, this setting affects Udis86 disassembler for Intel 32/Intel 64 targets only. Supported values are `intel` and `att`. +The `asm.syntax` configuration variable enables you to change the syntax flavor for disassembler syntax. Supported values can be queried using `e asm.syntax=?`. + +```bash +[0x00004050]> pd 10 @e:asm.syntax=att + ; DATA XREF from entry0 @ 0x5fb8 + ; DATA XREF from fcn.00015be0 @ 0x17078 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 pushq %r15 +| 0x00004056 pushq %r14 +| 0x00004058 pushq %r13 +| 0x0000405a pushq %r12 +| 0x0000405c pushq %rbp +| 0x0000405d pushq %rbx +| 0x0000405e subq $0xf8, %rsp +| 0x00004065 movq (%rsi), %rbx ; argv +| 0x00004068 movl %edi, var_118h ; argc +[0x00004050]> pd 10 @e:asm.syntax=masm + ; DATA XREF from entry0 @ 0x5fb8 + ; DATA XREF from fcn.00015be0 @ 0x17078 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0f8h +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc +[0x00004050]> pd 10 @e:asm.syntax=intel + ; DATA XREF from entry0 @ 0x5fb8 + ; DATA XREF from fcn.00015be0 @ 0x17078 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc +``` ### asm.tabs: `int` -If your disassembly doesn't fit in your screen or aligns clumsily, `asm.tabs` might be of help. You can use this variable to control the distance between the operands, by setting the number of spaces, while displaying your disassembly. +If the disassembly output doesn't fit on your screen or appears awkwardly aligned, `asm.tabs` can be helpful. You can adjust the spacing between operands by setting the number of spaces while displaying your disassembly using this variable. + +For example: + +```bash +[0x00004050]> pd 10 @e:asm.tabs=0 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc +[0x00004050]> pd 10 @e:asm.tabs=6 +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc -For example, this is the disassembly with the variable set to 0: -``` -[0x000040a7]> e asm.tabs=0 -[0x000040a7]> pd 6 -│ 0x000040a7 push rsp -│ 0x000040a8 mov r12d, edi ; argc -│ 0x000040ab push rbp -│ 0x000040ac mov rbp, rsi ; argv -│ 0x000040af push rbx -│ 0x000040b0 sub rsp, 0x48 -``` -And here's what it would look like after setting it to 6: -``` -[0x000040a7]> e asm.tabs=6 -[0x000040a7]> pd 6 -│ 0x000040a7 push rsp -│ 0x000040a8 mov r12d, edi ; argc -│ 0x000040ab push rbp -│ 0x000040ac mov rbp, rsi ; argv -│ 0x000040af push rbx -│ 0x000040b0 sub rsp, 0x48 ``` ### asm.tabs.once: `bool` -This is a boolean variable that can be set to true if you want to align only the opcodes, excluding the arguments. This makes sense only if you have set `asm.tabs` on. +`asm.tabs.once` represents a boolean variable, which can be configured as true if the alignment is desired solely for opcodes, omitting the arguments. This configuration is meaningful only when `asm.tabs` has been previously enabled. + +```bash +[0x00004050]> pd 10 @e:asm.tabs=10 @e:asm.tabs.once=false +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc +[0x00004050]> pd 10 @e:asm.tabs=10 @e:asm.tabs.once=true +/ int main(int argc, char **argv, char **envp); +| stack: 29 (vars 29, args 0) +| rg: 2 (vars 0, args 2) +| 0x00004050 endbr64 +| 0x00004054 push r15 +| 0x00004056 push r14 +| 0x00004058 push r13 +| 0x0000405a push r12 +| 0x0000405c push rbp +| 0x0000405d push rbx +| 0x0000405e sub rsp, 0xf8 +| 0x00004065 mov rbx, qword [rsi] ; argv +| 0x00004068 mov dword [var_118h], edi ; argc -``` -[0x00008290]> e asm.tabs=6 -[0x00008290]> e asm.tabs.once=false -[0x00008290]> pd 10 -│ 0x00008290 mov ip, sp -│ 0x00008294 push {r4, fp, ip, lr, pc} -│ 0x00008298 sub fp, ip, 4 -│ 0x0000829c sub sp, sp, 0x24 -│ 0x000082a0 str r0, [fp, -0x28] -│ 0x000082a4 str r1, [fp, -0x2c] -│ 0x000082a8 ldr r3, [fp, -0x28] -│ 0x000082ac cmp r3, 1 -│ ┌─< 0x000082b0 bgt 0x82c0 -│ │ 0x000082b4 mvn r3, 0 -``` -In the above example, the opcodes and the operands are aligned. Now, turning it on would align only the opcodes. -``` -[0x00008290]> e asm.tabs.once=true -[0x00008290]> pd 10 -│ 0x00008290 mov ip, sp -│ 0x00008294 push {r4, fp, ip, lr, pc} -│ 0x00008298 sub fp, ip, 4 -│ 0x0000829c sub sp, sp, 0x24 -│ 0x000082a0 str r0, [var_28h] -│ 0x000082a4 str r1, [var_2ch] -│ 0x000082a8 ldr r3, [var_28h] -│ 0x000082ac cmp r3, 1 -│ ┌─< 0x000082b0 bgt 0x82c0 -│ │ 0x000082b4 mvn r3, 0 ``` ### asm.trace: `bool` -A boolean value that controls displaying of tracing information (sequence number and counter) at the left of each opcode. It is used to assist with programs trace analysis. +`asm.trace` is a boolean parameter governing the display of tracing details (sequence number and counter) adjacent to each opcode. Its purpose is to aid in the analysis of program traces. ## Debug Configuration ### dbg.follow.child: `bool` -This variable lets you follow the child process, when a fork (system call) is encountered during debugging. By default, it is set to `false` and the parent process is traced. +The variable `dbg.follow.child` allows tracking the child process when encountering a fork (system call) during debugging. Its default setting is `false`, causing the parent process to be traced. ## Screen Configuration ### scr.color: `int` -This variable specifies the mode for colorized screen output. - -* `0` means no colors. -* `1` means 16-colors mode. -* `2` means 256-colors mode. -* `3` means 16 million-colors mode. +The variable `scr.color` designates the mode for displaying colorized output on the screen. -If your favorite theme looks weird, try to bump this up. +* `0` no colors (black and white) +* `1` ANSI colors (16 basic ANSI colors) +* `2` 256 colors (256 scale colors) +* `3` truecolor (24bit true color) ### scr.visual.mode: `int` -`scr.visual.mode` lets you set a default view for the visual mode. The variable -accepts an integer as its value and it gets mapped to the following modes: +The variable `scr.visual.mode` enables the configuration of a default view for the visual mode. This variable accepts an integer value, which corresponds to the following modes: * `0` - Hexadecimal view * `1` - Disassembly view @@ -295,32 +427,31 @@ accepts an integer as its value and it gets mapped to the following modes: * `3` - Color blocks (entropy) * `4` - Print in string format -So, if you want to have the disassembly view everytime you open up visual mode, you can -have `e scr.visual.mode=1` put on your `~/.rizinrc`. +For instance, if you prefer the disassembly view every time you initiate visual mode, you can include `e scr.visual.mode=1` in your `rizinrc` [initial script](initial_scripts.md). ### scr.seek: `string` -This variable accepts a full-featured expression or a pointer/flag (eg. eip). If set, rizin will set seek position to its value on startup. +The variable `scr.seek` can be assigned a full-featured expression or a pointer/flag (e.g., `eip`). When configured, Rizin will initialize the seek position to the specified value upon startup. ### scr.scrollbar: `bool` -If you have set up any [flagzones](http://book.rada.re/basic_commands/flags.html#flag-zones) (`fz?`), this variable will let you display the scrollbar with the flagzones, in Visual mode. Set it to `1` to display the scrollbar at the right end, `2` for the top and `3` to display it at the bottom. +When you have configured any [flagzones](http://book.rada.re/basic_commands/flags.html#flag-zones) (`fz?`), the `scr.scrollbar` variable facilitates the display of the scrollbar alongside the flagzones in Visual mode. Set it to `1` for displaying the scrollbar at the right end, `2` for the top, and `3` to position it at the bottom. ### scr.utf8: `bool` -Show UTF-8 characters instead of ANSI. +The variable `scr.utf8` toggles the display of UTF-8 characters instead of ANSI characters. ### scr.utf8.curvy: `bool` -This variable lets you display curved corners in places like function graphs. This variable requires `scr.utf8` to be turned on. +The `scr.utf8.curvy` variable enables the presentation of curved corners in locations such as function graphs. It is dependent on having the `scr.utf8` setting activated. -``` +```bash [0x0000415c]> pd 4 │ 0x0000415c cmp eax, 2 │ ┌─< 0x0000415f je 0x5001 │ │ 0x00004165 cmp eax, 3 │ ┌──< 0x00004168 jne 0x4348 -[0x0000415c]> e scr.utf8.curvy=1 +[0x0000415c]> e scr.utf8.curvy=true [0x0000415c]> pd 4 │ 0x0000415c cmp eax, 2 │ ╭─< 0x0000415f je 0x5001 @@ -330,67 +461,63 @@ This variable lets you display curved corners in places like function graphs. Th ### scr.wheel: `bool` -This variable lets you enable the mouse in Visual mode. Turning this variable on will be useful when you want to use your mouse to scroll through your disassembly or copy something in the Visual mode. +The `scr.wheel` variable permits the activation of the mouse in Visual mode. Enabling this variable proves beneficial when you wish to utilize your mouse for scrolling through disassembly or copying content in Visual mode. ## General Configuration ### cfg.bigendian: `bool` -Change endianness. "true" means big-endian, "false" is for little-endian. -"file.id" and "file.flag" both to be true. +The `cfg.bigendian` setting alters the endianness, where "true" indicates big-endian, and "false" corresponds to little-endian. ### cfg.fortunes: `bool` -Enables or disables "fortune" messages displayed at each rizin start. +The `cfg.fortunes` option allows you to enable or disable the display of "fortune" messages that appear at each Rizin start. ### cfg.fortunes.file: `string` -Rizin has two types for fortunes: tips and fun. Fortunes of the type 'tips' are general tips to help you use Rizin better, whereas the other one prints some lighthearted jokes. You can choose which type of fortune to display, using this variable. +Rizin offers two categories of fortunes: `tips` and `fun`. Fortunes categorized as `tips` provide general advice to enhance your usage of Rizin, while the other category offers lighthearted jokes. You can specify the type of fortune to display by utilizing the `cfg.fortunes.file` variable. -``` -[0x00000000]> e cfg.fortunes.file=tips -[0x00000000]> fo - -- Bindiff two files with '$ rz_diff /bin/true /bin/false' -[0x00000000]> e cfg.fortunes.file=fun -[0x00000000]> fo - -- Welcome to "IDA - the roguelike" +```bash +[0x00000000]> fortune @e:cfg.fortunes.file=tips + -- Interpret rizin scripts with '. '. Similar to the bash source alias command. +[0x00000000]> fortune @e:cfg.fortunes.file=fun + -- For a full list of commands see `strings /dev/urandom` [0x00000000]> ``` -Rizin also supports custom fortunes. You can save your fortunes in a file and provide the relative or absolute path to the same variable, to have them displayed at the startup. -``` -[0x00000000]> e cfg.fortunes.file=/path/to/my/fortunes.txt +Rizin additionally supports custom fortunes. You can store your own fortunes in a file and then specify the relative or absolute path to that file using the same variable. This allows your custom fortunes to be displayed at startup. + +```bash +[0x00000000]> fortune @e:cfg.fortunes.file=/path/to/my/fortunes.txt ``` -Please make sure that you add these in your `~/.rizinrc` to preserve the changes when you reopen rizin. +Ensure to include these configurations in your `rizinrc` file to retain the changes when reopening Rizin. ### cfg.newtab: `bool` -If this variable is enabled, help messages will be displayed along with command names in tab completion for commands. +Enabling the `cfg.newtab` variable results in the display of help messages alongside command names during tab completion for commands. ## Stack Configuration ### stack.size: `int` -This variable lets you set the size of stack in bytes. +The `stack.size` variable allows you to define the size of the stack hexdump in visual debug, specified in bytes. ## Command Configuration ## cmd.repeat: `bool` -Sometimes, you may need to run the same command repeatedly and that is what `cmd.repeat` is for. When set to `true`, pressing Return key (Enter key) will run the previous command again. +At times, you might find the need to execute a particular command repeatedly, and that's where `cmd.repeat` comes into play. When configured as `true`, pressing the Return key (Enter key) will rerun the previous command. This may alter the current offset. For example: -``` +```bash [0x00005bc0]> e cmd.repeat=true [0x00005bc0]> pd 2 ;-- entry.fini0: 0x00005bc0 endbr64 0x00005bc4 cmp byte [0x000232c8], 0 -``` -When turned on, you'd just need to press Enter key to run `pd 2` -``` -[0x00005bc0]> +[0x00005bc4]> 0x00005bce cmp qword [reloc.__cxa_finalize], 0 0x00005bd6 mov rbp, rsp +[0x00005bd6]> ``` diff --git a/src/configuration/files.md b/src/configuration/files.md deleted file mode 100644 index 19f04e1d..00000000 --- a/src/configuration/files.md +++ /dev/null @@ -1,41 +0,0 @@ -## Files - -Use `rizin -H` to list all the environment variables that matter to know where it will -be looking for files. Those paths depend on the way (and operating system) you have -built rizin for. - -``` -RZ_PREFIX=/usr -MAGICPATH=/usr/share/rizin/2.8.0-git/magic -PREFIX=/usr -INCDIR=/usr/include/libr -LIBDIR=/usr/lib64 -LIBEXT=so -RCONFIGHOME=/home/user/.config/rizin -RDATAHOME=/home/user/.local/share/rizin -RCACHEHOME=/home/user/.cache/rizin -LIBR_PLUGINS=/usr/lib/rizin/2.8.0-git -USER_PLUGINS=/home/user/.local/share/rizin/plugins -USER_ZIGNS=/home/user/.local/share/rizin/zigns -``` - -## RC Files - -RC files are rizin scripts that are loaded at startup time. Those files must be in 3 different places: - -### System - -rizin will first try to load /usr/share/rizin/rizinrc - -### Your Home - -Each user in the system can have its own rizin scripts to run on startup to select the color scheme, and other custom options by having rizin commands in there. - -* ~/.rizinrc -* ~/.config/rizin/rizinrc -* ~/.config/rizin/rizinrc.d/ - -### Target file - -If you want to run a script every time you open a file, just create a file with the same name of the file -but appending `.rz` to it. diff --git a/src/configuration/initial_scripts.md b/src/configuration/initial_scripts.md new file mode 100644 index 00000000..a0c55e78 --- /dev/null +++ b/src/configuration/initial_scripts.md @@ -0,0 +1,207 @@ +## Initial Scripts + +Initial scripts like the `rizinrc`, `binrc` or `${filename}.rz` are loaded during startup. + +It is possible to prevent Rizin from parsing the scripts, by using the `-N` or `-NN` options. + +These scripts are interpreted as commands by the Rizin command-line and can be situated in the following locations: + +1. **System directory** (also named as `system` within `rizin -hh`): This location is situated within the system and will be loaded by all users of the system. +2. **User home directory** (also named as `user` within `rizin -hh`): This location is user-specific and will be loaded exclusively for the individual user. +3. **Binary format directory** (also named as `binrc` within `rizin -hh`): This location is user-specific and will be loaded exclusively for the individual user; These scripts will be executed when the matching type of binary is loaded when executing rizin. +4. **Initial binary script** (also named as `file` within `rizin -hh`): When Rizin encounters a script with the same filename as the binary, along with a `.rz` extension, it is loaded and executed. Rizin will display a prompt (unless interactive mode is disabled) upon loading the binary. + +The actual paths of these directories depend on the environment, build flags, and operating system, but they can be viewed by executing `rizin -hh` (with double `h`) in the terminal. + +**Note**: You can also override the `rizinrc` path within the terminal by setting the `RZ_RCFILE` environment variable before executing `rizin`. + +### Examples of `rizinrc` scripts + +Here's a demonstration of loading an `rizinrc` file in various environments. + +These examples will show the content of the `rizinrc` file and their output upon executing `rizin`. + +Please note that `clippy` is a command within the Rizin command-line, and executing it will produce a message on the terminal. + +- Example of `rizinrc` within **linux**, **macOS** (or any UNIX-like environements). + +```bash +$ cat ~/.rizinrc +clippy 'This is executed from $HOME/.rizinrc' +$ rizin + .--. .--------------------------------------. + | \ | | + | O o < This is executed from $HOME/.rizinrc | + | | / | | + | ( / `--------------------------------------' + | / + `--' +[0x00000000]> q +$ cat some/folder/myrizinrc +clippy 'This is executed elsewhere' +$ export RZ_RCFILE="some/folder/myrizinrc" +$ rizin + .--. .----------------------------. + | _|_ | | + | O O < This is executed elsewhere | + | || | | + | _:| `----------------------------' + | | + `---' +[0x00000000]> q +``` + +- Example of `rizinrc` within **Windows**. + +```bash +C:\Users\user\Desktop\rizin> type %HOME%\.rizinrc +clippy 'This is executed from %HOME%/.rizinrc' +C:\Users\user\Desktop\rizin> rizin.exe + .--. .---------------------------------------. + | \ | | + | O o < This is executed from %HOME%/.rizinrc | + | | / | | + | ( / `---------------------------------------' + | / + `--' +[0x00000000]> q +C:\Users\user\Desktop\rizin> type some\folder\myrizinrc +clippy 'This is executed elsewhere' +C:\Users\user\Desktop\rizin> set RZ_RCFILE="some\folder\\myrizinrc" +C:\Users\user\Desktop\rizin> rizin.exe + .--. .----------------------------. + | _|_ | | + | O O < This is executed elsewhere | + | || | | + | _:| `----------------------------' + | | + `---' +[0x00000000]> q +``` + +### Example of initial binary script + +Here's a demonstration of loading an initial Rizin script in the same directory as the binary. As previously mentioned, the script's filename must match that of the original binary, with the addition of the `.rz` extension. In this instance, the binary is named `firmware.bin`, and the accompanying script is named `firmware.bin.rz`. Upon execution, `firmware.bin.rz` will display information about the binary and proceed to disassemble the initial 10 instructions. + +Please note that `clippy` is a command within the Rizin command-line, and executing it will produce a message on the terminal. + +```bash +$ ls +firmware.bin firmware.bin.rz +$ cat firmware.bin.rz +clippy 'This is executed at start' +# show bin info +i +# print the first 10 instructions +pd 10 +$ rizin firmware.bin +Do you want to run the 'firmware.bin.rz' script? (y/N) y + .--. .---------------------------. + | _|_ | | + | O O < This is executed at start | + | || | | + | _:| `---------------------------' + | | + `---' +fd 3 +file firmware.bin +size 0x3722 +humansz 13.8K +mode r-x +format avr +iorw false +block 0x100 +type ROM +arch avr +cpu N/A +baddr ---------- +binsz 0x00003722 +bintype N/A +bits 8 +retguard false +class N/A +compiler N/A +dbg_file N/A +endian LE +hdr.csum N/A +guid N/A +intrp N/A +laddr 0x00000000 +lang N/A +machine ATmel +maxopsz 4 +minopsz 2 +os avr +cc N/A +pcalign 2 +rpath N/A +subsys +stripped false +crypto false +havecode true +va false +sanitiz false +static true +linenum false +lsyms false +canary false +PIE false +RELROCS false +NX false + ;-- entry0: + 0x00000158 clr r1 + 0x0000015a out SREG, r1 + 0x0000015c ser r28 + 0x0000015e ldi r29, 0x10 + 0x00000160 out SPH, r29 + 0x00000162 out SPL, r28 + 0x00000164 ldi r17, 0x02 + 0x00000166 ldi r26, 0x00 + 0x00000168 ldi r27, 0x01 + 0x0000016a ldi r30, 0xfe + -- Add colors to your screen with 'e scr.color=X' where 1 is 16 colors, 2 is 256 colors and 3 is 16M colors +[0x00000158]> +``` + +### Example of `binrc` scripts + +Here's an example of loading a `binrc` file in a Linux environment (applicable elsewhere too). + +The provided example showcase the content of the `binrc` file and the resulting output when executing `rizin`. + +Make sure the script is stored within the `bin-` directory, where `` match the output of the `i~format` Rizin command. + +Please note that `clippy` is a command within the Rizin command-line, and executing it will produce a message on the terminal and `-e log.level=2` increments the verbosity of the rizin logs. + +```bash +$ cat ~/.local/share/rizin/rc.d/bin-elf64/myscript-for-elf64.rz +clippy 'This is executed only for ELF64 format' +$ cat ~/.local/share/rizin/rc.d/bin-pe/myscript-for-pe.rz +clippy 'This is executed only for PE format' +$ rizin -e log.level=2 example.elf64 +INFO: [binrc] path: '/home/username/.local/share/rizin/rc.d/bin-elf64' +INFO: [binrc] loading 'myscript-for-elf64.rz' + .--. .----------------------------------------. + | _|_ | | + | O O < This is executed only for ELF64 format | + | || | | + | _:| `----------------------------------------' + | | + `---' +[0x00005fa0]> i~format +format elf64 +[0x00005fa0]> q +$ rizin -e log.level=2 example.exe +INFO: [binrc] path: '/home/username/.local/share/rizin/rc.d/bin-pe' +INFO: [binrc] loading 'myscript-for-pe.rz' + .--. .-------------------------------------. + | \ | | + | O o < This is executed only for PE format | + | | / | | + | ( / `-------------------------------------' + | / + `--' +[0x00005fa0]> i~format +format pe +[0x00401260]> q +``` diff --git a/src/configuration/intro.md b/src/configuration/intro.md index 5d48dbdc..4f490c16 100644 --- a/src/configuration/intro.md +++ b/src/configuration/intro.md @@ -1,74 +1,80 @@ -# Configuration +## Introduction -The core reads `~/.config/rizin/rizinrc` while starting. You can add `e` commands to this file to tune the rizin configuration to your taste. +This chapter provides instructions on configuring and customizing Rizin to meet your preferences. -To prevent rizin from parsing this file at startup, pass it the `-N` option. +During the startup, Rizin loads an [initial script](initial_scripts.md) called `rizinrc`. Within this file, it is possible to incorporate configuration commands (`e` commands) to customize the tool. -All the configuration of rizin is done with the `eval` commands. A typical startup configuration file looks like this: -```sh +All the configuration adjustments in Rizin are made through the use of `e` commands. A standard startup configuration file often resembles the following: + +```bash $ cat ~/.rizinrc -e scr.color=1 -e dbg.bep = loader +# enable colors +e scr.color=2 +# enable utf8 output +e scr.utf8=true +e scr.utf8.curvy=true +# change color theme to nord +eco nord ``` -The configuration can also be changed with `-e` command-line option. This way you can adjust configuration from the command line, keeping the .rizinrc file intact. For example, to start with empty configuration and then adjust `scr.color` and `asm.syntax` the following line may be used: -```sh + +Configuration adjustments can also be made using the `-e option=value` command-line option. This allows you to modify configurations from the command line while keeping the `rizinrc` file unchanged. For instance, to initiate Rizin with an empty configuration and subsequently modify `scr.color` and `asm.syntax`, the following line can be employed: + +```bash $ rizin -N -e scr.color=1 -e asm.syntax=intel -d /bin/ls ``` -Internally, the configuration is stored in a hash table. The variables are grouped in namespaces: `cfg.`, `file.`, `dbg.`, `scr.` and so on. -To get a list of all configuration variables just type `e` in the command line -prompt. To limit the output to a selected namespace, pass it with an ending dot to `e`. For example, `e file.` will display all variables defined inside the "file" namespace. +The evaluable variables are named using namespaces, such as `cfg.`, `file.`, `dbg.`, `scr.`, and others. -To get help about `e` command type `e?`: +To obtain a list of all configuration variables, enter `el` in the command line prompt. If you want to filter the output by a specific namespace, append the namespace to `el`. For example, `el file` will display all evaluable variables starting with the `file` prefix. -``` +For configuration values that can assume one of several options, you can employ the `=?` operator to obtain a list of valid values. + +For guidance on the `e` command, refer to `e?`. + +```bash [0x00000000]> e? Usage: e[?] # List/get/set config evaluable vars | e [=] [[=] ...]] # Get/Set value of config variable | el[j*qlJ] [] # List config variables with their descriptions | e- # Reset config variables -| e! # Invert the boolean value of config variable -| ec[?] # Set color for given key (prompt, offset, ...) -| ee # Open editor to change the value of config variable -| ed # Open editor to change ~/.rizinrc -| er # Set config variable as read-only +| e! # Invert the boolean value of config variable +| ec[?] # Set color for given key (prompt, offset, ...) (see ec?? for more details) +| ee # Open editor to change the value of config variable +| er # Set config variable as read-only | es [] # List all config variable spaces or sub-keys/sub-spaces if a is provided -| et # Show type of given config variable -| env [[=]] # Get/set environment variables +| et # Show type of given config variable +[0x00000000]> el file + file.info: RzBin info loaded + file.lastpath: Path of current file + file.loadalign: Alignment of load addresses + file.offset: Offset where the file will be mapped at + file.openmany: Maximum number of files opened at once + file.path: Path of current file + file.type: Type of current file +[0x00000000]> e scr.nkey=? +fun +hit +flag ``` -A simpler alternative to the `e` command is accessible from the visual mode. Type `Ve` to enter it, use arrows (up, down, left, right) to navigate the configuration, and `q` to exit it. The start screen for the visual configuration edit looks like this: +A more straightforward alternative to the `e` command is available in visual mode. Type `Ve` to enter this mode, utilize arrow keys (up, down, left, right) for navigation through the configuration, and press `q` to exit. The initial screen for the visual configuration edit appears as follows: -``` +```bash [EvalSpace] - - > analysis - asm - bin - cfg - cmd - dbg - diff - dir - emu - esil - file - graph - hex - http - hud - io - key - log - magic - pdb - ... -``` - -For configuration values that can take one of several values, you can use the `=?` operator to get a list -of valid values: - -``` -[0x00000000]> e scr.nkey=? -scr.nkey = fun, hit, flag + > analysis + asm + basefind + bin + cfg + cmd + dbg + diff + dir + elf + emu + esil + file + flirt + graph + ... ``` diff --git a/src/crackmes/ioli/ioli_0x03.md b/src/crackmes/ioli/ioli_0x03.md index 5a616ae4..fbbb0b25 100644 --- a/src/crackmes/ioli/ioli_0x03.md +++ b/src/crackmes/ioli/ioli_0x03.md @@ -55,7 +55,7 @@ int32_t main (void) { Here comes the`sym.test`, called with two parameters. One is var_4h (our input from `scanf()`). The other is var_ch. The value of var_ch (as the parameter of `test()`) can be calculated like it did in crackme_0x02. It's 0x52b24. Try it! -```sh +```bash ./crackme0x03 IOLI Crackme Level 0x03 Password: 338724 @@ -137,7 +137,7 @@ print(''.join([chr(ord(i)-0x3) for i in 'LqydolgSdvvzrug$'])) the easier way is to `run` the decryption code, that means debug it or emulate it. I used rizin ESIL emulator but it got stuck when executed ` call dword imp.strlen`. And I can't find the usage of hooking function / skip instruction in rizin. The following is an example to show u how to emulate ESIL. -```sh +```bash [0x08048414]> s 0x08048445 # the 'sub al, 0x03' [0x08048445]> aei # init VM [0x08048445]> aeim # init memory @@ -182,7 +182,7 @@ dead at 0x00000000 By the way, you can also open the file and use write data command to decrypt data. -```sh +```bash rizin -w ./crackme0x03 [0x08048360]> aaa [0x08048360]> fs strings diff --git a/src/crackmes/ioli/ioli_0x04.md b/src/crackmes/ioli/ioli_0x04.md index d77f8ecc..f786495a 100644 --- a/src/crackmes/ioli/ioli_0x04.md +++ b/src/crackmes/ioli/ioli_0x04.md @@ -94,7 +94,7 @@ int32_t check(char *s) In short, it calculates the Digit Sum of a number (add a number digit by digit. for example, 96 => 9 + 6 = 15) : -```sh +```bash ./crackme0x04 IOLI Crackme Level 0x04 Password: 12345 diff --git a/src/crackmes/ioli/ioli_0x05.md b/src/crackmes/ioli/ioli_0x05.md index 605267f9..fd84b439 100644 --- a/src/crackmes/ioli/ioli_0x05.md +++ b/src/crackmes/ioli/ioli_0x05.md @@ -162,7 +162,7 @@ Now there are 2 constraints: The password is at our fingertips now. -```sh +```bash ./crackme0x05 IOLI Crackme Level 0x05 Password: 88 diff --git a/src/crackmes/ioli/ioli_0x06.md b/src/crackmes/ioli/ioli_0x06.md index 6f65e603..52ba6d4e 100644 --- a/src/crackmes/ioli/ioli_0x06.md +++ b/src/crackmes/ioli/ioli_0x06.md @@ -3,7 +3,7 @@ IOLI 0x06 nearly a routine to check this binary (not complete output in the following): -```shell +```bash rz-bin -z ./crackme0x06 [Strings] nth paddr vaddr len size section type string @@ -65,7 +65,7 @@ int32_t main (int32_t arg_10h) { main has 3 arguments `argc, argv, envp`, and this program is compiled with GCC, so the stack should be like this : -```sh +```bash [esp + 0x10] - envp [esp + 0x0c] - argv [esp + 0x08] - argc @@ -218,7 +218,7 @@ There are 3 constraints to crackme_0x06: * Odd Number * should have an environment variable whose name started with "LOL". -```sh +```bash $ ./crackme0x06 IOLI Crackme Level 0x06 Password: 12346 diff --git a/src/crackmes/ioli/ioli_0x07.md b/src/crackmes/ioli/ioli_0x07.md index 9d2eccf7..b9a60bb2 100644 --- a/src/crackmes/ioli/ioli_0x07.md +++ b/src/crackmes/ioli/ioli_0x07.md @@ -3,7 +3,7 @@ IOLI 0x07 a weird "wtf?" string. -```sh +```bash $ rz-bin -z ./crackme0x07 [Strings] nth paddr vaddr len size section type string @@ -30,7 +30,7 @@ int32_t main (int32_t arg_10h) { due to the symbol info lost, neither `aa` nor `aaa` show the name of functions. we can double check this in "flagspace". Rizin use fcn_080485b9 as the function name. It's a common case in reverse engineering that we don't have any symbol info of the binary. -```sh +```bash [0x080487fd]> fs symbols [0x080487fd]> f 0x08048400 33 entry0 @@ -113,7 +113,7 @@ int32_t fcn_080485b9 (char * s, void* envp) most part of crackme 0x07 is the same with 0x06. and it can be solved by the same password & environment: -```sh +```bash $ export LOLAA=help $ ./cracke0x07 IOLI Crackme Level 0x07 @@ -123,7 +123,7 @@ Password OK! wait ... where is the 'wtf?'. Often, we would like to find the cross reference (xref) to strings (or data, functions, etc.) in reverse engineering. The related commands in Rizin are under "ax" namespace: -```sh +```bash [0x08048400]> f 0x080487a8 5 str.LOLO 0x080487ad 21 str.Password_Incorrect diff --git a/src/crackmes/ioli/ioli_0x08.md b/src/crackmes/ioli/ioli_0x08.md index e3a0fd1d..afc7a7a6 100644 --- a/src/crackmes/ioli/ioli_0x08.md +++ b/src/crackmes/ioli/ioli_0x08.md @@ -3,7 +3,7 @@ IOLI 0x08 we can reverse it and find it's similar to 0x07, and use the same password to solve it: -```sh +```bash $ export LOLAA=help $ ./cracke0x08 IOLI Crackme Level 0x08 @@ -13,7 +13,7 @@ Password OK! [dustri](https://dustri.org/b/defeating-ioli-with-rizin.html) provided a better way to check crackme0x08. 0x07 is the stripped version of 0x08. -```sh +```bash $ rz-diff -A -C ./crackme0x07 ./crackme0x08 ... fcn.08048360 23 0x8048360 | MATCH (1.000000) | 0x8048360 23 sym._init diff --git a/src/crackmes/ioli/ioli_0x09.md b/src/crackmes/ioli/ioli_0x09.md index 406b4079..65bcaee9 100644 --- a/src/crackmes/ioli/ioli_0x09.md +++ b/src/crackmes/ioli/ioli_0x09.md @@ -3,7 +3,7 @@ IOLI 0x09 Hints: crackme0x09 hides the format string (%d and %s), and nothing more than 0x08. -```sh +```bash $ export LOLA=help $ ./crackme0x09 IOLI Crackme Level 0x09 diff --git a/src/debugger/apple.md b/src/debugger/apple.md index e242647c..e1931d8f 100644 --- a/src/debugger/apple.md +++ b/src/debugger/apple.md @@ -22,7 +22,7 @@ regular user, download the Entitlements file [here](https://github.com/rizinorg/rizin/blob/dev/binrz/rizin/rizin_macos.xml). Then execute the following command: -```sh +```bash $ codesign --entitlements --force -s - $(which rizin) ``` @@ -47,7 +47,7 @@ instruct taskport to not authenticate the user by executing the following commands. This will disable the debugging authentication prompt even after you reboot. -```sh +```bash security authorizationdb read system.privilege.taskport > taskport.plist /usr/libexec/PlistBuddy -c 'Set :authenticate-user false' ./taskport.plist sudo security authorizationdb write system.privilege.taskport < taskport.plist diff --git a/src/first_steps/basic_debugger_session.md b/src/first_steps/basic_debugger_session.md index 5d3efc74..567f204b 100644 --- a/src/first_steps/basic_debugger_session.md +++ b/src/first_steps/basic_debugger_session.md @@ -38,7 +38,7 @@ When Rizin is in debugger mode, it forks and loads the debuggee `ls` program int Execution pauses early in the `ld.so` dynamic linker, making the entrypoint and any shared libraries invisible at this stage. -To override this behavior and set another name for an entry breakpoint, add a Rizin command `e dbg.bep=entry` or `e dbg.bep=main` to your startup script (the `rizinrc` paths can be found by executing `rizin -hh`). +To override this behavior and set another name for an entry breakpoint, add a Rizin command `e dbg.bep=entry` or `e dbg.bep=main` to your `rizinrc` [initial script](../configuration/initial_scripts.md). An alternative method to continue until a specific address is by using the `dcu` command, meaning "debug continue until." Provide the address where you want to stop, for example: diff --git a/src/plugins/dev.md b/src/plugins/dev.md index 09d8dee3..fcdc97fb 100644 --- a/src/plugins/dev.md +++ b/src/plugins/dev.md @@ -117,7 +117,7 @@ struct rz_lib_struct_t rizin_plugin = { To build and install this plugin just type this: -```sh +```bash meson build ninja -C build && ninja -C build install ```