mate.build.tob_chess_utils.dwarf module

A utility model containing functions and classes related to parsing and interpreting DWARF information.

class mate.build.tob_chess_utils.dwarf.DWARFAddrLocation(address: int)

Bases: object

Represents a DWARF address location.

Parameters

address (int) –

Return type

None

address: int

The address location

class mate.build.tob_chess_utils.dwarf.DWARFRegLocation(reg: str, offset: Optional[int] = None, va_start: Optional[int] = None, va_end: Optional[int] = None)

Bases: object

Represents an DWARF program location based on a register.

Parameters

  • reg (str) –

  • offset (Optional[int]) –

  • va_start (Optional[int]) –

  • va_end (Optional[int]) –

Return type

None

offset: Optional[int] = None

The offset from the base register.

reg: str

The base register for the location computation.

va_end: Optional[int] = None

The ending VA for this location to be valid

va_start: Optional[int] = None

The beginning VA for this location to be valid

class mate.build.tob_chess_utils.dwarf.FieldOffset(offset: 'int', field: 'UnrolledField')

Bases: object

Parameters
Return type

None

field: mate.build.tob_chess_utils.dwarf.UnrolledField
offset: int
class mate.build.tob_chess_utils.dwarf.LocationListWalker(cu_base, location_list)

Bases: object

A helper class for iterating over DWARF location lists, yielding accurate base addresses for each entry.

locations()
class mate.build.tob_chess_utils.dwarf.MantiDwarfTypeInfo(name: 'str', base_type: 'str', base_type_size: 'int', total_size: 'int', common: 'DWARFTypeCommonInfo', locations: 'Optional[List[Union[DWARFRegLocation, DWARFAddrLocation]]]' = None, recursive: 'bool' = False, scope: 'Optional[ScopeInfo]' = None, parent_var: 'Optional[MantiDwarfTypeInfo]' = None, child_vars: 'Optional[Union[List[MantiDwarfTypeInfo], str]]' = None, ele_count: 'int' = 1, is_vla: 'bool' = False, indirections: 'int' = 0, location_conc: 'Optional[List[int]]' = None, values: 'Optional[List[int]]' = None)

Bases: object

Parameters
Return type

None

base_type: str
base_type_size: int

ele_count * base_type_size

child_vars: Optional[Union[List[mate.build.tob_chess_utils.dwarf.MantiDwarfTypeInfo], str]] = None

For arrays

common: mate_common.models.cpg_types.dwarf.DWARFTypeCommonInfo
ele_count: int = 1
indirections: int = 0

For run-time location info

is_vla: bool = False

For pointers

location_conc: Optional[List[int]] = None

For run-time value info

locations: Optional[List[Union[mate.build.tob_chess_utils.dwarf.DWARFRegLocation, mate.build.tob_chess_utils.dwarf.DWARFAddrLocation]]] = None
name: str
parent_var: Optional[mate.build.tob_chess_utils.dwarf.MantiDwarfTypeInfo] = None
recursive: bool = False
scope: Optional[mate.build.tob_chess_utils.dwarf.ScopeInfo] = None

For structs

total_size: int
values: Optional[List[int]] = None
class mate.build.tob_chess_utils.dwarf.ScopeInfo(va_start: int, va_end: int, contiguous: bool)

Bases: object

Represents some information about a DWARF scope.

Parameters

  • va_start (int) –

  • va_end (int) –

  • contiguous (bool) –

Return type

None

contiguous: bool

Whether or not the scope is contiguous, i.e., whether every address in [va_start, va_end) is in the scope.

va_end: int

The virtual address that the scope ends at (exclusive).

va_start: int

The virtual address that the scope begins at (inclusive).

class mate.build.tob_chess_utils.dwarf.SourceCodeInfo(path: 'str', line: 'int')

Bases: object

Parameters

  • path (str) –

  • line (int) –

Return type

None

property file
line: int
path: str
class mate.build.tob_chess_utils.dwarf.UnrolledField(name: 'UnrolledFieldName', size: 'int', padding: 'bool' = False)

Bases: object

Parameters
Return type

None

name: mate.build.tob_chess_utils.dwarf.UnrolledFieldName
padding: bool = False
size: int
class mate.build.tob_chess_utils.dwarf.UnrolledFieldName(nest_name: 'str', field_name: 'str')

Bases: object

Parameters

  • nest_name (str) –

  • field_name (str) –

Return type

None

