hilda 3.1.0__tar.gz → 3.2.0__tar.gz

{hilda-3.1.0 → hilda-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hilda
-Version: 3.1.0
+Version: 3.2.0
 Summary: LLDB wrapped and empowered by iPython's features
 Author-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>, netanel cohen <netanelc305@protonmail.com>
 Maintainer-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>, netanel cohen <netanelc305@protonmail.com>
@@ -129,7 +129,7 @@ You can may start a Hilda interactive shell by invoking any of the subcommand:
 - `hilda attach [-p pid] [-n process-name]`
   - Attach to an already running process on current host (specified by either `pid` or `process-name`)
 - `hilda remote HOSTNAME PORT`
-  - Attach to an already running process on a target host (sepcified by `HOSTNAME PORT`)
+  - Attach to an already running process on a target host (specified by `HOSTNAME PORT`)
 - `hilda bare`
   - Only start an LLDB shell and load Hilda as a plugin.
   - Please refer to the following help page if you require help on the command available to you within the lldb shell:
@@ -145,8 +145,8 @@ You can may start a Hilda interactive shell by invoking any of the subcommand:
     ... and attaching to a local process:
 
     ```shell
-    process attach -n proccess_name
-    process attach -p proccess_pid
+    process attach -n process_name
+    process attach -p process_pid
     ```
 
     When you are ready, just execute `hilda` to move to Hilda's iPython shell.
@@ -164,7 +164,7 @@ Basic flow control:
 - `step_into` - Step into current instruction
 - `step_over` - Step over current instruction.
 - `run_for` - Run the process for given interval
-- `force_return` - Prematurely return from a stack frame, short-circuiting exection of inner
+- `force_return` - Prematurely return from a stack frame, short-circuiting execution of inner
   frames and optionally yielding a specified value.
 - `jump` - Jump to given symbol
 - `wait_for_module` - Wait for a module to be loaded (`dlopen`) by checking if given expression is contained within its filename
@@ -176,7 +176,7 @@ Breakpoints:
 - `breakpoints.show` - Show existing breakpoints
 - `breakpoints.remove` - Remove a single breakpoint
 - `breakpoints.clear` - Remove all breakpoints
-- `monitor` or `breakpoints.add_monitor` - Creates a breakpoint whose callback implements the requested features (print register vallues, execute commands, mock return value, etc.)
+- `monitor` or `breakpoints.add_monitor` - Creates a breakpoint whose callback implements the requested features (print register values, execute commands, mock return value, etc.)
 
 Basic read/write:
 
@@ -212,7 +212,6 @@ Hilda symbols:
 
 - `symbol` - Get symbol object for a given address
 - `objc_symbol` - Get objc symbol wrapper for given address
-- `rebind_symbols` - Reparse all loaded images symbols
 - `file_symbol` - Calculate symbol address without ASLR
 - `save` - Save loaded symbols map (for loading later using the load() command)
 - `load` - Load an existing symbols map (previously saved by the save() command)
@@ -293,7 +292,7 @@ ui.show()
 ```
 
 By default `step_into` and `step_over` will show this UI automatically.
-You may disable this behaviour by executing:
+You may disable this behavior by executing:
 
 ```python
 ui.active = False
@@ -417,7 +416,7 @@ s[0] = 1
 s[0] = p.symbol(0x11223344)()  # calling symbols also returns symbols 
 
 # attempt to resolve symbol's name
-print(p.symbol(0x11223344).lldb_symbol)
+print(p.symbol(0x11223344).lldb_address)
 
 # monitor each time a symbol is called into console and print its backtrace (`bt` option)
 # this will create a scripted breakpoint which prints your desired data and continue
@@ -467,8 +466,8 @@ p.bp(('symbol_name', 'ModuleName'))
 #### Globalized symbols
 
 Usually you would want/need to use the symbols already mapped into the currently running process. To do so, you can
-access them using `symbols.<symbol-name>`. The `symbols` global object is of type `SymbolsJar`, which is a wrapper
-to `dict` for accessing all exported symbols. For example, the following will generate a call to the exported
+access them using `symbols.<symbol-name>`. The `symbols` global object is of type `SymbolList`, which acts like
+`dict` for accessing all exported symbols. For example, the following will generate a call to the exported
 `malloc` function with `20` as its only argument:
 
 ```python
@@ -491,22 +490,17 @@ x = malloc(20)
 Sometimes you don't really know where to start your research. All you have is just theories of how your desired exported
 symbol should be called (if any).
 
-For that reason alone, we have the `rebind_symbols()`
-command - to help you find the symbol you are looking for.
-
 ```python
-p.rebind_symbols()  # this might take some time
-
 # find all symbols prefixed as `mem*` AND don't have `cpy`
 # in their name
-jar = p.symbols.startswith('mem') - p.symbols.find('cpy')
+l = p.symbols.filter_startswith('mem') - p.symbols.filter_name_contains('cpy')
 
 # filter only symbols of type "code" (removing data global for example)
-jar = jar.code()
+l = l.filter_code_symbols()
 
 # monitor every time each one is called, print its `x0` in HEX
 # form and show the backtrace
-jar.monitor(regs={'x0': 'x'}, bt=True)
+l.monitor(regs={'x0': 'x'}, bt=True)
 ```
 
 #### Objective-C Classes
@@ -538,21 +532,21 @@ print(NSDictionary.ivars)
 # show the class' methods
 print(NSDictionary.methods)
 
-# show the class' proprties
+# show the class' properties
 print(NSDictionary.properties)
 
 # view class' selectors which are prefixed with 'init'
-print(NSDictionary.symbols_jar.startswith('-[NSDictionary init'))
+print(NSDictionary.methods.filter_startswith('init'))
 
-# you can of course use any of `SymbolsJar` over them, for example:
+# you can of course use any of `SymbolList` over them, for example:
 # this will `po` (print object) all those selectors returned value
-NSDictionary.symbols_jar.startswith('-[NSDictionary init').monitior(retval='po')
+NSDictionary.methods.filter_startswith('init').monitor(retval='po')
 
 # monitor each time any selector in NSDictionary is called
 NSDictionary.monitor()
 
 # `force_return` for some specific selector with a hard-coded value (4)
-NSDictionary.get_method('valueForKey:').address.monitor(force_return=4)
+NSDictionary.methods.get('valueForKey:').address.monitor(force_return=4)
 
 # capture the `self` object at the first hit of any selector
 # `True` for busy-wait for object to be captured
@@ -637,7 +631,7 @@ They all use the following concept to use:
 ```python
 from hilda.snippets import snippet_name
 
-snippet_name.do_domething()  
+snippet_name.do_something()
 ```
 
 For example, XPC sniffing can be done using:

{hilda-3.1.0 → hilda-3.2.0}/README.md

@@ -70,7 +70,7 @@ You can may start a Hilda interactive shell by invoking any of the subcommand:
 - `hilda attach [-p pid] [-n process-name]`
   - Attach to an already running process on current host (specified by either `pid` or `process-name`)
 - `hilda remote HOSTNAME PORT`
-  - Attach to an already running process on a target host (sepcified by `HOSTNAME PORT`)
+  - Attach to an already running process on a target host (specified by `HOSTNAME PORT`)
 - `hilda bare`
   - Only start an LLDB shell and load Hilda as a plugin.
   - Please refer to the following help page if you require help on the command available to you within the lldb shell:
@@ -86,8 +86,8 @@ You can may start a Hilda interactive shell by invoking any of the subcommand:
     ... and attaching to a local process:
 
     ```shell
-    process attach -n proccess_name
-    process attach -p proccess_pid
+    process attach -n process_name
+    process attach -p process_pid
     ```
 
     When you are ready, just execute `hilda` to move to Hilda's iPython shell.
@@ -105,7 +105,7 @@ Basic flow control:
 - `step_into` - Step into current instruction
 - `step_over` - Step over current instruction.
 - `run_for` - Run the process for given interval
-- `force_return` - Prematurely return from a stack frame, short-circuiting exection of inner
+- `force_return` - Prematurely return from a stack frame, short-circuiting execution of inner
   frames and optionally yielding a specified value.
 - `jump` - Jump to given symbol
 - `wait_for_module` - Wait for a module to be loaded (`dlopen`) by checking if given expression is contained within its filename
@@ -117,7 +117,7 @@ Breakpoints:
 - `breakpoints.show` - Show existing breakpoints
 - `breakpoints.remove` - Remove a single breakpoint
 - `breakpoints.clear` - Remove all breakpoints
-- `monitor` or `breakpoints.add_monitor` - Creates a breakpoint whose callback implements the requested features (print register vallues, execute commands, mock return value, etc.)
+- `monitor` or `breakpoints.add_monitor` - Creates a breakpoint whose callback implements the requested features (print register values, execute commands, mock return value, etc.)
 
 Basic read/write:
 
@@ -153,7 +153,6 @@ Hilda symbols:
 
 - `symbol` - Get symbol object for a given address
 - `objc_symbol` - Get objc symbol wrapper for given address
-- `rebind_symbols` - Reparse all loaded images symbols
 - `file_symbol` - Calculate symbol address without ASLR
 - `save` - Save loaded symbols map (for loading later using the load() command)
 - `load` - Load an existing symbols map (previously saved by the save() command)
@@ -234,7 +233,7 @@ ui.show()
 ```
 
 By default `step_into` and `step_over` will show this UI automatically.
-You may disable this behaviour by executing:
+You may disable this behavior by executing:
 
 ```python
 ui.active = False
@@ -358,7 +357,7 @@ s[0] = 1
 s[0] = p.symbol(0x11223344)()  # calling symbols also returns symbols 
 
 # attempt to resolve symbol's name
-print(p.symbol(0x11223344).lldb_symbol)
+print(p.symbol(0x11223344).lldb_address)
 
 # monitor each time a symbol is called into console and print its backtrace (`bt` option)
 # this will create a scripted breakpoint which prints your desired data and continue
@@ -408,8 +407,8 @@ p.bp(('symbol_name', 'ModuleName'))
 #### Globalized symbols
 
 Usually you would want/need to use the symbols already mapped into the currently running process. To do so, you can
-access them using `symbols.<symbol-name>`. The `symbols` global object is of type `SymbolsJar`, which is a wrapper
-to `dict` for accessing all exported symbols. For example, the following will generate a call to the exported
+access them using `symbols.<symbol-name>`. The `symbols` global object is of type `SymbolList`, which acts like
+`dict` for accessing all exported symbols. For example, the following will generate a call to the exported
 `malloc` function with `20` as its only argument:
 
 ```python
@@ -432,22 +431,17 @@ x = malloc(20)
 Sometimes you don't really know where to start your research. All you have is just theories of how your desired exported
 symbol should be called (if any).
 
-For that reason alone, we have the `rebind_symbols()`
-command - to help you find the symbol you are looking for.
-
 ```python
-p.rebind_symbols()  # this might take some time
-
 # find all symbols prefixed as `mem*` AND don't have `cpy`
 # in their name
-jar = p.symbols.startswith('mem') - p.symbols.find('cpy')
+l = p.symbols.filter_startswith('mem') - p.symbols.filter_name_contains('cpy')
 
 # filter only symbols of type "code" (removing data global for example)
-jar = jar.code()
+l = l.filter_code_symbols()
 
 # monitor every time each one is called, print its `x0` in HEX
 # form and show the backtrace
-jar.monitor(regs={'x0': 'x'}, bt=True)
+l.monitor(regs={'x0': 'x'}, bt=True)
 ```
 
 #### Objective-C Classes
@@ -479,21 +473,21 @@ print(NSDictionary.ivars)
 # show the class' methods
 print(NSDictionary.methods)
 
-# show the class' proprties
+# show the class' properties
 print(NSDictionary.properties)
 
 # view class' selectors which are prefixed with 'init'
-print(NSDictionary.symbols_jar.startswith('-[NSDictionary init'))
+print(NSDictionary.methods.filter_startswith('init'))
 
-# you can of course use any of `SymbolsJar` over them, for example:
+# you can of course use any of `SymbolList` over them, for example:
 # this will `po` (print object) all those selectors returned value
-NSDictionary.symbols_jar.startswith('-[NSDictionary init').monitior(retval='po')
+NSDictionary.methods.filter_startswith('init').monitor(retval='po')
 
 # monitor each time any selector in NSDictionary is called
 NSDictionary.monitor()
 
 # `force_return` for some specific selector with a hard-coded value (4)
-NSDictionary.get_method('valueForKey:').address.monitor(force_return=4)
+NSDictionary.methods.get('valueForKey:').address.monitor(force_return=4)
 
 # capture the `self` object at the first hit of any selector
 # `True` for busy-wait for object to be captured
@@ -578,7 +572,7 @@ They all use the following concept to use:
 ```python
 from hilda.snippets import snippet_name
 
-snippet_name.do_domething()  
+snippet_name.do_something()
 ```
 
 For example, XPC sniffing can be done using:

{hilda-3.1.0 → hilda-3.2.0}/hilda/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '3.1.0'
-__version_tuple__ = version_tuple = (3, 1, 0)
+__version__ = version = '3.2.0'
+__version_tuple__ = version_tuple = (3, 2, 0)

{hilda-3.1.0 → hilda-3.2.0}/hilda/breakpoints.py

@@ -227,6 +227,7 @@ class BreakpointList:
         if it does not exist.
 
         :param id_or_name_or_bp: Breakpoint's ID or name (or the breakpoint itself)
+        :return: `HildaBreakpoint` if one exists, or `None` otherwise
         """
 
         if isinstance(id_or_name_or_bp, int):
@@ -366,7 +367,7 @@ class BreakpointList:
             bp = bp_loc.GetBreakpoint()
             symbol = hilda.symbol(hilda.frame.addr.GetLoadAddress(hilda.target))
             thread = hilda.thread
-            printed_name = name if name is not None else str(symbol.lldb_symbol)
+            printed_name = name if name is not None else str(symbol.lldb_address)
 
             def format_value(fmt: Union[str, Callable], value: Symbol) -> str:
                 nonlocal hilda

{hilda-3.1.0 → hilda-3.2.0}/hilda/exceptions.py

@@ -1,7 +1,7 @@
 __all__ = ['HildaException', 'SymbolAbsentError', 'EvaluatingExpressionError', 'CreatingObjectiveCSymbolError',
            'ConvertingToNsObjectError', 'ConvertingFromNSObjectError', 'DisableJetsamMemoryChecksError',
            'GettingObjectiveCClassError', 'AccessingRegisterError', 'AccessingMemoryError',
-           'BrokenLocalSymbolsJarError', 'AddingLldbSymbolError', 'LLDBError', 'InvalidThreadIndexError']
+           'AddingLldbSymbolError', 'LLDBError', 'InvalidThreadIndexError']
 
 
 class HildaException(Exception):
@@ -59,11 +59,6 @@ class AccessingMemoryError(HildaException):
     pass
 
 
-class BrokenLocalSymbolsJarError(HildaException):
-    """ Raise when attempt to load an invalid symbols jar pickle """
-    pass
-
-
 class AddingLldbSymbolError(HildaException):
     """ Raise when failing to convert a LLDB symbol to Hilda's symbol. """
     pass

{hilda-3.1.0 → hilda-3.2.0}/hilda/hilda_client.py

@@ -40,7 +40,7 @@ from hilda.objective_c_symbol import ObjectiveCSymbol
 from hilda.registers import Registers
 from hilda.snippets.mach import CFRunLoopServiceMachPort_hooks
 from hilda.symbol import Symbol
-from hilda.symbols_jar import SymbolsJar
+from hilda.symbols import SymbolList
 from hilda.ui.ui_manager import UiManager
 from hilda.watchpoints import WatchpointList
 
@@ -127,7 +127,7 @@ class HildaClient:
         self.debugger = debugger
         self.target = debugger.GetSelectedTarget()
         self.process = self.target.GetProcess()
-        self.symbols = SymbolsJar.create(self)
+        self.symbols = SymbolList(self)
         self.breakpoints = BreakpointList(self)
         self.watchpoints = WatchpointList(self)
         self.captured_objects = {}
@@ -201,7 +201,7 @@ class HildaClient:
         :param address:
         :return: Hilda's symbol object
         """
-        return Symbol.create(address, self)
+        return self.symbols.add(address)
 
     def objc_symbol(self, address: int) -> ObjectiveCSymbol:
         """
@@ -214,18 +214,18 @@ class HildaClient:
         except HildaException as e:
             raise CreatingObjectiveCSymbolError from e
 
-    def inject(self, filename: str) -> SymbolsJar:
+    def inject(self, filename: str) -> SymbolList:
         """
         Inject a single library into currently running process.
 
         :param filename: library to inject (dylib)
-        :return: SymbolsJar
+        :return: SymbolList
         """
         module = self.target.FindModule(lldb.SBFileSpec(os.path.basename(filename), False))
         if module.file.basename is not None:
             self.log_warning(f'file {filename} has already been loaded')
 
-        injected = SymbolsJar.create(self)
+        injected = SymbolList(self)
         handle = self.symbols.dlopen(filename, 10)  # RTLD_GLOBAL|RTLD_NOW
 
         if handle == 0:
@@ -247,34 +247,9 @@ class HildaClient:
                 # ignore unnamed symbols and those which are not: data, code or objc classes
                 continue
 
-            injected[name] = self.symbol(load_addr)
+            injected.add(self.symbol(load_addr), name)
         return injected
 
-    def rebind_symbols(self, image_range=None, filename_expr=''):
-        """
-        Reparse all loaded images symbols
-        :param image_range: index range for images to load in the form of [start, end]
-        :param filename_expr: filter only images containing given expression
-        """
-        self.log_debug('mapping symbols')
-        self._symbols_loaded = False
-
-        for i, module in enumerate(tqdm(self.target.modules)):
-            filename = module.file.basename
-
-            if filename_expr not in filename:
-                continue
-
-            if image_range is not None and (i < image_range[0] or i > image_range[1]):
-                continue
-
-            for symbol in module:
-                with suppress(AddingLldbSymbolError):
-                    self.add_lldb_symbol(symbol)
-
-        globals()['symbols'] = self.symbols
-        self._symbols_loaded = True
-
     @stop_is_needed
     def poke(self, address, buf: bytes):
         """
@@ -594,7 +569,7 @@ class HildaClient:
         """ jump to given symbol """
         self.lldb_handle_command(f'j *{symbol}')
 
-    def lldb_handle_command(self, cmd: str) -> None:
+    def lldb_handle_command(self, cmd: str, capture_output: bool = False) -> Optional[str]:
         """
         Execute an LLDB command
 
@@ -602,8 +577,15 @@ class HildaClient:
             lldb_handle_command('register read')
 
         :param cmd: LLDB command
+        :param capture_output: True if capturing the command output
+        :return: The output if capture was requested, None if not or the command failed
         """
-        self.debugger.HandleCommand(cmd)
+        if capture_output:
+            result = lldb.SBCommandReturnObject()
+            self.debugger.GetCommandInterpreter().HandleCommand(cmd, result)
+            return result.GetOutput() if result.Succeeded() else None
+        else:
+            self.debugger.HandleCommand(cmd)
 
     def objc_get_class(self, name: str, module_name: Optional[str] = None) -> objective_c_class.Class:
         """
@@ -828,36 +810,6 @@ class HildaClient:
         """ Log at info level """
         self.logger.info(message)
 
-    def add_lldb_symbol(self, symbol: lldb.SBSymbol) -> Symbol:
-        """
-        Convert an LLDB symbol into Hilda's symbol object and insert into `symbols` global
-        :param symbol: LLDB symbol
-        :return: converted symbol
-        :raise AddingLldbSymbolError: Hilda failed to convert the LLDB symbol.
-        """
-        load_addr = symbol.addr.GetLoadAddress(self.target)
-        if load_addr == 0xffffffffffffffff:
-            # skip those not having a real address
-            raise AddingLldbSymbolError()
-
-        name = symbol.name
-        type_ = symbol.GetType()
-
-        if name in ('<redacted>',) or (type_ not in (lldb.eSymbolTypeCode,
-                                                     lldb.eSymbolTypeRuntime,
-                                                     lldb.eSymbolTypeData,
-                                                     lldb.eSymbolTypeObjCMetaClass)):
-            # ignore unnamed symbols and those which are not in a really used type
-            raise AddingLldbSymbolError()
-
-        value = self.symbol(load_addr)
-
-        # add it into symbols global
-        self.symbols[name] = value
-        self.symbols[f'{name}{{{value.filename}}}'] = value
-
-        return value
-
     def wait_for_module(self, expression: str) -> None:
         """ Wait for a module to be loaded using `dlopen` by matching given expression """
         self.log_info(f'Waiting for module name containing "{expression}" to be loaded')
@@ -901,7 +853,7 @@ class HildaClient:
 
         # Configure and start IPython shell
         ipython_config = Config()
-        ipython_config.IPCompleter.use_jedi = True
+        ipython_config.IPCompleter.use_jedi = False
         ipython_config.BaseIPythonApplication.profile = 'hilda'
         ipython_config.InteractiveShellApp.extensions = ['hilda.ipython_extensions.magics',
                                                          'hilda.ipython_extensions.events',

{hilda-3.1.0 → hilda-3.2.0}/hilda/ipython_extensions/events.py

@@ -6,7 +6,6 @@ from IPython.terminal.interactiveshell import TerminalInteractiveShell
 from hilda.exceptions import EvaluatingExpressionError, SymbolAbsentError
 from hilda.hilda_client import HildaClient
 from hilda.lldb_importer import lldb
-from hilda.symbols_jar import SymbolsJar
 
 
 class HIEvents:
@@ -30,22 +29,19 @@ class HIEvents:
                 # That are undefined
                 continue
 
-            if not hasattr(SymbolsJar, node.id):
-                # ignore SymbolsJar properties
-                try:
-                    symbol = getattr(self.hilda_client.symbols, node.id)
-                except SymbolAbsentError:
-                    pass
-                else:
-                    try:
-                        self.hilda_client._add_global(
-                            node.id,
-                            symbol if symbol.type_ != lldb.eSymbolTypeObjCMetaClass else self.hilda_client.objc_get_class(
-                                node.id)
-                        )
-                    except EvaluatingExpressionError:
-                        self.hilda_client.log_warning(
-                            f'Process is running. Pause execution in order to resolve "{node.id}"')
+            symbol = self.hilda_client.symbols.get(node.id)
+            if symbol is None:
+                continue
+
+            try:
+                self.hilda_client._add_global(
+                    node.id,
+                    symbol if symbol.type_ != lldb.eSymbolTypeObjCMetaClass else self.hilda_client.objc_get_class(
+                        node.id)
+                )
+            except EvaluatingExpressionError:
+                self.hilda_client.log_warning(
+                    f'Process is running. Pause execution in order to resolve "{node.id}"')
 
 
 def load_ipython_extension(ip: TerminalInteractiveShell):