Source code for binaryninja.typeparser

# Copyright (c) 2015-2024 Vector 35 Inc
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

import abc
import ctypes
import dataclasses
from json import dumps
from typing import List, Tuple, Optional, Dict

import sys
import traceback

# Binary Ninja Components
import binaryninja
import binaryninja._binaryninjacore as core

from .settings import Settings
from . import binaryview
from . import platform
from . import typecontainer
from . import types
from . import deprecation
from .log import log_error
from .enums import TypeParserErrorSeverity, TypeParserOption


[docs] @dataclasses.dataclass(frozen=True) class QualifiedNameTypeAndId: name: 'types.QualifiedNameType' id: str type: 'types.Type' @classmethod def _from_core_struct(cls, struct: core.BNQualifiedNameTypeAndId) -> 'QualifiedNameTypeAndId': name = types.QualifiedName._from_core_struct(struct.name) type = types.Type.create(handle=core.BNNewTypeReference(struct.type)) return QualifiedNameTypeAndId(name, struct.id, type) def _to_core_struct(self) -> core.BNQualifiedNameTypeAndId: result = core.BNQualifiedNameTypeAndId() result.name = types.QualifiedName(self.name)._to_core_struct() result.type = core.BNNewTypeReference(self.type.handle) result.id = self.id return result
[docs] @dataclasses.dataclass(frozen=True) class TypeParserError: severity: TypeParserErrorSeverity message: str file_name: str line: int column: int def __str__(self): text = "" if self.severity == TypeParserErrorSeverity.ErrorSeverity \ or self.severity == TypeParserErrorSeverity.FatalSeverity: text += "error: " if self.severity == TypeParserErrorSeverity.WarningSeverity: text += "warning: " if self.severity == TypeParserErrorSeverity.NoteSeverity: text += "note: " if self.severity == TypeParserErrorSeverity.RemarkSeverity: text += "remark: " if self.severity == TypeParserErrorSeverity.IgnoredSeverity: text += "ignored: " if self.file_name == "": text += f"<unknown>: {self.message}\n" else: text += f"{self.file_name}: {self.line}:{self.column} {self.message}\n" return text @classmethod def _from_core_struct(cls, struct: core.BNTypeParserError) -> 'TypeParserError': return TypeParserError(struct.severity, struct.message, struct.fileName, struct.line, struct.column) def _to_core_struct(self) -> core.BNTypeParserError: result = core.BNTypeParserError() result.severity = self.severity result.message = self.message result.fileName = self.file_name result.line = self.line result.column = self.column return result
[docs] @dataclasses.dataclass(frozen=True) class ParsedType: name: 'types.QualifiedNameType' type: 'types.Type' is_user: bool @classmethod def _from_core_struct(cls, struct: core.BNParsedType) -> 'ParsedType': name = types.QualifiedName._from_core_struct(struct.name) type = types.Type.create(handle=core.BNNewTypeReference(struct.type)) return ParsedType(name, type, struct.isUser) def _to_core_struct(self) -> core.BNParsedType: result = core.BNParsedType() result.name = types.QualifiedName(self.name)._to_core_struct() result.type = core.BNNewTypeReference(self.type.handle) result.isUser = self.is_user return result
[docs] @dataclasses.dataclass(frozen=True) class BasicTypeParserResult: types: Dict['types.QualifiedName', 'types.Type'] variables: Dict['types.QualifiedName', 'types.Type'] functions: Dict['types.QualifiedName', 'types.Type'] def __repr__(self): return f"<types: {self.types}, variables: {self.variables}, functions: {self.functions}>"
[docs] @dataclasses.dataclass(frozen=True) class TypeParserResult: types: List[ParsedType] variables: List[ParsedType] functions: List[ParsedType] def __repr__(self): return f"<types: {self.types}, variables: {self.variables}, functions: {self.functions}>" @classmethod def _from_core_struct(cls, struct: core.BNTypeParserResult) -> 'TypeParserResult': types = [] variables = [] functions = [] for i in range(struct.typeCount): types.append(ParsedType._from_core_struct(struct.types[i])) for i in range(struct.variableCount): variables.append(ParsedType._from_core_struct(struct.variables[i])) for i in range(struct.functionCount): functions.append(ParsedType._from_core_struct(struct.functions[i])) return TypeParserResult(types, variables, functions) def _to_core_struct(self) -> core.BNTypeParserResult: result = core.BNTypeParserResult() result.typeCount = len(self.types) result.variableCount = len(self.variables) result.functionCount = len(self.functions) result.types = (core.BNParsedType * len(self.types))() result.variables = (core.BNParsedType * len(self.variables))() result.functions = (core.BNParsedType * len(self.functions))() for (i, type) in enumerate(self.types): result.types[i] = type._to_core_struct() for (i, variable) in enumerate(self.variables): result.variables[i] = variable._to_core_struct() for (i, function) in enumerate(self.functions): result.functions[i] = function._to_core_struct() return result
[docs] def to_bytes(field): if type(field) == bytes: return field if type(field) == str: return field.encode() return str(field).encode()
class _TypeParserMetaclass(type): def __iter__(self): binaryninja._init_plugins() count = ctypes.c_ulonglong() types = core.BNGetTypeParserList(count) try: for i in range(0, count.value): yield CoreTypeParser(types[i]) finally: core.BNFreeTypeParserList(types) def __getitem__(self, value): binaryninja._init_plugins() handle = core.BNGetTypeParserByName(str(value)) if handle is None: raise KeyError(f"'{value}' is not a valid TypeParser") return CoreTypeParser(handle) @property def default(self): """ Get the default parser as specified by the user's settings :return: Default parser """ return CoreTypeParser(core.BNGetDefaultTypeParser())
[docs] class TypeParser(metaclass=_TypeParserMetaclass): name = None _registered_parsers = [] _cached_string = None _cached_result = None _cached_error = None def __init__(self, handle=None): if handle is not None: self.handle = core.handle_of_type(handle, core.BNTypeParser) self.__dict__["name"] = core.BNGetTypeParserName(handle)
[docs] def register(self): """ Register a custom parser with the API """ assert self.__class__.name is not None self._cb = core.BNTypeParserCallbacks() self._cb.context = 0 self._cb.getOptionText = self._cb.getOptionText.__class__(self._get_option_text) self._cb.preprocessSource = self._cb.preprocessSource.__class__(self._preprocess_source) self._cb.parseTypesFromSource = self._cb.parseTypesFromSource.__class__(self._parse_types_from_source) self._cb.parseTypeString = self._cb.parseTypeString.__class__(self._parse_type_string) self._cb.freeString = self._cb.freeString.__class__(self._free_string) self._cb.freeResult = self._cb.freeResult.__class__(self._free_result) self._cb.freeErrorList = self._cb.freeErrorList.__class__(self._free_error_list) self.handle = core.BNRegisterTypeParser(self.__class__.name, self._cb) self.__class__._registered_parsers.append(self)
def __str__(self): return f'<TypeParser: {self.name}>' def __repr__(self): return f'<TypeParser: {self.name}>' def _get_option_text(self, option, value, result) -> bool: try: value_py = core.pyNativeStr(value) result_py = self.get_option_text(option, value_py) if result_py is None: return False TypeParser._cached_string = core.cstr(result_py) result[0] = TypeParser._cached_string return True except: log_error(traceback.format_exc()) return False def _preprocess_source( self, ctxt, source, fileName, platform_, existingTypes, options, optionCount, includeDirs, includeDirCount, output, errors, errorCount ) -> bool: try: source_py = core.pyNativeStr(source) file_name_py = core.pyNativeStr(fileName) platform_py = platform.CorePlatform._from_cache(handle=core.BNNewPlatformReference(platform_)) existing_types_py = None if existingTypes: existing_types_py = typecontainer.TypeContainer(handle=core.BNDuplicateTypeContainer(existingTypes)) options_py = [] for i in range(optionCount): options_py.append(core.pyNativeStr(options[i])) include_dirs_py = [] for i in range(includeDirCount): include_dirs_py.append(core.pyNativeStr(includeDirs[i])) (output_py, errors_py) = self.preprocess_source( source_py, file_name_py, platform_py, existing_types_py, options_py, include_dirs_py) if output_py is not None and output is not None: TypeParser._cached_string = core.cstr(output_py) output[0] = TypeParser._cached_string if errorCount is not None: errorCount[0] = len(errors_py) if errors is not None: errors_out = (core.BNTypeParserError * len(errors_py))() for i in range(len(errors_py)): errors_out[i] = errors_py[i]._to_core_struct() TypeParser._cached_error = errors_out errors[0] = errors_out return output_py is not None except: errorCount[0] = 0 log_error(traceback.format_exc()) return False def _parse_types_from_source( self, ctxt, source, fileName, platform_, existingTypes, options, optionCount, includeDirs, includeDirCount, autoTypeSource, result, errors, errorCount ) -> bool: try: source_py = core.pyNativeStr(source) file_name_py = core.pyNativeStr(fileName) platform_py = platform.CorePlatform._from_cache(handle=core.BNNewPlatformReference(platform_)) existing_types_py = None if existingTypes: existing_types_py = typecontainer.TypeContainer(handle=core.BNDuplicateTypeContainer(existingTypes)) options_py = [] for i in range(optionCount): options_py.append(core.pyNativeStr(options[i])) include_dirs_py = [] for i in range(includeDirCount): include_dirs_py.append(core.pyNativeStr(includeDirs[i])) auto_type_source = core.pyNativeStr(autoTypeSource) (result_py, errors_py) = self.parse_types_from_source( source_py, file_name_py, platform_py, existing_types_py, options_py, include_dirs_py, auto_type_source) if result_py is not None and result is not None: result_struct = result_py._to_core_struct() TypeParser._cached_result = result_struct result[0] = result_struct if errorCount is not None: errorCount[0] = len(errors_py) if errors is not None: errors_out = (core.BNTypeParserError * len(errors_py))() for i in range(len(errors_py)): errors_out[i] = errors_py[i]._to_core_struct() TypeParser._cached_error = errors_out errors[0] = errors_out return result_py is not None except: result[0].typeCount = 0 result[0].variableCount = 0 result[0].functionCount = 0 errorCount[0] = 0 log_error(traceback.format_exc()) return False def _parse_type_string( self, ctxt, source, platform_, existingTypes, result, errors, errorCount ) -> bool: try: source_py = core.pyNativeStr(source) platform_py = platform.CorePlatform._from_cache(handle=core.BNNewPlatformReference(platform_)) existing_types_py = None if existingTypes: existing_types_py = typecontainer.TypeContainer(handle=core.BNDuplicateTypeContainer(existingTypes)) (result_py, errors_py) = self.parse_type_string( source_py, platform_py, existing_types_py) if result_py is not None and result is not None: result[0].name = types.QualifiedName(result_py[0])._to_core_struct() result[0].type = core.BNNewTypeReference(result_py[1].handle) if errorCount is not None: errorCount[0] = len(errors_py) if errors is not None: errors_out = (core.BNTypeParserError * len(errors_py))() for i in range(len(errors_py)): errors_out[i] = errors_py[i]._to_core_struct() TypeParser._cached_error = errors_out errors[0] = errors_out return result_py is not None except: errorCount[0] = 0 log_error(traceback.format_exc()) return False def _free_string( self, ctxt, string ) -> bool: try: TypeParser._cached_string = None return True except: log_error(traceback.format_exc()) return False def _free_result( self, ctxt, result ) -> bool: try: if TypeParser._cached_result is not None: for i in range(TypeParser._cached_result.typeCount): core.BNFreeType(TypeParser._cached_result.types[i].type) for i in range(TypeParser._cached_result.variableCount): core.BNFreeType(TypeParser._cached_result.variables[i].type) for i in range(TypeParser._cached_result.functionCount): core.BNFreeType(TypeParser._cached_result.functions[i].type) TypeParser._cached_result = None return True except: log_error(traceback.format_exc()) return False def _free_error_list( self, ctxt, errors, errorCount ) -> bool: try: TypeParser._cached_error = None return True except: log_error(traceback.format_exc()) return False
[docs] def get_option_text(self, option: TypeParserOption, value: str) -> Optional[str]: """ Get the string representation of an option for passing to parse_type_* :param option: Option type :param value: Option value :return: A string representing the option if the parser supports it, otherwise None """ return None
[docs] def preprocess_source( self, source: str, file_name: str, platform: 'platform.Platform', existing_types: Optional['types.TypeContainerType'] = None, options: Optional[List[str]] = None, include_dirs: Optional[List[str]] = None ) -> Tuple[Optional[str], List[TypeParserError]]: """ Preprocess a block of source, returning the source that would be parsed :param source: Source code to process :param file_name: Name of the file containing the source (does not need to exist on disk) :param platform: Platform to assume the source is relevant to :param existing_types: Optional collection of all existing types to use for parsing context :param options: Optional string arguments to pass as options, e.g. command line arguments :param include_dirs: Optional list of directories to include in the header search path :return: A tuple of (preproccessed source, errors), where the preproccessed source is None if there was a fatal error. """ raise NotImplementedError("Not implemented")
[docs] def parse_types_from_source( self, source: str, file_name: str, platform: 'platform.Platform', existing_types: Optional['types.TypeContainerType'] = None, options: Optional[List[str]] = None, include_dirs: Optional[List[str]] = None, auto_type_source: str = "" ) -> Tuple[Optional[TypeParserResult], List[TypeParserError]]: """ Parse an entire block of source into types, variables, and functions :param source: Source code to parse :param file_name: Name of the file containing the source (optional: exists on disk) :param platform: Platform to assume the types are relevant to :param existing_types: Optional container of all existing types to use for parsing context :param options: Optional string arguments to pass as options, e.g. command line arguments :param include_dirs: Optional list of directories to include in the header search path :param auto_type_source: Optional source of types if used for automatically generated types :return: A tuple of (result, errors) where the result is None if there was a fatal error """ raise NotImplementedError("Not implemented")
[docs] def parse_type_string( self, source: str, platform: 'platform.Platform', existing_types: Optional['types.TypeContainerType'] = None ) -> Tuple[Optional[Tuple['types.QualifiedNameType', 'types.Type']], List[TypeParserError]]: """ Parse a single type and name from a string containing their definition. :param source: Source code to parse :param platform: Platform to assume the types are relevant to :param existing_types: Optional container of all existing types to use for parsing context :return: A tuple of (result, errors) where result is a tuple of (type, name) or None of there was a fatal error. """ raise NotImplementedError("Not implemented")
[docs] class CoreTypeParser(TypeParser):
[docs] def get_option_text(self, option: TypeParserOption, value: str) -> Optional[str]: result_cpp = ctypes.c_char_p() if not core.BNGetTypeParserOptionText(self.handle, option, value, result_cpp): return None result = core.pyNativeStr(result_cpp.value) core.free_string(result_cpp) return result
[docs] def preprocess_source( self, source: str, file_name: str, platform: 'platform.Platform', existing_types: Optional['types.TypeContainerType'] = None, options: Optional[List[str]] = None, include_dirs: Optional[List[str]] = None ) -> Tuple[Optional[str], List[TypeParserError]]: if options is None: options = [] if include_dirs is None: include_dirs = [] existing_types_cpp = None if existing_types is not None: if isinstance(existing_types, (binaryview.BinaryView,)): existing_types_cpp = existing_types.type_container elif isinstance(existing_types, (typecontainer.TypeContainer,)): existing_types_cpp = existing_types else: assert False, "Unexpected type container type" options_cpp = (ctypes.c_char_p * len(options))() for (i, s) in enumerate(options): options_cpp[i] = core.cstr(s) include_dirs_cpp = (ctypes.c_char_p * len(include_dirs))() for (i, s) in enumerate(include_dirs): include_dirs_cpp[i] = core.cstr(s) output_cpp = ctypes.c_char_p() errors_cpp = ctypes.POINTER(core.BNTypeParserError)() error_count = ctypes.c_size_t() success = core.BNTypeParserPreprocessSource( self.handle, source, file_name, platform.handle, existing_types_cpp.handle if existing_types_cpp is not None else None, options_cpp, len(options), include_dirs_cpp, len(include_dirs), output_cpp, errors_cpp, error_count ) if success: output = core.pyNativeStr(output_cpp.value) core.free_string(output_cpp) else: output = None errors = [] for i in range(error_count.value): errors.append(TypeParserError._from_core_struct(errors_cpp[i])) core.BNFreeTypeParserErrors(errors_cpp, error_count.value) return output, errors
[docs] def parse_types_from_source( self, source: str, file_name: str, platform: 'platform.Platform', existing_types: Optional['types.TypeContainerType'] = None, options: Optional[List[str]] = None, include_dirs: Optional[List[str]] = None, auto_type_source: str = "" ) -> Tuple[Optional[TypeParserResult], List[TypeParserError]]: if options is None: options = [] if include_dirs is None: include_dirs = [] existing_types_cpp = None if existing_types is not None: if isinstance(existing_types, (binaryview.BinaryView,)): existing_types_cpp = existing_types.type_container elif isinstance(existing_types, (typecontainer.TypeContainer,)): existing_types_cpp = existing_types else: assert False, "Unexpected type container type" options_cpp = (ctypes.c_char_p * len(options))() for (i, s) in enumerate(options): options_cpp[i] = core.cstr(s) include_dirs_cpp = (ctypes.c_char_p * len(include_dirs))() for (i, s) in enumerate(include_dirs): include_dirs_cpp[i] = core.cstr(s) result_cpp = core.BNTypeParserResult() errors_cpp = ctypes.POINTER(core.BNTypeParserError)() error_count = ctypes.c_size_t() success = core.BNTypeParserParseTypesFromSource( self.handle, source, file_name, platform.handle, existing_types_cpp.handle if existing_types_cpp is not None else None, options_cpp, len(options), include_dirs_cpp, len(include_dirs), auto_type_source, result_cpp, errors_cpp, error_count ) if success: result = TypeParserResult._from_core_struct(result_cpp) else: result = None core.BNFreeTypeParserResult(result_cpp) errors = [] for i in range(error_count.value): errors.append(TypeParserError._from_core_struct(errors_cpp[i])) core.BNFreeTypeParserErrors(errors_cpp, error_count.value) return result, errors
[docs] def parse_type_string( self, source: str, platform: 'platform.Platform', existing_types: Optional['types.TypeContainerType'] = None ) -> Tuple[Optional[Tuple['types.QualifiedNameType', 'types.Type']], List[TypeParserError]]: existing_types_cpp = None if existing_types is not None: if isinstance(existing_types, (binaryview.BinaryView,)): existing_types_cpp = existing_types.type_container elif isinstance(existing_types, (typecontainer.TypeContainer,)): existing_types_cpp = existing_types else: assert False, "Unexpected type container type" result_cpp = core.BNQualifiedNameAndType() errors_cpp = ctypes.POINTER(core.BNTypeParserError)() error_count = ctypes.c_size_t() success = core.BNTypeParserParseTypeString( self.handle, source, platform.handle, existing_types_cpp.handle if existing_types_cpp is not None else None, result_cpp, errors_cpp, error_count ) if success: result = ( types.QualifiedName._from_core_struct(result_cpp.name), types.Type.create(handle=core.BNNewTypeReference(result_cpp.type)) ) core.BNFreeQualifiedNameAndType(result_cpp) else: result = None errors = [] for i in range(error_count.value): errors.append(TypeParserError._from_core_struct(errors_cpp[i])) core.BNFreeTypeParserErrors(errors_cpp, error_count.value) return result, errors
[docs] @deprecation.deprecated(deprecated_in="3.4.4271", details="Use TypeParser.preprocess_source instead.") def preprocess_source(source: str, filename: str = None, include_dirs: Optional[List[str]] = None) -> Tuple[Optional[str], str]: """ ``preprocess_source`` run the C preprocessor on the given source or source filename. :param str source: source to pre-process :param str filename: optional filename to pre-process :param include_dirs: list of string directories to use as include directories. :type include_dirs: list(str) :return: returns a tuple of (preprocessed_source, error_string) :rtype: tuple(str,str) :Example: >>> source = "#define TEN 10\\nint x[TEN];\\n" >>> preprocess_source(source) ('#line 1 "input"\\n\\n#line 2 "input"\\n int x [ 10 ] ;\\n', '') >>> """ if filename is None: filename = "input" if include_dirs is None: include_dirs = [] dir_buf = (ctypes.c_char_p * len(include_dirs))() for i in range(0, len(include_dirs)): dir_buf[i] = include_dirs[i].encode('charmap') output = ctypes.c_char_p() errors = ctypes.c_char_p() result = core.BNPreprocessSource(source, filename, output, errors, dir_buf, len(include_dirs)) assert output.value is not None assert errors.value is not None output_str = output.value.decode('utf-8') error_str = errors.value.decode('utf-8') core.free_string(output) core.free_string(errors) if result: return output_str, error_str return None, error_str