field_name: str
property full_name: str
nest_name: str
class mate.build.tob_chess_utils.dwarf.UnrolledTypeInfo(name: 'str', total_size: 'int', field_offsets: 'List[FieldOffset]' = <factory>)

Bases: object

Parameters
Return type

None

field_offsets: List[mate.build.tob_chess_utils.dwarf.FieldOffset]
name: str
total_size: int
mate.build.tob_chess_utils.dwarf.all_cus(dwarf: elftools.dwarf.dwarfinfo.DWARFInfo) → List[elftools.dwarf.compileunit.CompileUnit]

Given a DWARFInfo, returns all compilation unit DIEs.

Parameters

dwarf (elftools.dwarf.dwarfinfo.DWARFInfo) –

Return type

List[elftools.dwarf.compileunit.CompileUnit]

mate.build.tob_chess_utils.dwarf.all_dies(dwarf: elftools.dwarf.dwarfinfo.DWARFInfo) → List[elftools.dwarf.die.DIE]

Returns every single child DIE in every single compilation unit in the given DWARFInfo, including null DIEs.

Parameters

dwarf (elftools.dwarf.dwarfinfo.DWARFInfo) –

Return type

List[elftools.dwarf.die.DIE]

mate.build.tob_chess_utils.dwarf.collect_param_dies(func_dies: Collection[elftools.dwarf.die.DIE]) → Tuple[List[Set[elftools.dwarf.die.DIE]], List[Set[elftools.dwarf.die.DIE]]]

Given a set of DIEs for a particular function, return a list of sets of DIEs for each parameter to that function, as well as a list of sets of DIEs corresponding to the function’s template parameter packs (if it has any).

Parameters

func_dies (Collection[elftools.dwarf.die.DIE]) –

Return type

Tuple[List[Set[elftools.dwarf.die.DIE]], List[Set[elftools.dwarf.die.DIE]]]

mate.build.tob_chess_utils.dwarf.collect_scoped_vars(die: elftools.dwarf.die.DIE) → List[elftools.dwarf.die.DIE]

Given a DIE, recursively traverse its children and collect all child DW_TAG_variables.

Parameters

die (elftools.dwarf.die.DIE) –

Return type

List[elftools.dwarf.die.DIE]

mate.build.tob_chess_utils.dwarf.cpg_dwarf_unroll_type_info(session: Session, cpg: CPG, dwarf_type: DWARFType) → Optional[UnrolledTypeInfo]

This function uses the MATE CPG to return unrolled type information that Manticore can use (via dwarfcore).

Parameters

  • cpg – Connection to CPG

  • dwarf_type – The type to retrieve unrolled variable type information for

  • session (Session) –

  • cpg (CPG) –

  • dwarf_type (DWARFType) –

Returns

Type information

Return type

Optional[UnrolledTypeInfo]

mate.build.tob_chess_utils.dwarf.decode_global_location(var_die: elftools.dwarf.die.DIE, dwarf: elftools.dwarf.dwarfinfo.DWARFInfo) → List[Dict[str, Any]]

Given a DIE for a global variable, return a representation of that global’s DWARF location expression.

Parameters

  • var_die (elftools.dwarf.die.DIE) –

  • dwarf (elftools.dwarf.dwarfinfo.DWARFInfo) –

Return type

List[Dict[str, Any]]

mate.build.tob_chess_utils.dwarf.decode_locations(attr, dwarf: elftools.dwarf.dwarfinfo.DWARFInfo, parent_loc: Optional[List[int]] = None, var_name: str = '<unknown>', arch: str = 'x64') → List[Dict[str, Any]]

Turn a DW_AT_location into a list of location specifications.

A DW_AT_location is either:

  1. a location expression, which is decoded by the dwarflang into a register + an offset, or

  2. an offset into the location lists which has to be looked up, and becomes a list of location expressions as described below.

Because the value of registers can change over the lifetime of the program, this function returns a list of locations, each of which specifies the program counter range in which the location is valid (begin_offset to end_offset).

Parameters

  • dwarf (elftools.dwarf.dwarfinfo.DWARFInfo) –

  • parent_loc (Optional[List[int]]) –

  • var_name (str) –

  • arch (str) –

Return type

List[Dict[str, Any]]

mate.build.tob_chess_utils.dwarf.decode_scope(var_dies: Collection[elftools.dwarf.die.DIE]) → Dict[str, Any]

Given a set of DIEs corresponding to a local variable or parameter, determine the (maximal) VA range for which the underlying variable is in scope.

Parameters

var_dies (Collection[elftools.dwarf.die.DIE]) –

Return type

Dict[str, Any]

