Misc. Utilities

cle.gdb.convert_info_sharedlibrary(fname)

Convert a dump from gdb’s info sharedlibrary command to a set of options that can be passed to CLE to replicate the address space from the gdb session

Parameters:

fname – The name of a file containing the dump

Returns:

A dict appropriate to be passed as **kwargs for angr.Project or cle.Loader

cle.gdb.convert_info_proc_maps(fname)

Convert a dump from gdb’s info proc maps command to a set of options that can be passed to CLE to replicate the address space from the gdb session

Parameters:

fname – The name of a file containing the dump

Returns:

A dict appropriate to be passed as **kwargs for angr.Project or cle.Loader

class cle.memory.ClemoryBase

Bases: object

The base class of all Clemory classes.

__init__(arch)

load(addr, n)

store(addr, data)

backers(addr=0)

find(data, search_min=None, search_max=None) → Iterator[int]

Return type:

Iterator[int]

unpack(addr: int, fmt: str) → tuple[Any, ...]

Use the struct module to unpack the data at address addr with the format fmt.

Return type:

tuple[Any, ...]

Parameters:

• addr (int)

• fmt (str)

unpack_word(addr: int, size: int | None = None, signed: bool = False, endness: Endness | None = None) → int

Use the struct module to unpack a single integer from the address addr.

You may override any of the attributes of the word being extracted:

Parameters:

• size (int | None) – The size in bytes to pack/unpack. Defaults to wordsize (e.g. 4 bytes on a 32 bit architecture)

• signed (bool) – Whether the data should be extracted signed/unsigned. Default unsigned

• endness (Endness | None) – The endian to use in packing/unpacking. Defaults to memory endness

• addr (int)

Return type:

int

load_null_terminated_bytes(addr: int, max_size: int = 4096) → bytes

Load a null-terminated string from memory at address addr with a maximum size of max_size. Useful

Return type:

bytes

Parameters:

• addr (int)

• max_size (int)

pack(addr: int, fmt: str, *data)

Use the struct module to pack data into memory at address addr with the format fmt.

Parameters:

• addr (int)

• fmt (str)

pack_word(addr: int, data: int, size: int | None = None, signed: bool = False, endness: Endness | None = None)

Use the struct module to pack a single integer data into memory at the address addr.

You may override any of the attributes of the word being packed:

Parameters:

• size (int | None) – The size in bytes to pack/unpack. Defaults to wordsize (e.g. 4 bytes on a 32 bit architecture)

• signed (bool) – Whether the data should be extracted signed/unsigned. Default unsigned

• endness (Endness | None) – The endian to use in packing/unpacking. Defaults to memory endness

• addr (int)

• data (int)

read(nbytes: int)

The stream-like function that reads up to a number of bytes starting from the current position and updates the current position. Use with seek().

Up to nbytes bytes will be read, halting at the beginning of the first unmapped region encountered.

Parameters:

nbytes (int)

seek(value: int)

The stream-like function that sets the “file’s” current position. Use with read().

Parameters:

value (int) – The position to seek to.

tell() → int

Return type:

int

close()

class cle.memory.Clemory

Bases: ClemoryBase

An object representing a memory space.

Accesses can be made with [index] notation.

__init__(arch: Arch, root: bool = False)

Parameters:

• arch (Arch)

• root (bool)

consecutive: bool

min_addr: int

max_addr: int

add_backer(start: int, data: bytes | bytearray | memoryview | list[int] | Clemory | mmap, overwrite: bool = False)

Adds a backer to the memory.

Parameters:

• start (int) – The address where the backer should be loaded.

• data (bytes | bytearray | memoryview | list[int] | Clemory | mmap) – The backer itself. Can be either a bytestring or another Clemory.

• overwrite (bool) – If True and the range overlaps any existing backer, the existing backer will be split up and the overlapping part will be replaced with the new backer.

split_backer(addr: int)

Ensures that addr is the start of a backer, if it is backed.

Parameters:

addr (int)

remove_backer(start)

backers(addr=0) → Iterator[tuple[int, bytearray | memoryview | mmap | list[int]]]

Iterate through each backer for this clemory and all its children, yielding tuples of (start_addr, backer) where each backer is a bytearray.

Parameters:

addr – An optional starting address - all backers before and not including this address will be skipped.

Return type:

Iterator[tuple[int, bytearray | memoryview | mmap | list[int]]]

load(addr, n)

Read up to n bytes at address addr in memory and return a bytes object.

Reading will stop at the beginning of the first unallocated region found, or when n bytes have been read.

store(addr, data)

Write bytes from data at address addr.

Note: If the store runs off the end of a backer and into unbacked space, this function will update the backer but also raise KeyError.

find(data, search_min=None, search_max=None) → Iterator[int]

Find all occurances of a bytestring in memory.

Parameters:

• data (bytes) – The bytestring to search for

• search_min (int) – Optional: The first address to include as valid

• search_max (int) – Optional: The last address to include as valid

Return Iterator[int]:

Iterates over addresses at which the bytestring occurs

Return type:

Iterator[int]

class cle.memory.ClemoryView

Bases: ClemoryBase

A Clemory which presents a subset of another Clemory as an address space.

