Loaders

Program

class tritondse.Program(path: tritondse.types.PathLike)[source]

Representation of a program (loaded in memory). This class is wrapping LIEF to represent a program and to provide all the features allowing to pseudo-load one regardless of its format.

Parameters:

path (tritondse.types.PathLike) – Program path

Raises:

FileNotFoundError – if the file is not properly recognized by lief or in the wrong architecture

BASE_STACK = 4026531840
END_STACK = 1879048192
EXTERN_SYM_BASE = 251662336
EXTERN_SYM_SIZE = 4096
property arch_mode: ArchMode

ArchMode enum representing the starting mode (e.g. Thumb for ARM). if None, the default mode of the architecture will be used.

Return type:

Optional[ArchMode]

property architecture: Architecture

Architecture enum representing program architecture.

Return type:

Architecture

property cpustate: Dict[str, int]

Provide the initial cpu state in the forma of a dictionary of {“register_name” : register_value}

property endianness: Endian

Endianness of the loaded program

Returns:

Endianness

property entry_point: tritondse.types.Addr

Program entrypoint address as defined in the binary headers

Return type:

tritondse.types.Addr

find_function_addr(name: str) tritondse.types.Addr | None[source]

Search for the function name in functions of the binary.

Parameters:

name (str) – Function name

Returns:

Address of function if found

Return type:

Addr

property format: Format

Binary format. Supported formats are: ELF, PE, MachO

Return type:

Format

imported_functions_relocations() Generator[Tuple[str, tritondse.types.Addr], None, None][source]

Iterate over all imported functions by the program. This function is a generator of tuples associating the function and its relocation address in the binary.

Returns:

Generator of tuples function name and relocation address

imported_variable_symbols_relocations() Generator[Tuple[str, tritondse.types.Addr], None, None][source]

Iterate over all imported variable symbols. Yield for each of them the name and the relocation address in the binary.

Returns:

Generator of tuples with symbol name, relocation address

memory_segments() Generator[LoadableSegment, None, None][source]

Iterate over all memory segments of the program as loaded in memory.

Returns:

Generator of tuples addrs and content

Raises:

NotImplementedError – if the binary format cannot be loaded

property name: str

Name of the loader

path: Path

Binary file path

property platform: Platform | None

Platform of the binary. It’s solely based on the format of the file ELF, PE etc..

Returns:

Platform

property relocation_enum

LIEF relocation enum associated with the current architecture of the binary.

Returns:

LIEF relocation enum

Return type:

dict

CleLoader

class tritondse.CleLoader(path: str | Path, ld_path: str | Path | None = None)[source]
BASE_STACK = 4026531840
END_STACK = 1879048192
EXTERN_SYM_BASE = 251662336
EXTERN_SYM_SIZE = 4096
property arch_mode: ArchMode | None

ArchMode enum representing the starting mode (e.g. Thumb for ARM). if None, the default mode of the architecture will be used.

Return type:

Optional[ArchMode]

property architecture: Architecture

Architecture enum representing program architecture.

Return type:

Architecture

property cpustate

Provide the initial cpu state in the forma of a dictionary of {“register_name” : register_value}

property endianness: Endian

Endianness of the loaded program

Returns:

Endianness

property entry_point: int

Program entrypoint address as defined in the binary headers

Return type:

tritondse.types.Addr

find_function_addr(name: str) int | None[source]

Search for the function name in functions of the binary.

Parameters:

name (str) – Function name

Returns:

Address of function if found

Return type:

Addr

imported_functions_relocations() Generator[Tuple[str, int], None, None][source]

Iterate over all imported functions by the program. This function is a generator of tuples associating the function and its relocation address in the binary.

Returns:

Generator of tuples function name and relocation address

imported_variable_symbols_relocations() Generator[Tuple[str, int], None, None][source]

Iterate over all imported variable symbols. Yield for each of them the name and the relocation address in the binary.

Returns:

Generator of tuples with symbol name, relocation address

memory_segments() Generator[LoadableSegment, None, None][source]
Returns:

Generator of tuples addrs and content

property name: str

Name of the loader

path: Path

Binary file path

property platform: Platform | None

Platform of the binary.

Returns:

Platform

QuokkaProgram

class tritondse.QuokkaProgram(export_file: Path | str, exec_path: Path | str)[source]

Constructor

property architecture: Architecture
property call_graph: DiGraph

Compute the Call Graph of the binary

Every node in the call graph is a chunk (and not a function).

Returns:

A Call Graph (a networkx DiGraph)

property capstone: Cs

Compute a capstone context

