debuginfo module

binaryninja.debuginfo.DebugFunctionInfo([...])

DebugFunctionInfo collates ground-truth function attributes for use in BinaryNinja's analysis.

binaryninja.debuginfo.DebugInfo(handle)

class DebugInfo provides an interface to both provide and query debug info.

binaryninja.debuginfo.DebugInfoParser(handle)

DebugInfoParser represents the registered parsers and providers of debug information for Binary Ninja.
class DebugFunctionInfo(address: int | None = None, short_name: str | None = None, full_name: str | None = None, raw_name: str | None = None, function_type: Type | None = None, platform: Platform | None = None, components: List[str] | None = None)[source]

Bases: object

DebugFunctionInfo collates ground-truth function attributes for use in BinaryNinja’s analysis.

When contributing function info, provide only what you know - BinaryNinja will figure out everything else that it can.

Functions will not be created if an address is not provided, but are able to be queried by the user from bv.debug_info for later analysis.

Parameters:

  • address (int | None) –

  • short_name (str | None) –

  • full_name (str | None) –

  • raw_name (str | None) –

  • function_type (Type | None) –

  • platform (Platform | None) –

  • components (List[str] | None) –

address: int | None = None
components: List[str] | None = None
full_name: str | None = None
function_type: Type | None = None
platform: Platform | None = None
raw_name: str | None = None
short_name: str | None = None
class DebugInfo(handle: BNDebugInfo)[source]

Bases: object

class DebugInfo provides an interface to both provide and query debug info. The DebugInfo object is used internally by the binary view to which it is applied to determine the attributes of functions, types, and variables that would otherwise be costly to deduce.

DebugInfo objects themselves are independent of binary views; their data can be sourced from any arbitrary binary views and be applied to any other arbitrary binary view. A DebugInfo object can also contain debug info from multiple DebugInfoParsers. This makes it possible to gather debug info that may be distributed across several different formats and files.

DebugInfo cannot be instantiated by the user, instead you must get it from either the binary view (see 'binaryview.BinaryView'.debug_info) or a debug-info parser (see debuginfo.DebugInfoParser.parse_debug_info).

Note

Please note that calling one of add_* functions will not work outside of a debuginfo plugin.

Parameters:

handle (BNDebugInfo) –

add_data_variable(address: int, new_type: Type, name: str | None = None, components: List[str] | None = None) → bool[source]

Adds a data variable scoped under the current parser’s name to the debug info. Optionally, you can provide a path of component names under which that data variable should appear in the symbols sidebar.

Parameters:

  • address (int) –

  • new_type (Type) –

  • name (str | None) –

  • components (List[str] | None) –

Return type:

bool

add_function(new_func: DebugFunctionInfo) → bool[source]

Adds a function scoped under the current parser’s name to the debug info

Parameters:

new_func (DebugFunctionInfo) –

Return type:

bool

add_type(name: str, new_type: Type, components: List[str] | None = None) → bool[source]

Adds a type scoped under the current parser’s name to the debug info. While you’re able to provide a list of components a type should live in, this is currently unused.

Parameters:

  • name (str) –

  • new_type (Type) –

  • components (List[str] | None) –

Return type:

bool

data_variables_from_parser(name: str | None = None) → Iterator[DataVariableAndName][source]

Returns a generator of all data variables provided by a named DebugInfoParser

Parameters:

name (str | None) –

Return type:

Iterator[DataVariableAndName]

functions_from_parser(name: str | None = None) → Iterator[DebugFunctionInfo][source]

Returns a generator of all functions provided by a named DebugInfoParser

Parameters:

name (str | None) –

Return type:

Iterator[DebugFunctionInfo]

get_data_variable_by_address(parser_name: str, address: int) → Tuple[str, Type] | None[source]
Parameters:

  • parser_name (str) –

  • address (int) –

Return type:

Tuple[str, Type] | None

get_data_variable_by_name(parser_name: str, name: str) → Tuple[int, Type] | None[source]
Parameters:

  • parser_name (str) –

  • name (str) –

Return type:

Tuple[int, Type] | None

get_data_variables_by_address(address: int) → List[Tuple[str, Type]][source]

The values in the tuples returned in the list is (DebugInfoParserName, TypeName, type)

Parameters:

address (int) –

Return type:

List[Tuple[str, Type]]

get_data_variables_by_name(name: str) → List[Tuple[str, Type]][source]

The values in the tuples returned in the list is (DebugInfoParserName, address, type)

Parameters:

name (str) –

Return type:

List[Tuple[str, Type]]

get_type_by_name(parser_name: str, name: str) → Type | None[source]
Parameters:

  • parser_name (str) –

  • name (str) –

Return type:

Type | None

get_type_container(parser_name: str) → TypeContainer[source]

Type Container for all types in the DebugInfo that resulted from the parse of the given parser.

Parameters:

parser_name (str) – Name of parser

Returns:

Type Container for types from that parser

Return type:

TypeContainer

