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:
- property cpustate: Dict[str, int]
Provide the initial cpu state in the forma of a dictionary of {“register_name” : register_value}
- property entry_point: tritondse.types.Addr
Program entrypoint address as defined in the binary headers
- Return type:
- find_function_addr(name: str) tritondse.types.Addr | None[source]
Search for the function name in fonctions of the binary.
- Parameters:
name (str) – Function name
- Returns:
Address of function if found
- Return type:
Addr
- property format: EXE_FORMATS
Binary format. Supported formats by lief are: ELF, PE, MachO
- Return type:
lief.EXE_FORMATS
- 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 platform: Platform | None
Platform of the binary. Its 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:
Union[lief.ELF.RELOCATION_AARCH64, lief.ELF.RELOCATION_ARM, lief.ELF.RELOCATION_PPC64, lief.ELF.RELOCATION_PPC, lief.ELF.RELOCATION_i386, lief.ELF.RELOCATION_X86_64]
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:
- property cpustate
Provide the initial cpu state in the forma of a dictionary of {“register_name” : register_value}
- find_function_addr(name: str) int | None[source]
Search for the function name in fonctions 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
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 format: EXE_FORMATS
- 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 ofto. 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
- 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)>
- merge(coverage: CoverageSingleRun)[source]
- 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
- 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
MonolithicLoader
- class tritondse.MonolithicLoader(architecture: Architecture, cpustate: Dict[str, int] = None, maps: List[LoadableSegment] = None, set_thumb: bool = False, platform: Platform = None, endianess: 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:
- property architecture: Architecture
Architecture enum representing program architecture.
- Return type:
- property cpustate: Dict[str, int]
Provide the initial cpu state in the format of a dictionary of {“register_name” : register_value}
- property entry_point: tritondse.types.Addr
Program entrypoint address as defined in the binary headers
- Return type:
- find_function_addr(name: str) tritondse.types.Addr | None
Search for the function name in fonctions 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
Creating a new Loader
- class tritondse.LoadableSegment(address: int, size: int = 0, perms: Perm = Perm.R | W | X, 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.
- 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:
- property cpustate: Dict[str, int]
Provide the initial cpu state in the forma of a dictionary of {“register_name” : register_value}
- property entry_point: tritondse.types.Addr
Program entrypoint address as defined in the binary headers
- Return type:
- find_function_addr(name: str) tritondse.types.Addr | None[source]
Search for the function name in fonctions 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