API Documentation¶

class api.BP(addr, pgd, size=0, typ=0, func=None, new_style=False)¶

Class used to create execution, memory read, and memory write breakpoints

__init__(addr, pgd, size=0, typ=0, func=None, new_style=False)¶

Constructor for a BreakPoint

Parameters:	addr (int) – The (start) address where we want to put the breakpoint. If a str is provided, it will search for a symbol and put the breakpoint there. The syntax is module!symbol, and it does not require to specify the full module or symbol name as long as there is no ambiguity. pgd (int) – The PGD or address space where we want to put the breakpoint. Irrelevant for physical address breakpoints. size (int) – Optional. The size of the area we want to put a breakpoint on. We can put the BP on a single address or a memory range. typ (int) – The type of breakpoint: BP.EXECUTION, BP.MEM_READ, BP.MEM_WRITE, BP.MEM_READ_PHYS, BP.MEM_WRITE_PHYS func (function) – Optional. The function that will be called as callback for the breakpoint. The parameters for the function should be the ones corresponding to the INSN_BEGIN_CB callback for execution breakpoints, and MEM_READ_CB or MEM_WRITE_CB for memory read/write breakpoints. If no function is specified, a shell is started when the breakpoint is hit. new_style (bool) – Defines whether the function func optionally passed as parameter uses old or new callback calling convention. See documentation for further reference. Defaults to False.
Returns:	An instance of class BP for the inserted breakpoint
Return type:	BP

disable()¶

Disable a breakpoint

Returns:	None
Return type:	None

enable()¶

Enable a breakpoint

Returns:	None
Return type:	None

enabled()¶

Return whether the breakpoint is enabled or not

Returns:	Whether the breakpoint is enabled or not
Return type:	bool

get_addr()¶

Get the address where the breakpoint is registered

Returns:	The address
Return type:	int

get_pgd()¶

Get the PGD of the process where the breakpoint is registered

Returns:	The PGD of the process where the breakpoint is registered
Return type:	int

get_size()¶

Get the size of the breakpoint

Returns:	The size of the breakpoint
Return type:	int

get_type()¶

Get the type of the breakpoint

Returns:	The type of the breakpoint: BP.EXECUTION, BP.MEM_READ, BP.MEM_WRITE
Return type:	int

class api.CallbackManager(module_hdl, new_style=False)¶

Class that abstracts callback management,optionally associating names to callbacks, and registering the list of added callbacks so that we can remove them all with a single call to “clean()” after we are done.

__init__(module_hdl, new_style=False)¶

Constructor of the class

Parameters:	module_hdl (int) – The module handle provided to the script as parameter to the initialize_callbacks function. Use 0 if it doesn’t apply. new_style (bool) – Enables the new-style callback parameter format. New-style callback functions accept a single parameter (dictionary), with a key (str) per parameter, and a value (value of the parameter), instead of positional arguments.

add_callback(callback_type, func, name=None, addr=None, pgd=None, start_opcode=None, end_opcode=None, new_style=None)¶

Add a callback to the module, given a name, so that we can refer to it later.

If the name is repeated, it will provide back a new name based on the one passed as argument, that can be used later for removing it or attaching triggers to it.

Parameters:	name (str) – The name of the callback callback_type (int) – The callback type to insert. One of INSN_BEGIN_CB, BLOCK_BEGIN_CB, etc… See help(api) from a pyrebox shell to get a complete listing of constants ending in _CB func (function) – The callback function (python function) addr (int) – Optional. The address where we want to place the callback. Only applies eo INSN_BEGIN_CB, BLOCK_BEGIN_CB pgd (int) – Optional. The PGD (addr space) where we want to place the callback. Only applies to INSN_BEGIN_CB, BLOCK_BEGIN_CB new_style (bool) – Optional. Enables the new-style callback parameter format. New-style callback functions accept a single parameter (dictionary), with a key (str) per parameter, and a value (value of the parameter), instead of positional arguments. This parameter overrides the class-wide new_style parameter in the CallbackManager __init__ function.
Returns:	The actual inserted callback name. If the callback name indicated already existed, this name will be updated to make it unique. This name can be used as a handle to the callback
Return type:	str

add_trigger(name, trigger_path)¶

Add trigger to a callback.