get_types_by_name(name: str) → List[Tuple[str, Type]][source]

The first element in the Tuple returned in the list is the name of the debug info parser the type came from

Parameters:

name (str) –

Return type:

List[Tuple[str, Type]]

remove_data_variable_by_address(parser_name: str, address: int)[source]
Parameters:

  • parser_name (str) –

  • address (int) –

remove_function_by_index(parser_name: str, index: int)[source]
Parameters:

  • parser_name (str) –

  • index (int) –

remove_parser_data_variables(parser_name: str)[source]
Parameters:

parser_name (str) –

remove_parser_functions(parser_name: str)[source]
Parameters:

parser_name (str) –

remove_parser_info(parser_name: str)[source]
Parameters:

parser_name (str) –

remove_parser_types(parser_name: str)[source]
Parameters:

parser_name (str) –

remove_type_by_name(parser_name: str, name: str)[source]
Parameters:

  • parser_name (str) –

  • name (str) –

types_from_parser(name: str | None = None) → Iterator[Tuple[str, Type]][source]

Returns a generator of all types provided by a named DebugInfoParser

Parameters:

name (str | None) –

Return type:

Iterator[Tuple[str, Type]]

property data_variables: Iterator[DataVariableAndName]

A generator of all data variables provided by DebugInfoParsers

property functions: Iterator[DebugFunctionInfo]

A generator of all functions provided by DebugInfoParsers

property parsers: Iterator[str]
property types: Iterator[Tuple[str, Type]]

A generator of all types provided by DebugInfoParsers

class DebugInfoParser(handle: BNDebugInfoParser)[source]

Bases: object

DebugInfoParser represents the registered parsers and providers of debug information for Binary Ninja.

The debug information is used by Binary Ninja as ground-truth information about the attributes of functions, types, and variables that Binary Ninja’s analysis pipeline would otherwise work to deduce. By providing debug info, Binary Ninja’s output can be generated quicker, more accurately, and more completely.

A DebugInfoParser consists of:

  1. A name

  2. An is_valid function which takes a binaryview.BinaryView and returns a bool.

  3. A parse function which takes a DebugInfo object and uses the member functions DebugInfo.add_type, DebugInfo.add_function, and DebugInfo.add_data_variable to populate all the info it can.

And finally calling DebugInfoParser.register to register it with the core.

A working example:

import binaryninja as bn

def is_valid(bv: bn.binaryview.BinaryView) -> bool:
        return bv.view_type == "Raw"

def parse_info(debug_info: bn.debuginfo.DebugInfo, bv: bn.binaryview.BinaryView, debug_file: bn.binaryview.BinaryView, progress: Callable[[int, int], bool]) -> None:
        debug_info.add_type("name", bn.types.Type.int(4, True))
        debug_info.add_data_variable(0x1234, bn.types.Type.int(4, True), "name")
        function_info = bn.debuginfo.DebugFunctionInfo(0xadd6355, "short_name", "full_name", "raw_name", bn.types.Type.function(bn.types.Type.int(4, False), None), components=["some", "namespaces"])
        debug_info.add_function(function_info)

bn.debuginfo.DebugInfoParser.register("debug info parser", is_valid, parse_info)

DebugInfo will then be automatically applied to binary views that contain debug information (via the setting analysis.debugInfo.internal), binary views that provide valid external debug info files (analysis.debugInfo.external), or manually fetched/applied as below:

valid_parsers = bn.debuginfo.DebugInfoParser.get_parsers_for_view(bv)
parser = valid_parsers[0]
debug_info = parser.parse_debug_info(bv, bv)  # See docs for why BV is here twice
bv.apply_debug_info(debug_info)

Multiple debug-info parsers can manually contribute debug info for a binary view by simply calling parse_debug_info with the DebugInfo object just returned. This is automatic when opening a binary view with multiple valid debug info parsers. If you wish to set the debug info for a binary view without applying it as well, you can call 'binaryview.BinaryView'.set_debug_info.

Parameters:

handle (BNDebugInfoParser) –

is_valid_for_view(view: BinaryView) → bool[source]

Returns whether this debug-info parser is valid for the provided binary view

Parameters:

view (BinaryView) –

Return type:

bool

parse_debug_info(view: BinaryView, debug_view: BinaryView, debug_info: DebugInfo | None = None, progress: Callable[[int, int], bool] | None = None) → DebugInfo | None[source]

Returns a DebugInfo object populated with debug info by this debug-info parser. Only provide a DebugInfo object if you wish to append to the existing debug info.

Some debug file formats need both the original binaryview.BinaryView (the binary being analyzed/having debug information applied to it) in addition to the binaryview.BinaryView of the file containing the debug information. For formats where you can get all the information you need from a single file, calls to parse_debug_info are required to provide that file for both arguments. For formats where you can get all the information you need from a single file, implementations of parse should only read from the second debug_file parameter and ignore the former.

Parameters:
Return type:

DebugInfo | None

property name: str

Debug-info parser’s name (read-only)