UEFI Firmware#

exception cle.backends.uefi_firmware.UefiDriverLoadError[source]#

Bases: Exception

This error is raised (and caught internally) if the data contained in the UEFI entity tree doesn’t make sense.

__init__(*args, **kwargs)#

__new__(**kwargs)#

args#

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class cle.backends.uefi_firmware.UefiFirmware[source]#

Bases: Backend

A UEFI firmware blob loader. Support is provided by the uefi_firmware package.

is_default = True#

classmethod is_compatible(stream)[source]#: Determine quickly whether this backend can load an object from this stream

__init__(*args, **kwargs) → None[source]#

Parameters:

binary – The path to the binary to load
binary_stream – The open stream to this binary. The reference to this will be held until you call close.
is_main_bin – Whether this binary should be loaded as the main executable

Return type:

None

property arch: Arch#

addr_to_offset(addr: int) → int | None#

Return type:: Optional[int]
Parameters:: addr (int) –

classmethod check_compatibility(spec, obj) → bool#

Performs a minimal static load of spec and returns whether it’s compatible with other_obj

Return type:: bool

classmethod check_magic_compatibility(stream: BinaryIO) → bool#

Check if a stream of bytes contains the same magic number as the main object

Return type:: bool
Parameters:: stream (BinaryIO) –

close() → None#

Return type:: None

contains_addr(addr)#: Is addr in one of the binary’s segments/sections we have loaded? (i.e. is it mapped into memory ?)

property entry#

static extract_soname(path) → str | None#

Extracts the shared object identifier from the path, or returns None if it cannot.

Return type:: Optional[str]

property finalizers: List[int]#: Stub function. Like initializers, but with finalizers.

find_loadable_containing(addr)#

find_section_containing(addr: int) → cle.backends.region.Section | None#

Returns the section that contains addr or None.

Return type:: Optional[Section]
Parameters:: addr (int) –

find_segment_containing(addr: int) → cle.backends.region.Segment | None#

Returns the segment that contains addr, or None.

Return type:: Optional[Segment]
Parameters:: addr (int) –

get_symbol(name: str) → cle.backends.symbol.Symbol | None#

Stub function. Implement to find the symbol with name name.

Return type:: Optional[Symbol]
Parameters:: name (str) –

property image_base_delta#

initial_register_values()#: Deprecated

property initializers: List[int]#: Stub function. Should be overridden by backends that can provide initializer functions that ought to be run before execution reaches the entry point. Addresses should be rebased.

property loader: Loader#

property max_addr: int#: This returns the highest virtual address contained in any loaded segment of the binary.

property min_addr: int#: This returns the lowest virtual address contained in any loaded segment of the binary.

offset_to_addr(offset: int) → int | None#

Return type:: Optional[int]
Parameters:: offset (int) –

rebase(new_base)#: Rebase backend’s regions to the new base where they were mapped by the loader

relocate()#

Apply all resolved relocations to memory.

The meaning of “resolved relocations” is somewhat subtle - there is a linking step which attempts to resolve each relocation, currently only present in the main internal loading function since the calculation of which objects should be available

property sections: Regions[Section]#

property segments: Regions[Segment]#

set_arch(arch)#

property symbols_by_addr#

thread_registers(thread=None) → Dict[str, Any]#

If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This method should return the register file for a given thread (as named in Backend.threads) as a dict mapping register names (as seen in archinfo) to numbers. If the thread is not specified, it should return the context for a “default” thread. If there are no threads, it should return an empty dict.

Return type:: Dict[str, Any]

property threads: List#: If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This property should contain a list of names for these threads, which should be unique.

symbols: List[Symbol]#

imports: typing.Dict[str, 'Relocation']#

relocs: List[Relocation]#

child_objects: List['Backend']#

exception_handlings: List[ExceptionHandling]#

function_hints: List[FunctionHint]#

memory: Clemory#

class cle.backends.uefi_firmware.UefiModulePending[source]#

Bases: object

A worklist entry for the UEFI firmware loader.

