Lua API

Rdis provides a scriptable interface through lua. Lua has a semi-OOP model through metatables. When we refer to, "objects," we are referring to lua tables with metatables.

Instead of interacting directly with the objects used by rdis, the interface obtains a copy of requested objects. If an object changes in rdis, the object you hold in lua may be out of date.

When rdis loads a file, it will check for ~/.rdis.lua. If the file is found, it is opened, loaded and run each time an rdis object is created.

Rdis makes no limitations on the lua environment. While this opens a wealth of possibilities, one of those possibilities is os.execute("rm -rf /") or worse. Be careful what you run.

Cheat Sheet

uint64  uint64 ................ (string)
uint64  uint64 ................ (number)

nil     rdis.console .......... (string)
string  rdis.dump_json ........ ()
table   rdis.functions ........ ()
nil     rdis.load ............. (loader)
boolean rdis.loader ........... (string filename)
node    rdis.node ............. (uint64 index)
table   rdis.nodes ............ ()
integer rdis.peek ............. (uint64 address)
nil     rdis.poke ............. (uint64 address, string bytes)
rdg     rdis.rdg .............. (uint64 address)
nil     rdis.set_function_label (uint64 address, string label)
nil     rdis.set_ins_comment .. (uint64 node_index, uint64 ins_address, string comment)
string  rdis.sha256 ........... (data)

uint64  node:index ............ ()
table   node:edges ............ ()
table   node:instructions ..... ()

uint64  edge:head ............. ()
uint64  edge:tail ............. ()

uint64  ins:address ........... ()
uint64  ins:target ............ ()
string  ins:bytes ............. ()
string  ins:description ....... ()
string  ins:comment ........... ()

nil     rdg:save_png .......... (string filename)
node    rdg:node_by_coords .... (integer x, integer y)
ins     rdg:ins_by_coords ..... (integer x, integer y)
nil     rdg:highlight_ins ..... (uint64 node_index, uint64 ins_address)

uint64

Lua does not have native support for the type uint64_t. Support of this type can be accomplished via two means: modify lua or provide a uint64 object. We have elected to provide a uint64 object. This is cleaner, allows the use of luajit, and prevents us from having to distribute a custom version of lua with rdis.

Uint64 is used extensively through the rdis lua API.

---

uint64 uint64 (string)
uint64 uint64 (number)

The function uint64() accepts either a string or number and returns a uint64 object. When uint64 is given a string, the string is passed to strtoull and the returned 64-bit value is used.

---

uint64  uint64.__add (uint64)
uint64  uint64.__sub (uint64)
uint64  uint64.__mul (uint64)
uint64  uint64.__div (uint64)
uint64  uint64.__mod (uint64)
boolean uint64.__eq  (uint64)
boolean uint64.__lt  (uint64)
boolean uint64.__le  (uint64)
string  uint64.__tostring ()
string  uint64.string ()

If you are familiar with lua, then you already know these metamethods. Lua uses these methods internally to override operators on the uint64 object. An example follows:

a = uint64(32)

b = uint64("0xdeadbeef")
c = uint64("0xdeadbeeffeebdaed")
d = (((a + b) - c) * a) / b) % c
print(a)
rdis.console(tostring(a) .. " " .. b:string())
if a == b then print("a == b") end

rdis

nil     rdis.console .......... (string)
string  rdis.dump_json ........ ()
table   rdis.functions ........ ()
nil     rdis.load ............. (loader)
boolean rdis.loader ........... (string filename)
node    rdis.node ............. (uint64 index)
table   rdis.nodes ............ ()
integer rdis.peek ............. (uint64 address)
nil     rdis.poke ............. (uint64 address, string bytes)
rdg     rdis.rdg .............. (uint64 address)
nil     rdis.set_function_label (uint64 address, string label)
nil     rdis.set_ins_comment .. (uint64 node_index, uint64 ins_address, string comment)
string  rdis.sha256 ........... (data)

nil	rdis.console	(string)
Sends the string to the rdis console window. A newline will be appended.

