flopz.core package

Submodules

flopz.core.addressable_object module

class AddressableObject(object_addr)

Bases: object

An addressableObject is anything that can be placed into some sort of memory each AddressableObject can be addressed by - absolute address - relative address

• relative to some other address

Parameters

object_addr (int) –

get_absolute_address()

Return type

int

get_relative_address(other_addr)

Parameters

other_addr (int) –

Return type

int

flopz.core.assembler module

class Assembler

Bases: object

An Assembler is used to turn one piece of Shellcode (or a Module/Function) into assembly bytes It may be used without instantiating it explicitly (as done by the Shellcode class in .bytes())

bytes(shellcode)

Return type

bytes

Returns

binary code for assigned shellcode

exception AssemblerException

Bases: Exception

flopz.core.function module

class Function(address, save_register_module, restore_register_module, logic, make_call=None)

Bases: flopz.core.module.Module

A Function is a Module that can be called without having to manually clean registers In general, there should be no need to subclass this as any module can be wrapped by this class You can, however, subclass Function in order to provide cleaner syntax for often-used Functions For example, it might make sense to create a PPCFunction, where only the logic has to be provided and the other modules are static Simply pass the individual modules and enjoy

Parameters

• address (int) –

• save_register_module (Module) –

• restore_register_module (Module) –

• logic (Module) –

• make_call (Optional[Module]) –

bytes(assembler=None, instruction_args=None)

Parameters

instruction_args (Optional[dict]) –

Return type

bytes

get_call_bytes()

Return type

bytes

get_call_instructions()

Return type

List[Instruction]

flopz.core.label module

class AbsoluteLabelRef(label_name, ins, addr=0)

Bases: flopz.core.label.LabelRef

Same thing as LabelRef, but gives an absolute address instead of a relative one.

Parameters

• label_name (str) –

• ins (Callable[[int], Instruction]) –

• addr (int) –

resolve_with_label(label)

Parameters

label (Label) –

Return type

Instruction

class Label(name)

Bases: flopz.core.addressable_object.AddressableObject

A class for putting symbolic labels into your assembly

Parameters

name (str) –

finalize(addr)

Parameters

addr (int) –

ref(ins)

Returns

a LabelRef to this label

Parameters

ins (Callable[[int], Instruction]) –

class LabelRef(label_name, ins, addr=0)

Bases: flopz.core.addressable_object.AddressableObject

Wrap any instruction (or function), providing the address of a label once the label is resolved

Parameters

• label_name (str) –

• ins (Callable[[int], Instruction]) –

• addr (int) –

resolve_with_label(label)

Parameters

label (Label) –

Return type

Instruction

size()

Returns

the size of the underlying instruction, in bytes

flopz.core.module module

class Module(address, instructions=[], registers_written=[], registers_read=[], instructions_func=None, instructions_args=None)

Bases: flopz.core.shellcode.Shellcode

A Module is a piece of shellcode that describes which registers it uses Modules can be parameterized. Subclasses can define extra parameters that have to be filled Modules should be composable (SequentialModule consists of multiple Modules which are executed in sequence etc.)

Parameters

• address (int) –

• instructions (list) –

• registers_written (list) –

• registers_read (list) –

• instructions_func (Optional[Callable]) –

• instructions_args (Optional[dict]) –

bytes(assembler=None, instruction_args=None)

Parameters

instruction_args (Optional[dict]) –

registers_read()

Return type

list

registers_written()

Return type

list

class SequentialModule(address, modules)

Bases: flopz.core.module.Module

use this module to compose several other modules and assemble them sequentially

Parameters

• address (int) –

• modules (List[Module]) –

bytes(assembler=None)

registers_read()

Return type

list

Returns

aggregate list of all registers read by submodules

registers_written()

Return type

list

Returns

aggregate list of all registers written to by submodules

flopz.core.shellcode module

class Shellcode(instructions=[], address=0)

Bases: flopz.core.addressable_object.AddressableObject

