CGC

class cle.backends.cgc.CGC

Bases: ELF

Backend to support the CGC elf format used by the Cyber Grand Challenge competition.

See : https://github.com/CyberGrandChallenge/libcgcef/blob/master/cgc_executable_format.md

is_default = True

__init__(binary, binary_stream, *args, **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

static is_compatible(stream)

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

supported_filetypes = ['cgc']

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_arch(reader)

static extract_soname(path)

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

property finalizers

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(symid, symbol_table=None)

Gets a Symbol object for the specified symbol.

Parameters:

symid – Either an index into .dynsym or the name of a symbol.

property image_base_delta

initial_register_values()

Deprecated

property initializers

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 is_ppc64_abiv1

Returns whether the arch is PowerPC64 ABIv1.

Returns:

True if PowerPC64 ABIv1, False otherwise.

property is_ppc64_abiv2

Returns whether the arch is PowerPC64 ABIv2.

Returns:

True if PowerPC64 ABIv2, False otherwise.

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) –

property plt

Maps names to addresses.

property ppc64_initial_rtoc

Get initial rtoc value for PowerPC64 architecture.

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 reverse_plt

Maps addresses to names.

property sections: Regions[Section]

property segments: Regions[Segment]

set_arch(arch)

property symbols_by_addr

property symbols_by_name

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.cgc.BackedCGC

Bases: CGC

This is a backend for CGC executables that allows user provide a memory backer and a register backer as the initial state of the running binary.

is_default = True

__init__(*args, memory_backer=None, register_backer=None, writes_backer=None, permissions_map=None, current_allocation_base=None, **kwargs)

Parameters:

• path – File path to CGC executable.

• memory_backer – A dict of memory content, with beginning address of each segment as key and actual memory content as data.

• register_backer – A dict of all register contents. EIP will be used as the entry point of this executable.

• permissions_map – A dict of memory region to permission flags

• current_allocation_base – An integer representing the current address of the top of the CGC heap.

static is_compatible(stream)

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

property threads

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.

thread_registers(thread=None)

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.

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_arch(reader)

static extract_soname(path)

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

property finalizers

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(symid, symbol_table=None)

Gets a Symbol object for the specified symbol.

Parameters:

symid – Either an index into .dynsym or the name of a symbol.

property image_base_delta

initial_register_values()

Deprecated

property initializers

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 is_ppc64_abiv1

Returns whether the arch is PowerPC64 ABIv1.

Returns:

True if PowerPC64 ABIv1, False otherwise.

property is_ppc64_abiv2

Returns whether the arch is PowerPC64 ABIv2.

Returns:

True if PowerPC64 ABIv2, False otherwise.

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) –

property plt

Maps names to addresses.

property ppc64_initial_rtoc

Get initial rtoc value for PowerPC64 architecture.

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 reverse_plt

Maps addresses to names.

property sections: Regions[Section]

property segments: Regions[Segment]

set_arch(arch)

supported_filetypes = ['cgc']

property symbols_by_addr

property symbols_by_name

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

addr_to_line: SortedDict[int, Set[Tuple[int, int]]]

variables: Optional[List[Variable]]

compilation_units: Optional[List[CompilationUnit]]

class cle.backends.cgc.cgc.CGC

Bases: ELF

Backend to support the CGC elf format used by the Cyber Grand Challenge competition.

See : https://github.com/CyberGrandChallenge/libcgcef/blob/master/cgc_executable_format.md

is_default = True

__init__(binary, binary_stream, *args, **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

static is_compatible(stream)

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

supported_filetypes = ['cgc']

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_arch(reader)

static extract_soname(path)

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

property finalizers

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(symid, symbol_table=None)

Gets a Symbol object for the specified symbol.

Parameters:

symid – Either an index into .dynsym or the name of a symbol.

property image_base_delta

initial_register_values()

Deprecated

property initializers

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 is_ppc64_abiv1

Returns whether the arch is PowerPC64 ABIv1.

Returns:

True if PowerPC64 ABIv1, False otherwise.

property is_ppc64_abiv2

Returns whether the arch is PowerPC64 ABIv2.

Returns:

True if PowerPC64 ABIv2, False otherwise.

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) –

property plt

Maps names to addresses.

property ppc64_initial_rtoc

Get initial rtoc value for PowerPC64 architecture.

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 reverse_plt

Maps addresses to names.

property sections: Regions[Section]

property segments: Regions[Segment]

set_arch(arch)

property symbols_by_addr

property symbols_by_name

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

addr_to_line: SortedDict[int, Set[Tuple[int, int]]]

variables: Optional[List[Variable]]

compilation_units: Optional[List[CompilationUnit]]

class cle.backends.cgc.backedcgc.FakeSegment

Bases: Segment

__init__(start, size)

property is_readable: bool

property is_writable: bool

property is_executable: bool

addr_to_offset(addr)

Convert a virtual memory address into a file offset

contains_addr(addr)

Does this region contain this virtual address?

contains_offset(offset)

Does this region contain this offset into the file?

property max_addr

The maximum virtual address of this region

property max_offset

The maximum file offset of this region

property min_addr

The minimum virtual address of this region

min_offset()

The minimum file offset of this region

offset_to_addr(offset)

Convert a file offset into a virtual memory address

vaddr: int

memsize: int

filesize: int

class cle.backends.cgc.backedcgc.BackedCGC

Bases: CGC

This is a backend for CGC executables that allows user provide a memory backer and a register backer as the initial state of the running binary.

is_default = True

__init__(*args, memory_backer=None, register_backer=None, writes_backer=None, permissions_map=None, current_allocation_base=None, **kwargs)

Parameters:

• path – File path to CGC executable.

• memory_backer – A dict of memory content, with beginning address of each segment as key and actual memory content as data.

• register_backer – A dict of all register contents. EIP will be used as the entry point of this executable.

• permissions_map – A dict of memory region to permission flags

• current_allocation_base – An integer representing the current address of the top of the CGC heap.

static is_compatible(stream)

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

property threads

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.

thread_registers(thread=None)

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.

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_arch(reader)

static extract_soname(path)

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

property finalizers

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(symid, symbol_table=None)

Gets a Symbol object for the specified symbol.

Parameters:

symid – Either an index into .dynsym or the name of a symbol.

property image_base_delta

initial_register_values()

Deprecated

property initializers

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 is_ppc64_abiv1

Returns whether the arch is PowerPC64 ABIv1.

Returns:

True if PowerPC64 ABIv1, False otherwise.

property is_ppc64_abiv2

Returns whether the arch is PowerPC64 ABIv2.

Returns:

True if PowerPC64 ABIv2, False otherwise.

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) –

property plt

Maps names to addresses.

property ppc64_initial_rtoc

Get initial rtoc value for PowerPC64 architecture.

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 reverse_plt

Maps addresses to names.

property sections: Regions[Section]

property segments: Regions[Segment]

set_arch(arch)

supported_filetypes = ['cgc']

property symbols_by_addr

property symbols_by_name

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

addr_to_line: SortedDict[int, Set[Tuple[int, int]]]

variables: Optional[List[Variable]]

compilation_units: Optional[List[CompilationUnit]]