Adds a trigger to a given callback. If the trigger is not compiled or the binary is outdated, it will force a compilation of the trigger before loading it.

Parameters:	name (str) – The callback name to which we want to add the trigger trigger_path (str) – The path to the trigger.
Returns:	None
Return type:	None

call_trigger_function(name, function_name)¶

Call a trigger function associated to callback (name) with function name function_name

param name: The callback name

type name: str

param function_name:

The function name

type function_name:

str

return: The value, if it exists, None otherwise

rtype: str or int

callback_exists(name)¶

Determine if a callback exists or not, given its name

Parameters:	name (str) – The callback name to check
Returns:	True if the callback already exists
Return type:	bool

clean()¶

Clean all the inserted callbacks.

Clean all the inserted callbacks. Will remove all the callbacks registered within this manager.

Returns:	None
Return type:	None

generate_callback_name(name)¶

Generates a unique callback name given an initial name

Parameters:	name (str) – The initial name
Returns:	The new generated name
Return type:	str

get_module_handle()¶

Returns the module handle associated to this callback manager

Returns:	The handle of the module this callback manager is bound to.
Return type:	int

get_trigger_var(name, var_name)¶

Get a trigger variable associated to callback (name) with variable name var_name

param name: The callback name

type name: str

param var_name: The variable name

type var_name: str

return: The value, if it exists, None otherwise

rtype: str or int

rm_callback(name)¶

Remove a callback given its name. Associated triggers will get unloaded too.

Parameters:	name (str) – The name of the callback to remove
Returns:	None
Return type:	None

rm_trigger(name)¶

Remove the trigger from the callback specified as parameter

Parameters:	name (str) – The callback name from which we want to remove the trigger
Returns:	None
Return type:	None

set_trigger_var(name, var_name, val)¶

Add a trigger variable with name var_name and value val, to the callback with the given name

param name: Name of the callback

type name: str

param var_name: Name of the variable to set

type var_name: str

param val: Value of the variable to set

type val: unsigned int or str

return: None

rtype: None

class api.GuestFile(filesystem_index, file_handle, size, name)¶

Class used to manage guest files residing on the guest file system

__init__(filesystem_index, file_handle, size, name)¶

get_name()¶

Returns the name of the file

Returns:	The name of the file
Return type:	str or unicode

get_offset()¶

Returns the current offset

Returns:	The offset of the file
Return type:	int

get_size()¶

Returns the file size

Returns:	The file size
Return type:	int

read(size=None, offset=None)¶

Reads data at the current offset, or the specified offset.

Parameters:	size (int) – The size to read offset (int) – Optional. The offset to read at. It will not change the current file pointer.
Returns:	The data read
Return type:	str

seek(offset)¶

Sets the offset to read the file

Parameters:	offset (int) – The offset to set
Returns:	None
Return type:	None

api.get_filesystems()¶

Returns a list of filesystems to open.

Returns:	A list of dictionaries, each dictionary containing the keys: “index”, “type” and “size”, and their respective values.
Return type:	list

api.get_loaded_modules()¶

Returns a dictionary of modules loaded in pyrebox.

Returns:	Dictionary with the keys: “module_handle”, “module_name”, “is_loaded”
Return type:	dict

api.get_module_list(pgd)¶

Return list of modules for a given PGD

Parameters:	pgd (int) – The PGD of the process for which we want to extract the modules, or 0 to extract kernel modules
Returns:	List of modules, each element is a dictionary with keys: “name”, “fullname”, base”, “size”, and “symbols_resolved”
Return type:	list

api.get_num_cpus()¶

Returns the number of CPUs on the emulated system

Returns:	The number of CPUs on the emulated system
Return type:	int

api.get_os_bits()¶

Return the bitness of the system / O.S. being emulated

Returns:	The bitness of the system / O.S. being emualated
Return type:	int

api.get_process_list()¶

Return list of processes.

Returns:	List of processes. List of dictionaries with keys: “pid”, “pgd”, “name”, “kaddr”, where kaddr stands for the kernel address representing the process (e.g.: EPROCESS)
Return type:	list

api.get_running_process(cpu_index=0)¶

Returns the PGD or address space of the process that is being executed at this moment

Parameters:	cpu_index (int) – CPU index that we want to query. Each CPU might be executing a different address space
Returns:	The PGD or address space for the process that is executing on the indicated CPU
Return type:	int