clear() None.  Remove all items from D.
copy() a shallow copy of D
property endianness: Endian
property entry_point: int
find_function_addr(name: str) int | None[source]
find_function_from_addr(address: int) Function | None[source]
property format: Format
static from_binary(exec_path: Path | str, output_file: str | Path | None = None, database_file: str | Path | None = None, debug: bool = False, timeout: int | None = 600) Program | None

Generate an export file directly from the binary.

This methods will export exec_path directly using Quokka IDA’s plugin if installed.

Arguments:

exec_path: Binary to export. output_file: Where to store the result (by default: near the executable) database_file: Where to store IDA database (by default: near the executable) timeout: How long should we wait for the export to finish (default: 10 min) debug: Activate the debug output

Returns:

A |Program instance or None if

Raises:

FileNotFoundError: If the executable is not found

fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

property func_chunk_index: Dict[int, List[Function]]

Returns the list of functions attached to a chunk.

This method allows to find all the functions using a specific chunk. However, it is mostly an internal method and should not be directly used by a user. Instead, use get_function_by_chunk.

Returns:

A mapping of ChunkIndex to a list of Function.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

get_call_graph(backedge_on_ret=False) DiGraph[source]

Compute the call graph of the program.

Parameters:

backedge_on_ret – if true, add a back edge to represent the “return”

Returns:

call graph as a digraph

get_caller_instructions(target: Function) List[int][source]

Get the list of instructions calling target

get_chunk(chunk_index: int, block_index: int | None = None) Chunk

Get a Chunk

If the candidate Chunk is a SuperChunk, this method will resolve it to find the appropriate chunk (given a block index).

Arguments:

chunk_index: Chunk index block_index: Used to resolve SuperChunks

Returns:

A Chunk matching the criteria

Raises:

ChunkMissingError: When no chunk has been found

get_data(address: int) Data

Get data by address

Arguments:

address: Address to query

Returns:

A data at the address

get_first_function_by_chunk(chunk: Chunk) Function | None

Return the first function found when searching for a chunk.

Arguments:

chunk: Chunk belonging to the function

Returns:

A function in which chunk belongs

Raises:

FunctionMissingError: No function has been found for the chunk

get_function(name: str, approximative: bool = True, normal: bool = False) Function

Find a function in a program by its name

Arguments:

name: Function name approximative: Should the name exactly match or allow partial matches? normal: Return only FunctionType.NORMAL functions

Returns:

A function matching the research criteria

Raises:

ValueError: When no function is found

get_function_by_chunk(chunk: Chunk) List[Function]

Retrieves all the functions where chunk belongs.

Arguments:

chunk: Chunk to search for

Returns:

A list of corresponding functions

Raises:

IndexError: When no function is found for the chunk.

get_instruction(address: int) Instruction

Get an instruction by its address

Note: the address must be the head of the instruction.

TODO(dm): Improve the algorithm because the chunks are sorted (use bisect)

Arguments:

address: AddressT: Address to query

Returns:

A quokka.Instruction

Raises:

IndexError: When no instruction is found at this address

get_segment(address: int) Segment

Get a Segment by an address

The address must be in [segment.start, segment.end) to be found.

Arguments:

address: Segment’s address

Returns:

The corresponding Segment

Raises:

KeyError: When the segment is not found

static get_slice(graph: DiGraph, frm: Any, to: Any) DiGraph[source]

Compute the slice between the two nodes on the given graph. The slice is the intersection of reachable node (of frm) and ancestors of to. The result is a subgraph of the original graph.

Parameters:
  • graph – Graph on which to compute the slice

  • frm – node identifier

  • to – node identifier

Returns:

sub graph

property hash: str

Returns the hash value of the binary (either sha256 or MD5).

imported_functions_relocations() Generator[Tuple[str, int], None, None][source]
imported_variable_symbols_relocations() Generator[Tuple[str, int], None, None][source]
items() a set-like object providing a view on D's items
iter_chunk(chunk_types: List[FunctionType] | None = None) Iterator[Chunk]

Iterate over all the chunks in the program.

If a SuperChunk is found, it will split it and return individual chunks. By default, it iterates over all the chunks, even extern functions.

Arguments:
chunk_types: Allow list of chunk types. By default, it retrieves every

chunk.

Yields:

All the chunks in the program.

keys() a set-like object providing a view on D's keys
logger: logging.Logger = <Logger quokka.program (WARNING)>
memory_segments() Generator[LoadableSegment, None, None][source]
merge(coverage: CoverageSingleRun)[source]
property name: str

Returns the underlying binary name

property path: Path
property platform: Platform
pop(k[, d]) v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

property pypcode: pypcode.Context

Generate the Pypcode context.

read_bytes(v_addr: int, size: int) bytes

Read raw bytes from a virtual address

Arguments:

v_addr: Virtual address of the data to read size: Size of the data to read

