The Official Radare2 Book

Radare2 has seen many different user interfaces being developed over the years.

Maintaining a GUI is far from the scope of developing the core machinery of a reverse engineering toolkit: it is preferred to have a separate project and community, allowing both projects to collaborate and to improve together - rather than forcing cli developers to think in gui problems and having to jump back and forth between the graphic aspect and the low level logic of the implementations.

In the past, there have been at least 5 different native user interfaces (ragui, r2gui, gradare, r2net, bokken) but none of them got enough maintenance power to take off and they all died.

In addition, r2 has an embedded webserver and ships some basic user interfaces written in html/js. You can start them like this:

$ r2 -c=H /bin/ls

After 3 years of private development, Hugo Teso; the author of Bokken (python-gtk gui of r2) released to the public another frontend of r2, this time written in c++ and qt, which has been very welcomed by the community.

This GUI was named Iaito, but as long as he prefered not to keep maintaining it, Xarkes decided to fork it under the name of Cutter (name voted by the community), and lead the project. This is how it looks:

• https://github.com/radareorg/cutter.

Basic Radare2 Usage

The learning curve is usually somewhat steep at the beginning. Although after an hour of using it you should easily understand how most things work, and how to combine the various tools radare offers. You are encouraged to read the rest of this book to understand how some non-trivial things work, and to ultimately improve your skills.

Navigation, inspection and modification of a loaded binary file is performed using three simple actions: seek (to position), print (buffer), and alternate (write, append).

The 'seek' command is abbreviated as s and accepts an expression as its argument. The expression can be something like 10, +0x25, or [0x100+ptr_table]. If you are working with block-based files, you may prefer to set the block size to a required value with b command, and seek forward or backwards with positions aligned to it. Use s++ and s-- commands to navigate this way.

If radare2 opens an executable file, by default it will open the file in Virtual Addressing (VA) mode and the sections will be mapped to their virtual addresses. In VA mode, seeking is based on the virtual address and the starting position is set to the entry point of the executable. Using -n option you can suppress this default behavior and ask radare2 to open the file in non-VA mode for you. In non-VA mode, seeking is based on the offset from the beginning of the file.

The 'print' command is abbreviated as p and has a number of submodes — the second letter specifying a desired print mode. Frequent variants include px to print in hexadecimal, and pd for disassembling.

To be allowed to write files, specify the -w option to radare2 when opening a file. The w command can be used to write strings, hexpairs (x subcommand), or even assembly opcodes (a subcommand). Examples:

> w hello world ; string

> wx 90 90 90 90 ; hexpairs

> wa jmp 0x8048140 ; assemble

> wf inline.bin ; write contents of file

Appending a ? to a command will show its help message, for example, p?. Appending ?* will show commands starting with the given string, e.g. p?*.

To enter visual mode, press V. Use q to quit visual mode and return to the prompt.

In visual mode you can use HJKL keys to navigate (left, down, up, and right, respectively). You can use these keys in cursor mode toggled by c key. To select a byte range in cursor mode, hold down SHIFT key, and press navigation keys HJKL to mark your selection.

While in visual mode, you can also overwrite bytes by pressing i. You can press TAB to switch between the hex (middle) and string (right) columns. Pressing q inside the hex panel returns you to visual mode. By pressing p or P you can scroll different visual mode representations. There is a second most important visual mode - curses-like panels interface, accessible with V! command.

Command-line Options

Command Format

A general format for radare2 commands is as follows:

[.][times][cmd][~grep][@[@iter]addr!size][|>pipe] ;

People who use Vim daily and are familiar with its commands will find themselves at home. You will see this format used throughout the book. Commands are identified by a single case-sensitive character [a-zA-Z].

To repeatedly execute a command, prefix the command with a number:

px # run px

3px # run px 3 times

The ! prefix is used to execute a command in shell context. If you want to use the cmd callback from the I/O plugin you must prefix with =!.

Note that a single exclamation mark will run the command and print the output through the RCons API. This means that the execution will be blocking and not interactive. Use double exclamation marks -- !! -- to run a standard system call.

All the socket, filesystem and execution APIs can be restricted with the cfg.sandbox configuration variable.

A few examples:

ds ; call the debugger's 'step' command