name: Optional[str] = None#

pe_image: Optional[bytes] = None#

te_image: Optional[bytes] = None#

build(parent: cle.backends.uefi_firmware.UefiFirmware, guid: uuid.UUID) → cle.backends.uefi_firmware.UefiModuleMixin[source]#

Return type:

UefiModuleMixin

Parameters:

parent (UefiFirmware) –
guid (UUID) –

__init__(name: str | None = None, pe_image: bytes | None = None, te_image: bytes | None = None) → None#

Parameters:

name (str | None) –
pe_image (bytes | None) –
te_image (bytes | None) –

Return type:

None

class cle.backends.uefi_firmware.UefiModuleMixin[source]#

Bases: Backend

A mixin to make other kinds of backends load as UEFI modules.

__init__(*args, guid: uuid.UUID, name: str | None, **kwargs)[source]#

Parameters:

binary – The path to the binary to load
binary_stream – The open stream to this binary. The reference to this will be held until you call close.
is_main_bin – Whether this binary should be loaded as the main executable
guid (UUID) –
name (str | None) –

addr_to_offset(addr: int) → int | None#

Return type:: Optional[int]
Parameters:: addr (int) –

property arch: Arch#

classmethod check_compatibility(spec, obj) → bool#

Performs a minimal static load of spec and returns whether it’s compatible with other_obj

Return type:: bool

classmethod check_magic_compatibility(stream: BinaryIO) → bool#

Check if a stream of bytes contains the same magic number as the main object

Return type:: bool
Parameters:: stream (BinaryIO) –

close() → None#

Return type:: None

contains_addr(addr)#: Is addr in one of the binary’s segments/sections we have loaded? (i.e. is it mapped into memory ?)

property entry#

static extract_soname(path) → str | None#

Extracts the shared object identifier from the path, or returns None if it cannot.

Return type:: Optional[str]

property finalizers: List[int]#: Stub function. Like initializers, but with finalizers.

find_loadable_containing(addr)#

find_section_containing(addr: int) → cle.backends.region.Section | None#

Returns the section that contains addr or None.

Return type:: Optional[Section]
Parameters:: addr (int) –

find_segment_containing(addr: int) → cle.backends.region.Segment | None#

Returns the segment that contains addr, or None.

Return type:: Optional[Segment]
Parameters:: addr (int) –

get_symbol(name: str) → cle.backends.symbol.Symbol | None#

Stub function. Implement to find the symbol with name name.

Return type:: Optional[Symbol]
Parameters:: name (str) –

property image_base_delta#

initial_register_values()#: Deprecated

property initializers: List[int]#: Stub function. Should be overridden by backends that can provide initializer functions that ought to be run before execution reaches the entry point. Addresses should be rebased.

classmethod is_compatible(stream) → bool#

Determine quickly whether this backend can load an object from this stream

Return type:: bool

is_default = False#

property loader: Loader#

property max_addr: int#: This returns the highest virtual address contained in any loaded segment of the binary.

property min_addr: int#: This returns the lowest virtual address contained in any loaded segment of the binary.

offset_to_addr(offset: int) → int | None#

Return type:: Optional[int]
Parameters:: offset (int) –

rebase(new_base)#: Rebase backend’s regions to the new base where they were mapped by the loader

relocate()#

Apply all resolved relocations to memory.

property sections: Regions[Section]#

property segments: Regions[Segment]#

set_arch(arch)#

property symbols_by_addr#

thread_registers(thread=None) → Dict[str, Any]#

Return type:: Dict[str, Any]

property threads: List#: If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This property should contain a list of names for these threads, which should be unique.

symbols: List[Symbol]#

imports: typing.Dict[str, 'Relocation']#

relocs: List[Relocation]#

child_objects: List['Backend']#

exception_handlings: List[ExceptionHandling]#

function_hints: List[FunctionHint]#

memory: Clemory#

class cle.backends.uefi_firmware.UefiPE[source]#

Bases: UefiModuleMixin, PE

