# 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 ctypes
import traceback
# Binary Ninja components
import binaryninja
from . import _binaryninjacore as core
from . import binaryview
from . import types
from .log import log_error
from .architecture import Architecture, CoreArchitecture
from .platform import Platform
from typing import Iterable, List, Optional, Union, Tuple
[docs]
def get_qualified_name(names: Iterable[str]):
"""
``get_qualified_name`` gets a qualified name for the provided name list.
:param names: name list to qualify
:type names: list(str)
:return: a qualified name
:rtype: str
:Example:
>>> type, name = demangle_ms(Architecture["x86_64"], "?testf@Foobar@@SA?AW4foo@1@W421@@Z")
>>> get_qualified_name(name)
'Foobar::testf'
>>>
"""
return "::".join(names)
[docs]
def demangle_generic(
archOrPlatform: Union[Architecture, Platform],
mangled_name: str,
view: Optional['binaryview.BinaryView'] = None,
simplify: bool = False
) -> Optional[Tuple[Optional['types.Type'], List[str]]]:
"""
``demangle_generic`` demangles a mangled symbol name to a Type object.
:param Union[Architecture, Platform] archOrPlatform: Architecture or Platform for the symbol. Required for pointer/integer sizes and calling conventions.
:param str mangled_name: a mangled symbol name
:param view: (optional) view of the binary containing the mangled name
:param simplify: (optional) Whether to simplify demangled names
:return: returns tuple of (Optional[Type], demangled_name) or None on error
:rtype: Tuple
:Example:
>>> demangle_generic(Architecture["x86_64"], "?testf@Foobar@@SA?AW4foo@1@W421@@Z")
(<type: public: static enum Foobar::foo __cdecl (enum Foobar::foo)>, ['Foobar', 'testf'])
>>> demangle_generic(Architecture["x86_64"], "__ZN20ArmCallingConvention27GetIntegerArgumentRegistersEv")
(<type: immutable:FunctionTypeClass 'int64_t()'>, ['ArmCallingConvention', 'GetIntegerArgumentRegisters'])
>>>
"""
arch = None
if isinstance(archOrPlatform, Architecture):
arch = archOrPlatform
elif isinstance(archOrPlatform, Platform):
arch = archOrPlatform.arch
else:
raise TypeError("Unexpected arch or platform type")
out_type = ctypes.POINTER(core.BNType)()
out_var_name = core.BNQualifiedName()
view_handle = None
if view is not None:
view_handle = view.handle
if not core.BNDemangleGeneric(arch.handle, mangled_name, out_type, out_var_name, view_handle, simplify):
return None, [mangled_name]
result_type = None
if out_type:
result_type = types.Type.create(handle=out_type)
result_var_name = types.QualifiedName._from_core_struct(out_var_name)
core.BNFreeQualifiedName(out_var_name)
return result_type, result_var_name.name
[docs]
def demangle_llvm(mangled_name: str, options: Optional[Union[bool, binaryview.BinaryView]] = None) -> Optional[List[str]]:
"""
``demangle_llvm`` demangles a mangled name using the LLVM demangler.
:param str mangled_name: a mangled (msvc/itanium/rust/dlang) name
:param options: (optional) Whether to simplify demangled names : None falls back to user settings, a BinaryView uses that BinaryView's settings, or a boolean to set it directly
:type options: Optional[Union[bool, BinaryView]]
:return: returns demangled name or None on error
:rtype: Optional[List[str]]
:Example:
>>> demangle_llvm("?testf@Foobar@@SA?AW4foo@1@W421@@Z")
['public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)']
>>>
"""
outName = ctypes.POINTER(ctypes.c_char_p)()
outSize = ctypes.c_ulonglong()
names = []
if (
isinstance(options, binaryview.BinaryView) and core.BNDemangleLLVMWithOptions(
mangled_name, ctypes.byref(outName), ctypes.byref(outSize), options.handle
)
) or (
isinstance(options, bool) and core.BNDemangleLLVM(
mangled_name, ctypes.byref(outName), ctypes.byref(outSize), options
)
) or (
options is None and core.BNDemangleLLVMWithOptions(
mangled_name, ctypes.byref(outName), ctypes.byref(outSize), None
)
):
for i in range(outSize.value):
names.append(outName[i].decode('utf8')) # type: ignore
core.BNFreeDemangledName(ctypes.byref(outName), outSize.value)
return names
return None
[docs]
def demangle_ms(archOrPlatform: Union[Architecture, Platform], mangled_name: str, options: Optional[Union[bool, binaryview.BinaryView]] = False):
"""
``demangle_ms`` demangles a mangled Microsoft Visual Studio C++ name to a Type object.
:param Union[Architecture, Platform] archOrPlatform: Architecture or Platform for the symbol. Required for pointer/integer sizes and calling conventions.
:param str mangled_name: a mangled Microsoft Visual Studio C++ name
:param options: (optional) Whether to simplify demangled names : None falls back to user settings, a BinaryView uses that BinaryView's settings, or a boolean to set it directly
:type options: Optional[Union[bool, BinaryView]]
:return: returns tuple of (Type, demangled_name) or (None, mangled_name) on error
:rtype: Tuple[Optional[Type], Union[str, List[str]]]
:Example:
>>> demangle_ms(Platform["x86_64"], "?testf@Foobar@@SA?AW4foo@1@W421@@Z")
(<type: public: static enum Foobar::foo __cdecl (enum Foobar::foo)>, ['Foobar', 'testf'])
>>>
"""
handle = ctypes.POINTER(core.BNType)()
outName = ctypes.POINTER(ctypes.c_char_p)()
outSize = ctypes.c_ulonglong()
names = []
demangle = core.BNDemangleMS
demangleWithOptions = core.BNDemangleMSWithOptions
if isinstance(archOrPlatform, Platform):
demangle = core.BNDemangleMSPlatform
if (
isinstance(options, binaryview.BinaryView) and demangleWithOptions(
archOrPlatform.handle, mangled_name, ctypes.byref(handle), ctypes.byref(outName), ctypes.byref(outSize), options.handle
)
) or (
isinstance(options, bool) and demangle(
archOrPlatform.handle, mangled_name, ctypes.byref(handle), ctypes.byref(outName), ctypes.byref(outSize), options
)
) or (
options is None and demangleWithOptions(
archOrPlatform.handle, mangled_name, ctypes.byref(handle), ctypes.byref(outName), ctypes.byref(outSize), None
)
):
for i in range(outSize.value):
names.append(outName[i].decode('utf8')) # type: ignore
core.BNFreeDemangledName(ctypes.byref(outName), outSize.value)
if not handle:
return (None, names)
return (types.Type.create(handle), names)
return (None, mangled_name)
[docs]
def demangle_gnu3(arch, mangled_name: str, options: Optional[Union[bool, binaryview.BinaryView]] = None):
"""
``demangle_gnu3`` demangles a mangled name to a Type object.
:param Architecture arch: Architecture for the symbol. Required for pointer and integer sizes.
:param str mangled_name: a mangled GNU3 name
:param options: (optional) Whether to simplify demangled names : None falls back to user settings, a BinaryView uses that BinaryView's settings, or a boolean to set it directly
:type options: Optional[Union[bool, BinaryView]]
:return: returns tuple of (Type, demangled_name) or (None, mangled_name) on error
:rtype: Tuple[Optional[Type], Union[str, List[str]]]
"""
handle = ctypes.POINTER(core.BNType)()
outName = ctypes.POINTER(ctypes.c_char_p)()
outSize = ctypes.c_ulonglong()
names = []
if (
isinstance(options, binaryview.BinaryView) and core.BNDemangleGNU3WithOptions(
arch.handle, mangled_name, ctypes.byref(handle), ctypes.byref(outName), ctypes.byref(outSize), options.handle
)
) or (
isinstance(options, bool) and core.BNDemangleGNU3(
arch.handle, mangled_name, ctypes.byref(handle), ctypes.byref(outName), ctypes.byref(outSize), options
)
) or (
options is None and core.BNDemangleGNU3WithOptions(
arch.handle, mangled_name, ctypes.byref(handle), ctypes.byref(outName), ctypes.byref(outSize), None
)
):
for i in range(outSize.value):
names.append(outName[i].decode('utf8')) # type: ignore
core.BNFreeDemangledName(ctypes.byref(outName), outSize.value)
if not handle:
return (None, names)
return (types.Type.create(handle), names)
return (None, mangled_name)
[docs]
def simplify_name_to_string(input_name: Union[str, types.QualifiedName]):
"""
``simplify_name_to_string`` simplifies a templated C++ name with default arguments and returns a string
:param input_name: String or qualified name to be simplified
:type input_name: Union[str, QualifiedName]
:return: simplified name (or original name if simplifier fails/cannot simplify)
:rtype: str
:Example:
>>> demangle.simplify_name_to_string("std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >")
'std::string'
>>>
"""
result = None
if isinstance(input_name, str):
result = core.BNRustSimplifyStrToStr(input_name)
elif isinstance(input_name, types.QualifiedName):
result = core.BNRustSimplifyStrToStr(str(input_name))
else:
raise TypeError("Parameter must be of type `str` or `types.QualifiedName`")
return result
[docs]
def simplify_name_to_qualified_name(input_name: Union[str, types.QualifiedName], simplify: bool = True):
"""
``simplify_name_to_qualified_name`` simplifies a templated C++ name with default arguments and returns a qualified name. This can also tokenize a string to a qualified name with/without simplifying it
:param input_name: String or qualified name to be simplified
:type input_name: Union[str, QualifiedName]
:param bool simplify: (optional) Whether to simplify input string (no effect if given a qualified name; will always simplify)
:return: simplified name (or one-element array containing the input if simplifier fails/cannot simplify)
:rtype: QualifiedName
:Example:
>>> demangle.simplify_name_to_qualified_name(QualifiedName(["std", "__cxx11", "basic_string<wchar, std::char_traits<wchar>, std::allocator<wchar> >"]), True)
'std::wstring'
>>>
"""
name = None
if isinstance(input_name, str):
name = core.BNRustSimplifyStrToFQN(input_name, simplify)
assert name is not None, "core.BNRustSimplifyStrToFQN returned None"
elif isinstance(input_name, types.QualifiedName):
name = core.BNRustSimplifyStrToFQN(str(input_name), True)
assert name is not None, "core.BNRustSimplifyStrToFQN returned None"
else:
raise TypeError("Parameter must be of type `str` or `types.QualifiedName`")
result = types.QualifiedName._from_core_struct(name)
core.BNFreeQualifiedName(name)
if len(result) == 0:
return None
return result
class _DemanglerMetaclass(type):
def __iter__(self):
binaryninja._init_plugins()
count = ctypes.c_ulonglong()
types = core.BNGetDemanglerList(count)
try:
for i in range(0, count.value):
yield CoreDemangler(types[i])
finally:
core.BNFreeDemanglerList(types)
def __getitem__(self, value):
binaryninja._init_plugins()
handle = core.BNGetDemanglerByName(str(value))
if handle is None:
raise KeyError(f"'{value}' is not a valid Demangler")
return CoreDemangler(handle)
[docs]
class Demangler(metaclass=_DemanglerMetaclass):
"""
Pluggable name demangling interface. See :py:func:`register` and :py:func:`demangle`
for details on the process of this interface.
The list of Demanglers can be queried:
>>> list(Demangler)
[<Demangler: MS>, <Demangler: GNU3>]
"""
name = None
_registered_demanglers = []
_cached_name = None
def __init__(self, handle=None):
if handle is not None:
self.handle = core.handle_of_type(handle, core.BNDemangler)
self.__dict__["name"] = core.BNGetDemanglerName(handle)
else:
self.handle = None
[docs]
@classmethod
def register(cls):
"""
Register a custom Demangler. Newly registered demanglers will get priority over
previously registered demanglers and built-in demanglers.
"""
demangler = cls()
assert demangler.__class__.name is not None
assert demangler.handle is None
demangler._cb = core.BNDemanglerCallbacks()
demangler._cb.context = 0
demangler._cb.isMangledString = demangler._cb.isMangledString.__class__(demangler._is_mangled_string)
demangler._cb.demangle = demangler._cb.demangle.__class__(demangler._demangle)
demangler._cb.freeVarName = demangler._cb.freeVarName.__class__(demangler._free_var_name)
demangler.handle = core.BNRegisterDemangler(cls.name, demangler._cb)
cls._registered_demanglers.append(demangler)
def __eq__(self, other):
if not isinstance(other, Demangler):
return False
return self.name == other.name
def __str__(self):
return f'<Demangler: {self.name}>'
def __repr__(self):
return f'<Demangler: {self.name}>'
def _is_mangled_string(self, ctxt, name):
try:
return self.is_mangled_string(core.pyNativeStr(name))
except:
log_error(traceback.format_exc())
return False
def _demangle(self, ctxt, arch, name, out_type, out_var_name, view):
try:
api_arch = CoreArchitecture._from_cache(arch)
api_view = None
if view is not None:
api_view = binaryview.BinaryView(handle=core.BNNewViewReference(view))
result = self.demangle(api_arch, core.pyNativeStr(name), api_view)
if result is None:
return False
type, var_name = result
if not isinstance(var_name, types.QualifiedName):
var_name = types.QualifiedName(var_name)
Demangler._cached_name = var_name._to_core_struct()
if type:
out_type[0] = core.BNNewTypeReference(type.handle)
else:
out_type[0] = None
out_var_name[0] = Demangler._cached_name
return True
except:
log_error(traceback.format_exc())
return False
def _free_var_name(self, ctxt, name):
try:
Demangler._cached_name = None
except:
log_error(traceback.format_exc())
[docs]
def is_mangled_string(self, name: str) -> bool:
"""
Determine if a given name is mangled and this demangler can process it
The most recently registered demangler that claims a name is a mangled string
(returns true from this function), and then returns a value from
:py:func:`demangle` will determine the result of a call to :py:func:`demangle_generic`.
Returning True from this does not require the demangler to succeed the call to
:py:func:`demangle`, but simply implies that it may succeed.
:param name: Raw mangled name string
:return: True if the demangler thinks it can handle the name
"""
raise NotImplementedError()
[docs]
def demangle(
self,
arch: Architecture,
name: str,
view: Optional['binaryview.BinaryView'] = None
) -> Optional[Tuple['types.Type', 'types.QualifiedName']]:
"""
Demangle a raw name into a Type and QualifiedName.
The result of this function is a (Type, QualifiedName) tuple for the demangled
name's details.
Any unresolved named types referenced by the resulting Type will be created as
empty structures or void typedefs in the view, if the result is used on
a data structure in the view. Given this, the call to :py:func:`demangle`
should NOT cause any side-effects creating types in the view trying to resolve this
and instead just return a type with unresolved named type references.
The most recently registered demangler that claims a name is a mangled string
(returns true from :py:func:`is_mangled_string`), and then returns a value from
this function will determine the result of a call to :py:func:`demangle_generic`.
If this call returns None, the next most recently used demangler(s) will be tried instead.
If the mangled name has no type information, but a name is still possible to extract,
this function may return a successful (None, <name>) result, which will be accepted.
:param arch: Architecture for context in which the name exists, eg for pointer sizes
:param name: Raw mangled name
:param view: (Optional) BinaryView context in which the name exists, eg for type lookup
:return: Tuple of (Type, Name) if successful, None if not. Type may be None if only
a demangled name can be recovered from the raw name.
"""
raise NotImplementedError()
[docs]
class CoreDemangler(Demangler):
[docs]
def is_mangled_string(self, name: str) -> bool:
return core.BNIsDemanglerMangledName(self.handle, name)
[docs]
def demangle(self, arch: Architecture, name: str, view: Optional['binaryview.BinaryView'] = None) -> Optional[Tuple[Optional['types.Type'], 'types.QualifiedName']]:
out_type = ctypes.POINTER(core.BNType)()
out_var_name = core.BNQualifiedName()
view_handle = None
if view is not None:
view_handle = view.handle
if not core.BNDemanglerDemangle(self.handle, arch.handle, name, out_type, out_var_name, view_handle):
return None
result_type = None
if out_type:
result_type = types.Type.create(handle=out_type)
result_var_name = types.QualifiedName._from_core_struct(out_var_name)
core.BNFreeQualifiedName(out_var_name)
return result_type, result_var_name