__init__(backer, start, end, offset=0)

Parameters:

• backer – The parent clemory to use

• start – The address in the parent to start at

• end – The address in the parent to end at (exclusive)

• offset – Where the address space should start in this Clemory. Default 0.

backers(addr=0)

load(addr, n)

store(addr, data)

find(data, search_min=None, search_max=None) → Iterator[int]

Return type:

Iterator[int]

class cle.memory.ClemoryTranslator

Bases: ClemoryBase

Uses a function to translate between address spaces when accessing a child clemory. Intended to be used only as a stream object.

__init__(backer: ClemoryBase, func)

Parameters:

backer (ClemoryBase)

load(addr, n)

store(addr, data)

backers(addr=0)

find(data, search_min=None, search_max=None) → Iterator[int]

Return type:

Iterator[int]

class cle.memory.UninitializedClemory

Bases: Clemory

A special kind of Clemory that acts as a placeholder for uninitialized and invalid memory. This is needed for the PAGEZERO segment for MachO binaries, which is 4GB worth of memory This does _not_ handle data being written to it, this is only for uninitialized memory that is technically occupied but should never be accessed

__init__(arch, size)

max_addr: int

add_backer(start, data, overwrite=False)

Adds a backer to the memory.

Parameters:

• start – The address where the backer should be loaded.

• data – The backer itself. Can be either a bytestring or another Clemory.

• overwrite – If True and the range overlaps any existing backer, the existing backer will be split up and the overlapping part will be replaced with the new backer.

split_backer(addr)

Ensures that addr is the start of a backer, if it is backed.

remove_backer(start)

backers(addr=0)

Technically this object has no real backer We could create a fake backer on demand, but that would be a waste of memory, and code like the function prolog discovery for MachO binaries would search 4GB worth of nullbytes for a prolog, which is a waste of time Instead we just return an empty byte array, which seems to pass the test cases :type addr: :param addr: :return:

load(addr, n)

Read up to n bytes at address addr in memory and return a bytes object.

Reading will stop at the beginning of the first unallocated region found, or when n bytes have been read.

store(addr, data)

Write bytes from data at address addr.

Note: If the store runs off the end of a backer and into unbacked space, this function will update the backer but also raise KeyError.

find(data, search_min=None, search_max=None) → Iterator[int]

The memory has no value, so matter what is searched for, it won’t be found.

Return type:

Iterator[int]

consecutive: bool

min_addr: int

class cle.patched_stream.PatchedStream

Bases: object

An object that wraps a readable stream, performing passthroughs on seek and read operations, except to make it seem like the data has actually been patched by the given patches.

__init__(stream, patches)

Parameters:

• stream – The stream to patch

• patches – A list of tuples of (addr, patch data)

read(*args, **kwargs)

seek(*args, **kwargs)

tell()

close()

class cle.address_translator.AddressTranslator

Bases: object

__init__(rva, owner)

Parameters:

• rva (int) – virtual address relative to owner’s object image base

• owner (cle.Backend) – The object owner address relates to

classmethod from_lva(lva, owner)

Loads address translator with LVA

classmethod from_mva(mva, owner)

Loads address translator with MVA

classmethod from_rva(rva, owner)

Loads address translator with RVA

classmethod from_raw(raw, owner)

Loads address translator with RAW address

classmethod from_linked_va(lva, owner)

Loads address translator with LVA

classmethod from_va(mva, owner)

Loads address translator with MVA

classmethod from_mapped_va(mva, owner)

Loads address translator with MVA

classmethod from_relative_va(rva, owner)

Loads address translator with RVA

to_lva()

VA -> LVA :rtype: int

to_mva()

RVA -> MVA :rtype: int

to_rva()

RVA -> RVA :rtype: int

to_raw()

RVA -> RAW :rtype: int

to_linked_va()

VA -> LVA :rtype: int

to_va()

RVA -> MVA :rtype: int

to_mapped_va()

RVA -> MVA :rtype: int

to_relative_va()

RVA -> RVA :rtype: int

cle.address_translator.AT

alias of AddressTranslator

cle.utils.ALIGN_DOWN(base, size)

cle.utils.ALIGN_UP(base, size)

cle.utils.get_mmaped_data(stream, offset, length, page_size)

cle.utils.stream_or_path(obj, perms='rb')

cle.utils.key_bisect_floor_key(lst, key, lo=0, hi=None, keyfunc=<function <lambda>>)

cle.utils.key_bisect_find(lst, item, lo=0, hi=None, keyfunc=<function <lambda>>)

cle.utils.key_bisect_insort_left(lst, item, lo=0, hi=None, keyfunc=<function <lambda>>)

cle.utils.key_bisect_insort_right(lst, item, lo=0, hi=None, keyfunc=<function <lambda>>)

cle.utils.get_text_offset(path)

Offset of text section in the binary.

cle.utils.extract_null_terminated_bytestr(data: bytes | bytearray, offset: int = 0, sentinel_value: bytes = b'\\x00') → bytes

Return an exclusive null-terminated sequence of bytes at offset in data.

Return type:

bytes

Parameters:

• data (bytes | bytearray)

• offset (int)

• sentinel_value (bytes)