A PE file contained in a UEFI image.

__init__(*args, guid: uuid.UUID, name: str | None, **kwargs)#

Parameters:

binary – The path to the binary to load
binary_stream – The open stream to this binary. The reference to this will be held until you call close.
is_main_bin – Whether this binary should be loaded as the main executable
guid (UUID) –
name (str | None) –

addr_to_offset(addr: int) → int | None#

Return type:: Optional[int]
Parameters:: addr (int) –

property arch: Arch#

classmethod check_compatibility(spec, obj)#: Performs a minimal static load of spec and returns whether it’s compatible with other_obj

classmethod check_magic_compatibility(stream)#: Check if a stream of bytes contains the same magic number as the main object

close()#

contains_addr(addr)#: Is addr in one of the binary’s segments/sections we have loaded? (i.e. is it mapped into memory ?)

property entry#

static extract_soname(path) → str | None#

Extracts the shared object identifier from the path, or returns None if it cannot.

Return type:: Optional[str]

property finalizers: List[int]#: Stub function. Like initializers, but with finalizers.

find_loadable_containing(addr)#

find_section_containing(addr: int) → cle.backends.region.Section | None#

Returns the section that contains addr or None.

Return type:: Optional[Section]
Parameters:: addr (int) –

find_segment_containing(addr: int) → cle.backends.region.Segment | None#

Returns the segment that contains addr, or None.

Return type:: Optional[Segment]
Parameters:: addr (int) –

get_symbol(name)#: Look up the symbol with the given name. Symbols can be looked up by ordinal with the name "ordinal.%d" % num

property image_base_delta#

initial_register_values()#: Deprecated

property initializers: List[int]#: Stub function. Should be overridden by backends that can provide initializer functions that ought to be run before execution reaches the entry point. Addresses should be rebased.

static is_compatible(stream)#: Determine quickly whether this backend can load an object from this stream

is_default = True#

property loader: Loader#

property max_addr: int#: This returns the highest virtual address contained in any loaded segment of the binary.

property min_addr: int#: This returns the lowest virtual address contained in any loaded segment of the binary.

offset_to_addr(offset: int) → int | None#

Return type:: Optional[int]
Parameters:: offset (int) –

rebase(new_base)#: Rebase backend’s regions to the new base where they were mapped by the loader

relocate()#

Apply all resolved relocations to memory.

property sections: Regions[Section]#

property segments: Regions[Segment]#

set_arch(arch)#

property symbols_by_addr#

thread_registers(thread=None) → Dict[str, Any]#

Return type:: Dict[str, Any]

property threads: List#: If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This property should contain a list of names for these threads, which should be unique.

symbols: List[Symbol]#

imports: typing.Dict[str, 'Relocation']#

relocs: List[Relocation]#

child_objects: List['Backend']#

exception_handlings: List[ExceptionHandling]#

function_hints: List[FunctionHint]#

memory: Clemory#

class cle.backends.uefi_firmware.UefiTE[source]#

Bases: UefiModuleMixin, TE

A TE file contained in a UEFI image.

__init__(*args, guid: uuid.UUID, name: str | None, **kwargs)#

Parameters:

binary – The path to the binary to load
binary_stream – The open stream to this binary. The reference to this will be held until you call close.
is_main_bin – Whether this binary should be loaded as the main executable
guid (UUID) –
name (str | None) –

addr_to_offset(addr: int) → int | None#

Return type:: Optional[int]
Parameters:: addr (int) –

property arch: Arch#

classmethod check_compatibility(spec, obj) → bool#

Performs a minimal static load of spec and returns whether it’s compatible with other_obj

Return type:: bool

classmethod check_magic_compatibility(stream: BinaryIO) → bool#

Check if a stream of bytes contains the same magic number as the main object

Return type:: bool
Parameters:: stream (BinaryIO) –

close() → None#

Return type:: None

contains_addr(addr)#: Is addr in one of the binary’s segments/sections we have loaded? (i.e. is it mapped into memory ?)