px 200 @ esp ; show 200 hex bytes at esp

pc > file.c ; dump buffer as a C byte array to file.c

wx 90 @@ sym.* ; write a nop on every symbol

pd 2000 | grep eax ; grep opcodes that use the 'eax' register

px 20 ; pd 3 ; px 40 ; multiple commands in a single line

The standard UNIX pipe | is also available in the radare2 shell. You can use it to filter the output of an r2 command with any shell program that reads from stdin, such as grep, less, wc. If you do not want to spawn anything, or you can't, or the target system does not have the basic UNIX tools you need (Windows or embedded users), you can also use the built-in grep (~).

See ~? for help.

The ~ character enables internal grep-like function used to filter output of any command:

pd 20~call ; disassemble 20 instructions and grep output for 'call'

Additionally, you can grep either for columns or for rows:

pd 20~call:0 ; get first row

pd 20~call:1 ; get second row

pd 20~call[0] ; get first column

pd 20~call[1] ; get second column

Or even combine them:

pd 20~call:0[0] ; grep the first column of the first row matching 'call'

This internal grep function is a key feature for scripting radare2, because it can be used to iterate over a list of offsets or data generated by disassembler, ranges, or any other command. Refer to the loops section (iterators) for more information.

The @ character is used to specify a temporary offset at which the command to its left will be executed. The original seek position in a file is then restored.

For example, pd 5 @ 0x100000fce to disassemble 5 instructions at address 0x100000fce.

Most of the commands offer autocompletion support using key, for example seek or flags commands. It offers autocompletion using all possible values, taking flag names in this case. Note that it is possible to see the history of the commands using the !~... command - it offers a visual mode to scroll through the radare2 command history.

To extend the autocompletion support to handle more commands or enable autocompletion to your own commands defined in core, I/O plugins you must use the !!! command.

Expressions

Expressions are mathematical representations of 64-bit numerical values. They can be displayed in different formats, be compared or used with all commands accepting numeric arguments. Expressions can use traditional arithmetic operations, as well as binary and boolean ones. To evaluate mathematical expressions prepend them with command ?:

[0xb7f9d810]> ?vi 0x8048000

134512640

[0xv7f9d810]> ?vi 0x8048000+34

134512674

[0xb7f9d810]> ?vi 0x8048000+0x34

134512692

[0xb7f9d810]> ? 1+2+3-4*3

hex 0xfffffffffffffffa

octal 01777777777777777777772

unit 17179869184.0G

segment fffff000:0ffa

int64 -6

string "\xfa\xff\xff\xff\xff\xff\xff\xff"

binary 0b1111111111111111111111111111111111111111111111111111111111111010

fvalue: -6.0

float: nanf

double: nan

trits 0t11112220022122120101211020120210210211201

Supported arithmetic operations are:

• + : addition

• - : subtraction

• * : multiplication

• / : division

• % : modulus

• > : shift right

• < : shift left

[0x00000000]> ?vi 1+2+3

6

To use of logical OR should quote the whole command to avoid executing the | pipe:

[0x00000000]> "? 1 | 2"

hex 0x3

octal 03

unit 3

segment 0000:0003

int32 3

string "\x03"

binary 0b00000011

fvalue: 2.0

float: 0.000000f

double: 0.000000

trits 0t10

Numbers can be displayed in several formats:

0x033 : hexadecimal can be displayed

3334 : decimal

sym.fo : resolve flag offset

10K : KBytes 10*1024

10M : MBytes 10*1024*1024

You can also use variables and seek positions to build complex expressions.

Use the ?$? command to list all the available commands or read the refcard chapter of this book.

$$ here (the current virtual seek)

$l opcode length

$s file size

$j jump address (e.g. jmp 0x10, jz 0x10 => 0x10)

$f jump fail address (e.g. jz 0x10 => next instruction)

$m opcode memory reference (e.g. mov eax,[0x10] => 0x10)

$b block size

Some more examples:

[0x4A13B8C0]> ? $m + $l

140293837812900 0x7f98b45df4a4 03771426427372244 130658.0G 8b45d000:04a4 140293837812900 10100100 140293837812900.0 -0.000000

[0x4A13B8C0]> pd 1 @ +$l

0x4A13B8C2 call 0x4a13c000