A Shellcode is an AddressableObject that contains a bunch of instructions that can be assembled

Parameters

• instructions (list) –

• address (int) –

bytes(assembler=None)

get_instructions()

Return type

list

flopz.core.target module

class Target(target_ram, target_ram_len)

Bases: object

Base class that all targets have to derive from A target - provides code for all Gadgets (SlicePatch, SliceGadget, InstrumentationGadget, DataOut) - provides optional gadgets and hooks - provides a Protocol that the listener can use to talk to the instrumentation code

It is parameterizable, in that it receives target addresses for the locations of each gadgets

A SlicePatch is a Patch that replaces original instructions with a jump to the SliceGadget

A SliceGadget is generated for each SlicePatch. It is in charge of saving at least one register, jumping to the appropriate InstrumentationGadget, executing the sliced original code and returning back to the original code after that

An InstrumentationGadget is generated for each possible type of “output data combination” or hook action It needs to dump data that it is configured to dump, by sending it to the host using the DataOut function. it can implement many other functions, if necessary. After it’s done, it needs to return to the SliceGadget. How that happens is up to the developer, it needs to be adjusted for each architecture or processor core

The dataOut function is the last thing that is mandatory to be provided by the Target. It implements logic to send out data to the host. The format is always [tracelet ID][data as defined in trace config]

Parameters

• target_ram (int) –

• target_ram_len (int) –

get_data_out_function(target_addr)

Implement this, so it returns a function that sends data to the instrumenting host using whatever channel your target can provide. How the function reads its parameters is up to you. At the very least, the caller should provide a length and a pointer to memory. :type target_addr: int :param target_addr: absolute base address of function :rtype: Function :return: a function which handles the egress of data

get_init_gadgets(init_slice_addr, original_bytes, init_gadget_addr)

The init Gadget is a SlicePatch that calls into custom initialization code. :type init_slice_addr: int :param init_slice_addr: where to put the call to our init function, as absolute addr within the original file :type original_bytes: bytes :param original_bytes: which bytes to replace :type init_gadget_addr: int :param init_gadget_addr: where to put the init gadget, as absolute addr :rtype: Tuple[Shellcode, Shellcode] :return: a tuple, with first element being the SlicePatch to replace the original instructions, the second element being the instrumentation initialization code

get_instrumentation_gadget(config, target_addr, dataout_func)

generate an instrumentation gadget, based on ‘dump’ config The instrumentation gadget is in charge of sending a configurable amount of data and returning back to the SliceGadget the instrumentation gadget should be used by _many_ sliceGadgets, which means you need to pass the return address somehow ..instead of jumping to a constant address :type config: dict :param config: dump config :type target_addr: int :param target_addr: where to put the instrumentation gadget :type dataout_func: Function :param dataout_func: the data_out function to use :rtype: Shellcode :return: A shellcode/module which implements the instrumentation (i.e. send data and jump back to SliceGadget)

static get_protocol()

Return type

Protocol

Returns

A Protocol that works with this target

get_slice_gadgets(slice_addr, original_bytes, id, slice_gadget_addr, instrumentation_gadget)

Called for each configured target location/slice The SlicePatch has to replace the original instructions and jump to the SliceGadget The SliceGadget needs to prepare execution of the InstrumentationGadget and jump to it After the InstrumentationGadget has executed, the SliceGadget has to execute the original instructions ..and finally return to the original code location

Parameters

• slice_addr (int) – the absolute address of the target instrumentation location within the original file

• original_bytes (bytes) – which original bytes to replace

• id (int) – each slice needs to have a unique id

• slice_gadget_addr (int) – where to put the slice gadget

• instrumentation_gadget (AddressableObject) – the instrumentation gadget to jump to

Return type

Tuple[Shellcode, Shellcode]

Returns

a tuple, with the first element being the SlicePatch (replacing the original instructions) and the second element being the associated SliceGadget

static name()

override this to return a unique name for your target :rtype: str :return: a string containing a unique name for this target

Module contents