dwarfcore.dwarfcore module

This module contains the DwarfCore class that plugins will use to query DWARF information.

DwarfCore does not actually parse the DWARF information itself. It extracts the information from the MATE CPG.

There could be a difference between what Manticore uses for the VA of a function or location and what DWARF information lists. Care must be taken to make sure that the correct associated VA is used. One case this occurs is when a binary is compiled with a dynamic base address, i.e. position-independent code (PIC) with the ET_DYN ELF attribute. The DWARF information will report from a 0x0 offset, but Manticore loads the code at an arbitrary offset (see Manticore’s Linux.BASE_DYN_ADDR_32 and Linux.BASE_DYN_ADDR constants).

class dwarfcore.dwarfcore.Address

Bases: int

Convenience class for pretty-printing addresses.

class dwarfcore.dwarfcore.DwarfAddress

Bases: dwarfcore.dwarfcore.Address

An address that DWARF debug info uses.

class dwarfcore.dwarfcore.DwarfCore(session: sqlalchemy.orm.session.Session, cpg: mate_query.db.Graph, program_path: pathlib.Path)

Bases: object

Parameters
all_functions() → Dict[dwarfcore.dwarfcore.DwarfAddress, str]

Retrieve all known functions, local and dynamic.

Returns

Mapping of DWARF address to function name

Return type

Dict[dwarfcore.dwarfcore.DwarfAddress, str]

first_insn_writing_to_reg(disasm: capstone.Cs, code: bytes, reg_name: str) → Optional[int]

Find the first instruction that writes to the register reg_name in the given code segment with the given disassembler.

Returns the first offset of the instruction that writes to the register or None if no instructions in the range write to the register

A use case is to find when a function prologue writes to the base pointer register that begins the scope of stack-based variables

Parameters

  • disasm (capstone.Cs) –

  • code (bytes) –

  • reg_name (str) –

Return type

Optional[int]

func_addr_tree() → mate.build.tob_chess_utils.range_avl_tree.RangeAVL

A data structure for fast lookup of mapping from DWARF VA to function name.

This is useful because a function is a _range_ of VAs, and a RangeAVL tree will take care of comparing bounds on the passed VA to find the correct function.

Returns

RangeAVL tree of DWARF VA to function name

Return type

mate.build.tob_chess_utils.range_avl_tree.RangeAVL

func_name_from_va(va: Union[dwarfcore.dwarfcore.ManticoreAddress, manticore.core.smtlib.expression.Expression]) → Optional[str]

Return the mangled function name from a given Manticore VA.

Parameters
Returns

Function name or None

Return type

Optional[str]

last_insn_writing_to_reg(disasm: capstone.Cs, code: bytes, reg_name: str) → Optional[int]

Find the last instruction that writes to the register in the given code segment.

Returns the last offset of the instruction that writes to the register or None if no instructions in the range write to the register

A use case is to find when a function prologue writes to the base pointer register that ends the scope of stack-based variables

Parameters

  • disasm (capstone.Cs) –

  • code (bytes) –

  • reg_name (str) –

Return type

Optional[int]

source_info_from_va(binary_path: str, va: dwarfcore.dwarfcore.ManticoreAddress) → mate.build.tob_chess_utils.dwarf.SourceCodeInfo
Parameters
Return type

mate.build.tob_chess_utils.dwarf.SourceCodeInfo

start_va_of_function(func: str) → Optional[dwarfcore.dwarfcore.DwarfAddress]

Get the start VA (DWARF-VA) of given function or None if not found.

Parameters

  • func – Function name

  • func (str) –

Returns

DWARF VA or None

Return type

Optional[dwarfcore.dwarfcore.DwarfAddress]

start_va_of_function_m(func: str) → Optional[dwarfcore.dwarfcore.ManticoreAddress]

Get the start VA (Manticore-VA) of given function or None if not found.

Parameters

  • func – Function name

  • func (str) –

Returns

Manticore VA or None

Return type

Optional[dwarfcore.dwarfcore.ManticoreAddress]

va_to_func_in_cpg(va: Union[ManticoreAddress, Expression]) → Optional[MachineFunction]

Get the DWARF information for a function, given a Manticore VA.

Parameters
Returns

Function information or None

Return type

Optional[MachineFunction]

variables_at_va(va: Union[dwarfcore.dwarfcore.ManticoreAddress, manticore.core.smtlib.expression.Expression], state: manticore.native.state.State, regfile: Optional[manticore.native.cpu.abstractcpu.RegisterFile] = None) → List[mate.build.tob_chess_utils.dwarf.MantiDwarfTypeInfo]

Get the variables that are in scope at a Manticore VA.

Parameters

  • va – Manticore VA of instruction to be executed

  • state – Manticore state to look up register values

  • regfile – Optional register file to use for register values instead of from state’s

  • va (Union[dwarfcore.dwarfcore.ManticoreAddress, manticore.core.smtlib.expression.Expression]) –

  • state (manticore.native.state.State) –

  • regfile (Optional[manticore.native.cpu.abstractcpu.RegisterFile]) –

Returns

Mapping of variables where keys are “params” and “vars” and the values are custom dictionary that describe the variables

Return type

List[mate.build.tob_chess_utils.dwarf.MantiDwarfTypeInfo]

exception dwarfcore.dwarfcore.DwarfcoreException

Bases: Exception

Generic dwarfcore exception.

class dwarfcore.dwarfcore.ManticoreAddress

Bases: dwarfcore.dwarfcore.Address

An address that Manticore uses.

class dwarfcore.dwarfcore.VariableOperations(read, write)

Bases: tuple

Parameters

  • read (List[str]) –

  • write (List[str]) –

read: List[str]

Alias for field number 0

write: List[str]

Alias for field number 1

dwarfcore.dwarfcore.variables_for_function(session: sqlalchemy.orm.session.Session, cpg: mate_query.db.Graph, func_name: str) → List

Return all variables this function could access during execution.

This includes locals, arguments, and globals

Parameters

  • cpg – CPG handle

  • func_name – Function name to lookup

  • session (sqlalchemy.orm.session.Session) –

  • cpg (mate_query.db.Graph) –

  • func_name (str) –

Returns

List of variables that the function could access

Return type

List