property entry#

static extract_soname(path) → str | None#

Extracts the shared object identifier from the path, or returns None if it cannot.

Return type:: Optional[str]

property finalizers: List[int]#: Stub function. Like initializers, but with finalizers.

find_loadable_containing(addr)#

find_section_containing(addr: int) → cle.backends.region.Section | None#

Returns the section that contains addr or None.

Return type:: Optional[Section]
Parameters:: addr (int) –

find_segment_containing(addr: int) → cle.backends.region.Segment | None#

Returns the segment that contains addr, or None.

Return type:: Optional[Segment]
Parameters:: addr (int) –

get_symbol(name: str) → cle.backends.symbol.Symbol | None#

Stub function. Implement to find the symbol with name name.

Return type:: Optional[Symbol]
Parameters:: name (str) –

property image_base_delta#

initial_register_values()#: Deprecated

property initializers: List[int]#: Stub function. Should be overridden by backends that can provide initializer functions that ought to be run before execution reaches the entry point. Addresses should be rebased.

classmethod is_compatible(stream)#: Determine quickly whether this backend can load an object from this stream

is_default = True#

property loader: Loader#

property max_addr: int#: This returns the highest virtual address contained in any loaded segment of the binary.

property min_addr: int#: This returns the lowest virtual address contained in any loaded segment of the binary.

offset_to_addr(offset: int) → int | None#

Return type:: Optional[int]
Parameters:: offset (int) –

rebase(new_base)#: Rebase backend’s regions to the new base where they were mapped by the loader

relocate()#

Apply all resolved relocations to memory.

property sections: Regions[Section]#

property segments: Regions[Segment]#

set_arch(arch)#

property symbols_by_addr#

thread_registers(thread=None) → Dict[str, Any]#

Return type:: Dict[str, Any]

property threads: List#: If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This property should contain a list of names for these threads, which should be unique.

symbols: List[Symbol]#

imports: typing.Dict[str, 'Relocation']#

relocs: List[Relocation]#

child_objects: List['Backend']#

exception_handlings: List[ExceptionHandling]#

function_hints: List[FunctionHint]#

memory: Clemory#

class cle.backends.te.HeaderType#

Bases: tuple

HeaderType(signature, machine, number_of_sections, subsystem, stripped_size, address_of_entry_point, base_of_code, image_base, data_directory_0_virtual_address, data_directory_0_size, data_directory_1_virtual_address, data_directory_1_size)

static __new__(_cls, signature, machine, number_of_sections, subsystem, stripped_size, address_of_entry_point, base_of_code, image_base, data_directory_0_virtual_address, data_directory_0_size, data_directory_1_virtual_address, data_directory_1_size)#: Create new instance of HeaderType(signature, machine, number_of_sections, subsystem, stripped_size, address_of_entry_point, base_of_code, image_base, data_directory_0_virtual_address, data_directory_0_size, data_directory_1_virtual_address, data_directory_1_size)

address_of_entry_point#: Alias for field number 5

base_of_code#: Alias for field number 6

count(value, /)#: Return number of occurrences of value.

data_directory_0_size#: Alias for field number 9

data_directory_0_virtual_address#: Alias for field number 8

data_directory_1_size#: Alias for field number 11

data_directory_1_virtual_address#: Alias for field number 10

image_base#: Alias for field number 7

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

machine#: Alias for field number 1

number_of_sections#: Alias for field number 2

signature#: Alias for field number 0

stripped_size#: Alias for field number 4

subsystem#: Alias for field number 3

class cle.backends.te.SectionHeaderType#

Bases: tuple

SectionHeaderType(section_name, physical_address_virtual_size, virtual_address, size_of_raw_data, pointer_to_raw_data, pointer_to_relocations, pointer_to_line_numbers, number_of_relocations, number_of_line_numbers, characteristics)

