diff options
Diffstat (limited to 'python/debuginfo.py')
| -rw-r--r-- | python/debuginfo.py | 108 |
1 files changed, 71 insertions, 37 deletions
diff --git a/python/debuginfo.py b/python/debuginfo.py index 2898fb38..7e189afd 100644 --- a/python/debuginfo.py +++ b/python/debuginfo.py @@ -107,15 +107,17 @@ class _DebugInfoParserMetaClass(type): @staticmethod def _parse_info( - debug_info: core.BNDebugInfo, view: core.BNBinaryView, progress: ProgressFuncType, - callback: Callable[["DebugInfo", 'binaryview.BinaryView'], bool], + debug_info: core.BNDebugInfo, view: core.BNBinaryView, debug_view: core.BNBinaryView, progress: ProgressFuncType, + callback: Callable[["DebugInfo", 'binaryview.BinaryView', 'binaryview.BinaryView', ProgressFuncType], bool], ) -> bool: try: file_metadata = filemetadata.FileMetadata(handle=core.BNGetFileForView(view)) view_obj = binaryview.BinaryView(file_metadata=file_metadata, handle=core.BNNewViewReference(view)) + debug_file_metadata = filemetadata.FileMetadata(handle=core.BNGetFileForView(debug_view)) + debug_view_obj = binaryview.BinaryView(file_metadata=debug_file_metadata, handle=core.BNNewViewReference(debug_view)) parser_ref = core.BNNewDebugInfoReference(debug_info) assert parser_ref is not None, "core.BNNewDebugInfoReference returned None" - return callback(DebugInfo(parser_ref), view_obj, progress) + return callback(DebugInfo(parser_ref), view_obj, debug_view_obj, progress) except: log_error(traceback.format_exc()) return False @@ -123,18 +125,19 @@ class _DebugInfoParserMetaClass(type): @classmethod def register( cls, name: str, is_valid: Callable[['binaryview.BinaryView'], bool], - parse_info: Callable[["DebugInfo", 'binaryview.BinaryView', ProgressFuncType], bool] + parse_info: Callable[["DebugInfo", 'binaryview.BinaryView', 'binaryview.BinaryView', ProgressFuncType], bool] ) -> "DebugInfoParser": """Registers a DebugInfoParser. See ``debuginfo.DebugInfoParser`` for more details.""" binaryninja._init_plugins() - is_valid_cb = ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, - ctypes.POINTER(core.BNBinaryView - ))(lambda ctxt, view: cls._is_valid(view, is_valid)) + is_valid_cb = ctypes.CFUNCTYPE( + ctypes.c_bool, ctypes.c_void_p, ctypes.POINTER(core.BNBinaryView) + )(lambda ctxt, view: cls._is_valid(view, is_valid)) + parse_info_cb = ctypes.CFUNCTYPE( - ctypes.c_bool, ctypes.c_void_p, ctypes.POINTER(core.BNDebugInfo), ctypes.POINTER(core.BNDebugInfo), ctypes.POINTER(core.BNBinaryView), - ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, ctypes.c_size_t, ctypes.c_size_t), ctypes.c_void_p, - )(lambda ctxt, debug_info, view, progress, progress_ctxt: cls._parse_info(debug_info, view, lambda cur, max: progress(progress_ctxt, cur, max), parse_info)) + ctypes.c_bool, ctypes.c_void_p, ctypes.POINTER(core.BNDebugInfo), ctypes.POINTER(core.BNBinaryView), ctypes.POINTER(core.BNBinaryView), + ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, ctypes.c_size_t, ctypes.c_size_t), ctypes.c_void_p, + )(lambda ctxt, debug_info, view, debug_view, progress, progress_ctxt: cls._parse_info(debug_info, view, debug_view, lambda cur, max: progress(progress_ctxt, cur, max), parse_info)) # Don't let our callbacks get garbage collected global _debug_info_parsers @@ -148,7 +151,7 @@ class _DebugInfoParserMetaClass(type): class DebugInfoParser(object, metaclass=_DebugInfoParserMetaClass): """ - :py:class:`DebugInfoParser` represents the registered parsers and providers of debug information to Binary Ninja. + :py:class:`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 @@ -157,7 +160,7 @@ class DebugInfoParser(object, metaclass=_DebugInfoParserMetaClass): A DebugInfoParser consists of: 1. A name - 2. An ``is_valid`` function which takes a BV and returns a bool + 2. An ``is_valid`` function which takes a :py:class:`binaryview.BinaryView` and returns a bool. 3. A ``parse`` function which takes a :py:class:`DebugInfo` object and uses the member functions :py:meth:`DebugInfo.add_type`, :py:meth:`DebugInfo.add_function`, and :py:meth:`DebugInfo.add_data_variable` to populate all the info it can. And finally calling :py:meth:`DebugInfoParser.register` to register it with the core. @@ -169,10 +172,10 @@ class DebugInfoParser(object, metaclass=_DebugInfoParserMetaClass): 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) -> None: + 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(0xdead1337, "short_name", "full_name", "raw_name", bn.types.Type.int(4, False), []) + 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) @@ -181,7 +184,7 @@ class DebugInfoParser(object, metaclass=_DebugInfoParserMetaClass): valid_parsers = bn.debuginfo.DebugInfoParser.get_parsers_for_view(bv) parser = valid_parsers[0] - debug_info = parser.parse_debug_info(bv) + 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 @@ -220,7 +223,13 @@ class DebugInfoParser(object, metaclass=_DebugInfoParserMetaClass): return core.BNIsDebugInfoParserValidForView(self.handle, view.handle) def parse_debug_info(self, view: 'binaryview.BinaryView', debug_view: 'binaryview.BinaryView', debug_info: Optional["DebugInfo"] = None, progress: ProgressFuncType = None) -> Optional["DebugInfo"]: - """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.""" + """ + 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 :py:class:`binaryview.BinaryView` (the binary being analyzed/having debug information applied to it) in addition to the :py:class:`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. + """ if progress is None: progress = lambda cur, max: True progress_c = ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, ctypes.c_size_t, ctypes.c_size_t)(lambda ctxt, cur, max: progress(cur, max)) @@ -242,11 +251,11 @@ class DebugInfoParser(object, metaclass=_DebugInfoParserMetaClass): @dataclass(frozen=True) class DebugFunctionInfo(object): """ - ``DebugFunctionInfo`` collates ground-truth function-external attributes for use in BinaryNinja's internal analysis. + ``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, as it usually does. + 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 will be able to be queried from debug info for later user analysis. + 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. """ address: Optional[int] = None short_name: Optional[str] = None @@ -254,6 +263,7 @@ class DebugFunctionInfo(object): raw_name: Optional[str] = None function_type: Optional[_types.Type] = None platform: Optional['_platform.Platform'] = None + components: Optional[List[str]] = None def __repr__(self) -> str: suffix = f"@{self.address:#x}>" if self.address != 0 else ">" @@ -278,7 +288,7 @@ class DebugInfo(object): 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 get it from either the binary view (see ``'binaryview.BinaryView'.debug_info``) + 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. @@ -289,10 +299,6 @@ class DebugInfo(object): def __del__(self) -> None: core.BNFreeDebugInfoReference(self.handle) - def get_parsers(self) -> List[str]: - """Kept for backward compatibility. Use ``parsers`` property instead.""" - return self.parsers - @property def parsers(self) -> List[str]: count = ctypes.c_ulonglong() @@ -303,7 +309,6 @@ class DebugInfo(object): finally: core.BNFreeStringList(parsers, count.value) - def get_type_container(self, parser_name: str) -> 'typecontainer.TypeContainer': """ Type Container for all types in the DebugInfo that resulted from the parse of @@ -336,20 +341,25 @@ class DebugInfo(object): try: assert functions is not None, "core.BNGetDebugFunctions returned None" for i in range(0, count.value): + function = functions[i] - if functions[i].type: - function_type = _types.Type.create(core.BNNewTypeReference(functions[i].type)) + if function.type: + function_type = _types.Type.create(core.BNNewTypeReference(function.type)) else: function_type = None - if functions[i].platform: - func_platform = _platform.Platform(handle=core.BNNewPlatformReference(functions[i].platform)) + if function.platform: + func_platform = _platform.Platform(handle=core.BNNewPlatformReference(function.platform)) else: func_platform = None + components = [] + for c in range(0, function.componentN): + components.append(function.components[c]) + yield DebugFunctionInfo( - functions[i].address, functions[i].shortName, functions[i].fullName, functions[i].rawName, - function_type, func_platform + function.address, function.shortName, function.fullName, function.rawName, + function_type, func_platform, components ) finally: core.BNFreeDebugFunctions(functions, count.value) @@ -467,10 +477,16 @@ class DebugInfo(object): def remove_data_variable_by_address(self, parser_name: str, address: int): return core.BNRemoveDebugDataVariableByAddress(self.handle, parser_name, address) - def add_type(self, name: str, new_type: '_types.Type') -> bool: - """Adds a type scoped under the current parser's name to the debug info""" + def add_type(self, name: str, new_type: '_types.Type', components: Optional[List[str]] = None) -> bool: + """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.""" + if components is None: + components = [] + component_list = (ctypes.c_char_p * len(components))() + for i in range(0, len(components)): + component_list[i] = str(components[i]).encode('charmap') + if isinstance(new_type, _types.Type): - return core.BNAddDebugType(self.handle, name, new_type.handle) + return core.BNAddDebugType(self.handle, name, new_type.handle, component_list, len(components)) return NotImplemented def add_function(self, new_func: DebugFunctionInfo) -> bool: @@ -494,6 +510,18 @@ class DebugInfo(object): else: return NotImplemented + if new_func.components is None: + components = [] + elif isinstance(new_func.components, list): + components = new_func.components + else: + return NotImplemented + component_list = (ctypes.c_char_p * len(components))() + for c in range(0, len(components)): + component_list[c] = str(components[c]).encode('charmap') + func_info.components = component_list + func_info.componentN = len(components) + func_info.shortName = new_func.short_name func_info.fullName = new_func.full_name func_info.rawName = new_func.raw_name @@ -501,8 +529,14 @@ class DebugInfo(object): return core.BNAddDebugFunction(self.handle, func_info) - def add_data_variable(self, address: int, new_type: '_types.Type', name: Optional[str] = None) -> bool: - """Adds a data variable scoped under the current parser's name to the debug info""" + def add_data_variable(self, address: int, new_type: '_types.Type', name: Optional[str] = None, components: Optional[List[str]] = None) -> bool: + """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.""" + if components is None: + components = [] + component_list = (ctypes.c_char_p * len(components))() + for i in range(0, len(components)): + component_list[i] = str(components[i]).encode('charmap') + if isinstance(address, int) and isinstance(new_type, _types.Type): - return core.BNAddDebugDataVariable(self.handle, address, new_type.handle, name) + return core.BNAddDebugDataVariable(self.handle, address, new_type.handle, name, component_list, len(components)) return NotImplemented |