api.get_symbol_list(pgd=None)¶

Return list of symbols

Parameters:	pgd (int) – The pgd to obtain the symbols from. 0 to get kernel symbols
Returns:	List of symbols, each element is a dictionary with keys: “mod”, “mod_fullname”, “name”, and “addr”
Return type:	list

api.get_system_time()¶

Retrieve the system time for the running guest.

Returns:	The system time for the running system.
Return type:	datetime.datetime

api.import_module(module_name)¶

Import a module given its name (e.g. scripts.script_example)

Parameters:	module_name (str) – The module name following python notation. E.g.: scripts.script_example
Returns:	None
Return type:	None

api.is_kernel_running(cpu_index=0)¶

Returns True if the corresponding CPU is executing in Ring 0

Parameters:	cpu_index (int) – CPU index that we want to query. Each CPU might be executing a different address space
Returns:	True if the corresponding CPU is executing in Ring 0, False otherwise
Return type:	bool

api.is_monitored_process(pgd)¶

Returns true of a given process is being monitored. Process-wide callbacks will be called for every process that is being monitored

param pgd: PGD, or address space of the process to monitor

type pgd: int

return: True of the process is being monitored, False otherwise

rtype: bool

api.load_vm(name)¶

Load a previously saved snapshot of the virtual machine.

Parameters:	name (str) – Name of the snapshot to load
Returns:	None
Return type:	None

api.open_guest_path(filesystem_index, path)¶

Open a file or directory in a given file system.

Parameters:	filesystem_index (int) – The index of the filesystem to open path (str) – The path to open (either a file or directory).
Returns:	A list of files (if the path is a directory), an instance of GuestFile (if the path is a file), or None
Return type:	list, GuestFile, or None

api.r_cpu(cpu_index=0)¶

Read CPU register values :param cpu_index: The CPU index to read. 0 by default. :type cpu_index: int

Returns:	The CPU
Return type:	X64CPU \| X86CPU \| …

api.r_ioport(address, size)¶

Read I/O port

Parameters:	address (int) – The port address to read, from 0 to 65536 size (int) – The size to read (1, 2, or 4)
Returns:	The value read
Return type:	int

api.r_pa(addr, length)¶

Read physical address

Parameters:	addr (int) – The address to read length (int) – The length to read
Returns:	The read content
Return type:	str

api.r_va(pgd, addr, length, use_filesystem=False)¶

Read virtual address

Parameters:	pgd (int) – The PGD (address space) to read from addr (int) – The address to read length (int) – The length to read use_filesystem (bool) – Optional. Default: False. If set to True, PyREBox will use The Sleuthkit to inspect the file system and obtain this data from the file backing the memory page: The referenced file if it is memory mapped, or the pagefile.sys in case it has been paged out.
Returns:	The read content
Return type:	str

api.reload_module(module_handle)¶

Reload a module given its handle.

Parameters:	module_handle (int) – The module handle.
Returns:	None
Return type:	None

api.save_vm(name)¶

Save the state of the virtual machine so that it can be restored later

Parameters:	name (str) – Name of the snapshot to save
Returns:	None
Return type:	None

api.start_monitoring_process(pgd)¶

Start monitoring a process. Process-wide callbacks will be called for every process that is being monitored

Parameters:	pgd (int) – PGD, or address space of the process to check
Returns:	None
Return type:	None

api.stop_monitoring_process(pgd, force=False)¶

Start monitoring a process. Process-wide callbacks will be called for every process that is being monitored

Parameters:	pgd (int) – PGD, or address space of the process to stop monitoring
Returns:	None
Return type:	None

api.sym_to_va(pgd, mod_name, func_name)¶

Resolve an address given a symbol name

Parameters:	pgd (int) – The PGD or address space for the process for which we want to search the symbol mod_name (str) – The module name that contains the symbol func_name (str) – The function name to resolve
Returns:	The address, or None if the symbol is not found
Return type:	str

api.unload_module(module_handle)¶

Unload a module given its handle.

Parameters:	module_handle – The module handle.
Returns:	None
Return type:	None

api.va_to_pa(pgd, addr)¶

Virtual to physical address.