static __new__(_cls, section_name, physical_address_virtual_size, virtual_address, size_of_raw_data, pointer_to_raw_data, pointer_to_relocations, pointer_to_line_numbers, number_of_relocations, number_of_line_numbers, characteristics)#: Create new instance of SectionHeaderType(section_name, physical_address_virtual_size, virtual_address, size_of_raw_data, pointer_to_raw_data, pointer_to_relocations, pointer_to_line_numbers, number_of_relocations, number_of_line_numbers, characteristics)

characteristics#: Alias for field number 9

count(value, /)#: Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

number_of_line_numbers#: Alias for field number 8

number_of_relocations#: Alias for field number 7

physical_address_virtual_size#: Alias for field number 1

pointer_to_line_numbers#: Alias for field number 6

pointer_to_raw_data#: Alias for field number 4

pointer_to_relocations#: Alias for field number 5

section_name#: Alias for field number 0

size_of_raw_data#: Alias for field number 3

virtual_address#: Alias for field number 2

class cle.backends.te.TE[source]#

Bases: Backend

A “Terse Executable” format image, commonly used as part of UEFI firmware drivers.

is_default = True#

classmethod is_compatible(stream)[source]#: Determine quickly whether this backend can load an object from this stream

__init__(*args, **kwargs)[source]#

Parameters:

binary – The path to the binary to load
binary_stream – The open stream to this binary. The reference to this will be held until you call close.
is_main_bin – Whether this binary should be loaded as the main executable

addr_to_offset(addr: int) → int | None#

Return type:: Optional[int]
Parameters:: addr (int) –

property arch: Arch#

classmethod check_compatibility(spec, obj) → bool#

Performs a minimal static load of spec and returns whether it’s compatible with other_obj

Return type:: bool

classmethod check_magic_compatibility(stream: BinaryIO) → bool#

Check if a stream of bytes contains the same magic number as the main object

Return type:: bool
Parameters:: stream (BinaryIO) –

close() → None#

Return type:: None

contains_addr(addr)#: Is addr in one of the binary’s segments/sections we have loaded? (i.e. is it mapped into memory ?)

property entry#

static extract_soname(path) → str | None#

Extracts the shared object identifier from the path, or returns None if it cannot.

Return type:: Optional[str]

property finalizers: List[int]#: Stub function. Like initializers, but with finalizers.

find_loadable_containing(addr)#

find_section_containing(addr: int) → cle.backends.region.Section | None#

Returns the section that contains addr or None.

Return type:: Optional[Section]
Parameters:: addr (int) –

find_segment_containing(addr: int) → cle.backends.region.Segment | None#

Returns the segment that contains addr, or None.

Return type:: Optional[Segment]
Parameters:: addr (int) –

get_symbol(name: str) → cle.backends.symbol.Symbol | None#

Stub function. Implement to find the symbol with name name.

Return type:: Optional[Symbol]
Parameters:: name (str) –

property image_base_delta#

initial_register_values()#: Deprecated

property initializers: List[int]#: Stub function. Should be overridden by backends that can provide initializer functions that ought to be run before execution reaches the entry point. Addresses should be rebased.

property loader: Loader#

property max_addr: int#: This returns the highest virtual address contained in any loaded segment of the binary.

property min_addr: int#: This returns the lowest virtual address contained in any loaded segment of the binary.

offset_to_addr(offset: int) → int | None#

Return type:: Optional[int]
Parameters:: offset (int) –

rebase(new_base)#: Rebase backend’s regions to the new base where they were mapped by the loader

relocate()#

Apply all resolved relocations to memory.

property sections: Regions[Section]#

property segments: Regions[Segment]#

set_arch(arch)#

property symbols_by_addr#

thread_registers(thread=None) → Dict[str, Any]#

Return type:: Dict[str, Any]

property threads: List#: If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This property should contain a list of names for these threads, which should be unique.

symbols: List[Symbol]#

imports: typing.Dict[str, 'Relocation']#

relocs: List[Relocation]#

child_objects: List['Backend']#

exception_handlings: List[ExceptionHandling]#

function_hints: List[FunctionHint]#

memory: Clemory#