mate.build.tob_chess_utils.dwarf.die_name(die: elftools.dwarf.die.DIE) → Optional[str]

Return a sensible name for this DIE, or None if this DIE doesn’t have a DW_AT_linkage_name or DW_AT_name.

Parameters

die (elftools.dwarf.die.DIE) –

Return type

Optional[str]

mate.build.tob_chess_utils.dwarf.dies_attribute_many(dies: Collection[elftools.dwarf.die.DIE], name: str) → List[elftools.dwarf.die.AttributeValue]

Returns zero or more AttributeValues from an iterable of semantically linked DIEs.

Parameters

  • dies (Collection[elftools.dwarf.die.DIE]) –

  • name (str) –

Return type

List[elftools.dwarf.die.AttributeValue]

mate.build.tob_chess_utils.dwarf.dies_attribute_one(dies: Collection[elftools.dwarf.die.DIE], name: str) → Optional[elftools.dwarf.die.AttributeValue]

Returns exactly one AttributeValue from an iterable of semantically linked DIEs, or None under the following conditions:

  1. None of the linked DIEs contain the attribute

  2. One or more of the DIEs disagree about the value of the attribute

Parameters

  • dies (Collection[elftools.dwarf.die.DIE]) –

  • name (str) –

Return type

Optional[elftools.dwarf.die.AttributeValue]

mate.build.tob_chess_utils.dwarf.dies_attribute_one_value(dies: Collection[elftools.dwarf.die.DIE], name: str) → Optional[Any]

Like dies_attribute_one, but returns the underlying attribute value directly instead of the AttributeValue container.

Returns None under the same conditons as dies_attribute_one.

Parameters

  • dies (Collection[elftools.dwarf.die.DIE]) –

  • name (str) –

Return type

Optional[Any]

mate.build.tob_chess_utils.dwarf.dwarf_expr_as_value(expr: List[dwarflang.ast.DwarfInstr], parent_loc_expr: Optional[List[dwarflang.ast.DwarfInstr]] = None, arch: str = 'x64') → Optional[Union[str, Tuple[str, int]]]

Return a representation of this DWARF expression as a value.

This only works if the expression is length 1 (a single instruction), and that instruction is one of the various DW_OP_(b?)reg([0-9]+) registers.

It may return:

  • The name of a register, in which case the value of the expression is the value stored in register

  • A (register name, offset) pair, in which case the value of the expression is a pointer equal to the value stored in that register plus an offset

  • None, if the expression is more complex

Parameters
Return type

Optional[Union[str, Tuple[str, int]]]

mate.build.tob_chess_utils.dwarf.dwarf_getattr(die: elftools.dwarf.die.DIE, name: str, default: Optional[Any] = None) → Optional[Any]

Extracts the value from a DWARF DIE’s attributures by name, returning the specified default if no such attribute exists.

Parameters

  • die (elftools.dwarf.die.DIE) –

  • name (str) –

  • default (Optional[Any]) –

Return type

Optional[Any]

mate.build.tob_chess_utils.dwarf.dwarf_reg_to_machine_reg(opcode_name: str, arch='x64') → str

Change a DW_OP_(b?)reg([0-9]+) to the name of an x86(_64)? register.

arch may be "x64" or "x86".

Parameters

opcode_name (str) –

Return type

str

mate.build.tob_chess_utils.dwarf.get_referent_die(die: elftools.dwarf.die.DIE, referent_attr: str) → Optional[elftools.dwarf.die.DIE]

Given a DIE containing an attribute that references another DIE, attempt to return the referenced DIE.

Returns None if the DIE can’t be found.

Parameters

  • die (elftools.dwarf.die.DIE) –

  • referent_attr (str) –

Return type

Optional[elftools.dwarf.die.DIE]

mate.build.tob_chess_utils.dwarf.global_dies_map(dwarf: elftools.dwarf.dwarfinfo.DWARFInfo, externals=True) → Dict[str, List[elftools.dwarf.die.DIE]]

Return a mapping of global variable names to their DIE entries.

Parameters

dwarf (elftools.dwarf.dwarfinfo.DWARFInfo) –

Return type

Dict[str, List[elftools.dwarf.die.DIE]]

mate.build.tob_chess_utils.dwarf.is_block_inlined(block_die: elftools.dwarf.die.DIE) → bool

Walks up a “block”-type DIE (e.g. scope)’s parents to the nearest function, returning whether or not that function has been inlined by the compiler.

Parameters

block_die (elftools.dwarf.die.DIE) –

Return type

bool