string	rdis.dump_json	()
Dumps the entire state of rdis into a giant json string. F*ck yeah open source in the cloud.

table	rdis.functions	()
Returns a table of all functions rdis has loaded. The table keys are the function addresses of type uint64. The values are the function labels of type string.

nil	rdis.load	(loader)
Allows for the user of custom loaders written in lua. This code will probably chance in the future and should be considered unstable at best.

boolean	rdis.loader	(string filename)
Loads a binary at the given filename as specified by rdis. This will call lua's internal loaders. Returns true on success, or false on failure.

node	rdis.node	(uint64 index)
Returns a node from the Control Flow Graph at the given index. If no node was found with the given index, an error is thrown. A node's index is the same as the address of the first instruction found in that node.

table	rdis.nodes	()
Returns a table containing all nodes in the rdis graph.

integer	rdis.peek	(uint64 address)
Fetches the value of the byte in rdis's memory model found at address.

nil	rdis.poke	(uint64 address, string bytes)
Sets the bytes of rdis's internal memory model at address to the value given by bytes. Bytes is a string of arbitrary length. This triggers several actions internally in rdis, such as the regraphing of functions with instructions in the updated memory area.

rdg	rdis.rdg	(uint64 address)
Creates and returns a rdg (Rdis Draw Graph) object. Address should be the address of the entry point for the function you wish to graph. In reality, it is the index of the first node used to create the rdg.

nil	rdis.set_function_label	(uint64 address, string label)
Sets the label of the function at address to label. Throws an error if the label cannot be found.

nil	rdis.set_ins_comment	(uint64 node_index, uint64 ins_address, string comment)
Sets the comment of the instruction with address ins_address, found in node node_index, to the value in comment.

nil	rdis.sha256	(string data)
Hashes data with the sha256 cryptographic hashing algorithm and returns the ASCII lowercase hexademical representation of the sum.

node

uint64  node:index ...... ()
table   node:edges ...... ()
table   node:instructions ()

uint64	node:index	()
Returns the index of this node, which is equal to the address of the first instruction in this node.

table	node:edges	()
Returns a table with values of type edge representing the directional edges of this node.

table	node:instructions	()
Returns a table with values of type ins for the instructions in this table. The instructions are given in the order they will be executed, not necessarily by address.

edge

uint64  edge:head ()
uint64  edge:tail ()

uint64	edge:head	()
Returns the index of the node at the head (predecessor) of this edge.

uint64	edge:tail	()
Returns the index of the node at the tail (sucessor) of this edge.

ins

uint64 ins:address ... ()
uint64 ins:target .... ()
string ins:bytes ..... ()
string ins:description ()
string ins:comment ... ()

uint64	ins:address	()
Returns the address where this instruction was found.

uint64	ins:target	()
Certain instructions, such as conditional jumps and call instructions, are set with targets. The target is the alternate address where control flow may continue to. Non-conditional jumps do not have targets, as there is only one address where control flow may continue to. Returns nil if no target.

string	ins:bytes	()
Returns the bytes that compose this instruction.

string	ins:description	()
Returns a textual description of the instruction, for example: "xor eax, eax".

string	ins:comment	()
Returns the comment stored with this instruction, or nil if no comment exists.

rdg

nil  rdg:save_png ..... (string filename)
node rdg:node_by_coords (integer x, integer y)
ins  rdg:ins_by_coords  (integer x, integer y)
nil  rdg:highlight_ins  (uint64 node_index, uint64 ins_address)

nil	rdg:save_png	(string filename)
Saves the current Rdis Display Graph to a png.

node	rdg:node_by_coords	(integer x, integer y)
Given x, y coords into the rdg graph, returns the node displayed there, or nil if no node.

ins	rdg:ins_by_coords	(integer x, integer y)
Given x, y coords into the rdg graph, returns the instruction displayed there, or nil if no instruction.

nil	rdg:highlight_ins	(uint64 node_index, uint64 ins_address)
Given the index of a node and the address of an instruction inside that node, highlights that node in the rdg graph.