Parameters:	pgd – PGD, or address space of the address to translate addr (int) – Virtual address to translate
Returns:	The translated physical address
Return type:	int

api.va_to_sym(pgd, addr)¶

Find symbols for a particular virtual address

Parameters:	pgd (int) – The PGD or address space for the process for which we want to search the symbol addr (int) – The virtual address to search
Returns:	A tuple containing the module name and the function name, None if nothing found
Return type:	tuple

api.w_ioport(address, size, value)¶

Write I/O port

Parameters:	address (int) – The port address to write, from 0 to 65536 size (int) – The size to read (1, 2, or 4)
Returns:	The value written
Return type:	int

api.w_pa(addr, buff, length=None)¶

Write physical address

Parameters:	addr (int) – The address to write buff – The buffer to write
Returns:	None
Return type:	None

api.w_r(cpu_index, regname, val)¶

Write register

Parameters:	cpu_index (int) – CPU index of the register to write regname (str) – Name of the register to write val (int) – Value to write
Returns:	None
Return type:	None

api.w_sr(cpu_index, regname, selector, base, limit, flags)¶

Write segment register. Only applies to x86 / x86-64

Parameters:	cpu_index (int) – CPU index of the register to write regname (str) – Name of the register to write selector (int) – Value (selector) to write base – Value (base) to write limit – Value (limit) to write
Returns:	None
Return type:	None

api.w_va(pgd, addr, buff, length=None)¶

Write virtual address

Parameters:	pgd (int) – The PGD (address space) to write to. addr (int) – The address to write buff – The buffer to write
Returns:	None
Return type:	None

class plugins.guest_agent.GuestAgentPlugin(cb, printer)¶

This plugin deals with a host-guest interface through unused opcodes. It facilitates getting samples into the guest VM, starting them, …

How to use this plugin:

For scripts: - Add plugins.guest_agent: True to your pyrebox.conf

or

Add a member to your module named “requirements” containing a list of required plugins/scripts. E.g.:

requirements = [“plugins.guest_agent”]

Import the plugin with from plugins.guest_agent import guest_agent in your script.

Interact with the guest agent using the public interface of this class (agent is a singleton instance of GuestAgentPlugin).

In the ipython shell: - If no loaded script is loading the guest_agent plugin, you will need to make sure it

gets loaded by adding plugins.guest_agent: True to your pyrebox.conf

Interact with the guest agent using the global member agent that is a singleton instance of GuestAgentPlugin.

__init__(cb, printer)¶

Create a new instance of the GuestAgentPlugin.

Parameters:	cb – The callback manager. printer – The printer where logs should go to.

copy_file(source_path, destiny_path, callback=None)¶

Copy file from host machine to guest VM

Parameters:	source_path (str) – The path (on the host) of the file to copy destiny_path – The path (on the guest) of the file to copy callback (func) – A python function that will be called when the command is requested by the guest (just before it is executed).

execute_file(path, args=[], env={}, exit_afterwards=False, callback=None)¶

Execute file on the guest VM and terminate the agent

Parameters:	path (str) – The path of the file to execute. args (list) – The list of arguments to execute the file. (list of str) env (dict) – A dictionary with environment variables to set for the file to be executed. callback (func) – A python function that will be called when the command is requested by the guest (just before it is executed).

exit_agent()¶: Forces the agent to exit. Nevertheless, if a new agent is spawned in the guest, it will be up and running again.

print_command_list()¶: Prints the list of commands in the queue.

remove_command(cmd_number)¶

Removes a command from the queue of commands to execute

Parameters:	cmd_number (int) – The command number to remove (obtained from print_command_list())

stop_agent()¶: Forces the agent to exit, and stops listening to agent creation, so guest agent interaction is disabled forever.

plugins.guest_agent.clean()¶: Clean up everything.

API Documentation¶

PyREbox

Navigation

Related Topics

param function_name:
param name:	The callback name
type name:	str
	The function name
type function_name:
	str
return:	The value, if it exists, None otherwise
rtype:	str or int

param name:	Name of the callback
type name:	str
param var_name:	Name of the variable to set
type var_name:	str
param val:	Value of the variable to set
type val:	unsigned int or str
return:	None
rtype:	None

param pgd:	PGD, or address space of the process to monitor
type pgd:	int
return:	True of the process is being monitored, False otherwise
rtype:	bool