mate.build.tob_chess_utils.dwarf.is_external_declaration(die: elftools.dwarf.die.DIE) → bool

Returns whether or not the given DIE corresponds to an external declaration.

Parameters

die (elftools.dwarf.die.DIE) –

Return type

bool

mate.build.tob_chess_utils.dwarf.offset_die_map(dwarf: elftools.dwarf.dwarfinfo.DWARFInfo) → Dict[int, elftools.dwarf.die.DIE]

Returns a mapping of offset -> DIE for all non-trivial (i.e., non- null) DIEs in the supplied DWARFInfo.

Parameters

dwarf (elftools.dwarf.dwarfinfo.DWARFInfo) –

Return type

Dict[int, elftools.dwarf.die.DIE]

mate.build.tob_chess_utils.dwarf.real_dwarf_scope_end(session: Session, cpg: CPG, func_name: str, dwarf_scope: DWARFScope)
Parameters

  • session (Session) –

  • cpg (CPG) –

  • func_name (str) –

  • dwarf_scope (DWARFScope) –

mate.build.tob_chess_utils.dwarf.ref_to_stream_off(ref: elftools.dwarf.die.AttributeValue, cu: elftools.dwarf.compileunit.CompileUnit) → int

Converts a DWARF reference (in attribute form) into an appropriate offset into the containing .debug_info stream.

Parameters

  • ref (elftools.dwarf.die.AttributeValue) –

  • cu (elftools.dwarf.compileunit.CompileUnit) –

Return type

int

mate.build.tob_chess_utils.dwarf.source_info_from_va(_session: mate_query.db.Session, _cpg: mate_query.db.Graph, binary_path: str, va: int) → mate.build.tob_chess_utils.dwarf.SourceCodeInfo

Retrieve source code information given an VA.

Parameters
Returns

Source Code info

Return type

mate.build.tob_chess_utils.dwarf.SourceCodeInfo

mate.build.tob_chess_utils.dwarf.summarize_func_dies(_func_name: str, func_dies: Collection[elftools.dwarf.die.DIE], dwarf: elftools.dwarf.dwarfinfo.DWARFInfo, arch='x64')
Parameters

  • _func_name (str) –

  • func_dies (Collection[elftools.dwarf.die.DIE]) –

  • dwarf (elftools.dwarf.dwarfinfo.DWARFInfo) –

mate.build.tob_chess_utils.dwarf.summarize_local_var(var_dies: Collection[elftools.dwarf.die.DIE], dwarf: elftools.dwarf.dwarfinfo.DWARFInfo, parent_loc: Optional[List[int]], arch='x64') → Dict[str, Any]

Summarize a parameter or local variable from a set of associated DIEs.

Parameters

  • var_dies (Collection[elftools.dwarf.die.DIE]) –

  • dwarf (elftools.dwarf.dwarfinfo.DWARFInfo) –

  • parent_loc (Optional[List[int]]) –

Return type

Dict[str, Any]

mate.build.tob_chess_utils.dwarf.summarize_params(param_dicts, _param_pack_dies_list)
mate.build.tob_chess_utils.dwarf.type_info_to_manti_info(session: Session, cpg: CPG, type_info: DWARFType, parent_var=None, indirections=0) → MantiDwarfTypeInfo
Parameters
Return type

MantiDwarfTypeInfo

mate.build.tob_chess_utils.dwarf.unroll_nested_type_fields(typ: mate.build.tob_chess_utils.dwarf.MantiDwarfTypeInfo) → mate.build.tob_chess_utils.dwarf.UnrolledTypeInfo

Unroll an object that has fields, including nested structs into a single level representation of the fields contained within that object.

Parameters
Returns

An unrolled representation of a type

Return type

mate.build.tob_chess_utils.dwarf.UnrolledTypeInfo

mate.build.tob_chess_utils.dwarf.va_dies_map(dwarf) → Dict[int, Set[elftools.dwarf.die.DIE]]

Returns a mapping of function VAs to a set of DIEs for each function.

Return type

Dict[int, Set[elftools.dwarf.die.DIE]]

mate.build.tob_chess_utils.dwarf.var_info_to_manti_info(session: Session, cpg, cpg_var: Union[DWARFLocalVariable, DWARFArgument, ASMGlobalVariable], cpg_func: Optional[MachineFunction] = None) → MantiDwarfTypeInfo

Fill out the MantiDwarfTypeInfo struct from the CPG variable Node.

Parameters
Returns

Type that Manticore can handle

Return type

MantiDwarfTypeInfo