Returns:

The raw data at the specified address

property relocation_enum
property segments: List[Segment]

Returns the list of segments defined in the program.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

property strings: Iterable[str]

Program strings

Retrieves all the strings used in the program.

Returns:

A list of strings.

property structures: List[Structure]

Structures accessor

Allows to retrieve the different structures of a program (as defined by the disassembler).

Returns:

A list of structures

update([E, ]**F) None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() an object providing a view on D's values

RawBinaryLoader

class tritondse.RawBinaryLoader(architecture: Architecture, cpustate: Dict[str, int] = None, maps: List[LoadableSegment] = None, set_thumb: bool = False, platform: Platform = None, endianness: Endian = Endian.LITTLE)[source]

Monolithic loader. It helps loading raw firmware at a given address in DSE memory space, with the various attributes like architecture etc.

property arch_mode: ArchMode

ArchMode enum representing the starting mode (e.g. Thumb for ARM).

Return type:

ArchMode

property architecture: Architecture

Architecture enum representing program architecture.

Return type:

Architecture

property cpustate: Dict[str, int]

Provide the initial cpu state in the format of a dictionary of {“register_name” : register_value}

property endianness: Endian

Endianness of the monolithic loader. (default is LITTLE)

property entry_point: tritondse.types.Addr

Program entrypoint address as defined in the binary headers

Return type:

tritondse.types.Addr

find_function_addr(name: str) tritondse.types.Addr | None

Search for the function name in functions of the binary.

Parameters:

name (str) – Function name

Returns:

Address of function if found

Return type:

Addr

imported_functions_relocations() Generator[Tuple[str, tritondse.types.Addr], None, None]

Iterate over all imported functions by the program. This function is a generator of tuples associating the function and its relocation address in the binary.

Returns:

Generator of tuples function name and relocation address

imported_variable_symbols_relocations() Generator[Tuple[str, tritondse.types.Addr], None, None]

Iterate over all imported variable symbols. Yield for each of them the name and the relocation address in the binary.

Returns:

Generator of tuples with symbol name, relocation address

memory_segments() Generator[LoadableSegment, None, None][source]

In the case of a monolithic firmware, there is a single segment. The generator returns a single tuple with the load address and the content.

Returns:

Generator of tuples addrs and content

property name: str

Name of the loader

property platform: Platform | None

Platform of the binary.

Returns:

Platform

Creating a new Loader

class tritondse.LoadableSegment(address: int, size: int = 0, perms: ~tritondse.types.Perm = <Perm.R|W|X: 7>, content: bytes | None = None, name: str = '')[source]

Represent a Segment to load in memory. It can either provide a content and will thus be initialized in a context or virtual.

address: int

Virtual address where to load the segment

content: bytes | None = None

Content of the segment

name: str = ''

Name to give to the segment

perms: Perm = 7

Permissions to assign the segment

size: int = 0

Size of the segment. If content is present use len(content)

class tritondse.Loader(path: str)[source]

This class describes how to load the target program in memory.

property arch_mode: ArchMode | None

ArchMode enum representing the starting mode (e.g. Thumb for ARM). if None, the default mode of the architecture will be used.

Return type:

Optional[ArchMode]

property architecture: Architecture

Architecture enum representing program architecture.

Return type:

Architecture

property cpustate: Dict[str, int]

Provide the initial cpu state in the forma of a dictionary of {“register_name” : register_value}

property endianness: Endian

Endianness of the loaded program

Returns:

Endianness

property entry_point: tritondse.types.Addr

Program entrypoint address as defined in the binary headers

Return type:

tritondse.types.Addr

find_function_addr(name: str) tritondse.types.Addr | None[source]

Search for the function name in functions of the binary.

Parameters:

name (str) – Function name

Returns:

Address of function if found

Return type:

Addr

imported_functions_relocations() Generator[Tuple[str, tritondse.types.Addr], None, None][source]

Iterate over all imported functions by the program. This function is a generator of tuples associating the function and its relocation address in the binary.

Returns:

Generator of tuples function name and relocation address

imported_variable_symbols_relocations() Generator[Tuple[str, tritondse.types.Addr], None, None][source]

Iterate over all imported variable symbols. Yield for each of them the name and the relocation address in the binary.

Returns:

Generator of tuples with symbol name, relocation address

memory_segments() Generator[LoadableSegment, None, None][source]

Iterate over all memory segments of the program as loaded in memory.

Returns:

Generator of tuples addrs and content

Raises:

NotImplementedError – if the binary format cannot be loaded

property name: str

Name of the loader and target being loaded.

Returns:

str of the loader name

property platform: Platform | None

Platform of the binary.

Returns:

Platform